You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
The Blueriq web application is equipped with a REST API to expose methods to allow clients to control the flowing of the application. This page gives a description about the available services. For all of the below endpoints, an Accept header of application/json must be present in the request.
Authentication
Login user
POST /api/v2/login
Description
Log the user in with the provided credentials
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| username | string | Username of the user to login. |
| password | string | Password of the user to login. |
Response
204 No Content, if successful.
401 Unauthorized, if unsuccessful.
Logout user
POST /api/v2/logout
Description
Logout the current user and close all Blueriq sessions
Response
204 No Content
Starting a Blueriq session
Start Shortcut
POST /api/v2/start/{shortcutName?}
Description
Starts a session by specifying the name of a shortcut.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| shortcutName | string | The shortcut name, leave empty to start the default shortcut |
Example response
{
"sessionId": "2f177274-514d-4be9-aa3d-4a550ab9e724",
"sessionTimeout": 1800
}
Start Project
POST /api/v2/start?project=export-kinderbijslag&flow=Main
Description
Starts a session with project parameters. This endpoint may be disabled in production for security reasons, so using shortcuts is preferred.
Parameters
| Query parameter | Expected Type | Description | Required |
|---|---|---|---|
| project | string | The project to start | Yes |
flow | string | The flow to start | Only required if more than one exposed flow is present in the project |
| version | string | The branch version | No |
| languageCode | string | The project language | No |
| ui | string | The UI variant to use, by default only mvc and xslt is supported | No |
| theme | string | The project theme | No |
| channel | string | the project channel | No |
Example response
{
"sessionId": "2f177274-514d-4be9-aa3d-4a550ab9e724",
"sessionTimeout": 1800
}
Interacting with a session
In Blueriq, each session is part of (usually) one subscription in order to allow receiving changes from multiple Blueriq sessions simultaneously. After having started a session using one of the /api/v2/start endpoints, its initial page contents may be obtained via a POST to /api/v2/session/{sessionId}/load. The result of this call is the full page model, necessary for initial rendering of the page. Subsequently, events may be submitted to the runtime via a POST to /api/v2/session/{sessionId}/event, resulting in a response containing all changes (add, update, delete) for each session that is attached to the subscription. An example response containing the changes:
Change Events
{"events":[
{"sessionId":"27390ee2-4968-4f27-ae71-3d6516ba06ec",
"changes": {
"changes":[
{"type":"add",
"key":"P521-C0-F1",
"model":{
"key":"P521-C0-F1",
"name":"e.a2",
"properties":{},
"questionText":"q2",
"explainText":null,
"dataType":"boolean",
"rejectedValue":null,
"readonly":false,
"required":false,
"hasDomain":false,
"multiValued":false,
"refresh":false,
"displayLength":-1,
"domain":[],
"messages":[],
"values":[],
"type":"field",
"styles":[]
}
}
]
}
]}
In this example a field is added to the page. The available properties per element are listed in the REST Page Models.
Serialization
The serialization of page element to datamodel is handled by the IApiRendererFactory, this renderer factory can be overridden to customize the serialization. In Java by use of the AquimaApiRendererFactory annotation, in .NET in your plugin by registering your custom renderer factory to the plugin context.
Load session information
After a session has been created using /api/v2/start, the current state of the session can be obtained through:
POST /api/v2/session/{sessionId}/load
Description
Loads the information of the provided session and registers the session with the specified subscriptionId.
Example response
{
"elements": [
{
"key": "P381-C1",
"name": "Single",
"properties": {
},
"children": [
"P381-C1-F0",
"P381-C1-F1",
"P381-C1-F7"
],
"displayName": "Single Items",
"contentStyle": "container",
"type": "container",
"styles": [
]
}
],
"language": {
"patterns": {
"datetime": "yyyy-mm-dd hh:mm:ss",
"date": "yyyy-mm-dd"
},
"languageCode": "en-GB"
}
}
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The id of the session. |
Response body
Contains a description of the current page model and language settings. For more information about the page elements see REST Page Models.
{
language {
languageCode: string, // Current language of the session
patterns: { [string]: string }, // Formatter patterns for dates
}, // Language information of the session
elements [{
type: string,
key: string,
name: string,
styles: string[],
properties: { [string]: string },
}] // All elements of the currently active Blueriq page. Further explained under 'REST Page Models'
}
Send user event
POST /api/v2/session/{sessionId}/event
Description
Handles a page event and returns the events that occurred in any of the sessions in the subscription.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id. |
Request body
At least the element that triggered the event and all editable fields on the page must be included in the request.
{
elementKey: string, // Key of the element the event originates from
fields: [{
key: string, // Key of the field
values: string[], // Values of the field, an array even if the field is not multivalued
}], // Data of all fields on the page
parameters: { [string]: string } // Additional parameters that may be passed to the backend
}
Example request
{
"elementKey": "P960-C2-B1",
"fields": [
{
"key": "P960-C1-F0",
"values": [
"testValue"
]
},
{
"key": "P960-C1-F6",
"values": [
"testValue2"
]
}
]
}
Response body
Returns an event response, for more info about an event response see: REST Events.
{
events: { EventResponse }[]
}
Example response
{
"events": [{
"sessionId": "45992123-f893-4b22-a6a3-ff648b63267c",
"changes": {
"changes": [
{
"type": "add",
"key": "P501-C1-B0",
"model": {
"key": "P501-C1-B0",
"name": "Annuleer",
"properties": {
},
"disabled": false,
"refresh": false,
"caption": "Annuleer",
"type": "button",
"styles": [
]
}
},
},
"type": "page"
}]
}
Start flow
POST /api/v2/session/{sessionId}/flow/{flowName}
Description
Starts a flow and returns the events that occurred in any of the sessionsExample response
{
"events": [{
"sessionId": "7c2868f4-4fe9-48b6-841a-cf3e4831750a",
"changes": {
"changes": [{
"type": "delete",
"key": "P977-C1",
"model": null
}]
},
"type": "page"
}]
}
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id. |
| flowName | string | The name of the flow. |
Response body
Returns an event response, for more info about an event response see: REST Events.
Close session
POST /api/v2/session/{sessionId}/close
Description
Closes a session and all its child session.
Parameters
URL Segment | Expected Type | Description |
|---|---|---|
sessionId | string | The sessionId |
Keep alive
POST /api/v2/session/{sessionId}/keepalive
Description
Assures that the session stays alive by refreshing its most recent access date.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id. |
Response
204 No Content
Create widget
POST /api/v2/session/{sessionId}/widget/{infoKey}
Description
provides a service that creates a child-session using the provided sessionId as its parent, to be used for widgets.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id |
| infoKey | string | The info key of the widget to load, available in properties.info of a page mode of type dashboard_flowwidget |
Reponse
The sessionId of the existing or newly created session.
{"sessionId":"a487f65e-6804-4803-bf4b-c89e45f97e38"}
Handling files
Endpoints that go with AQ_File_Upload/AQ_File_Download containers.
Upload file
POST /api/v2/session/{sessionId}/file/{configurationId}/upload
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id. |
| configurationId | string | The configuration id. |
Response body
GET /api/v2/session/{sessionId}/file/{configurationId}/download
Description
Gets the file from the specified connection based on its configuration
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id |
configurationId | string | The property configuration id, available |
Example response
The requested file, transferred using Content-Disposition: attachment.
Check authorization
GET /api/v2/session/{sessionId}/file/{configurationId}/checkauthorization
Description
Check if the user has the authority to download the file.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id |
configurationId | string | The configuration id |
Example response
200 OK, if the current user is authorized to download the file
401 Unauthorized, otherwise
Documents
Use to render a Blueriq document or page. A call to this service returns the binary data of the document or page.
Render a document
GET /api/v2/session/{sessionId}/document/{documentName}/{type}
Description
Renders a document and returns its binary value.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The id of the session. |
| documentName | string | Name of the document. |
| type | string | Type of document (e.g. PDF). |
Response body
Transfers the binary data of a document using Content-Disposition: attachment
Render a page
GET /api/v2/session/{sessionId}/document/page/{pageName}/{type}
Description
Renders a page and returns its binary value.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The id of the session. |
| pageName | string | Name of the page. |
| type | string | Type of page (e.g. PDF). |
Response body
Transfers the binary data of a page using Content-Disposition: attachment
Images
Retrieve an image
GET api/v2/session/{sessionId}/image/{imageName}
Description
Returns the binary data of a named Blueriq image.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The id of the session. |
| imageName | string | The name of the image. |
Response body
Returns the binary data of an image.
Retrieve a QR Code image
GET api/v2/session/{sessionId}/image/{imageName}/key/{key}
Description
Returns the binary data of a named Blueriq QR Code image.
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The id of the session. |
| imageName | string | The name of the image. |
| key | string | the element key. |
Response body
The binary data of an image.
Offline functionality
Prepare offline task
POST api/v2/session/{sessionId}/offline/prepare/{taskId}
Description
Prepares a task to be executed in offline mode
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id. |
| taskId | string | The id of the task to prepare offline mode for |
Response body
A PageModel instance with the page contents started by the task. For more information about the page contents (elements) see: REST Page Models.
Inference details
The DMN service is part of the development plugin and can be used to get inference details for attribute instances
Get Decision Tree
GET /api/v2/session/{sessionId}/dmn/{entityName}/{instanceId}/{attributeName}
Description
Gets a decision tree model for the specified attribute instance
Parameters
| URL Segment | Expected Type | Description |
|---|---|---|
| sessionId | string | The session id to create an event response for |
| entityName | string | Entity name for the attribute for which the decision tree is requested |
| instanceId | string | Instance id for the attribute for which the decision tree is requested |
| attributeName | string | Name of the attribute for which the decision tree is requested |
Example response
A decision tree for DMN starts with a rootNode and it is possible that there are 0 or more usedDecisions. A used decision describes an attribute that is used to derive the parent attribute.
{
"rootNode": {
"ruleName": "DMNEntity.DataRuleEndResult",
"justification": null,
"usedDecisions": [
{
"ruleName": "DataRuleForPage",
"justification": null,
"usedDecisions": [],
"entityName": "DMNEntity",
"attributeName": "DataRule",
"attributeValues": [
"44"
],
"sourceType": "System",
"defaultRuleType": null,
"instanceId": "40c05cc5-8ddf-48a3-8d5d-53228ca7305c"
}
],
"entityName": "DMNEntity",
"attributeName": "DataRuleEndResult",
"attributeValues": [
"1342"
],
"sourceType": "Default",
"defaultRuleType": "expression",
"instanceId": "40c05cc5-8ddf-48a3-8d5d-53228ca7305c"
}
}
Standard response codes
All services return a 200 response code on successful requests and a 500 response code if an error occurs. For more information about errors see REST Errors.
Overview
Content Tools