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 an Accept
header of header of application/json
must must be present in the request.
...
Authentication
Login user
Code Block |
---|
|
POST /api/v2/login |
Description
Log Login the user
...
with the provided credentials
...
Request body
URL SegmentExpected TypeDescriptionstring | Username of the user to login. | password | string | Password of the user to login. |
Response
204 No Content, if successful.
401 Unauthorized, if unsuccessful.
: string,
password: string
} |
Code Block |
---|
language | js |
---|
title | Example request |
---|
|
{
"username": "testUser",
"password": "secret"
} |
Info |
---|
Before release 12.10, Blueriq expected the username and password to be in the request parameters of the login request (e.g. http://.../api/v2/login?username=testUser&password=secret). Since release 12.10, the username and password are retrieved from the login request body. For backwards compatibility the login information can still be retrieved from the request parameters as well. The material theme sends the login information in the request body by default from release 12.10. It is possible to configure the theme to still use the legacy request parameter method of logging in, by configuring the backend module in your theme: Code Block |
---|
language | js |
---|
title | app.module.ts |
---|
| V2BackendModule.forRoot({
baseUrl: ....,
legacyLoginWithQueryParams: true,
}), |
|
Response
204 No Content, if successful.
401 Unauthorized, if unsuccessful.
Logout user
Code Block |
---|
|
POST /api/v2/logout |
Parameters
Logout user
Code Block |
---|
|
POST /api/v2/logout |
Description
Logout the current user and close all Blueriq sessions
Response
204 No Content
Starting a Blueriq session
Start Shortcut
Code Block |
---|
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
Code Block |
---|
{
"sessionId": "2f177274-514d-4be9-aa3d-4a550ab9e724",
"sessionTimeout": 1800
} |
Start Project
Code Block |
---|
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 |
---|
projectThe 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 |
URL to redirect to after logout | Conditional (see Response) |
Description
Logout the current user and close all Blueriq sessions
Response
204 No Content
302 Found
- if redirect_uri parameter is present
- the Location header contains the redirect_uri
400 Bad Request
- if the Runtime is configured with OpenID Connect and SSO Logout, and no redirect_uri parameter was received
- if a whitelist is defined for the redirect_uri parameter and the received redirect_uri is not whitelisted
Starting a Blueriq session
Start Shortcut
Code Block |
---|
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
Code Block |
---|
{
"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/v1/start
endpoints, its initial page contents may be obtained via a POST
to /api/v1/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/v1/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:
Code Block |
---|
language | xml |
---|
title | 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.
Info |
---|
|
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. |
Start Project
Code Block |
---|
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 is supported | No |
theme | string | The project theme | No |
channel | string | the project channel | No |
Example response
Code Block |
---|
{
"sessionId": "2f177274-514d-4be9-aa3d-4a550ab9e724",
"sessionTimeout": 1800
} |
Interacting with a session
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). In Blueriq each session may be part of a hierarchy of sessions. For example, in a DCM application, the session of a flow widget is a child session of the main dashboard session. An event in one session may cause changes in other sessions if Portal Messages are thrown. Therefore, the response of /api/v2/session{sessionId}/event
endpoint will contain changes in all sessions in the heirarchy. An example response containing the changes:
Code Block |
---|
language | xml |
---|
title | 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.
Info |
---|
|
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. |
...
After a session has been created using /api/v2/start
, the current state of the session can be obtained through:
TO BE DELETED
Create subscription
In Blueriq, a "subscription" is used for bundling multiple sessions together in order for all their events to be published together, which is useful for DCM application where task widgets have their own session, but participate in the main Blueriq session. A subscription is required even if only a single session is used.
When using one of the /api/v1/start
endpoints, a subscription with id equal to the sessionId has already been created, so usually there is no need to create a subscription manually yourself. It is however possible to create your own subscription through a POST
to /api/v1/subscription/{subscriptionId}/create
, providing the ID of the subscription to be created.
Code Block |
---|
|
POST /api/v1v2/subscriptionsession/{subscriptionIdsessionId}/create |
Description
Creates a subscription to which sessions can subscribe. The specified subscription ID may be chosen freely and will be the identifier of the created subscription.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId | string | The ID of the subscription to create |
Response
204 No Content
After a session has been created using /api/v2/start
, the current state of the session can be obtained through:
Code Block |
---|
|
POST /api/v2/session/{sessionId}/load |
Loads the information of the provided session.
Example response
Code Block |
---|
|
{
"elements": [
{
|
Description
Loads the information of the provided session and registers the session with the specified subscriptionId.
Example response
Code Block |
---|
|
{
"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. |
subscriptionId | string | The subscription id the session is part of. |
Response body
Contains a description of the current page model and language settings. For more information about the page elements see REST Page Models.
Code Block |
---|
|
{
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
Code Block |
---|
|
POST /api/v2/session/{sessionId}/event |
Description
Handles a page event and returns the events that occurred in any of the sessions in the subscriptionheirarchy.
Name | Value |
---|
Content-Type | application/json |
Parameters
URL Segment | Expected Type | Description |
---|
sessionId | string | The session id. | subscriptionId | string | The subscription id the session is part of. |
Request body
At least the element that triggered the event and all editable fields on the page must be included in the request.
Code Block |
---|
|
{
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
} |
Code Block |
---|
language | text |
---|
title | 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.
Code Block |
---|
|
{
events: { EventResponse }[]
} |
Code Block |
---|
language | text |
---|
title | 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
Code Block |
---|
|
POST /api/v2/session/{sessionId}/flow/{flowName} |
Description
Starts a flow and returns the events that occurred in any of the sessions
in the subscriptionhierarchy. When a page is currently active, only flows which have already been visited can be started.Example response
Code Block |
---|
|
{
"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. |
subscriptionIdflowName | string | The subscription id the session is part of. | flowName | string | The name of name of the flow. |
Response body
Returns an event response, for more info about an event response see: REST Events V1.
...
Close session
Code Block |
---|
|
POST /api/v2/session/{sessionId}/close |
Description
Closes a session and all its child session.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionIdsessionId | string | The | subscription id the session is part of. sessionId | string | The sessionId
Response
204 No Content
Keep alive
Code Block |
---|
|
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 |
---|
subscriptionId | string | The subscription id the session is part of. |
sessionId | string | The session id. |
Response
Code Block |
---|
|
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 |
---|
subscriptionIdsessionId | string | The | subscription id the session is part of.session id |
infoKey | sessionId | string | The | session idinfoKey | 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.
Code Block |
---|
|
{"sessionId":"a487f65e-6804-4803-bf4b-c89e45f97e38"} |
Handling files
Endpoints that go with AQ_File_Upload/AQ_File_Download containers.
Starting an external flow consists of multiple calls.
Init
Upload filePOST POST /api/v2/session/{sessionId}/ |
file/{configurationId}/uploadRequestbody
Code Block |
---|
|
{"configurationId":"fd308ecf-bf93-4061-bbc7-7cace2cde764","baseUrl":""} |
Description
provides a service that initializes an external flow starting from your current session.
Parameters
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId | string | The subscription id the session is part of. |
URL Segment | Expected Type | Description |
---|
sessionId | string | The session id |
. configuration id.Response body
Returns an event response, for more info about an event response see: REST Events.
Download a file
info key of the widget to load, available in properties.configurationId of a page model of type external_flow |
Reponse
Code Block |
---|
|
{"configurationId":"fd308ecf-bf93-4061-bbc7-7cace2cde764","baseUrl":""} |
Start
GET session/{sessionId}/file/{configurationId}/downloadRequestbody
Code Block |
---|
|
{"configurationId":"fd308ecf-bf93-4061-bbc7-7cace2cde764"} |
Description
provides a service that creates a child-session, to be used for widgets.
Parameters
Description
Gets the file from the specified connection based on its configuration
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionIdstring | The subscription id the session is part of. | sessionId | string | The session id |
configurationId | string | The |
property configuration id, available
Example response
The requested file, transferred using Content-Disposition: attachment
.
Check authorization
info key of the widget to load, available in properties.configurationId of a page model of type external_flow |
Reponse
Code Block |
GET The sessionId of the existing or newly created session. After starting a session its initial page contents may be obtained via a POST
to
/api/v2/session/{sessionId}/load
.
Code Block |
---|
|
{"sessionId":"9f79ac63-f994-4b9e-8a4d-86ef5a561291"} |
Handling files
Endpoints that go with AQ_File_Upload/AQ_File_Download containers.
Upload file
Code Block |
---|
|
POST /api/v2/session/{sessionId}/file/{configurationId}/upload |
Parameters
URL Segment | Expected Type | Description |
---|
file/{configurationId}/checkauthorizationDescription
Check if the user has the authority to download the file.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId | string | The subscription id the session is part of. |
---|
sessionId | string | The session id. |
configurationId | string | The configuration id. |
Response body
Returns an event response, for more info about an event response see: REST Events V1.
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
Code Block |
GET GET /api/v2/session/{sessionId}/ |
documentdocumentName{type}Description
Renders a document and returns its binary value.
Parameters
Gets the file from the specified connection based on its configuration
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId subscription id the session is part of.sessionIdsession id |
configurationId | string | The property configuration id, available |
Query Parameters
Query Parameter | Expected Type | Description |
---|
error-redirect | string | Optional. Specifies the URL to be redirected to if the file download fails. If not provided, the default JSON error output will be used instead. |
Example response
The requested file, transferred
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
.
Check authorization
Render a page
|
GET /api/v2/session/{sessionId}/ |
document/pagepageName{type}Description
Renders a page and returns its binary valueCheck if the user has the authority to download the file.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId subscription id the session is part of.session id |
configurationId |
sessionId | string | The configuration id |
of the session.pageName | string | Name of the page. |
type | string | Type of page (e.g. PDF). |
Response body
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
Transfers the binary data of a page using Content-Disposition: attachment
Images
Retrieve an image
Code Block |
---|
|
GET apiimagedocument/{documentName}/{ |
imageNameReturns the binary data of a named Blueriq image.
Parameters
Renders a document and returns its binary value.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId subscription is part ofsessionIdThe id sessionimageNameThe name of the image. |
Response body
Type of document (e.g. PDF). |
Query Parameters
Query Parameter | Expected Type | Description |
---|
error-redirect | string | Optional. Specifies the URL to be redirected to if the document download fails. If not provided, the default JSON error output will be used instead. |
Response body
Transfers the binary data of a document using Content-Disposition: attachment
Render a page
Returns the binary data of an image.
Retrieve a QR Code imageGET apiGET /api/v2/session/{sessionId}/ |
imageimageName/keykeyReturns the binary data of a named Blueriq QR Code imageRenders a page and returns its binary value.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId subscription is part ofsessionIdThe id sessionimageNameThe name of the image. | key | string | the element key. |
Query Parameters
Query Parameter | Expected Type | Description |
---|
error-redirect | string | Optional. Specifies the URL to be redirected to if the document download fails. If not provided, the default JSON error output will be used instead. |
Response body
Transfers the binary data of a page using Content-Disposition: attachment
Images
Retrieve an image
Response body
The binary data of an image.
Offline functionality
Prepare offline task
Code Block |
POST apioffline/preparetaskIdPrepares a task to be executed in offline mode Returns the binary data of a named Blueriq image.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId subscription is part ofsessionId session id.taskId | string | The id of the task to prepare offline mode forInference details
The DMN service is part of the development plugin and can be used to get inference details for attribute instances
Get Decision Tree
A PageModel instance with the page contents started by the task. For more information about the page contents (elements) see: REST Page Models.
Returns the binary data of an image.
Retrieve a QR Code image
GET api/dmnentityName{instanceId}attributeName
Gets a decision tree model for the specified attribute instance
Returns the binary data of a named Blueriq QR Code image.
Parameters
URL Segment | Expected Type | Description |
---|
subscriptionId subscription is part ofsessionId session id to create an event response forentityName | 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.
Code Block |
---|
|
{
"rootNode": {
"ruleName": "DMNEntity.DataRuleEndResult",
"justification": null,
"usedDecisions": [
{name of the image. |
key | string | The element key of the image. |
Response body
The binary data of an image.
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
Code Block |
---|
|
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.
Code Block |
---|
|
{
"rootNode": {
"ruleName": "DMNEntity.DataRuleEndResult",
"justification": null,
"usedDecisions": [
{
"ruleName": "DataRuleForPage",
"justification": null,
"usedDecisions": [],
"entityName": "DMNEntity",
"attributeName": "DataRule",
"attributeValues": [
"44"
],
" |
ruleNameDataRuleForPagejustificationdefaultRuleType": null,
" |
usedDecisions[],"40c05cc5-8ddf-48a3-8d5d-53228ca7305c"
}
],
"entityName": "DMNEntity",
|
DataRule 44 System null "instanceId": "40c05cc5-8ddf-48a3-8d5d-53228ca7305c"
|
],
"entityName": "DMNEntity",
Language
Get current languages
Code Block |
---|
GET /api/v2/session/{sessionId}/language |
Description
Returns a status code 200 if request was successful and a body containing a JSON Array with the available languages that are available in the current project.
Example response
attributeNameDataRuleEndResult attributeValues[
"1342], sourceTypeDefault defaultRuleTypeexpression, "instanceId": "40c05cc5-8ddf-48a3-8d5d-53228ca7305c"
}
}Set language
Code Block |
---|
POST /api/v2/session/{sessionId}/language/current?languageCode=nl-NL |
Description
Sets the specified language in the languageCode parameter for the currently active project. If the specified language does not exist a Bad Request status code is returned. Changing the language using this endpoint also changes the value of system.language in the profile.
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 V2.