Backend REST API V1

As a precondition, A static version of the latest API documentation can be found here. When the runtime is installed, an API manifest is also available.

The main entry point for the API is /api/v1/. The resource at this URL provides information about the Runtime

It also shows information on other available endpoints: 

{
    "name": "Runtime",
    "productionMode": true,
    "version": "9.6.0.0",
    "links":
    [
        {
            "rel": "self",
            "href": "http://localhost/runtime/api/v1/"
        },
        {
            "rel": "caseEvents",
            "href": "http://localhost/runtime/api/v1/caseEvents"
        },
        {
            "rel": "cases",
            "href": "http://localhost/runtime/api/v1/cases"
        },
        {
            "rel": "endpoints",
            "href": "http://localhost/runtime/api/v1/endpoints"
        },
        {
            "rel": "projects",
            "href": "http://localhost/runtime/api/v1/projects"
        },
        {
            "rel": "shortcuts",
            "href": "http://localhost/runtime/api/v1/shortcuts"
        },
        {
            "rel": "tasks",
            "href": "http://localhost/runtime/api/v1/tasks"
        }
    ]
}

To be able to specify the runtime name, a property has to be set in the main properties file. For java the property blueriq.runtime.name=<name> has to be set.

Configuration endpoints

Endpoints

The endpoints GET /api/v1/endpoints and GET /api/v1/endpoints/{id} returns the configured endpoints, such as stated in the properties file. An endpoint consists of a name and the URL of the web service.

Shortcuts

The endpoints GET /api/v1/shortcuts and GET /api/v1/shortcuts/{id} retrieves the configured shortcuts in the properties file. A shortcut is a URL with which a project can be directly started without the runtime dashboard. Note that this functionality is only available in Java.

Projects

The endpoint GET /api/v1/projects and GET /api/v1/projects/{id} renders the available projects on runtime. It also exposes exports from the exports folder. There is also a GET /api/v1/projects/{id}/metadata endpoint which retrieves the metadata of a project. The metadata of a project shows which libraries are used and which web service calls there are. A web service call object contains three parameters: endpoint, name, type. The type of web service call can be either SOAP (soap) or REST (http). The name is the web service name in studio. If the endpoint is configured the name and the endpoint have the same value. In case the name is entered and the endpoint is empty means that there is a service defined in studio, but not configured.

HATEOAS

The Runtime REST API uses the Hypermedia as the Engine of Application State (HATEOAS) principle. The main entry point is the only URL that REST clients need to know beforehand. All other endpoints provided by the API can be discovered using the resource links in the resource representations returned by the server.

Authentication in the Runtime REST API

The REST API uses Basic authentication to access its endpoints. Each request should include an Authorization  header with a Basic  token.

GET http://localhost/runtime/api/v1/cases HTTP/1.1
Authorization: Basic cmVzdGFwcDoxMjM=
Host: localhost

"Authorization: Basic " + base64("username:password")

Authorization in the Runtime REST API

The credentials of the REST client are configured in properties file in the Java Runtime.

#format: USERNAME=PASSWORD,ROLE1,ROLE2

Since the Backend REST API relies on the in-memory users, make sure the in-memory authentication provider is added to the authentication-chain. For more information, check Runtime authentication. If another provider is used for Runtime Flow Authentication, set this in-memory provider as last in the chain. Also make sure that the configured users are limited by their roles to only provide the actions necessary on the Backend REST API.

#format: blueriq.permission.ROLE1=PERMISSION1,PERMISSION2
#format: blueriq.permission.ROLE2=PERMISSION1,PERMISSION3 

There is a predefined set of permissions:

Permission	Case Events		Cases	Projects	Shortcuts	Tasks		Endpoints
Method	GET	POST	GET	GET	GET	GET	PUT	GET
ALL_ALL
ALL_READ
ALL_CREATE
ALL_UPDATE
CASE_EVENTS_ALL
CASE_EVENTS_READ
CASE_EVENTS_CREATE
CASES_ALL
CASES_READ
PROJECTS_ALL
PROJECTS_READ
SHORTCUTS_ALL
SHORTCUTS_READ
TASKS_ALL
TASKS_READ
TASKS_UPDATE
ENDPOINTS_ALL
ENDPOINTS_READ

All actions that are of type POST or PUT are traced in the Traceability data store.

Paging and Sorting Results

All endpoints which return resource lists return a PagedObject containing the requested resources. A PagedObject represents a paged view of a list of resources and apart from the resources themselves, it contains information about the current page, the page size, the total amount of pages and the total amount of items. In order to ease navigation between pages, a PagedObject also contains links to the first, previous, next and last page. The page number and page size can be controller with the optional request parameters page and pageSize. If these parameters are not specified, the first page is returned using a default page size.

