You are viewing the documentation for Blueriq 15. Documentation for other versions is available in our documentation directory.

Introduction

The Blueriq Runtime provides a REST API for the following operations

  • listing cases and obtaining the details of a specific case
  • listing tasks and obtaining the details of a specific task
  • reopening a started task
  • listing case events and obtaining the details of a specific case event
  • retriggering a case event
  • listing configured SOAP and HTTP endpoints and obtaining the details of a specific endpoint
  • listing projects and obtaining the details of a specific project
  • listing shortcuts and obtaining the details of a specific shortcut

It is recommended to not expose these backend endpoints via the load balancer/firewall to the public and thereby only make them accessible from inside the network.

On this page:

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

In the examples provided in this documentation, it is assumed the Runtime is installed at the following URL: http://localhost/runtime 


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

ParameterTypeDescription
namestringThe name of the runtime. This has to be configured.
productionModebooleanWhether the addressed runtime runs in production mode.
versionstringThe runtime version.


It also shows information on other available endpoints: 

The Runtime Resource
{
    "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.

configuration

The /api/v1/endpoints returns a list endpoints based on the configurable property blueriq.connection.names. If this property is not configured the REST API will return an empty list of endpoints

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.

Example Request with authentication token
GET http://localhost/runtime/api/v1/cases HTTP/1.1
Authorization: Basic cmVzdGFwcDoxMjM=
Host: localhost

Building the Basic authorization header

A basic authentication header is encoded as follows:


"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.

users.properties
#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.

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


There is a predefined set of permissions:

PermissionCase EventsCasesProjectsShortcutsTasksEndpoints
MethodGETPOSTGETGETGETGETPUTGET
ALL_ALL(tick)(tick)(tick)(tick)(tick)(tick)(tick)(tick)
ALL_READ(tick)
(tick)(tick)(tick)(tick)
(tick)
ALL_CREATE
(tick)





ALL_UPDATE





(tick)
CASE_EVENTS_ALL(tick)(tick)





CASE_EVENTS_READ(tick)






CASE_EVENTS_CREATE
(tick)





CASES_ALL

(tick)




CASES_READ

(tick)




PROJECTS_ALL


(tick)



PROJECTS_READ


(tick)



SHORTCUTS_ALL



(tick)


SHORTCUTS_READ



(tick)


TASKS_ALL




(tick)(tick)
TASKS_READ




(tick)

TASKS_UPDATE





(tick)
ENDPOINTS_ALL






(tick)
ENDPOINTS_READ






(tick)

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:

API CallSorting behaviour
/api/v1/tasksThe tasks are not sorted.
/api/v1/tasks?sort=nameThe tasks are sorted by name ascending.
/api/v1/tasks?sort=name+ascThe tasks are sorted by name ascending.
/api/v1/tasks?sort=name+descThe tasks are sorted by name descending.
/api/v1/tasks?sort=name,statusThe tasks are sorted by name ascending. Tasks with the same name are sorted by status ascending.
/api/v1/tasks?sort=name+desc,statusThe tasks are sorted by name descending. Tasks with the same name are sorted by status ascending.

Please note that the + character is in fact a url-encoded space character. The REST client that is being used may already url-encode parameter values. When such clients are being used, please use a space character instead of + in order to specify the sort direction.


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.


Filtering tasks by status
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:

OperatorEquivalentDescription
EQ=Equals
NOT!=Not Equals
GT>Greater Than
GTE>=Greater Than or Equals
LT<Less Than
LTE<=Less Than or Equals
LIKESQL likethe equivalent of the SQL property LIKE '%value%'
INSQL inthe equivalent of the SQL property IN ('value1', 'vaue2')

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.


Case Event TypecaseId parameterEndpoint behaviour
timerN/AThe new timer event is retriggered in the case where the original timer event occurred. The caseId parameter, if specified, must match the original case id.
unicast messagenot specifiedThe new incoming message is delivered to the same case as the original incoming message
unicast messagespecifiedThe new incoming message is delivered to the case specified by the caseId parameter.
broadcast messagenot specifiedThe new incoming message is delivered to all cases.
broadcast messagespecifiedThe new incoming message is delivered to the case specified by the caseId parameter (even though the original incoming message had been delivered to all cases)


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.

The endpoint uses an algorithm to determine the corresponding model that is used to evaluate the display name for each case and task.

The algorithm uses the application id of the case, the application id of the exports (or studio models) and the Control applicationId behavior in the aquima.properties as parameters.


The application id of a case is stored in the CASES table in database and consist of a project and a version. The application id of a export consist also of a project and a version.


The algorithm works as follows:

IF ( EXIST case.applicationid.project = export.applicationid.project AND case.applicationid.version = export.applicationid.version )

THEN migrate case with export-[case.applicationid.project]:[case.applicationid.version]

ELSEIF ( EXIST case.applicationid.project = export.applicationid.project AND ( export.appidignoremode = version OR export.appidignoremode = all))

THEN migrate case with export-[case.applicationid.project]:[existing version]

ELSEIF ( export.appidignoremode = project AND case.applicationid.version = export.applicationid.version )

THEN migrate case with export-[existing project]:[case.applicationid.version]

ELSEIF ( export.appidignoremode = all )

THEN migrate case with export-[existing project]:[existing version]

ELSE error in log

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

When starting the migration, check the runtime log file. This is to verify that the service is running correctly and the migration is running smoothly.

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:

Status CodeStatus MessageError Description
400Bad RequestThe endpoints respond with this error when the request parameters are invalid, for example missing required parameters, invalid date formats.
401UnauthorizedThe endpoints respond with this error when the OAuth token is missing, invalid or expired. The error message describes which of these conditions has occurred.
404Not FoundThe endpoints respond with this error when a referenced resource is not found. The resource may be referenced directly through an id parameter, or indirectly through a property of a resource (for example, when the caseId property of a task resource references a nonexistent case)
500Internal Server ErrorThe endpoints respond with this error when an unexpected error occurs. For security reasons, the error message will not offer any details about the error. To obtain the error details and stack trace, please consult the logs.


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