Custom Action

The Custom Action step enables you to utilize external resources for processing data from within a robot using Connectors. Connectors are packages that define one or more actions a robot can use and contain all necessary resources to implement the actions.

Connectors can define actions that perform calls to external programs, shell commands, or execute JavaScript and Python in private instances. These actions are available as Actions in the Custom Action step in Design Studio.

Visit the Kofax Intelligent Automation SmartHub at https://smarthub.kofax.com/ to explore additional solutions, robots, connectors, and more.

Set up Connectors

This section describes how to set up Connectors to use in the Custom Action step.

Before you can use Connectors in your robot, select Allow the use of Connectors on the Security tab in the RoboServer Settings application. RoboServer Settings can be started from the Windows Start menu. For details, see "RoboServer Configuration" in the Kofax RPA Administrator's Guide.

Creating a Connector

Connectors are distributed as .zip archives with the .connector extension. Before creating a robot with a Custom Action step, archive your Connector using ZIP, rename the file extension to .connector, and add it to the project. When the project is uploaded to the Management Console, you can see available Connectors on the Repository > Resources tab. The Connectors are then uploaded to RoboServers and automated desktop computers if necessary.

Each .zip file must contain a manifest.json file in its root. This file must contain a manifest that defines all available actions for the Connector. See the manifest description below.

Each action defines a set of parameters, a response, and a command line. The parameters are presented to the robot designer and must be filled in by the robot. The command line is composed using a combination of the parameters and used to execute the request. The output of the request is parsed and used to fill the variables defined in the response.

Upload Connectors to Management Console

When you complete the design of a robot with a Custom Action step in Design Studio, upload it to the Management Console. After the project is uploaded to the Management Console, you can see available Connectors on the Resources tab of Repository. The Connectors are then uploaded to RoboServers and automated desktop computers if necessary.

Note that Connectors using Python and NodeJS are loaded on demand and if they are not used, they do not require any resources. Each Connector receives its own python or node.js instance, and you can run multiple Connectors of these types each with a different version if necessary.

Executing a Program (type: program)

Program actions call the indicated program directly with the current working directory set to the extracted Connector file. If the executable is part of the Connector package, the manifest should make this explicit with a relative path, such as ./executable, otherwise the robot might not locate the executable file.

If additional configuration (PATH settings or Linux dynamic loader settings) is required, it is recommended to use a shell wrapper to set up the settings and then call the executable. Parameters are passed directly to the program without further escaping.

Executing a shell command (type: shell)

Shell interfaces start a shell to execute the command line directly with the current working directory set to the extracted Connector file. Processing of this command line is handled by the shell itself and therefore depends on the platform:

  • On Windows, the action calls CMD /C and passes all elements of the command line directly to the shell.

  • On Linux, the action calls bash -c and passes each element of the command line as a separate argument. Parameters are passed directly to the shell without further escaping. See the documentation on the bash -c option for details.

Executing JavaScript (type: node)

Node.js JavaScript requests are wrapped in a function() context and executed. If the code contains require statements, they are resolved using the node_modules directory in the root of the Connector package.

By default, parameters are converted into strings and escaped before they are inserted into the command line. The command line is not escaped.

If the interface is synchronous, the robot receives both the value returned by the JavaScript and an exception value. Only one of these two fields has a non-empty value. An object is serialized to JSON before it is returned to the robot.

A specific Node.js executable can be embedded in the package by placing it in the root. If no executable is present, the Node.js LTS version included with Kofax RPA is used.

Executing Python (type: python)

Python requests are run using the exec() statement with a persistent private global() dictionary. The root of the connector package is added to the front of the sys.path to allow the connector to provide its own modules.

By default, parameters are converted into strings and escaped before they are inserted into the command line. The command line is not escaped.

Because the Python exec() statement does not allow the return statement at the top level, the request must assign its result to the global rpa_return variable instead. This variable is removed from the global scope between requests. If the interface is synchronous, the robot receives the value of the rpa_return variable and an exception value. Only one of these two fields has a non-empty value. An object is serialized to JSON before it is returned to the robot.

The RPAConnector name is reserved for internal use. Do not use it as a module name or create a directory named RPAConnector in the Connector package.

Kofax RPA uses the default Python interpreter. You can override this setting in the manifest by using a different name or path, such as "python3.8" or "/usr/bin/python3". It is left to the system to resolve the specified interpreter.

The package must be configured for the Python version that is used. Refer to the Kofax RPA Technical Specifications for supported Python versions.

Execute Connectors on local devices

To use your custom Connectors with the local device in your robot, select the Allow the use of Connectors option in the RoboServer Settings application in the local device RoboServer.

Connector timeout

By default, the robot waits for the connector to complete processing and get the results. The default Custom Action step timeout value is set to 240 seconds.

