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.

Note: API Tasks does not support interactive forms.

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 Enter the ID of the automation to be deployed. The ID is visible on the address bar when you open the automation in an editor.
automationName String No Enter the name you used when you created the automation.
description String No Enter the description you used when you created the automation.
botLabel String No Enter the label you applied when you checked in the automation. You can enter Production or N/A.
executionType String No Enter the execution type associated with the bot. You can enter one of the following execution types:
  • RUN_NOW
  • RUN_WITH_QUEUE
  • RUN_WITH_EVENT_TRIGGERS
automationPriority String No Enter the priority for automation execution. You can enter one of the following priorities:
  • PRIORITY_MEDIUM
  • PRIORITY_HIGH
  • PRIORITY_LOW
The default priority is set as PRIORITY_MEDIUM.
headlessRequest Object.
numberOfExecutions Integer No Enter the number of executions to run for a given on-demand (headless) request.
queueOnSlotsExhaustion boolean No Enter True or False to specify whether the deployment must be queued.
sharedRunAsUserId Integer No Enter the user id of the apitaskrunner user to establish the RunAsUser context for API Tasks.

The user id is visible on the address bar when you edit the user details in Edit user page.

For more information on apitaskrunner, see Run-as-user for API Task (apitaskrunner).
Note: The RunAsUser does not require a Bot Runner license.
botInput Object
type Any No Enter the type of the input variable.

You can enter one of the following variable types: 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.
string String No Enter the string that must be used as input for the STRING variable.
Response
{
  "deploymentId": "320a2149-aa44-41ab-af9b-f9343ae2581b",
  "automationName": "SAMPLE_APITASK"
}
Response parameters
Parameter Type Description
deploymentId String The deployment Id that is generated during bot deployment.
automationName String The name of the deployed automation. If you do not include the automation name 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).