You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.
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".
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,
{ "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
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 }
{ "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 |