Starting scripts via HTTPS request to client API

In IBM Robotic Process Automation, you can start scripts by calling the host computer's API if the ports are open. This section shows the syntax for this.

About this task

You can call scripts to perform attended or unattended automation depending on your needs, but you need to integrate the caller system with the API. In other words, the caller system must be able to make HTTPS requests to the API of the IBM Robotic Process Automation client to trigger scripts.

You can make as many API calls to the host computer as you like, but the script's operation depends on the number of Bot Runtime licenses available. If there is no license available, the call returns an error message.

  • Input parameters and API response
    Calling scripts via API is one of the methods that you can use to start a script with predefined input values. Starting from version 21.0.3, which introduced API v2.0, you can also use the Process API method to manage orchestration processes. For a more detailed information, see APIs reference. To do so, you need to specify the script's input parameters, and the values they should receive during launch. The API response returns the values that are stored in the script's output parameters when it completed its operation.

  • Unlocking the machine
    Unattended scripts need to unlock the machine using the credentials that are assigned to them in IBM RPA Control Center, otherwise, the script tries to attach itself to an available user session, resulting in failure if it can't find one.

    To configure the script to unlock the machine or not during the API call, you must use the unlockMachine parameter.

    The following query string shows how you must encode the URL encoded in the API call:

    ?unlockMachine=true|false

    Where:

    unlockMachine=true
    Setting the parameter to true means that the script tries to unlock the host computer by using the credential that is assigned to it in the IBM RPA Control Center. If the host computer is a virtual machine, you must set unlockMachine=true.

    unlockMachine=false
    The script tries to attach itself to a running user session. If none is found, the script returns an error.

Before you begin

  • You must have an available Bot Runtime license on the host machine to be able to start the script via API call. You can see your available licenses by navigating to https://localhost:8099/web/en/license in the host machine.
  • You need to publish your script to the IBM RPA Control Center. See Publishing scripts for details.
  • Unattended scripts running on virtual machines always need to unlock the machine.
  • You must enable remote REST requests in your tenant, otherwise calls get denied by the IBM RPA Agent. Log in to IBM RPA Control Center 🡥, go to Tenants > Tenant configuration > Computer policies, and set Remote REST request to On. For more information about remote REST requests, see Computer policies: Remote REST request.

Calling a script by using the GET method

The following syntax shows how to call a script via API using the HTTP GET method:

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

Where:

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

  • unlockMachine
    Whether the script should unlock the machine. 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]
    Optional. Initial values for the script's input parameters. Format is URL encoded. These values are loaded to the script's input parameter variables before the script starts running.

  • 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.

  • 8099
    The port listening for calls. This port is used for fast integrations with external applications and HTTPS requests. This port must be open for inbound connections in the host computer.

Calling a script by using the POST method

The following syntax shows how to call a script via API using the HTTP POST method:

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

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

where:

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

  • unlockMachine
    Whether the script should unlock the machine. 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. localhost, the computer making the call is calling itself. Otherwise, use the target host computer's IP address.

  • 8099
    The port listening for calls. This port is used for fast integrations with external applications and HTTPS requests. This port must 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
    Optional. The payload is the data that is 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.