Planning for using the broker system

The broker system reroutes API calls to start a script to an available computer from a pool of computers. Rerouting takes place until the script starts successfully or the pool is exhausted or rerouting takes longer than 01 min 40 sec. You can only leverage the broker when calling scripts via API using port 8096.

⚠ Attention: The broker system is deprecated. Use script orchestration instead.

Before you begin

  • You can only make use of the broker system by calling scripts via API using port 8096. To learn more about how to call scripts via API, see Calling scripts via API.
  • You need to configure the broker for the script you want to run in the IBM RPA Control Center. See Starting scripts via API using broker to learn how to configure your script.

Key concepts

  • Unattended automation
    When using the broker, there is no guarantee that the script will run on the target host computer, because if the computer is not available, the broker will reroute the call to another computer from the pool. In this case, it is best you use the broker when running scripts on unattended automation.

  • Operation frequency
    Starting scripts via API call happens on demand depending on the system making the call. You can program the caller system to do the HTTPS request to the API whenever conditions are met. Nonetheless, you need available Bot Runtime licenses for each call.

  • Input parameters and API response
    Calling scripts via API is the only method where you can start a script with predefined input values. For this, you specify the script's input parameters and the values they should receive during start up. The API response returns the values stored in the script's output parameters when it completed its operation. You define input and output parameters when developing scripts.

  • Unlocking the machine
    When running scripts on unattended automation, they need to unlock the machine using the credentials configured to them in IBM RPA Control Center, otherwise, the script will try to attach itself to an available user session, resulting in failure if the script can't find an active user session. Note that scripts running on virtual machines unnatended always need to unlock the machine.

To configure the script to unlock the machine or not during the API call, use the unlockMachine parameter. This parameter is mandatory.

This parameter must be URL encoded in the API call as a query string as


Where it accepts either the true or the false value.

  • Licenses needed
    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 License page (https://localhost:8099/web/en/license) in the host machine.

  • User privileged and user for the script
    When you start a script via API call, you can have two possible outcomes:

    • You set unlockMachine=true
      In this case, the script tries to unlock the host computer by using the credential configured for that computer register in IBM RPA Control Center. If the host computer is a virtual machine, you must set unlockMachine=true.

    • You set unlockMachine=false
      In this case, the script tries to attach itself to a running user session. If none is found, the script returns an error.

  • IBM RPA Vault mode
    Because you can integrate your organization's systems with IBM RPA to trigger scripts via API, you can use both the IBM RPA Vault's user or system mode depending on your need. See What is the IBM RPA Vault? to learn more.

  • Number of machines available
    Using the broker only makes sense if you have more than one host computer available to run scripts so rerouting can take place.

  • Configuration for each script
    You must configure the script to run the broker, and configure the computers and computer groups that can run the script. Learn more about how to configure and how to run the broker in Starting scripts via API using broker.

What to do next

To learn how to call your scripts via API using the broker, see Starting scripts via API using broker.