Triggering processes in Robocorp Cloud via the Process API

The process API is being deprecated in favor of the new workspace-scoped API features of Robocorp Cloud.

In addition to scheduling and running processes manually in Robocorp Cloud, the Robocorp Cloud Process API allows you to trigger them using a simple API call.

Activating the process API access for a process

You need to activate the Process API access for each process you want to be able to trigger remotely.

To do so, navigate to the process page in Robocorp Cloud, and click on the edit button in the Process API access section:

Click on the Generate secret button in the popup that will appear:

Now your access secret has been created, and you can access the Process API Access information:

You can use the buttons to delete the secret (this will disable the API access for this process), or to generate a new secret.

If you close this window, you can open it again later by clicking on the edit button:

Triggering the execution of a process via the API Call

The access secret information screen also provides you with an example command that you can use with curl to trigger the process:

curl
--request POST
--header "robocloud-process-secret: YOURSECRETHERE"
--header "Content-Type: application/json"
--data "{\"workItemKey\":\"workItemValue\"}"
https://api.eu1.robocorp.com/workspace-v1/workspaces/YOUR_WORKSPACE_ID_HERE/processes/YOUR_PROCESS_ID_HERE/runs

• The request method must be POST.
• The process secret must be passed in an header called robocloud-process-secret.
• You can pass additional data to the process by passing a JSON object as the body of the request (in this example command, we are using the --data curl parameter)
• The Content-Type header must be set to application/json
• The URL endpoint is different for each process, since it contains your workspace and process ids.

In case the system you are using does not allow you to set headers on the request, you can pass the secret as part of the URL as a query string parameter. Just append ?robocloud-process-secret=YOURSECRETHERE to the URL. If possible, however, the header method should be preferred for security reasons, since URLs (and their query string parameters) can easily be logged.

On a successful request, your process will be added to the queue for immediate execution, and you will receive a response with status 200:

{
  "message": "OK",
  "processRunId": "9f8ea...",
  "processId": "139bc...",
  "workspaceId": "...",
  "workItemId": "06dcf..."
}

Security considerations

The generated secret can only be used to trigger the execution of the process that it was created for.

Treat the secret with high security, just like any other access credential.

Passing additional data to the process

When triggering a process via the API, you can pass data to it in JSON format as the body of the request. This opens up many possibilities, because it allows you to set any variable for a specific run of your process.

See a practical example of how to pass variables to your robots in this article.

Monitoring a process

After triggering the process via API you can monitor the process run status. The response for the process trigger returns the needed details:

{
  "message": "OK",
  "processRunId": "9f8ea...",
  "processId": "139bc...",
  "workspaceId": "...",
  "workItemId": "06dcf..."
}

You can query the process status:

curl
--request GET
--header "robocloud-process-secret: YOURSECRETHERE"
--header "Content-Type: application/json"
https://api.eu1.robocorp.com/workspace-v1/workspaces/{workspaceId}/processes/{processId}/runs/{processRunId}

..and you get the response:

{
  "id": "9f8ea...",
  "result": "OK",
  "state": "COMPL",
  "errorCode": "",
  "duration": 9,
  "workspaceId": "..."
}