Last Updated: 2024–10-16
Background
As developers create custom Processors, Controller Services, and other component types, a process is needed to allow the NAR files that are created to be included in a Datavolo Runtime.
Scope of the tutorial
In this tutorial, you will learn how to deploy NAR files as well as some of the side effects and dependency requirements that may surface. This tutorial will NOT present information for creating a NAR file.
Learning objectives
Once you've completed this tutorial, you will be able to:
- Deploy a simple Processor with a single NAR file.
- Understand "ghosted" Processor behavior when the appropriate NAR file is missing.
- Determine if a custom NAR file is missing a dependency.
- Deploy a Processor that requires a Controller Service packaged in another NAR file.
- Understand the behavior when uploading a rebuilt Processor with new required properties.
Prerequisites
- Access to a Datavolo Runtime, such as Datavolo Cloud. See Datavolo Cloud: Getting started.
- Recommended, basic familiarization of building dataflows with Datavolo. See Build a simple NiFi flow.
Tutorial video
As an option, you can watch a video version of this tutorial.
Section video
As an option, you can watch a video of this step.
Review the use case
You will address the following use cases in this tutorial.
- Given a NAR file that contains a simple Processor, upload it and utilize the Processor in a flow.
- To simulate deploying a flow that references a custom Processor for which no appropriate NAR file is present, delete the NAR file from the previous use case in order to see the "ghosted" behavior of the Processor on the flow. Resolve the issue by adding the NAR file back.
- Resolve a dependency issue with a NAR file that depends on another NAR file.
- Upload a new version of a NAR file that has a newly required property on the included Processor.
Download NAR files
Download upload-nar-examples.zip to your workstation and unzip the file. You should have the following files that will be used in this tutorial.
Initialize the canvas
Access a Runtime
Log into Datavolo Cloud and access (create if necessary) a Runtime. Alternatively, leverage a Datavolo Server Runtime that you have access to.
Setup a process group
Create a Process Group (PG) named Tutorial: NAR upload and navigate into it.
This step is focused on uploading an existing NAR file that contains a Processor with no dependencies on other components.
Section video
As an option, you can watch a video of this step.
Upload the NAR
Choose Controller Settings from the navigation drawer (aka hamburger menu) on the far right of the UI then navigate to the Local Extensions tab and click on the + icon on the far right.
Choose the nifi-simple-nar-1.0.nar file from the compressed file you downloaded earlier.
Verify it reports as Installed.
Use the processor
While adding a Processor, Filter types for, and Add, one named MyProcessor.
Notice the configuration items that make it invalid.
Resolve these by assigning a value of anything to the My Property property and connecting the success relationship to a Funnel.
The Processor is ready to be utilized.
This scenario shows what happens when a Processor is on the canvas, but the required NAR file is not present.
Section video
As an option, you can watch a video of this step.
Delete the NAR file
Go to the Local Extensions tab of the Controller Settings and click on the vertical ellipsis to the far right of the NAR list item. Click on Delete from the contextual menu that surfaces.
Confirm the deletion request.
Understand the "ghost"
Return to the canvas and notice a dashed line border around MyProcessor and the invalid configuration message that surfaces when you hover over the yellow triangle icon.
Upload the nifi-simple-nar-1.0.nar file again and verify that the border is solid again and that it is in a stopped state.
Clean up
Delete MyProcessor from the canvas (you will have to remove the connection first) and then delete the NAR file again.
This scenario shows what happens after uploading a NAR file that has missing dependencies.
Section video
As an option, you can watch a video of this step.
Upload another NAR
From Controller Settings go to the Local Extensions tab and after verifying that the NAR file from the last step has been deleted, add a new one. Upload nifi-example-processors-nar-1.0.nar this time.
Notice the STATUS reports Missing Dependency.
Click on the vertical ellipsis near the STATUS and then choose View Details.
The Bundle Dependency identifies the NAR file dependency that is missing.
Add dependent NAR file
As called out above, upload nifi-example-service-api-nar-1.0.nar via the same manner as before to resolve the missing dependency. Verify both NAR files are reporting a STATUS of Installed.
You also need to upload nifi-example-service-nar-1.1.nar as the previously uploaded NAR only contains the API interface code and this third NAR contains the implementation of the associated Controller Service.
Ensure that all THREE ARTIFACTs are listed with a STATUS of Installed.
Use the processor
Add a MyProcessor component to the canvas. Resolve the same issues as before; assign a value to My Property and connect the success relationship to a Funnel. Notice there is still a remaining issue.
Right click on the canvas and select Controller Services and click on the + icon on the page with the same name.
Type my for Filter types and ensure StandardMyService is highlighted before clicking Add.
Use the familiar vertical ellipsis > Edit pattern to reach the Properties tab of StandardMyService. Type anything for the value of My Property and then Apply the change. Then Enable the Controller Service from the vertical ellipsis options and verify the STATE reports correctly.
Back on the canvas, go to Edit Processor and assign the newly created Controller Service to the My Service property.
The Processor is ready to be utilized.
This scenario shows what happens after uploading a new version of a NAR file that now has a new required parameter.
Upload modified NAR
Upload nifi-example-processors-nar-1.0-MODIFIED.nar.
Notice the BUILD TIME was updated. Previously, both ARTIFACT items showed the same timestamp.
Resolve the issue
Notice there the Processor is reporting another validation issue. This is the newly required property that was added in the updated NAR file.
Add anything for Extra Property and MyProcessor will be ready to be utilized.
Congratulations, you've completed the Upload custom NAR files tutorial!
What you learned
- How to deploy a simple Processor with a single NAR file.
- How to interpret & resolve a "ghosted" Processor.
- How to determine what dependencies may be missing from a deployed NAR file.
- How to resolve missing dependencies of a NAR file.
- How to resolve a situation where a new version of a NAR file required an additional property.
What's next?
Check out some of these codelabs...