API Task on-demand endpoint

Invoke API Tasks instantly with an endpoint. This dynamically launches and executes API Tasks on demand using the deploy API in conjunction with the on-demand request. This approach streamlines workflows and improves resource efficiency compared to traditional static deployments.

Key benefits

  • Programmatic deployment: Deploy API Task from anywhere on-demand using your preferred API client.
  • Processing:
    • Automations are activated only when needed, ensuring optimal resource utilization. This means they are not constantly deployed in the cloud, reserving resources. Instead, they are loaded and executed upon each request.
    • During high-volume periods, automations are placed in a queue and executed as soon as devices become available, ensuring smooth operations even under heavy load. You can view the progress of the automations in the Activity page.
    • Premium license helps to scale your automation and provide access to a larger pool of cloud resources that can execute multiple instances of your API Task, boosting concurrency and enabling you to handle more API Task requests simultaneously.
  • Ideal use cases:
    • Batch processing jobs (such as analyzing sales data, generating reports)
    • Scheduled tasks
    • Situations where immediate response is not critical
Note: To enable on-demand API Task deployment within a process, generate a Registration Key in Administration > Settings > Bot agent bulk install > Generate a new key and click Save Changes.

Authenticate

Acquire the requisite authentication credentials to interact with the deploy API. This commonly involves access tokens or API keys. The following sample deploys an API Task on-demand to a cloud device. You can also pass variables to bots when they are deployed.

POST https://{{ControlRoomURL}}/v4/automations/deploy

Header: X-Authorization: <<authentication token>> or Authorization: Bearer <<b
earer token>>

All API calls must contain either an authentication token from Authentication API (generates JSON Web token) or a bearer token from OAuth services. You cannot use both together in an API.

Compose the On-Demand Request

Request:
{
  "botId": 121,
  "automationName": "SAMPLE_APITASK",
  "description": "My first API Task deploy using api",
  "botLabel": "string",
  "executionType": "RUN_NOW",
  "automationPriority": "PRIORITY_MEDIUM",
  "headlessRequest": {
    "numberOfExecutions": 1,
    "queueOnSlotsExhaustion": false,
    "sharedRunAsUserId": 12
  },
  "botInput": {
    "inputVar": {
      "type": "STRING",
      "string": "PassingString"
    }
  }
}
Note:

Automation deploy requests can be made without any input fields. If you specify inputs, make sure that for the API Task to successfully receive these mapped-in values, the variable for that automation must be marked as input. Additionally, the name of the variable in the API Task has to match the value that is being mapped in the request body.

Request parameters
Parameter Type Required Description
botId Integer Yes

ID of the automation to be deployed.
automationName String No Name of the automation to be deployed. You can enter a name to easily identify your automation. Such as SAMPLE_APITASK, FIRST_API_TASK, apitask-on-demand.
description String No Description of the automation being deployed. For example: My first API Task deploy using api
botLabel String No Label for the automation being deployed.
executionType String No Execution type associated with the bot.
automationPriority String No The automation priority. By default it is set to PRIORITY_MEDIUM. Possible values for automationPriority include: PRIORITY_MEDIUM, PRIORITY_HIGH, and PRIORITY_LOW.
headlessRequest Object.
numberOfExecutions Integer No Number of executions to run for a given on-demand (headless) request.
queueOnSlotsExhaustion boolean No Specifies whether the deployment has to be queued.
sharedRunAsUserId Integer No The apitaskrunner to establish the RunAsUser context for API Tasks. For more information on apitaskrunner, see Run-as-user for API Task (apitaskrunner).
Note: This RunAsUser does not require a Bot Runner license.
botInput Object
type Any No By default it is STRING. Possible values for type includes: STRING, NUMBER, BOOLEAN, FILE, ITERATOR, LIST, DICTIONARY, TABLE, VARIABLE, CONDITIONAL, WINDOW, TASKBOT, DATETIME, UIOBJECT, RECORD, EXCEPTION, CREDENTIAL, COORDINATE, IMAGE, REGION, PROPERTIES, TRIGGER, CONDITIONALGROUP, FORM, FORMELEMENT, HOTKEY, and WORKITEM.
Response
{
  "deploymentId": "320a2149-aa44-41ab-af9b-f9343ae2581b",
  "automationName": "SAMPLE_APITASK"
}
Response parameters
Parameter Type Description
deploymentId String The deployment Id created.
automationName String Name of the deployed automation. If this name is not supplied in the request, a random name is assigned to the deployed automation.
You can test this endpoint in the Swagger interface, which is included in all your Control Room instances.
Tip: Access Swagger by navigating to your Control Room instance and adding /swagger/ at the end of the URL.
https://{{ControlRoomURL}}/swagger/

View the activity page in your Control Room to track your on-demand (headless) execution progress from Queued >> In Progress >> Completed.

API-Task-Activity-page

For more details on deploy API, see Bot deploy API (V4).