If you expect that connector exceeds this time, we recommend changing your connector to perform processing asynchronously or on a background thread and add a second Custom Action step to poll the connector for (partial) results and completion. In this way, the robot can perform quick status inquiries and process results in parallel with the connector.

If this is not possible, set the timeout to a higher value. To do so, edit the common.conf file in the installation\bin folder. Add the following line:

  • wrapper.java.additional.<nr>=-Dtimeout.action.seconds=<timeout>

Replace <nr> with the next sequence number for the wrapper.java.additional settings already present in the file.

Replace <timeout> with the required timeout value in seconds.

Manifest

The manifest.json file must contain the following JSON elements:

Field

Status

Description

actions

required

Array of actions.

name

required

Name of the Connector shown in the Custom Action step.

python

optional

String

Specifies the executable to run for Python actions. This setting applies to all platforms but can be overridden using one of the following platform-specific settings.

Default: “python

python-windows

optional

String

If present, specifies the executable to run for Python actions on the Windows platform.

python-linux

optional

String

If present, specifies the executable to run for Python actions on the Linux platform.

python-support

optional

Integer

Specifies the major version of Python that is used.

For example, for Python version 3.x the value is 3.

Action

Action format is detailed in the following table.

Action format

Field

Status

Description

name

required

Name of the Action.

type

required

Type of the Action. It must be one of the following: “program”, “shell”, “node,” or “python.

parameters

optional

A set of parameters represented in the Custom Action step as input fields.

response

optional

A set of responses represented in the Custom Action step as output fields. If this field is omitted, a default set of responses is used depending on the definition of the Action. The default responses can be:

  • For the "shell" and "python" actions, a returncode type of integer is added.
  • For the "stdout" and/or "stder" actions, corresponding text fields are added to the result set.
  • For the "node" and "python" actions, two string fields are added: result and error.

For the "shell" and "program" actions, you may set the wait field to false to get no response. In this case, the action starts and runs in the background. Note that you cannot set the "node" or "python" actions to have no responses.

commandline

required

A set of strings representing the parameters of the request command. For “program” actions, the first parameter is the executable. Parameters can be inserted using %n escapes (inserts the nth value from the parameters array). Use %% to insert a percent sign.

Elements that are empty after parameter substitution are removed.

For the “node” and “python” requests, it is permitted to send complete scripts.

prune

optional

Boolean

Indicates that elements expanded to an empty string should be removed from the command line array.

Default: true

wait

optional

Boolean

Indicates that the robot should wait for the action to finish. This setting is ignored for “node” and “python” actions or if the action has a response array.

Default: true

stdout

optional

Boolean

Enables the capturing of the standard output stream from a “program” or “shell” action in a variable. This field is ignored if “wait” is false.

Default: false

stderr

optional

Boolean

Enables capturing of the standard error stream from a “program” or “shell” action in a variable. This field is ignored if “wait” is false.

Default: false

Parameter

Parameter format is detailed in the following table.

Parameter format

Field

Status

Description

name

required

Name of the parameter. The name is shown in the Custom Action step.

type

required

Type of the parameter. The type must be one of the following: “string” or “number.” “number” parameters are restricted to integral numbers.

default

optional

Default value of the parameter.

Default: “” or 0 depending on the type of the parameter.

min

optional

Number

The minimum permitted value for the parameter. This attribute is only supported for “number” parameters; it is ignored for other types.

Default: -2147483648

max

optional

Number

The maximum permitted value for the parameter. This attribute is only supported for “number” parameters; it is ignored for other types.

Default: +2147483647

optional

optional

Boolean

Optional parameters can be left unassigned or empty in the robot.

Default: false

escape

optional

Boolean

Wrap the value in quotation marks and escape special characters. This attribute is currently supported for “node” and “python” string parameters; it is ignored in all other situations.

Default: true

For numerical parameters, the default value must be between the min and max values (inclusive). All three settings must be in the range of -2147483648 to +2147483647 (inclusive).

Response

The following table describes response format.

Response format

Field

Status

Description

name

required

Name of the response. The name is shown in the Custom Action step.

type

required

Type of the response. The type must be one of the following: “string” or “number.” “number” response are converted to integral numbers.

optional

optional

Boolean

Indicates that the response is not required to be present in the output. If the response is omitted, the variable is filled with its default value.

Default: false

default

optional

Default value for the parameter.

This value is used if an optional parameter is omitted from the response.

Default: “” or 0 depending on the type of the parameter.

Floating-point numerical values in the application’s response are converted to integers.

manifest.json examples

The following Linux-based examples use different connectors (shell, node, python, program) that call corresponding functions to add two numbers. The function parameters are defined in the order they are passed to this function, such as: First number and Second number. The result of the calculation is passed back to the robot in the variable assigned to the Sum value. The output value is assigned differently in different connectors.

