EasyRPA Control Server supports API calls to allow other systems/clients to launch/execute some actions within EasyRPA.

API specification

Control Server API specification is always available in the Swagger JSON format at the following endpoint: https://<CS_ADDRESS>/v3/api-docs/cs-api. Feel free to use Swagger UI tool of your choice to learn the API.

Swagger UI

Swagger UI with the API specification comes preinstalled. In a browser open https://<CS_ADDRESS>/swagger-ui/index.html URL to reach the UI.

There you will be able not only see the API documentation but also play with it using 'Try it out' feature.

For some of API methods you would need to authorize first - for that press Authorize button (top right corner of the page) or Lock button (Lock icon on the line's right ) then submit Swagger client authorization form with the client_id=SWAGGER and client_secret=secret.

You will be redirected to the standard Easy RPA Authentification UI - fill in user name and password of own user and submit.

API Client Authentication

Control Server API supports only Client Credentials server-to-server flow. In that flow external client has to be registered and is to be authenticated by so-called 'client secret', other authentication methods are not supported. Good news is - with every registered Developer or Admin user comes auto-generated client with the client_id matching user name. The only thing needed to start using such client is client secret.

Client Secret

Client secret is a permanent client authentication token that further gives you access to a temporary session token.

Ensure that your client secret is kept in a secure place and is not shared with anyone.

Getting Client Secret with Control Server UI

Depending on your role you can either request you own Client Secret (Developer Role) or Client Secret for other applicable user (Administrator Role).

Getting Own Client Secret with Control Server UI

For the own Client Secret go to the user profile menu and choose API Secret option

That will open popup with the actual Client Secret for own use. The REGENERATE button will invalidate actual secret and create new one.

Getting a User Client Secret with Control Server UI

For administrators there is option to request Client Secret for any user. That option is available in the User Management UI

Once clicked API SECRET button will bring same popup as above but Client Secret inside is belonging to selected user.

Session token

Once you know your client's secret, you can then get temporary session access token to be used for API calls.

Make POST call to /authrpa/oauth2/token with the following parameters:

grant_type = client_credentials

client_id = <user_name>

client_secret = <client_secret>

scope = rpaplatform

And you will receive session Access Token:

Session token has limited life time (see returned "expires_in" property). Token has to be re-issued once expired using same procedure above.

Calling API methods with Session Token

Once you got access token – you can make API calls using Bearer Token authentication:

Example

Let's consider most typical scenario where some client needs to run an Automation Process and then check the run status.

First call would be POST to the endpoint /api/v1/automation_processes/<PROCESS_ID>/runs

curl -k -H 'accept: */*' -H 'authorization: Bearer <SESSION_TOKEN>' -X POST -d '' 'https://<CS_ADDRESS>/api/v1/automation_processes/<PROCESS_ID>/runs'

In the response body there should be JSON structure returned, describing run instance:

Run Instance JSON

{
	"id": 1033,
	"updateTimeStamp": "2022-09-13T17:11:04.700284+03:00",
	"createTimeStamp": "2022-09-13T17:11:04.552115+03:00",
	"createdBy": {
		"id": 1,
		"firstName": "System",
		"lastName": "Admin",
		"fullName": "System Admin"
	},
	"updatedBy": {
		"id": 1,
		"firstName": "System",
		"lastName": "Admin",
		"fullName": "System Admin"
	},
	"uuid": "76611dec-64cf-4232-ba33-f3205485fc26",
	"automationProcess": {
		"id": 2600,
		"updateTimeStamp": "2022-09-05T10:06:11.34993+03:00",
		"createTimeStamp": "2022-09-05T09:15:24.444415+03:00",
		"createdBy": {
			"id": 1,
			"firstName": "System",
			"lastName": "Admin",
			"fullName": "System Admin"
		},
		"updatedBy": {
			"id": 1,
			"firstName": "System",
			"lastName": "Admin",
			"fullName": "System Admin"
		},
		"uuid": "6f09b0b6-e0bc-4476-add5-968f668ee91c",
		"name": "Invoice Plane Automation Demo",
		"description": "Browser Driver Demo",
		"repositoryId": "eu.ibagroup.samples.ap:easy-rpa-invoiceplane-ap:jar:2.5.0",
		"moduleClass": "eu.ibagroup.easyrpa.ap.productsreader.ProductsReaderAp",
		"dedicated": true,
		"statistic": {},
		"capabilities": [],
		"dedicatedNodes": [
			"NODE 2"
		],
		"params": [],
		"groups": [
			{
				"id": 1,
				"name": "Administrators"
			}
		]
	},
	"status": "QUEUED",
	"numberOfTasks": 0,
	"runUuid": "76611dec-64cf-4232-ba33-f3205485fc26",
	"apUuid": "6f09b0b6-e0bc-4476-add5-968f668ee91c"
}

As we can see from the response new Process Run Instance was created and queued with the id 1033. In a couple of seconds lets check the status of the Process Run by issuing another GET request to the /api/v1/runs/<PROCESS_RUN_INSTANCE_ID> endpoint.

curl -k -H 'accept: */*' -H 'authorization: Bearer <SESSION_TOKEN>' 'https://<CS_ADDRESS>/api/v1/runs/1033'

This time we get similar JSON structure with the actual status - FAILED.

Run Instance JSON

{
	"id": 1033,
	"updateTimeStamp": "2022-09-13T17:11:05.668921+03:00",
	"createTimeStamp": "2022-09-13T17:11:04.552115+03:00",
	"createdBy": {
		"id": 1,
		"firstName": "System",
		"lastName": "Admin",
		"fullName": "System Admin"
	},
	"updatedBy": {
		"id": 3,
		"firstName": "System",
		"lastName": "Queue",
		"fullName": "System Queue"
	},
	"uuid": "76611dec-64cf-4232-ba33-f3205485fc26",
	"automationProcess": {
		"id": 2600,
		"updateTimeStamp": "2022-09-05T10:06:11.34993+03:00",
		"createTimeStamp": "2022-09-05T09:15:24.444415+03:00",
		"createdBy": {
			"id": 1,
			"firstName": "System",
			"lastName": "Admin",
			"fullName": "System Admin"
		},
		"updatedBy": {
			"id": 1,
			"firstName": "System",
			"lastName": "Admin",
			"fullName": "System Admin"
		},
		"uuid": "6f09b0b6-e0bc-4476-add5-968f668ee91c",
		"name": "Invoice Plane Automation Demo",
		"description": "Browser Driver Demo",
		"repositoryId": "eu.ibagroup.samples.ap:easy-rpa-invoiceplane-ap:jar:2.5.0",
		"moduleClass": "eu.ibagroup.easyrpa.ap.productsreader.ProductsReaderAp",
		"dedicated": true,
		"statistic": {},
		"capabilities": [],
		"dedicatedNodes": [
			"NODE 2"
		],
		"params": [],
		"groups": [
			{
				"id": 1,
				"name": "Administrators"
			}
		]
	},
	"status": "FAILED",
	"numberOfTasks": 0,
	"runUuid": "76611dec-64cf-4232-ba33-f3205485fc26",
	"apUuid": "6f09b0b6-e0bc-4476-add5-968f668ee91c",
	"_permissions": [
		"CREATE",
		"DELETE",
		"UPDATE",
		"ACTION",
		"READ"
	]
}