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.robocloud.eu/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 toapplication/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.robocloud.eu/workspace-v1/workspaces/{workspaceId}/processes/{processId}/runs/{processRunId}
..and you get the response:
{
"id": "9f8ea...",
"result": "OK",
"state": "COMPL",
"errorCode": "",
"duration": 9,
"workspaceId": "..."
}