Community blogs are written by members of the SS&C Blue Prism Community and represent the views of the author. For more information on Community Blogs, or to submit your own, see here.
From Blue Prism Enterprise version 7 onwards, Blue Prism provides a RESTful API. Using the Blue Prism API, you can explore different capabilities that can be used by custom solutions to interact with BP programmatically as mentioned in the table below. Capability or end points are being continuously added in newer versions. In terms of architecture, Blue Prism API provides a common interface for Hub and other products to connect with Blue Prism database.
This blog covers the following topics:
- Authenticating, connecting, and getting started with the Blue Prism API
- Executing Blue Prism processes on a resource machine
- Key things to remember
Endpoint count in version 7.3.1 and 7.5.1
The table in the below spoiler compares API endpoint counts in Blue Prism versions 7.3.x and 7.5.x. Light blue highlights indicate endpoints added in version 7.5.x. (Open the below spoiler for the table)
| API End Point Type | 7.3.x API Endpoint Count | 7.5.x API Endpoint Count |
| Session | 7 | 7 |
| Session Logs | 2 | 3 |
| Session Queue Groups | 6 | 6 |
| Work Queue | 6 | 8 |
| Work Queue Item | 7 | 8 |
| Calendar | 10 | 10 |
| Holiday Region | 2 | 2 |
| Process | 2 | 2 |
| Resource | 3 | 3 |
| License | 3 | 3 |
| Schedule Logs | 2 | 2 |
| User | 1 | 1 |
| Time Zone | 1 | 1 |
| Health | 1 | 1 |
| Encryption | 1 | 1 |
| Dashboard | 5 | 5 |
| Env Variable | 5 | 5 |
| Schedule | 18 | 18 |
| Subscriptions | 0 | 1 |
| Total | 82 | 87 |
Authentication & Getting started on Blue Prism API via Swagger
Below are pre-requisites to start with Blue Prism API.
- Swagger UI is the documented method to test the Blue Prism API, and it's included alongside the Blue Prism API install. Swagger UI is disabled by default and must be enabled to use BP API. It is recommended that the Swagger UI is not enabled in Production environments, given it is primarily intended as a tool for testing the API.
- Create a service account in Blue Prism Hub with Blue Prism API permissions to store the client ID and secret. Users provide these credentials to Authentication Server to authenticate their requests. Separate service accounts can be created for different API access levels.
- Service account must have proper permission configured to run Blue Prism API.
- Swagger URL -> https://yourbpapibaseURL.com/swagger/ui/index is the sample swagger URL
where yourbpapibaseURL.com is usually the hostname of Web server where API is installed.
Steps to Authenticate
In Swagger, authenticate using your client ID and client secret or via an API key. Click GET, then select Expand operation or click the endpoint to open it.
Click the red icon on the right, highlighted in yellow below, and enter your credentials.
Choose Request body from type drop down. Feed your client ID, secret or Feed Api key in Value field and click on Authorize.
After clicking Authorize, the red color icon shown in first screenshot will change to blue and you are ready to go-ahead with Blue Prism API.
Please note that by default, all API endpoints return only 10 entries. For example, GET /api/v7/workqueues returns 10 work queues; the same limit applies to other endpoints.
Increase the parameter shown below to retrieve more work queue items. You can do the same for other endpoints.
You can set the count to a maximum of 1000. Higher values return to an error, as shown below.
Another way to retrieve more than 10 entries from the Blue Prism API is to use pagination, as explained below. The API provides a paging token to retrieve the next set of results. Pagination returns data in smaller chunks, or pages, rather than all at once, helping prevent large datasets from overwhelming the server or client.
Execute a process on a resource Machine
Follow these high-level steps to run a Blue Prism process on a resource:
Step 1 - Use the Process endpoint to get the ID of the process you want to run. In the snapshot below, you can see various parameters available which can be used in API calls. I used the processParameters.processName.strtw parameter for this example.
Input Parameters
| End Point URL | Method |
|
https://yourbpapibaseURL.com/api/v7/processes?processParameters.processName.strtw=bpprocess |
GET |
Output Response Body - Find the process ID in the response below:
|
{ "pagingToken": null, "items": [ { "processId": "4dcaa092-17e5-123e-7d14-829513d13e23", ] } } |
Step 2 - Use the resource endpoint to retrieve the ID of the resource on which you want to run the process.
Input Parameters
| End Point URL | Method |
| https://yourbpapibaseURL.com/api/v7/resources?resourceParameters.name.strtw=Resourcename where "Resourcename” is your resource name/ FQDN of your resource |
GET |
Output Response Body - Retrieve the process ID from the response body shown below:
|
{ "pagingToken": null, "items": [ { "id": "6rqav278-3zzb-538e-edf6-we759bd5ac8f", ] } } |
Step 3 - Use the Session endpoint to create a pending process session on the resource.
Input Parameters
| End point URL | Method | Body |
| https://yourbpapibaseURL.com/api/v7/sessions | POST |
{ "resourceId": "00000000-0000-0000-0000-000000000000", "processId": "00000000-0000-0000-0000-000000000000" } |
The response returns the new session ID, as shown below, and a pending session appears in Blue Prism Control Room.
Step 4 - Start the pending session
Input Parameters
| End Point URL | Method | Body |
| https://yourbpapibaseURL.com/api/v7/sessions/SessionID | PATCH |
{ "status": "Running" } |
Response Body – A successful start of process will show like below
Note: Before running the session, you can also check if any other process is running against resource or not.
Key things to remember
- Some Work Queue endpoints require encryption keys as the data within them is encrypted. Two options are available:
- Make server based encryption schemes available to the API, as documented here.
- Modify the work queue to remove encryption before using the Blue Prism API.
- Webhooks related end points are added in version 7.5.
- Capability for calendars, Processes, Pools, schedule Logs, Time zone, user were added in version 7.1.
- There is no end point available as of now to work on Credentials.
- Details for installation of API is detailed out in Blue Prism portal link - Install the Blue Prism API
Share your Story
Please share your feedback and any challenges you’ve encountered while working with the Blue Prism API. Also, let me know what integrations you’ve successfully implemented using the BP API.
