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.

  • LuaDocument - the function is passed a LuaDocument object containing the document reference, metadata, and content so that you can read or modify this data. You cannot modify the FlowFile attributes or associated content files.
  • LuaFlowFileDocument, LuaProcessorSession - use this option to read or modify the FlowFile itself (for example adding or modifying FlowFile attributes, and associated content files). You can access the document from the FlowFile. To use this option the body of the FlowFile must be in application/x.idol.doc format. For example, it must have originated from an IDOL Connector.
  • LuaFlowFile, LuaProcessorSession - use this option to directly read from, or write to, a FlowFile that is not in IDOL document format. To read from or write to the FlowFile you can use the readFlowFile and writeFlowFile functions, in the LuaFlowFile class. For more information about these functions, refer to the Lua Reference Documentation.
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  

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.

TIP: To use a Lua script to filter out irrelevant documents, you could return documents that you want to continue processing, and return nil for any documents that you want to discard. The returned relationship will then contain the documents that you want to continue processing and the success relationship will contain documents that you want to discard.

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 lua: followed by an arbitrary name. Set the value of the property to the path of the script file, or the actual script.

Any scripts you add can be referenced in the main script by calling:

require("require_module_name").

Replace require_module_name with the name of the property you create (without the lua: prefix).

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.
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...