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.

Table of Contents

maxLevel	2

...

Authentication

Login user

Code Block

language	js

POST /api/v2/login

Description

Log

Login the user

...

with the provided credentials

...

Request body

URL Segment

Code Block

Expected Type

language

Description

js

{
	username

stringUsername of the user to login.passwordstringPassword 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

language	js

POST /api/v2/logout

Parameters

Query Parameter	Expected Type	Description	Required
redirect_uri	string	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

Logout user

Code Block

language	js

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 SegmentExpected TypeDescriptionshortcutNamestring

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 parameterExpected TypeDescriptionRequiredprojectstring

The project to start

Yes

flow

stringThe flow to startOnly required if more than one exposed flow is present in the projectversionstringThe branch versionNolanguageCodestringThe project languageNouistringThe UI variant to use, by default only mvc and xslt is supportedNothemestringThe project themeNochannelstringthe project channelNo

Example response

Code Block
{ "sessionId": "2f177274-514d-4be9-aa3d-4a550ab9e724", "sessionTimeout": 1800 }

Interacting with a session

...

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

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

title	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 using /api/v2/start, the current state of the session can be obtained through:

Code Block

language	js

POST /api/v2/session/{sessionId}/load

Description

Loads the information of the provided session.

Example response

Code Block

language	text

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

Code Block

language	js

{
	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

Send user event

Code Block

language	js

POST /api/v2/session/{sessionId}/event

Description

Handles a page event and returns the events that occurred in any of the sessions in heirarchy.

Headers

Name	Value
Content-Type	application/json

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.

Code Block

language	js

{
	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

language	js

{
    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

language	js

POST /api/v2/session/{sessionId}/flow/{flowName}

Description

Starts a flow and returns the events that occurred in any of the sessions in the hierarchy. When a page is currently active, only flows which have already been visited can be started.

Example response

Code Block

language	text

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

...

Close session

Code Block

language	js

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

Response

204 No Content

Keep alive

Code Block

language	js

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

Code Block

language	js

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.

Code Block

language	js

{"sessionId":"a487f65e-6804-4803-bf4b-c89e45f97e38"}

Handling files

Endpoints that go with AQ_File_Upload/AQ_File_Download containers.

Create external flow widget

Starting an external flow consists of multiple calls.

Init

Upload file

Code Block

language	js

POST

POST /api/v2/session/{sessionId}/

file/{configurationId}/upload

Parameters

URL SegmentExpected TypeDescriptionsessionIdstringThe session id.configurationIdstringThe configuration id.

Response body

Returns an event response, for more info about an event response see: REST Events.

Download a file

externalflow/init

Requestbody

Code Block

language	js

{"configurationId":"fd308ecf-bf93-4061-bbc7-7cace2cde764","baseUrl":""}

Description

provides a service that initializes an external flow starting from your current session.

Parameters

Code Block

language	js

GET /api/v2/session/{sessionId}/file/{configurationId}/download

Description

Gets the file from the specified connection based on its configuration

Parameters

URL SegmentExpected TypeDescriptionsessionIdstring

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

info key of the widget to load, available in properties.configurationId of a page model of type external_flow

Reponse

Code Block

language	js

{"configurationId":"fd308ecf-bf93-4061-bbc7-7cace2cde764","baseUrl":""}

Start

Code Block

language	js

POST

Code BlockGET

 /api/v2/

session/{sessionId}/file/{configurationId}/checkauthorization

externalflow/start

Requestbody

Code Block

language	js

{"configurationId":"fd308ecf-bf93-4061-bbc7-7cace2cde764"}

Description

provides a service that creates a child-session, to be used for widgets.

Parameters

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 info key of the widget to load, available in `properties.configurationId` of a page model of type `external_flow`

Reponse

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

language	js

{"sessionId":"9f79ac63-f994-4b9e-8a4d-86ef5a561291"}

Handling files

Endpoints that go with AQ_File_Upload/AQ_File_Download containers.

Upload file

Code Block

language	js

POST

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

Code Block

language	js

GET /api/v2/session/{sessionId}/document/{documentName}/{type}

Description

Renders a document and returns its binary value.

Parameters

URL SegmentExpected TypeDescriptionsessionIdstringThe id of the session.documentNamestringName of the document.typestringType of document (e.g. PDF).

Response body

Transfers the binary data of a document using Content-Disposition: attachment

Render a page

Code Block

language	js

GET

/api/v2/session/{sessionId}/

document

file/

page/

pageName

configurationId}/

{type}

Description

Renders a page and returns its binary value.

upload

Parameters

URL Segment	Expected Type	Description
sessionId	string	The session id

of the session

.

pageName

configurationId

string

Name of the page

The configuration id.

typestringType of page (e.g. PDF).

Response body

Returns an event response, for more info about an event response see: REST Events V1.

Download a file

Response body

Transfers the binary data of a page using Content-Disposition: attachment

Images

Retrieve an image

Code Block

language	js

GET api

GET /api/v2/session/{sessionId}/

image

file/{

imageName

configurationId}/download

Description

Returns the binary data of a named Blueriq image.

Gets the file from the specified connection based on its configuration

Parameters

URL Segment	Expected Type	Description
sessionId	string	The session id

of the session.

imageName

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 using Content-Disposition: attachment.

Check authorization

Code Block
GET /api/

name of the image.

Response body

Returns the binary data of an image.

Retrieve a QR Code image

Code Block

language	js

GET api/

v2/session/{sessionId}/

image

file/{

imageName

configurationId}/

key/{key}

checkauthorization

Description

Returns the binary data of a named Blueriq QR Code image

Check if the user has the authority to download the file.

Parameters

URL Segment	Expected Type	Description
sessionId	string	The session id

of the session.

imageName

configurationId

string

The

name of the image.keystringthe element key.

Response body

The binary data of an image.

Offline functionality

Prepare offline task

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

Code Block

language	js

GET /

Code BlockPOST

api/v2/session/{sessionId}/

offline

document/

prepare

{documentName}/{

taskId

type}

Description

Prepares a task to be executed in offline mode

Renders a document and returns its binary value.

Parameters

URL Segment	Expected Type	Description
sessionId	string	The id of the session

id

.

taskId

documentName

string

The id

Name 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

document.
type	string	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

Code Block

language	js

GET

Code Block

language	js

GET

/api/v2/session/{sessionId}/

dmn

document/

{entityName}

page/{

instanceId

pageName}/{

attributeName

type}

Description

Gets a decision tree model for the specified attribute instance

Renders a page and returns its binary value.

Parameters

URL Segment	Expected Type	Description
sessionId	string	The

session id to create an event response forentityName

id of the session.
pageName	string

Entity name for the attribute for which the decision tree is requestedinstanceIdstringInstance id for the attribute for which the decision tree is requestedattributeNamestringName 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

language	text

{ "rootNode": { "ruleName": "DMNEntity.DataRuleEndResult", "justification": null, "usedDecisions": [ {

Name of the page.
type	string	Type of page (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 page using Content-Disposition: attachment

Images

Retrieve an image

Code Block

language	js

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

Code Block

language	js

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

language	js

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

language	text

{
  "rootNode": {
    "ruleName": "DMNEntity.DataRuleEndResult",
    "justification": null,
    "usedDecisions": [
      {
        "ruleName": "DataRuleForPage",
        "justification": null,
        "usedDecisions": [],
        "entityName": "DMNEntity",
        "attributeName": "DataRule",
        "attributeValues": [
          "44"
        ],
        "

ruleName

sourceType": "System",

"DataRuleForPage"

       "defaultRuleType": null,
        "instanceId":

"justification": null,

"40c05cc5-8ddf-48a3-8d5d-53228ca7305c"
      }

"usedDecisions":

[

],

    "entityName": "DMNEntity",

"attributeName": "

DataRule

DataRuleEndResult",

"attributeValues": [

44

1342"

],

"sourceType": "

System

Default",

"defaultRuleType":

null

"expression",

"instanceId": "40c05cc5-8ddf-48a3-8d5d-53228ca7305c

" } ],

"entityName": "DMNEntity", "attributeName": "DataRuleEndResult

}
}

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

Code Block
[ { "code": "nl-NL",

attributeValues

name":

[

1342

Nederlands"
  },

],

sourceType

code": "

Default

en-US",

defaultRuleType

name": "

expression

English"

,

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

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 6

New Version Current

Key

Authentication

Login user

Request body

Response

Response

Logout user

Parameters

Description

Response

Starting a Blueriq session

Start Shortcut

Description

Parameters

Logout user

Description

Response

Starting a Blueriq session

Start Shortcut

Description

Parameters

Example response

Start Project

Description

Parameters

Example response

Example response

Interacting with a session

Start Project

Description

Parameters

Example response

Interacting with a session

Load session information

Description

Example response

Parameters

Response body

Send user event

Description

Headers

Parameters

Request body

Response body

Start flow

Description

Example response

Parameters

Response body

Close session

Description

Parameters

Response

Keep alive

Description

Parameters

Response

Create widget

Description

Parameters

Reponse

Handling files

Create external flow widget

Init

Code BlocklanguagejsPOST POST /api/v2/session/{sessionId}/file/{configurationId}/upload

Parameters

Response body

Download a file

Requestbody

Description

Parameters

Description

Parameters

Example response

Code Block
language js
POST
POST /api/v2/session/{sessionId}/
file/{configurationId}/upload

URL Segment Expected Type Description
sessionId string
The session id
configurationId string The info key of the widget to load, available in `properties.configurationId` of a page model of type `external_flow`