Starting scripts via API using broker

Before you begin

• Read the key concepts described in Planning for using the broker.
• Make sure to read the Getting started section if you are new to IBM RPA development.
• For introduction on script deployment, see Deploying scripts.
• Make sure that the computers that will run your script contain the private key or certificate registered in the environment's configuration. See more in Credentials.

Procedure

Configuring the broker for a script

1. Log in to IBM RPA Control Center.
2. On left side menu, click the Scripts section.
3. Locate the script to configure. Click the Vertical ellipsis button ⋮ > Details
4. Click the Broker tab.
5. Select the Computers groups to run the script, or select the Computers that will run the script individually.

Starting a script via API using the broker

To use the broker during an API call to start a script, you need to use port 8096.

Important: The port needs to accept inbound connections in the host computer.

The following syntax defines the API call to start a script using the HTTP GET method:

GET /scripts/{script_name}?unlockMachine=false[&param1=value1&param2=value2] HTTP/1.1
Host: localhost:8096

where:

• {script_name}
  The script name as in te IBM RPA Control Center.

• unlockMachine
  Whether the script should unlock the machine or not. Accepted values are true or false.

🛈 Remember: If the target machine is a virtual machine, you must set the script to unlock the machine.

• [&param1=value1&param2=value2]
  Initial values for the script's input parameters. Format is URL encoded. This value is optional.
  These values are loaded to the script's input parameter variables before the script begins.

• localhost
  The host computer that gets the HTTPS request. If localhost, the computer making the call is calling itself. Otherwise, use the target host computer's IP address.

• 8096
  The port listening for calls. Available ports are 8099 for HTTPS requests and 8096 for HTTPS requests that uses the IBM RPA broker. The port you use needs to be open for inbound connections in the host computer.

The following syntax defines the API call to start a script using the HTTP POST method:

POST /scripts/{script_name}?unlockMachine=false HTTP/1.1
Host: localhost:8096
Content-Type: application/json
Content-Length: 51

{
    "param1":"value1",
    "param2":"value2"
}

where:

• {script_name}
  The script name as in te IBM RPA Control Center.

• unlockMachine
  Whether the script should unlock the machine or not. Accepted values are true or false.

🛈 Remember: If the target machine is a virtual machine, you must set the script to unlock the machine.

• localhost
  The host computer that gets the HTTPS request. If localhost, the computer making the call is calling itself. Otherwise, use the target host computer's IP address.

• 8096
  The port listening for calls. Available ports are 8096 for HTTPS requests and 8096 for HTTPS requests that uses the IBM RPA broker. The port you use needs to be open for inbound connections in the host computer.

• Content-Type
  The type of the payload. In this example, the payload is a JSON containing values for two parameters. Available MIMEs for Content-Type are application/json and application/x-www-form-urlencoded.

• Content-Length
  The length of the payload in characters. Usually, the caller system calculates this header automatically.

• Payload
  The payload is the data sent in the API call. You can send data to set initial values for the script's input parameters. In this example, the payload is a JSON containing two parameters that gets two values. These parameters are the script's input parameters. If the format is URL encoded, you use the syntax param1=value1&param2=value2 and change Content-Type: application/x-www-form-urlencoded. This value is optional.

Results

As when running using the regular API call, the script tries to run on localhost. When using the broker, if localhost is not available, the call is rerouted to another computer from the pool of computers defined in the IBM RPA Control Center. Computer is chosen with a round-robin algorithm.

The rerouting takes place until:

• Script starts successfully
• Pool is exhausted, resulting in an error
• 01 min 40 sec passes, resulting in an error

Related links

Parent topic:

• The broker system