{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":469,"path":"api-reference/rest-apis/auto-api.md","title":"Automation Center API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Automation Center API\n\nThe Automation Center API provides endpoints to create and update data related to robots, processes, and execution jobs. By leveraging this API, you can integrate and reflect details from your automation workflows into the Automation Center dashboard.\n\nKey concepts of the API:\n\n- Robots: Software agents that execute bot processes. RPA robots can operate in attended or unattended modes.\n- Processes: Instances of RPA workflows executed on a specific robot. To uniquely identify a process, both the process ID and the robot ID must be specified.\n- Executions: Individual tasks performed within a process, such as transferring information from one resource to another \\(such as, copying data from emails into a spreadsheet\\).\n\nHow to use the API:\n\nYou can use the API to send data from third-party RPA tools, including robots, processes, and executions, to Automation Center.\n\nRecommended Workflow:\n\n1. Send the robot data.\n2. Send the process data linked to the sent robot.\n3. Send execution data that references the corresponding robot and process.\n\n **Note:** Execution data without its associated robot and process already captured in Automation Center will not appear on the dashboard.\n\n\nAdditional information:\n\n- Event retention: Events created using this API are automatically removed from your instance after 14 days \\(default setting\\).\n- Record limits: Each API call can handle a maximum of 2,000 records. This limit cannot be changed.\n- Event deletion: This API does not support event deletion.\n\nThis 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.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Automation Center - POST /sn\\_ac/automation/rpa\n\nCreates robot, process, and execution events.\n\nThese events provide process automation. They appear in the Overview and Execution Automation Center dashboards to measure and monitor the output from multiple RPA vendors.\n\n### URL format\n\nVersioned URL: `/api/sn_ac/{api_version}/automation/rpa`\n\nDefault URL: `/api/sn_ac/v1/automation/rpa`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\napi\\_version\n\n\n\nOptional. 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\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\ndepartmentName\n\n\n\nProcess 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:\n\n- process: department field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.\n- robot: department field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: String\n\n
\n\ndomainId\n\n\n\nSys\\_id of the domain to which the event belongs. This value is stored in the following tables depending on the event type:\n\n- execution: sys\\_domain field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.\n- process: sys\\_domain field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.\n- robot: sys\\_domain field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: String\n\n
\n\nendtime\n\n\n\nExecution 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\n\nData type: String\n\n
\n\nenvironment\n\n\n\nExecution 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.\n\nData type: String\n\n
\n\nerrorMessage\n\n\n\nExecution 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\n\n
\n\neventName\n\n\n\nRequired. Name of the event type. This value determines the type of event to process.Valid values \\(case-sensitive\\):\n\n- execution\n- process\n- robot\n\nData type: String\n\n
\n\nid\n\n\n\nRequired. Unique numeric identifier of the associated event. This value is stored in the following tables depending on the event type:\n\n- execution: automation\\_execution\\_id field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.\n- process: correlation\\_id field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.\n- robot: correlation\\_id field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: Number \\(Integer\\)\n\n
\n\nname\n\n\n\nProcess and robot event types only. Required. Name of the event. This value is stored in the following tables depending on the event type:\n\n- process: name field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.\n- robot: name field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: String\n\n
\n\npriority\n\n\n\nExecution event type only. Priority of the execution.Valid values \\(case-sensitive\\):\n\n- Critical\n- High\n- Medium\n- Low\n\nThis value is stored in the priority field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.Data type: String\n\nDefault: None - Not displayed in the dashboard.\n\n
\n\nprocessId\n\n\n\nExecution 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 stored in the automation field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.\n\nData type: String\n\n
\n\nrobotId\n\n\n\nExecution 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 stored in the robot field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.\n\nData type: String\n\n
\n\nsource\n\n\n\nRequired. 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 stored in the following tables depending on the event type:\n\n- execution: Source field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.\n- process: Source field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.\n- robot: Source field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: String\n\n
\n\nstarttime\n\n\n\nExecution 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.Data type: String\n\nFormat: YYYY-MM-DD HH:MM:SS\n\n
\n\nstate\n\n\n\nRobot and execution event types only. State of the associated event.Valid values for robot \\(case-sensitive\\):\n\n- Cancelled\n- Complete\n- Error\n- Queued\n- Running\n\nDefault: Queued\n\nPossible values for execution \\(case-sensitive\\):\n\n- Available\n- Busy\n- Disconnected\n- New\n- Responsive\n\nDefault: New\n\nThis value is stored in the following tables depending on the event type:\n\n- execution: state field in the Automation Execution \\[sn\\_ac\\_automation\\_execution\\] table.\n- robot: robot\\_state field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: String\n\n
\n\nstatus\n\n\n\nProcess event type only. Required. Status of the process.Possible values \\(case-sensitive\\):\n\n- Build\n- In Maintenance\n- In Use\n- Retired\n\nThis value is stored in the life\\_cycle\\_stage\\_status field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.Data type: String\n\n
\n\ntriggeredBy\n\n\n\nExecution 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.\n\nData type: String\n\n
\n\ntype\n\n\n\nProcess and robot event types only. Required for process, Optional for robot. Type of processing to perform.Valid values \\(case-sensitive\\):\n\n- Attended\n- Unattended\n\nThis value is stored in the following tables depending on the event type:\n\n- process: process\\_type field in the Base Bot Process \\[cmdb\\_ci\\_base\\_rpa\\_process\\] table.\n- robot: robot\\_type field in the Base Robot \\[cmdb\\_ci\\_base\\_rpa\\_robot\\] table.\n\nData type: String\n\nDefault: Unattended for robot\n\n
\n\nversion\n\n\n\nRobot 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.\n\nData type: String\n\n
### Headers\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n\n
\n\nHeader\n\n\n\nDescription\n\n
\n\nAccept\n\n\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
\n\nContent-Type\n\n\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n
|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|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.|\n\n### Response body parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nresult\n\n\n\nEmpty if the request is successful. For failure, additional information is provided.Data type: Object\n\n```\n\"result\": {\n \"fields\": {\n \"\": [Array]\n }\n \"reason\": \"String\"\n}\n```\n\nFor example, if records 1, 2, and 3 are all missing a required field, a message similar to the following is returned:\n\n```\n{\n \"result\": {\n \"fields\": {\n \"1\": [\n \"id\"\n ],\n \"2\": [\n \"status\"\n ],\n \"3\": [\n \"name\"\n ]\n },\n \"reason\": \"We are not able to process the data as following records have insufficient data\"\n }\n}\n```\n\n
### cURL request\n\nThe following code example shows how to post three robot event type records.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n records: [{\n id: 8001,\n name: \"Quotes system Automation Robot\",\n state: \"Available\",\n status: \"In Use\",\n version: 5.6,\n departmentName: \"Customer Support\",\n type: \"Unattended\",\n source: \"servicenow_rpa\",\n eventName: \"robot\"\n },\n {\n id: 8002,\n name: \"Invoice Matching Robot\",\n state: \"Responsive\",\n status: \"In Maintenance\",\n version: 3,\n departmentName: \"HR\",\n type: \"Unattended\",\n source: \"servicenow_rpa\",\n eventName: \"robot\"\n },\n {\n id: 8003,\n name: \"Data Reconciliation Robot\",\n state: \"Busy\",\n status: \"Retired\",\n version: 2,\n departmentName: \"Finance\",\n type: \"Unattended\",\n source: \"servicenow_rpa\",\n eventName: \"robot\"\n }]\n} \"\\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n### cURL request\n\nThe following code example shows how to post three process event type records.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n records: [{\n id: 9001,\n name: \"RPA Execution Process\",\n status: \"In Maintenance\",\n type: \"Attended\",\n departmentName: \"Customer Support\",\n source: \"servicenow_rpa\",\n eventName: \"process\"\n },\n {\n id: 9002,\n name: \"Customer Onboarding\",\n status: \"In Use\",\n type: \"Attended\",\n departmentName: \"Finance\",\n source: \"servicenow_rpa\",\n eventName: \"process\"\n },\n {\n id: 9003,\n name: \"Data Reconciliation\",\n status: \"Retired\",\n type: \"Unattended\",\n departmentName: \"HR\",\n source: \"servicenow_rpa\",\n eventName: \"process\"\n }]\n}\" \\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n### cURL request\n\nThe following code example shows how to post three execution event type records.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n records: [{\n id: 7001,\n name: \"Customer Onboarding\",\n starttime: \"2022-03-18 00:49:13\",\n endtime: \"2022-03-20 00:58:03\",\n state: \"Running\",\n priority: \"Critical\",\n environment: \"system\",\n triggeredBy: \"Schedule\",\n processId: 9001,\n robotId: 8001,\n source: \"servicenow_rpa\",\n eventName: \"execution\"\n },\n {\n id: 7002,\n name: \"Data Reconciliation\",\n starttime: \"2022-04-30 00:19:11\",\n endtime: \"2022-05-02 00:41:35\",\n state: \"Error\",\n priority: \"Low\",\n environment: \"system\",\n triggeredBy: \"API\",\n processId: 9002,\n robotId: 8002,\n source: \"servicenow_rpa\",\n eventName: \"execution\"\n },\n {\n id: 7003,\n name: \"Customer Onboarding\",\n starttime: \"2022-01-22 02:38:53\",\n endtime: \"2022-01-23 02:50:44\",\n state: \"Queued\",\n priority: \"Moderate\",\n environment: \"system\",\n triggeredBy: \"Schedule\",\n processId: 9003,\n robotId: 8003,\n source: \"servicenow_rpa\",\n eventName: \"execution\"\n }]\n} \"\\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n### cURL request\n\nThe 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**.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\nrecords: [{\nid: 9001,\nname: \"RPA Execution Process\",\nstatus: \"In Maintenance\",\ntype: \"Attended\",\ndepartmentName: \"Customer Support\",\nsource: \"servicenow_rpa\",\neventName: \"process\"\n}]\n} \"\\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n### cURL request\n\nThe following code example shows how to publish a process. You can publish a process by passing the **status** parameter set to \"Published\".\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\nrecords: [{\nid: 9002,\nname: \"RPA Execution Process\",\nstatus: \"Published\",\ntype: \"Attended\",\ndepartmentName: \"Customer Support\",\nsource: \"servicenow_rpa\",\neventName: \"process\"\n}]\n} \"\\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n### cURL request\n\nThe 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**.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\nrecords: [{\nid: 8001,\nname: \"Quotes system Automation Robot\",\nstate: \"Available\",\nstatus: \"In Use\",\nversion: 5.6,\ndepartmentName: \"Customer Support\",\ntype: \"Unattended\",\nsource: \"servicenow_rpa\",\neventName: \"robot\"\n} \"\\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n### cURL request\n\nThe 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**.\n\n```\ncurl \"https://instance.servicenow.com/api/sn_ac/automation/rpa\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\nrecords: [{\nid: 7001,\nname: \"Customer Onboarding\",\nstarttime: \"2022-03-18 00:49:13\",\nendtime: \"2022-03-20 00:58:03\",\nstate: \"Running\",\npriority: \"Critical\",\nenvironment: \"http://acqa.servicenow.com\",\ntriggeredBy: \"Schedule\",\nprocessId: 9001,\nrobotId: 8001,\nsource: \"servicenow_rpa\",\neventName: \"execution\",\nerrorMessage:\"Error due to Inactivity\"\n}]\n} \"\\\n--user \"username\":\"password\"\n```\n\nThis endpoint only returns an HTTP status code on success and an HTTP status code and error message on failure.\n\n```\nNone\n```\n\n"}}