Custom Action

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.

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.

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.

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

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.