The Automation Center API provides endpoints to create and update processes, robots, and execution jobs.

Using this API, you can define end-to-end automations for repetitive tasks and then manage and monitor those tasks.

This API enables you to create the following types of events within your ServiceNow instance:
  • Robots: Software agents that runs a bot process. RPA robots can run attended or unattended.
  • Process: Instance of an RPA on a specific robot. It is responsible for running jobs. To uniquely identify a process, you must specify both the process ID and the robot ID.
  • Execution: Specific task to run in a robot process, such as copying information from one resource and copying it to another, as when copying information from emails to a spreadsheet.
For example, you can use this API to define the entities necessary to log into application, copy and paste information, move documents and files, and extract content from emails, PDFs, and forms.

Typically, you should create a robot first and then any processes associated to that robot, but this is not enforced by the API. You must however create the robot and process before you try to run any jobs for them or the job request will fail.

Note:
  • You cannot delete an event using this API. Events are automatically removed from an instance after 14 days by default.
  • You can pass in a maximum of 2,000 records per call. This value cannot be modified.

This API requires the Automation Center plugin to be active and requires the user to have either the sn_as.automation_technical_user or sn_ac.automation_admin role.

Automation Center - POST /sn_ac/automation/rpa

Creates robot, process, and execution events.

These events provide process automation. They appear in the Overview and Execution Automation Center dashboards to measure and monitor the output from multiple RPA vendors.

URL format

Versioned URL: /api/sn_ac/{api_version}/automation/rpa

Default URL: /api/sn_ac/v1/automation/rpa

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
Name Description
departmentName Process and robot event types only. Name of the department to which the event belongs.
This value is stored in the following tables depending on the event type:
  • process: department field in the Base Bot Process [cmdb_ci_base_rpa_process] table.
  • robot: department field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String
domainId Sys_id of the domain to which the event belongs.
This value is stored in the following tables depending on the event type:
  • execution: sys_domain field in the Automation Execution [sn_ac_automation_execution] table.
  • process: sys_domain field in the Base Bot Process [cmdb_ci_base_rpa_process] table.
  • robot: sys_domain field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String
endtime Execution event type only. End time of the execution. This value is stored in the end_time field in the Automation Execution [sn_ac_automation_execution] table.

Format: YYYY-MM-DD HH:MM:SS

Data type: String
environment Execution event type only. Environment of the execution, such as a URL. This value is stored in the environment field in the Automation Execution [sn_ac_automation_execution] table.
Note: This value is not used by the ServiceNow instance and can contain any value required by your implementation.

Data type: String
errorMessage Execution event type only. Name of the error message log. This value is stored in the message field in the Automation Execution [sn_ac_automation_execution] table.

Data type: String
eventName Required. Name of the event type. This value determines the type of event to process.
Valid values (case-sensitive):
  • execution
  • process
  • robot

Data type: String
id Required. Unique numeric identifier of the associated event.
This value is stored in the following tables depending on the event type:
  • execution: automation_execution_id field in the Automation Execution [sn_ac_automation_execution] table.
  • process: correlation_id field in the Base Bot Process [cmdb_ci_base_rpa_process] table.
  • robot: correlation_id field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: Integer
name Process and robot event types only. Required. Name of the event.
This value is stored in the following tables depending on the event type:
  • process: name field in the Base Bot Process [cmdb_ci_base_rpa_process] table.
  • robot: name field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String
priority Execution event type only. Priority of the execution.
Possible values (case-sensitive):
  • Critical
  • High
  • Medium
  • Low
This value is stored in the priority field in the Automation Execution [sn_ac_automation_execution] table.

Data type: String

Default: None - not displayed in dashboard
processId Execution event type only. Required. Unique identifier of the process on which to run the execution. This value is located in the correlation_id field of the corresponding process record in the Base Bot Process [cmdb_ci_base_rpa_process] table.

This value is then stored in the automation field in the Automation Execution [sn_ac_automation_execution] table.

Data type: String
robotId Execution event type only. Required. Unique identifier of the robot on which to run the execution. This value is located in the correlation_id field of the corresponding robot record in the Base Robot [cmdb_ci_base_rpa_robot] table.

This value is then stored in the robot field in the Automation Execution [sn_ac_automation_execution] table.

Data type: String
source Required. Source to which the event belongs, such as "servicenow_rpa". This value is located in the internal_name field of the Automation Source [sn_ac_automation_source] table.
This value is then stored in the following tables depending on the event type:
  • execution: Source field in the Automation Execution [sn_ac_automation_execution] table.
  • process: Source field in the Base Bot Process [cmdb_ci_base_rpa_process] table.
  • robot: Source field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String
starttime Execution event type only. Start time of the execution. This value is stored in the start_time field in the Automation Execution [sn_ac_automation_execution] table.

Format: YYYY-MM-DD HH:MM:SS

Data type: String
state Robot and execution event types only. State of the associated event.
Possible values for robot (case-sensitive):
  • Cancelled
  • Complete
  • Error
  • Queued
  • Running
Default: Queued
Possible values for execution (case-sensitive):
  • Available
  • Busy
  • Disconnected
  • New
  • Responsive
Default: New
This value is stored in the following tables depending on the event type:
  • execution: state field in the Automation Execution [sn_ac_automation_execution] table.
  • robot: robot_state field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String
