ExecuteDocumentLua
Runs a Lua script on a FlowFile or document.
Properties
Name | Default Value | Description |
---|---|---|
IDOL License Service |
An IdolLicenseServiceImpl that provides a way to communicate with an IDOL License Server. |
|
Document Registry Service | A DocumentRegistryServiceImpl controller service that manages and updates a document registry database. This ensures that documents are indexed in the correct order. | |
Lua script file | The path of the script to run (or the actual Lua script). | |
Lua script function | handler | The name of the function to call when the script runs. |
Lua script function arguments | LuaDocument |
The types of arguments that are passed to the function specified by Lua script function.
|
Route to | success | The connection to route the input document (or FlowFile) to after the Lua script has finished successfully. If the input document is routed by the script or is returned by the script, this property is ignored. |
Route returned to | returned | The connection to route documents (or FlowFiles) to when they are returned by the Lua function. New LuaDocuments that you return are converted to new FlowFiles. |
Route untransferred to |
If this property is configured, any FlowFile that has not already been routed is routed to this connection. If this property is not configured and there are unrouted FlowFiles, the processor will fail and any FlowFiles that have been processed are rolled back to their original state and returned to the input queue. |
|
Additional output relationships | A comma separated list of output relationships to create. If you select the "LuaFlowFileDocument, LuaProcessorSession" option for the Lua script function arguments property, then you can transfer FlowFiles to these relationships using the LuaProcessorSession object. | |
lua:require_module_name |
You can use this property to require another Lua script. Set the name of the property to Any scripts you add can be referenced in the main script by calling:
Replace |
Relationships
Name | Description |
---|---|
success | This is the default relationship for FlowFiles that have been processed by your script but not explicitly returned. FlowFiles that are processed can be routed to this relationship even if your script throws an exception. |
returned |
This is the default relationship for all documents that you return from the Lua function named by the property Lua script function. You might return new documents if you want to split one document into several. TIP: To use a Lua script to filter out irrelevant documents, you could return documents that you want to continue processing, and return |
failure | FlowFiles that had an invalid or unknown format. |
Advanced Configuration
The ExecuteDocumentLua processor has an advanced configuration interface. This includes a code editor so that you can write and debug Lua scripts, and sample code snippets that demonstrate how to complete common tasks. To open the advanced configuration interface, right-click the processor and click Configure. Then, after the Configure Processor dialog box opens, click Advanced. For more information, see Write and Debug Lua Scripts.
Example Script (to process a document)
The following is an example Lua script that you might use to process a document (when you set the "Lua script function arguments" property to LuaDocument
).
Your script must contain a function that matches the name defined by the "Lua script function" property. This function must accept a single argument (a LuaDocument). The default function name is handler
.
Any changes that you make to the LuaDocument are reflected in the FlowFile that is routed to the relationship specified by the "Route to" property (when the document is not explicitly returned) or the relationship specified by the "Route returned to" property (when it is).
The function does not need to return anything, but you can return new documents. Any new documents that you return are routed to the relationship specified by the "Route returned to" property in the processor. Unlike Lua scripts for use with CFS, you do not return true or false.
-- require a module defined by the value of the property 'lua:some_property' require("some_property") function handler(document) -- Write a log message log_info("Processing a document") -- Perform modifications to the document document:addField("some_field", "some_field_value") -- Create and return a new document, routed to the -- relationship specified by the 'Route returned to' property local newDocument = LuaDocument:new("new_document_reference") return newDocument end
Example Script (to process a FlowFile)
The following is an example Lua script that you might use to process a FlowFile (when you set the "Lua script function arguments" property to LuaFlowFileDocument,LuaProcessorSession
).
Your script must contain a function that matches the name defined by the "Lua script function" property. This function must accept two arguments (a LuaFlowFileDocument and a LuaProcessorSession). The default function name is handler
.
function handler(flowfile,session) -- Set a FlowFile attribute flowfile:setAttributes( {["name"]="value"} ) end
Example Script (routing FlowFiles)
The following example Lua script demonstrates how to route FlowFiles:
function documentHandler(doc) -- do any LuaDocument operations here return true end function handler(ff, s) -- check if connection has space available if s:relationshipAvailable("success") then -- cause the processor to rollback error("success connection unavailable") end -- call CFS style handler returning boolean local result = ff:modifyDocument(documentHandler) if result then -- transfer the modified input to the 'success' relationship s:transfer(ff, "success") else -- otherwise discard this document s:remove(ff) return end -- Create a new LuaFlowFileDocument with a reference local newff = s:create("new_flowfile_reference") -- add some content to the new document newff:append( function(a) a:addContent("some_content") end ) -- Create a new LuaDocument with a reference local doc = LuaDocument:new("new_document_reference") -- return doc to be converted to FlowFile and newff, both of which -- are routed to the 'returned' relationship return doc, newff end
Write Log Messages from Lua Scripts
The ExecuteDocumentLua processor can write log messages to NiFi log files. If you use the default logging configuration these messages are output to the log file nifi-idol.log
. To log a message, use the Lua functions log_trace(message)
, log_debug(message)
, log_info(message)
, log_warn(message)
, and log_error(message)
.
Lua Reference Documentation
For information about the Lua classes and methods that you can use in your Lua scripts, right-click the ExecuteDocumentLua processor, and click View Usage. Then, after the documentation window opens, click Additional Details...