You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.
Table of contents
Domain schema editor
You can find the Domain schema editor under Connectivity.
The domain schema is a contract of communication. The purpose of the domain schema is to define what items are needed in a message and to specify its elements. For example the representation of a person. In this case the persons first name (1), always followed by his last name and his job(s). The right column represents the application domain, where the left column represents the domain schema of the message.
You start with an entity (2) that represents the begin and the end of the message. For every attribute/relation (3) you can select a name (4), what datatype (5) it is, if it is required (6) to be part of the message, if it is multivalued (7) and any additional documentation (8) that will be part of the Swagger feed. It is also possible to add validation types on the value (9).
- When you add the right column of the domain schema first, the left column will be prefilled with a copy of the name from the right column. When editing the left column then it is "user-set" and the automatic copy function will be disabled.
- When an attribute or relation is selected, the fields on the right side of the screen are prefilled using the information of the attribute or relation. You may deviate from this chosen setting.
- The validations can only be a validation type. It is not possible to use validation rules.
- When optional elements of the messages are left out, the parser will set the value unknown for them. This is the same for NULL values in JSON.
- When generating a JSON message, unknown values will be mapped to NULL. However, the element will be left out completely when the attribute is not required and the value is not user-set.
A domain schema is case sensitive. The attribute in the right-hand column typically contains one or more uppercase characters (the use of CamelCase is a modeling guideline). This is copied to the left-hand column as a suggestion for the incoming attribute name. If the incoming response has the same attribute name, but not the exact same casing, this attribute is not found in the domain schema and the mapping won't work. This can be a problem that is easily overlooked.
You can make translations between message and your application domain. For example, it is possible to store a single-valued attribute in the message in a multi-valued attribute in your application domain. You have to be aware that you can only make a translation into a more general data type. For example the other way is not possible. When sending a message, it is not possible to place a multivalued attribute of your application domain in a single valued attribute of the domain schema.
After completing the domain schema it is possible to preview the message format by clicking the preview button, as shown below. It is possible to choose between XML and JSON format.
Unnamed arrays
New feature
Starting with Blueriq 10.1 JSON messages can also be defined as unnamed arrays.
Example of a JSON message that consists of an unnamed array:
[
{ "John", 23 },
{ "Rick", 30 },
{ "Paul", 27 }
]
To define an unnamed array the 'Hide root element' checkbox corresponding to the domain schema root element must be ticked.
Simple example of use:
Say that you have a service that returns e-mail addresses of your new subscribers in form of a JSON unnamed array:
[ "John@sever.org", "Peter@sever.org", "Maarten@server.org" ]
The Studio coresponding domain schema should look something like this:
But now by clicking on the 'Preview' button you can observe that the generated JSON doesn't look like the expected message:
{
"email_address": [ "value" ]
}
To fix this, you can just click on the root element and tick the 'Hide root element' checkbox located on the right in the application domain. By doing this your JSON message should be correct and you should be able to map indeed all the values recieved in the email_address attribute.
[ "value" ]
When making use of unnamed arrays, only one child (relation or attribute) can follow the root element. For instance, the following is NOT correct and hence the project will have validation errors:
Domain Schema in another Domain Schema
New feature
Starting with Blueriq 10.3 other DomainSchemas can be included as domain properties in another DomainSchema.
A new option is available for selection in the drop-down for adding a new domain property , which consists of the domain property name, the relation name and the domain schema name.
When selecting the sub-domain schema, the following validations are applied :
- a sub-domain schema can be added under the root entity or under a relation
- the root entity of the sub-domain schema should be the target entity of the selected relation
- the root entity of the sub-domain schema should have as base entity the target entity of the selected relation
- adding a sub-schema which has root element hidden will trigger a validation message
Infinite loop
Because domain schemas can be referenced by other domain schemas, it is now possible that infinite loops are created.
For preview purposes, a hardcoded limit of 2 loops was set for the Studio preview.
For more information on how to set the infinite-loop-limit for Runtime, check the properties documentation page
Schema Element in Domain Schema
New feature
Starting with Blueriq 11.4 custom schema elements can be included as domain properties in another DomainSchema.
A new option is available for selection in the drop-down for adding a new domain property , which consists of the domain property name and the custom schema element name.
This feature can be used for adding extra explanation for the value of attribute domain properties in the domain schema, for example by adding the AQ_JustificationTree custom schema element.
Justification Tree in a Rest service based on a Domain Schema (JSON)
Justification trees can be included in a webservice message and sent to another system. Using REST (+JSON) is the most common structure to expose messages. Justification trees can be selected in the domain editor using a custom schema element. This will lead to a JSON structure of the given tree, placed in the selected element of the domain. For more information, check Custom Schema Element: AQ_JustificationTreeV2.
Justification Tree from another module
When the Justification Tree is modeled in the same module as the domain schema, the schema element can consume the Justification Tree right away. However, in many cases, the module that contains the domain schema will not be the module that contains the Justification Tree. In the example below, the domain module "Service" contains the domain schema (with the AQ_JustificationTree schema element). Due to the data mapping and lack of rules, all attributes used in this module are user set, so no Justification will be available. The domain module "Domain" contains the logical domain of the Blueriq model. The Justification Tree will be available from this module.
In order to use the Justification Tree in the Service module, a data mapping is possible from the Domain module To the Service module. The Justification Tree will be generated, and be available in the other module to be attached to the webservice call .
A Justification Tree will be generated from the scope of the target instance from the matching source instance, so a tree would be available for each instance of the given entity
Clicking on the tree icon will enable you to attach a Justification Tree to the element in the target module and attribute (in the example above "Car.Costs"). When the Justification tree is used in the Custom Schema Element of Car.Costs, this tree will be used.
The tree will be generated based on the Justification of the attribute Tax.AnnualAmount (of the source module), and attached to the attribute in the target module as if this was the Justification of "Car.Costs".
As a result of the data mapping, both the attribute Car.Costs as well as its justification tree become user-set.
The depth and asset format(s) will determine the available tree in the target (service) module. If the depth is set lower in the data mapping than the Schema element, the schema element might miss information to be set in the response message.
Consuming a Justification Tree
In the current situation, Blueriq is able to send a Justification Tree using a custom Schema element. Blueriq is not able to consume an incoming message using a custom schema element. When information is needed in Blueriq (from another Blueriq webservice), the Justification tree could be interpreted as a part of the message, and handled using a corresponding model (with the elements that are relevant for the consumer).
Overview
Content Tools