You are viewing the documentation for Blueriq 16. Documentation for other versions is available in our documentation directory.
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.
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
Parameter | Type | Description |
---|---|---|
name | string | The name of the runtime. This has to be configured. |
productionMode | boolean | Whether the addressed runtime runs in production mode. |
version | string | The runtime version. |
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.
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.
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.
#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:
API Call | Sorting behaviour |
---|---|
/api/v1/tasks | The tasks are not sorted. |
/api/v1/tasks?sort=name | The tasks are sorted by name ascending. |
/api/v1/tasks?sort=name+asc | The tasks are sorted by name ascending. |
/api/v1/tasks?sort=name+desc | The tasks are sorted by name descending. |
/api/v1/tasks?sort=name,status | The tasks are sorted by name ascending. Tasks with the same name are sorted by status ascending. |
/api/v1/tasks?sort=name+desc,status | The 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.
The list of supported operators is summarized in the following table:
Operator | Equivalent | Description |
---|---|---|
EQ | = | Equals |
NOT | != | Not Equals |
GT | > | Greater Than |
GTE | >= | Greater Than or Equals |
LT | < | Less Than |
LTE | <= | Less Than or Equals |
LIKE | SQL like | the equivalent of the SQL property LIKE '%value%' |
IN | SQL in | the 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 Type | caseId parameter | Endpoint behaviour |
---|---|---|
timer | N/A | The 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 message | not specified | The new incoming message is delivered to the same case as the original incoming message |
unicast message | specified | The new incoming message is delivered to the case specified by the caseId parameter. |
broadcast message | not specified | The new incoming message is delivered to all cases. |
broadcast message | specified | The 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.
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
- Run upgrade scripts;
- The Studio models used when the cases/tasks were initially created have to be available in the aquima home exports (or via studio connection);
- 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
- The recommended heap maximum size that has to be set as VM argument when staring the application server (tomcat, jboss, etc) is 1024m (-Xmx1024m);
- 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;
- 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.
- It is also recommended that the load on the runtime is low or absent during the migration process;
- Any foreground operation will be blocked while the migration is still running.
- This API was designed to be executed just once !
Preconditions
- 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;
- 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;
- The REST API oauth2.client-id and oauth2.secret have to be defined in aquima.properties;
- 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
- Access http://{server}:{port}/{runtime}/docs/index.html
- 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)
- Expand the display names endpoint
- Try it out !
- 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 Code | Status Message | Error Description |
---|---|---|
400 | Bad Request | The endpoints respond with this error when the request parameters are invalid, for example missing required parameters, invalid date formats. |
401 | Unauthorized | The endpoints respond with this error when the OAuth token is missing, invalid or expired. The error message describes which of these conditions has occurred. |
404 | Not Found | The 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) |
500 | Internal Server Error | The 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
1 Comment
Unknown User (b.de.keulenaar)
When calling the backend API from a Blueriq application, a space has to be used instead of a + when sorting the API result (between the sort attribute and the sort method desc or asc)