Adapter - Lua Script

This page describes version 2.0.4 of the adapter.

Overview

The Lua script adapter is used to execute a Lua script as part of a workflow.

The Lua script is passed a request object with the input properties defined in the command step of the workflow. The values for these properties are passed as strings and can be queried using the functions described below.

The Lua script can set response properties that are passed back to the workflow using the response object to set output parameters.

All strings, property names and values, are UTF-8 encoded.

The overflow flow of a script is:

Read properties from the request object
Perform any processing
Set properties on the response object

Lua Runtime

This adapter uses the Lua version 5.4 runtime. Refer to the Lua 5.4 Reference Manual for the official definition of the Lua language.

The following Lua standard libraries are supported with the noted exceptions:

Basic Functions
String Manipulation
Basic UTF-8 Support
Table Manipulation
Mathematical Functions
Operating System Functions
- no os.execute
- no os.exit
- no os.remove
- no os.rename
- no os.setlocale
- no os.tmpname

The following Lua standard libraries are not supported:

Coroutine
Modules (Package)
Input and Output (IO)
Debug Facilities

If an error is raised during Lua script execution, or the error(message [, level]) function is called directly, the script will be terminated and the response object will be set to failed using:

code = LuaError
message = The string passed to the error function.

Request

The following functions can be called on the request object:

get(name, [def]) - return the string value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be a string otherwise a type error is thrown.
geti(name, [def]) - return the integer value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be an integer otherwise a type error is thrown.
getn(name, [def]) - return the number value of the property with the provided nam-.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be a number otherwise a type error is thrown.
getb(name, [def]) - return the boolean value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be a boolean otherwise a type error is thrown.
set(name, value) - set the name property to value.
- value is converted to a string if it is a string, number, integer, or boolean.
- If value is nul nothing is set.
- Any other type of value will throw a type error.
delete(name) - delete the property with the specified name.
- Returns a boolean if the property was deleted.
contains(name) - returns if the specified property exists.
- Returns a boolean if the property exists.

The name parameter should not include the index. prefix defined in the workflow. So to read the value of the input.num1 property from the workflow use request.get('num1') in the Lua script.

Response

The following functions can be called on the response object:

get(name, [def]) - return the string value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be a string otherwise a type error is thrown.
geti(name, [def]) - return the integer value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be an integer otherwise a type error is thrown.
getn(name, [def]) - return the number value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be a number otherwise a type error is thrown.
getb(name, [def]) - return the boolean value of the property with the provided name.
- The optional def parameter is returned if the property does not exist; otherwise nil is returned.
- If the def parameter is provided it must be a boolean otherwise a type error is thrown.
set(name, value) - set the name property to value.
- value is converted to a string if it is a string, number, integer, or boolean.
- If value is nul nothing is set.
- Any other type of value will throw a type error.
delete(name) - delete the property with the specified name.
- Returns a boolean if the property was deleted.
contains(name) - returns if the specified property exists.
- Returns a boolean if the property exists.
setFailed([code], [message]) - set the response as failed.
- The code and message parameters are optional and will be filled with defaults if not provided.

Example

A workflow is created with the following script and properties:

input.num1 = 4
input.num2 = 7
input.name = abc123

-- A helper function to reverse a UTF-8 string
function utf8.reverse(s)
    local r = ""
    for p,c in utf8.codes(s) do
        r = utf8.char(c)..r
    end
    return r
end
-- Read 'input.num1' and 'input.num2' and add them
-- Set the result a 'num3' in the response
x = request.geti('num1', 99)
y = request.geti('num2')
z = x + y
if (z > 10) then
    z = -z 
end
if (z > 800) then
   error(string.format('too big: %d', z))
end
response.set('num3', z)
-- Read 'input.name' from the request and set it in
-- the response both normal and reversed
a=request.get('name')
response.set('name', a)
if (a) then
    response.set('namereversed', utf8.reverse(a))
end

Properties

Name	Display	Is Required	Comments	Type	Default Value	Maximum Value	Minimum Value	Maximum Length	Minimum Length
maxScripts	Max Scripts	False	The maximum number of script commands that can run simultaneously.	integer	10	50	1
maxInstructions	Max Instructions	False	The maximum number of instructions that can run in one script before it is aborted (maximum is 1 million). This prevents a script from running forever.	integer	500000	1000000	1

Commands

Run a Lua script (script)

Run a Lua script with input parameters.

Request Properties

Name	Display	Description	Is Required	Type
script	Lua Script	The Lua script to run	True	string
input.*	Input	Each input.* adds a property accessible in the Lua script as request.get('name'). Do not pass the 'input.' prefix.	False	string

Release History

Version	Type	Description	Tracking #	Date
2.0.1	Initial	First release in the Adapter Type store.	NAP-24694	2023-03-02
2.0.4	Maintenance	Updated third-party components and improved maintainability.	NAP-27635	2024-07-31