All endpoints which return lists also support sorting by one or more properties of the requested resources. In order to control sorting, the sort parameter may be used. The value of this parameter should be a comma-separated list of property names to sort by (without spaces around the comma). In order to control the sorting direction, the suffix +asc or +desc may be appended to property names. Both sorting itself and sort direction are optional. If sorting is not specified, the resources are returned in an unspecified order. If sort direction for a property is not specified, the resources are sorted ascending by that property.

The following table lists a few examples:

Filtering Cases and Tasks

The /cases and /tasks endpoints also support filtering by one ore more properties of the returned resources. The general form of a filtering parameter is propertyName=operator:value, where propertyName is the name of a property, operator is one of the supported operators and value is the value to filter by.

GET http://localhost/runtime/api/v1/tasks?status=eq:completed HTTP/1.1
Host: localhost
Authentication: Bearer d1b5ceb6-7cb1-472f-816e-f9dbe1791a5a
Connection: closed
 
 
HTTP/1.1 200 OK
Content-Type: application/json
 
{
	"items":
	[
		{
			"name": "Event: UpdateAutomaticTask",
			"status": "completed",
			"assignee": null,
			"required": false,
			"executedBy": null,
			"priority": null,
			"startDate": null,
			"attributes":
			{
				"Case.Name": "a"
			},
			"customFields":
			{
			},
			"caseId": 85,
			"conditional": false,
			"dueDate": null,
			"eventName": "UpdateAutomaticTask",
			"lastPriorityCheck": null,
			"timeOutDate": null,
			"type": "event",
			"links":
			[
				{
					"rel": "self",
					"href": "http://localhost/runtime/api/v1/tasks/116"
				}
			],
			"id": 116
		},
		{
			"name": "Event: UpdateDoubleTimer",
			"status": "completed",
			"assignee": null,
			"required": false,
			"executedBy": null,
			"priority": null,
			"startDate": null,
			"attributes":
			{
				"Case.Name": "c"
			},
			"customFields":
			{
			},
			"caseId": 86,
			"conditional": false,
			"dueDate": null,
			"eventName": "UpdateDoubleTimer",
			"lastPriorityCheck": null,
			"timeOutDate": null,
			"type": "event",
			"links":
			[
				{
					"rel": "self",
					"href": "http://localhost/runtime/api/v1/tasks/121"
				}
			],
			"id": 121
		}
	],
	"page": 1,
	"pageSize": 50,
	"nrOfPages": 1,
	"itemsTotalCount": 2,
	"links":
	[
		{
			"rel": "self",
			"href": "http://localhost/runtime/api/v1/tasks?page=1&pageSize=50&status=eq:completed"
		},
		{
			"rel": "first",
			"href": "http://localhost/runtime/api/v1/tasks?page=1&pageSize=50&status=eq:completed"
		},
		{
			"rel": "prev",
			"href": "http://localhost/runtime/api/v1/tasks?page=1&pageSize=50&status=eq:completed"
		},
		{
			"rel": "next",
			"href": "http://localhost/runtime/api/v1/tasks?page=1&pageSize=50&status=eq:completed"
		},
		{
			"rel": "last",
			"href": "http://localhost/runtime/api/v1/tasks?page=1&pageSize=50&status=eq:completed"
		}
	]
}

The list of supported operators is summarized in the following table:

Extra query arguments

Extra information can be queried using extra query parameters. When an endpoint is called, the extra query parameters will be returned as one of the possibilities. For example the endpoint "api/v1/tasks" could return one of the links:

http://[host]:[port]/[runtime_name]/api/v1/tasks{?attributes,customFields}

