Conversation API V2

Searching decision trees

There are 2 endpoints available to search for decision trees:

http://localhost/runtime/server/api/v2/dtree/search/{shortcut}
http://localhost/runtime/server/api/v2/dtree/search/{project}/{version}

The first endpoint needs a shortcut. Please refer to Create a shortcut in the Runtime on how to configure a shortcut. It is also possible to secure the shortcut and when doing so, please refer to Runtime Authentication for how to configure authentication on your Runtime.

The second endpoint is only available when blueriq.production.shortcuts-only is set to false in the application.properties file.

Example search

In the example below, in the Search request body the symptom text contains keywords that are modelled for the Decision Tree, like the word "coffee".

Example Search request

POST http://localhost/runtime/server/api/v2/dtree/search/coffee HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46d2VsY29tZQ==
Accept-Language: en-GB # header used in Blueriq to show the texts. If not set, the default language in the model is used
{
	"symptomText": "What coffee should I drink?", # Search query
	"maximumResults": 5, # Maximum number of results which will be returned. Default: 5
	"threshold": 15.0 # The threshold match percentage. Only match results greater or equal to the threshold are shown. Default: 0
}

The response will contain the list of all decision trees that are exposed in the flow started by the shortcut (or by project / version). Each decision tree has 3 properties:

name - the name of the DecisionTree as defined in Studio
description - the display name of the DecisionTree as defined in Studio
score - indicates matching score between the symptomText from the request with the decision tree's symptoms.

Example :

The Decision Tree "WhatCoffeeShouldIDrink" has the following symptoms: Coffee, Drink, Help, Sleepy, Stressed. The decision tree returns a score of 20, as one of the 5 words in the symptom text matches with one symptom of the decision tree.

The Decision Tree "DecisionTreeTest" has the following symptoms: keyword1, keyword2, keyword3. The decision tree returns a score of 0, as none of the words in the symptom text matches with the symptoms of the decision tree,

Example Search response

{
    "trees": [
        {
            "name": "WhatCoffeeShouldIDrink",
            "description": "What coffee should I drink?",
            "score": 20
        },
        {
            "name": "DecisionTreeTest",
            "description": "This is a test",
            "score": 0
        }
    ]
}

Error Messages

When the search 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	Request body is empty or symptomText is empty, unable to search
401	Unauthorized	Shortcut is secured.
403	Forbidden	Production mode: shortcut access only
404	Not Found	Unknown shortcut, project or version
500	Internal Server Error	Internal error

Executing a decision tree

There are 2 endpoints available to execute a decision tree:

http://localhost/runtime/server/api/v2/dtree/execute/{shortcut}/{name}
http://localhost/runtime/server/api/v2/dtree/execute/{project}/{version}/{name}

The first endpoint needs a shortcut.Please refer to Create a shortcut in the Runtime on how to configure a shortcut. It is also possible to secure the shortcut and when doing so, please refer to Runtime Authentication for how to configure authentication on your Runtime.

The second endpoint is only available when the development tools profile is enabled and blueriq.production.shortcuts-only=false.

Both endpoints are stateless. This means the request body should contain all the already submitted answers.

Example search

Example Execute request

POST http://localhost/runtime/server/api/v2/dtree/execute/coffee/WhatCoffeeShouldIDrink HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic YWRtaW46d2VsY29tZQ==
Accept-Language: en-GB # header used in Blueriq to show the texts. If not set, the default language in the model is used
{
    "answers": [
        {
            "key": "Person.DateOfBirth",            
            "value": "1986-04-03"            
        },
        {
            "key": "Person.Mood",            
            "value": "Excited"            
        }
    ],
	"showAttributeSolutions": true, # The attributes used as action in the tree are returned. Default: true
	"showImplicitAnswers": false, # The response contains derived values. When false, the response does not contain derived values. Default: false
	"skipFilledQuestions": true # The tree will skip questions where the answer is known or can be derived. Default: true
}

Example Execute response

{
    "answers": [
        {
            "key": "Person.DateOfBirth",
            "type": "date",
            "value": "1986-04-03",
            "questionText": "When where you born?",
            "domain": false,
            "answered": true,
            "domainValues": []
        },
        {
            "key": "Person.Age",
            "type": "integer",
            "value": "33",
            "questionText": "Age",
            "domain": false,
            "answered": true,
            "domainValues": []
        },
        {
            "key": "Person.Mood",
            "type": "text",
            "value": "Excited",
            "questionText": "How are you feeling today?",
            "domain": true,
            "answered": true,
            "domainValues": [
                {
                    "key": "Excited",
                    "description": "I'm excited"
                },
                {
                    "key": "Peaceful",
                    "description": "I'm peaceful"
                },
                {
                    "key": "Sleepy",
                    "description": "I'm sleepy"
                },
                {
                    "key": "Cranky",
                    "description": "I'm cranky"
                },
                {
                    "key": "Depressed",
                    "description": "I'm depressed"
                },
                {
                    "key": "Stressed",
                    "description": "I'm stressed"
                }
            ]
        }
    ],
    "questions": [],
    "solutions": [
        {
            "parts": [
                {
                    "value": "In your state of mind a nice cup of chamomile tea to calm you down."
                }
            ]
        }
    ]
}

Since Blueriq 12, when a solution part contains an attribute with a value list it returns additional information in the following JSON structure:

"solutions": [
	{
		"parts": [
			{
				"value": "Excited",
				"key": "Person.Mood",
				"questionText": "How are you feeling today?",
				"displayValue": "I'm excited"
			}
		]
	}
]

The key and questionText in the JSON response correspond to the fully qualified attribute name and the Question modelled in Studio. When then attribute does not have a Value list, the value in the JSON response contains the actual value of the attribute and the displayValue is null.

When the attribute has a Value list, the value and displayValue in the JSON response correspond to the value and displayValue of the Value list modelled in Studio.

Error Messages

When the execution 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
401	Unauthorized	Shortcut is secured. Security: Blueriq as a Service
403	Forbidden	Production mode: shortcut access only
404	Not Found	Unknown shortcut, project or version
500	Internal Server Error	Internal error

Space shortcuts

Page tree

Introduction

Example search

Error Messages

Executing a decision tree

Example search

Error Messages