status Process event type only. Required. Status of the process.
Possible values (case-sensitive):
  • Build
  • In Maintenance
  • In Use
  • Retired
This value is stored in the life_cycle_stage_status field in the Base Bot Process [cmdb_ci_base_rpa_process] table.

Data type: String
triggeredBy Execution event type only. Trigger source of the execution. This value is stored in the trigger_by field in the Automation Execution [sn_ac_automation_execution] table.
Note: This value is not used by the ServiceNow instance and can contain any value required by your implementation.

Data type: String
type Process and robot event types only. Required for process, Optional for robot. Type of processing to perform.
Possible values (case-sensitive):
  • Attended
  • Unattended
This value is stored in the following tables depending on the event type:
  • process: process_type field in the Base Bot Process [cmdb_ci_base_rpa_process] table.
  • robot: robot_type field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String

Default: Unattended for robot
version Robot event type only. Version of the robot.

This value is stored in the version field in the Base Robot [cmdb_ci_base_rpa_robot] table.

Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Failure. The request was rejected, due to mandatory fields missing or the request contains invalid values. The associated error message describes the reason for failure.

Response body parameters

Name Description
result Empty if the request is successful. For failure, additional information is provided.

Data type: Object

"result": {
  "fields": {
    "<record_number>": [
      "<field_in_err_or_missing>": "String"
    ]
  }
  "reason": "String"
}
For example, if records 1, 2, and 3 are all missing a required field, a message similar to the following is returned:
{
  "result": {
    "fields": {
      "1": [
        "id"
      ],
      "2": [
        "status"
      ],
      "3": [
        "name"
      ]
    },
    "reason": "We are not able to process the data as following records have insufficient data"
  }
}

Example: cURL request

The following code example shows how to post three robot event type records.

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 8001,
    name: "Quotes system Automation Robot",
    state: "Available",
    status: "In Use",
    version: 5.6,
    departmentName: "Customer Support",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8002,
    name: "Invoice Matching Robot",
    state: "Responsive",
    status: "In Maintenance",
    version: 3,
    departmentName: "HR",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8003,
    name: "Data Reconciliation Robot",
    state: "Busy",
    status: "Retired",
    version: 2,
    departmentName: "Finance",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  }]
} "\
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None

Example: cURL request

The following code example shows how to post three process event type records.

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 9001,
    name: "RPA Execution Process",
    status: "In Maintenance",
    type: "Attended",
    departmentName: "Customer Support",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9002,
    name: "Customer Onboarding",
    status: "In Use",
    type: "Attended",
    departmentName: "Finance",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9003,
    name: "Data Reconciliation",
    status: "Retired",
    type: "Unattended",
    departmentName: "HR",
    source: "servicenow_rpa",
    eventName: "process"
  }]
}" \
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None

Example: cURL request

The following code example shows how to post three execution event type records.

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 7001,
    name: "Customer Onboarding",
    starttime: "2022-03-18 00:49:13",
    endtime: "2022-03-20 00:58:03",
    state: "Running",
    priority: "Critical",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9001,
    robotId: 8001,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7002,
    name: "Data Reconciliation",
    starttime: "2022-04-30 00:19:11",
    endtime: "2022-05-02 00:41:35",
    state: "Error",
    priority: "Low",
    environment: "system",
    triggeredBy: "API",
    processId: 9002,
    robotId: 8002,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7003,
    name: "Customer Onboarding",
    starttime: "2022-01-22 02:38:53",
    endtime: "2022-01-23 02:50:44",
    state: "Queued",
    priority: "Moderate",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9003,
    robotId: 8003,
    source: "servicenow_rpa",
    eventName: "execution"
  }]
} "\
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None

Example: cURL request

The following code example shows how to create or update a process. You create a process by passing all of the mandatory parameters for a process to execute along with the eventName set to "process". The mandatory parameters needed to create a process are: id, type, status, name, and source.

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9001,
name: "RPA Execution Process",
status: "In Maintenance",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None

Example: cURL request

The following code example shows how to publish a process. You can publish a process by passing the status parameter set to "Published".

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9002,
name: "RPA Execution Process",
status: "Published",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None

Example: cURL request

The following code example shows how to create or update a robot. You create a robot by passing all of the mandatory parameters for a robot along with the eventName set to "robot". The mandatory parameters needed to create a robot are: id, status, name, and source.

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 8001,
name: "Quotes system Automation Robot",
state: "Available",
status: "In Use",
version: 5.6,
departmentName: "Customer Support",
type: "Unattended",
source: "servicenow_rpa",
eventName: "robot"
} "\
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None

Example: cURL request

The following code example shows how to create or update an execution. You create an execution by passing all of the mandatory parameters for an execution along with the eventName set to "execution". The mandatory parameters needed to create an execution are: id, processId, robotId, and source.

curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 7001,
name: "Customer Onboarding",
starttime: "2022-03-18 00:49:13",
endtime: "2022-03-20 00:58:03",
state: "Running",
priority: "Critical",
environment: "http://acqa.servicenow.com",
triggeredBy: "Schedule",
processId: 9001,
robotId: 8001,
source: "servicenow_rpa",
eventName: "execution",
errorMessage:"Error due to Inactivity"
}]
} "\
--user "username":"password"

This endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.

None