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

_FT_HTML5_bannerTitle.htm