python.connector

For this connector to work, install the latest Python version on the computer where a robot with the connector is running.

{"actions": [
    {
      "name": "Adder",
      "type": "python",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": [
        "rpa_return = { 'Sum': %1 + %2 }"
      ]
    }
  ],
  "name": "Adder Function (python)"
}
shell.connector

{
  "actions": [
    {
      "name": "Adder",
      "type": "shell",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": [
	"echo \"{ \\\"Sum\\\": $((%1 + %2)) }\""
      ]
    }
  ],
  "name": "Adder Function (shell)"
}

node.connector

{
  "actions": [
    {
      "name": "Adder",
      "type": "node",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": [
        "return { Sum: %1 + %2 };"
      ]
    }
  ],
  "name": "Adder Function (node)"
}

program.connector

This connector uses an executable program "add" called by the connector.

{
  "actions": [
    {
      "name": "Adder",
      "type": "program",
      "parameters": [
        {
          "name": "First number",
          "type": "number"
        },
        {
          "name": "Second number",
          "type": "number",
          "min": 1,
          "default": 1000
        }
      ],
      "response": [
        {
          "name": "Sum",
          "type": "number"
        }
      ],
      "commandline": {
      "windows":["./add.exe", "%1", "%2"],
      "linux":["./add", "%1", "%2"],
    }
  ],
  "name": "Adder Function (program)"
}
Response definitions
Program

JSON data sent as a response must conform to the JavaScript Object Notation (JSON) Data Interchange Format standard RFC-8259. Program connectors must ensure that their outputs are UTF-8 encoded, as required by this standard.

Program actions are as follows:

  • If the action has a response array, the wait field is ignored and the robot waits until the program terminates. The standard output of the program is captured and parsed as a JSON string and the variables are filled with the respective fields from this string. The robot fails if the program does not produce a valid JSON string.
  • If the action has no response array and the wait field is false, the step has no response variables.
  • If the action has no response array and the wait field is true, the step has the following response variables:
    • rc: Return code of the program.
    • stdout: Standard output stream of the program (provided only if stdout is true).
    • stderr: Standard error stream of the program (provided only if stderr is true).

Regardless of the configuration of the connector, the standard output stream and standard error stream are logged at the INFO level to the Kofax RPA logs.

Shell

JSON data sent as a response must conform to the JavaScript Object Notation (JSON) Data Interchange Format standard RFC-8259. Shell connectors must ensure that their outputs are UTF-8 encoded, as required by this standard.

Shell actions are executed using CMD.EXE on Windows and bash on Linux.

  • If the Action has a response array, the wait field is ignored and the robot waits until the shell terminates. The standard output of the shell is captured and parsed as a JSON string and the variables are filled with the respective fields from this string. The robot fails if the program does not produce a valid JSON string.
  • If the Action has no response array and the wait field is false, the step has no response variables.
  • If the Action has no response array and the wait field is true, the step has the following response variables:
    • rc: Return code of the shell.
    • stdout: Standard output stream of the shell (provided only if stdout is true).
    • stderr: Standard error stream of the shell (provided only if stderr is true).

Regardless of the configuration of the connector, the Standard output stream and Standard error stream are logged at the INFO level to the Kofax RPA logs.

NodeJS

The command line is executed in the context of a function. The command must use the return statement to return its results to the robot.

  • If the action has a response block, it is expected to return an object or JSON string and the variables are filled with the respective fields from this object. The robot fails if an exception is thrown and not handled.
  • If the action has no response block, the step has the following two response variables:

    result: If the statement completed successfully, this variable receives the value returned by the statement.

    error: If an exception is thrown and not handled in the JavaScript code, this variable contains the text of the exception.

Python

The command line is executed using the exec() function. The command must assign a value to the global variable rpa_return to return its results to the robot.

  1. If the action has a response block, rpa_return must contain an object or JSON string and the variables are filled with the respective fields from this object. The robot fails if an exception is thrown and not handled.

  1. If the action has no response block, the step has the following two response variables:
    • result: If the statement completed successfully, this variable receives the value of rpa_return.

    • error: If an exception is thrown and not handled in the Python code, this variable contains the text of the exception.

Implementation details

The following elements in the .zip file are reserved:

Type

Path

Description

file

/manifest.json

Manifest

file

/node

Node.js executable for the Linux platform. If this file is not present, the Node.js instance included with Kofax RPA is used.

file

/node.exe

Node.js executable for the Windows platform. If this file is not present, the Node.js instance included with Kofax RPA is used.

directory

/node_modules

Location of the Node.js modules.

directory

/RPAConnector

Reserved for internal use.

directory

/node_modules/RPAConnector

Reserved for internal use.