Litmus Access Processors for Apache NiFi

overview the following provides an installation and usage guide for the litmus access processor for apache nifi installing the litmus access processors into apache nifi requirements the litmus edge processors available via the litmus central portal provide a compressed zip or tar gz file both should contain the following nar files nifi nats processor nar {version} nar nifi nats service api nar {version} nar nifi nats service nar {version} nar ensure you have either and continue to the installation steps below installation steps extract the zip or tar gz file and verify you have the expected nar files stop apache nifi copy all of the extract nar files into the lib folder of your apache nifi installation start apache nifi in a web browser, navigate to the apache nifi canvas accessible at https //{host ip} 8443/nifi (example https //localhost 8443/nifi ) login with you apache nifi credentials these are set by the system admin, for more details read apache nifi documentation https //nifi apache org/docs/nifi docs/html/getting started html#i started nifi now what verify you are now able to select datahubsubscribe and datahubpublish processors in the canvas if you are, your installation is complete! preparing litmus edge to communicate with apache nifi requirements to allow litmus edge to communicate through apache nifi using litmus access, you must do the following create an access account with configured read and/write topics (see create an api account docid\ gqfpiafxtu5x1bmu4bdxn for more details) save this key as it will be used later ingesting data from litmus edge using datahubsubscribe processors requirements to allow that data can be ingested from litmus edge by apache nifi using litmus access, three requirements have to be met beforehand the litmus access processors for apache nifi have to be imported an access account with configured read and optional write topics has to be created verify that the access accounts has the correct read/write permissions for your desired topics steps this guide will provide instructions on how to create a datahubsubscribe processor in apache nifi to ingest data from litmus edge this section assumes familiarity with how to build an apache nifi flow if you are unfamiliar with this process, refer to the apache nifi documentation https //nifi apache org/docs/nifi docs/html/user guide html#building dataflow step 1 login to the apache nifi flow canvas navigate to the apache nifi flow canvas as `https //{address} 8443/nifi step 2 add a new processor to add a new processor, drag the add processor icon from the components toolbar onto the canvas step 3 select the datahubsubscribe processor in the " add processor " dialogue, search for the datahubsubscribe processor, select it, and press the " add " button step 4 configure the processor double click the datahubsubscribe processor from the canvas step 5 modify its properties select the " properties " tab step 6 configure the topic name copy the topic to be used from the tags ui of litmus edge as described by the litmus edge user guide https //docs litmus io/litmusedge v1/product features/devicehub/tags/default topics and descriptions select the value field for the topic name property to bring up the value editor paste the topic into the text field and press the ok button the topic is now set topics can be either for a single tag example devicehub alias plc rc1 ccs htr htg rmpdowtim sp all tags for a specific device example devicehub alias plc rc1 ccs > all tags collected by devicehub example devicehub alias > to be able to read data from litmus edge through the processor, the topic has to be allowed for the access account being used! step 7 add an access service select the value field for the access service property to bring up the value editor if no access service is shown by the drop down, select the create new service option if an access account does exist, please continue at step 21 step 8 create a new access service to add a new accessservice, press the create button step 9 add the new access service now press the arrow icon at the far right side to configure the new access service step 10 approve the new access service confirm the prompt with the yes button step 11 configure the access service press the gear icon at the far right to provide the required settings for the accessservice step 12 modify the access service properties select the properties tab step 13 configure the access uri configure the url which is the ip address and port used for connecting to litmus edge select the value field for the access url property to bring up the value editor replace the word "localhost" with the ip address of the litmus edge device keep the port as 9094 press the ok button the access url is now set step 14 add an access api key to the access service copy the api key to be used from the access account ui of litmus edge as described by the litmus edge documentation https //docs litmus io/litmusedge v1/product features/system/tokens/manage api accounts select the value field for the access api key property to bring up the value editor paste the api key into the text field and press the ok button the access api key is now set step 15 apply changes press the apply button to accept the settings for the access service step 16 enable the access service enable the access service through the lightning icon on the far right side step 17 confirm enablement confirm the enabling through the enable button step 18 close dialogue wait for the green tick and close the window through the close button step 19 wait for service start wait for the status to change from enabling to enabled the window may need to be refreshed manually through the update button at the left lower corner note if a document icon appears next to the book icon on the left side, an error occurred when trying to connect the error text is show when hovering over the document icon step 20 return to nifi canvas close the the configuration window the focus will now return to the nifi flow please continue at step 24 step 21 select the service (if does not exist) if an access service already does exist, that access service can be selected from the drop down step 22 approve selection press the ok button step 23 apply service press the apply button step 24 build the flow the processor is now ready and can be used to build the rest of the flow in apache nifi, processors are linked via a connection how to setup and configure these connections can be found in the apache nifi documentation https //nifi apache org/docs/nifi docs/html/user guide html#connecting components the datahub subscribe processor will usually be at the start of the flow as it does read data to then be processed if part of a flow, the triangle icon will change to a red square example flow the processor can now be enabled using the run icon the run state is shown by a green sideways triangle how to send data from apache nifi to litmus edge this section will provide instructions on how to setup the datahubpublish processor for apache nifi to send data to litmus edge requirements to allow that data can be published to litmus edge from apache nifi using litmus access, three requirements have to be met beforehand the litmus access processors for apache nifi have to be imported an access account with configured read and write topics has to be created how to add topics to an litmus access account is described in the litmus documentation https //docs litmus io/litmusedge/userguide/current le/content/ed userguide/t ed add topics htm for access step by step guide to publish data to litmus edge via apache nifi this guide will provide instructions on how to create a datahubpublish processor in apache nifi to publish data to litmus edge using litmus access this chapter will not provide instructions on how to build an apache nifi flow, as is it expected that user are familiar with this process also does apache nifi provide well documented https //nifi apache org/docs/nifi docs/html/user guide html#building dataflow instruction onto this aspect step 1 log on to apache nifi to be able to create a new nifi flow step 2 add a new processor, by dragging the add processor icon from the components toolbar onto the canvas step 3 select the datahubpublish processor and press the add button step 4 double click the datahubpublish processor from the canvas step 5 select the properties tab step 6 the first step is to setup the topic name which the datahubpublish processor will write too to be able to write to litmus edge, the topic to be used for writing has to be configured for the access account as described by the litmus edge user guide https //docs litmus io/litmusedge v1/product features/system/tokens/manage api accounts select the value field for the topic name property to bring up the value editor enter the topic used for writing into the text field and press the ok button the topic is now set to be able to write data to litmus edge through the processor, the topic has to be allowed for the access account being used how to setup topics for the access account is described by the chapter "step by step guide to create and configure an access account" step 7 the second step is to add an access service, which is the configuration for connecting to the litmus edge device select the value field for the access service property to bring up the value editor if no access service is shown by the drop down, select the create new service option if an access account does exist, please continue at step 21 step 8 to add a new accessservice, press the create button ​ step 9 now press the arrow icon at the far right side to configure the new access service ​ step 10 confirm the prompt with the yes button ​ step 11 press the gear icon at the far right to provide the required settings for the accessservice step 12 select the properties tab step 13 the first step is to setup the access url which is the ip address and port used for connecting to litmus edge select the value field for the access url property to bring up the value editor replace the word "localhost" with the ip address of the litmus edge device keep the port as 9094 press the ok button the access url is now set step 14 the second step is to setup the access api key which is used for authentication of the access account copy the api key to be used from the access account ui of litmus edge as described by the litmus edge documentation https //docs litmus io/litmusedge v1/product features/system/tokens/manage api accounts select the value field for the access api key property to bring up the value editor paste the api key into the text field and press the ok button the access api key is now set step 15 press the apply button to accept the settings for the access service step 16 enable the access service through the lightning icon on the far right side step 17 confirm the enabling through the enable button step 18 wait for the green tick and close the window through the close button step 19 wait for the status to change from enabling to enabled the window may need to be refreshed manually through the update button at the left lower corner note if a document icon appears next to the book icon on the left side, an error occurred when trying to connect the error text is show when hovering over the document icon step 20 close the the configuration window the focus will now return to the nifi flow please continue at step 24 step 21 if an access service already does exist, that access service can be selected from the drop down step 22 press the ok button step 23 press the apply button step 24 the processor is now ready and can be used to build the rest of the flow in apache nifi, processors are linked via a connection how to setup and configure these connections can be found in the apache nifi documentation https //nifi apache org/docs/nifi docs/html/user guide html#connecting components this processor will most of the time be the last processor in a flow as it does publish data if part of a flow, the triangle icon will change to a red square the processor can now be enabled using the run icon the run state is shown by a green sideways triangle step 25 to verify that data are received by le, a flow can be used using the access node and listening to the topic used for writing after saving the flow, the debug window will show the data received from apache nifi note in case apache nifi is unable to reconnect by itself after a connected le is rebooted, either restart apache nifi or disable and reenable the accessservice