Starting bots by API call

This section describes the scripting execution procedure by API call in IBM Robotic Process Automation API.

The IBM Robotic Process Automation API allows you to execute scripts through requests. Requests can start bots local or remotely. This API is exposed on computers that have IBM Robotic Process Automation.

Requirements:

Requests to IBM Robotic Process Automation API to start bots follow the format:

https://{IP}:{port}/scripts/{scriptname}[/{versionnumber}]

where:

{IP}
The IP address of the target computer request. The target computer is where the script execution occurs. For local execution, use localhost.

{port}
The port for communication between the target computer and the computer that performs the request. The ports are:

    8099
    Port for HTTPS requests. The supported methods are GET and POST.

    8096
    Port for HTTPS requests using the IBM Robotic Process Automation brokering system. See details in Brokering.

{scriptname}
The name of the script to execute.

[/{versionnumber}]
Optional. The version number of the script to be executed. {scriptname} and {versionnumber} must be separated by a common bar (/). If no number is informed, the production version is defined.

Passing parameters

The execution of scripts by API call allows passage of parameters to input variables in the script. Parameters are text values ​​that are loaded into script input variables for use in your logic.

Important: The name of the parameters during the request must be equal to the names of the script input variables. The values ​​assigned to the parameters will be loaded to the input variables of the same name. Names should be unique.

GET method

To pass parameters to the script input variables using the HTTPS GET method, use URL encoding:

https://{IP}:{port}/scripts/{scriptname}[/{versionnumber}][?{params_and_values}]

The ?{params_and_values} propertie

The parameters and values ​​to be passed during the request. Formatting must be in URL encoding. The question mark (?) must precede the parameters and values. This type of formatting is also known as query string.

POST method

To pass parameters to the script input variables using the HTTPS POST method, use:

JSON example:

POST /scripts/scriptname HTTP/1.1

Host: localhost:8099

Accept: application/json

Content-Length: 36

{

  "parameter_name": "Text value"

}

unlockMachine parameter

There is a special parameter named unlockMachine. This parameter accepts the True or False values ​​and sets if the Bot Agent should try or not unlock the target computer set in {ip}. By default, unlockMachine=true.

The unlockMachine parameter must be sent in URL encoding format, regardless of the method.

Brokering

IBM Robotic Process Automation offers a brokering system for intermediate script execution. This brokering system operates only when an HTTPS request for the API on port 8096 triggers the script. The broker configuration is individual for each script.

When running a script by calling the API occurs on port 8096 for a script that has the configured broker, the broker intermediate the execution attempt. The broker notes if the execution can start on the target computer and, if it is not possible, redirects the call to other computers. The broker configuration for the script defines the group of computers available.

Broker configuring process

Requirements:

Procedure:

  1. Log in to the Web Client.
  2. In the left side menu, click Scripts.
  3. Locate the script to configure. Click on the button and click Details.
  4. Click the Broker tab.
  5. Select as following:
    • If you want to use computer groups, select the groups of computers in the Groups field.
    • If you want to select computers individually, select the computers in the Computers field
    • If you want to use groups and computers, select both.

The execution of scripts through API calls using the broker should occur in port 8096 and using the GET or POST method of HTTPS.

Optional: Configuring computer groups

Requirement: User account on the Web Client must have administrator permissions or superadministrator.

  1. Log in to the Web Client.
  2. In the left side menu, click Configuration> Groups.
  3. Click the New Group button.
  4. Fill in the fields according to:
    • In the Name field, enter the group name.
    • Optional: In the Groups field, select the groups of computers you want to join this group.
    • In the Computers field, select the computers.

Note: Groups can group users or computers or both.

See also