In the tasks endpoint there are two extra query parameters possible (attributes and customFields. The notation of adding this information to the results, is the query parameter with the possible values (comma separated). For example:

http://[host]:[port]/[runtime_name]/api/v1/tasks?customFields=optional_task,custom_priority&attributes=testattribute_x

When all values of the query parameter is needed, the * notation can be used:

http://[host]:[port]/[runtime_name]/api/v1/tasks?customFields=*

In the current implementation, it is possible to add information to the result, but it is not possible to filter on these attributes.

Reopening Tasks

The PUT /api/v1/tasks/{taskId} endpoint allows changing the status of a started task back to open. The body of the request must contain the task resource that should be reopened. Its id property must match the taskId parameter in the endpoint, and its status must be open. The task referenced by the taskId parameter must exist in the database, must be of type task and must have status started. In the current version, all other properties of the task resource are ignored.

If the operation completes sucessfully, the status of the task is changed to open. If the task is automatic, it will also be executed. The endpoint may respond in one of two ways, depending on the outcome:

• if the task is an automatic task, and the execution of the automatic task resulted in the case being completed, the endpoint responds with status 204 No Content and an empty response
• otherwise, the endpoint responds with status 200 OK and the response will contain the updated task resource

Retriggering Case Events

In version 9.6 the concept of a case event was introduced. A case event represents an incoming message or an elapsed timer, therefore case events may be of two distinct types: message and timer. Case events of type message have 2 subtypes, broadcast and unicast, depending on whether the message was broadcast to all cases or to a specific set of cases. Broadcast case events have a null caseId property, while unicast case events have a non-null caseId property. Each event is associated with a task that triggered it through its taskId property.

In order to retrigger a case event the POST /api/v1/caseEvents/{eventId} endpoint may be used. The endpoint creates a new copy of the event referenced by the eventId parameter and delivers it to the process engine. The process engine will start the process flow from the task referenced by the event.

Timer events are always unicast events. Retriggering a timer event will affect only the case in which the original event was triggered. The process flow will continue from the referenced timer node as if the delay on that node had just expired.

Message events may be broadcast message events or unicast message events. The endpoint allows specifying in which case or cases the message event should be re-triggered using the caseId parameter. The process flow will continue from the referenced incoming message node as if a new message had just been received.

When retriggering an event is successful, the endpoint will respond with status 201 Created, and will contain a Location header with the URL where the details of the newly created case event may be obtained.

Migration API

After upgrading from a version lower than 9.9, the following two tables are created in the database: cases_displaynames and tasks_displaynames. The purpose of these tables is to store evaluated display names with potential TSL expressions. These display names are used when expanding AQ_CaseList and AQ_WorkList containers. 

An Runtime REST API endpoint is available for filling these tables with display names for cases and tasks that were already saved before Release 9.9. The endpoint reads cases and tasks from the database, evaluates the display name for each case and task based on the corresponding model (from the Studio) and inserts the display name values in the new tables. General authentication and authorization rules for the Runtime REST API apply to this endpoint as well. The cases get migrated in batches of 1,000. You can keep track of the progress by using count statements on the display names table in the database.

 PUT http://[host]:[port]/[runtime_name]/api/v1/displayNames/

Preconditions

1. Run upgrade scripts;
2. The Studio models used when the cases/tasks were initially created have to be available in the aquima home exports (or via studio connection);
3. The user that calls the migration endpoint needs to have a role with one of the following permissions: ALL_ALL or MIGRATION_MANAGER for Java
4. The recommended heap maximum size that has to be set as VM argument when staring the application server (tomcat, jboss, etc) is 1024m (-Xmx1024m);
5. Even though the job triggered by the rest call does not depend on the client connection, we advise to not close the client, in order to see the response feedback of the operations in the end;
6. We also advise to adjust the database table space (Oracle) size depending on the number of cases and tasks that have to be updated; A row will be inserted for each case+language and task+language combination.
7. It is also recommended that the load on the runtime is low or absent during the migration process;
8. Any foreground operation will be blocked while the migration is still running.
9. This API was designed to be executed just once !

Preconditions

1. migrate-displaynames-endpoint.enabled=true property has to be added in aquima.properties, otherwise the endpoint won't be enabled and the request will return 404 as response;
2. hibernate.cache.use_second_level_cache=false has to be present in the processdao.hibernate.properties; This line can be removed after the operation is done;
3. The REST API oauth2.client-id and oauth2.secret have to be defined in aquima.properties;
4. We recommend the using of the Swagger UI exposed by the Blueriq Runtime in order to speed up the process of token generation and also to see some details about the exposed endpoint (http://{host}:{port}/{runtime}/docs/index.html)

Usage

1. Access http://{server}:{port}/{runtime}/docs/index.html 
2. Fill the user and the password in order to obtain authentication token. (If a pop up appears that request username and password please add oauth2.client as username and oauth2.secret as password (these properties have to be previously defined in aquima.properties)
3. Expand the display names endpoint
4. Try it out !
5. If everything works, an 200 OK response is received, otherwise an error message with the root cause is displayed.

Error Messages

When an operation fails, the endpoints respond with a status code and a JSON error object detailing the encountered error. The following table summarizes the possible error messages:

Using the REST API combined with a reverse proxy server

When there is a reverse proxy server between the client and the application server (for example Tomcat) serving the REST API, additional configuration is required. The reverse proxy server (for example Microsoft IIS) needs to add HTTP headers to the API requests being forwarded to the application server. The header 'X-Forwarded-Host' should be filled with the host name of the application server. The header 'X-Forwarded-Proto' should be filled with the protocol (for example 'https') the client used to connect to the reverse proxy.

API Manifest

The Blueriq Runtime also includes an API manifest which is structured according OAS3. On editor.swagger.io you can import our API manifest to get an interactive documentation page of the Backend RestAPI V1.

http://<server>:<port>/Runtime/api/v1/docs