skip to main content
Corticon Server: Integration & Deployment Guide : Request and response examples : JSON/RESTful request and response messages : About creating a JSON request message for a Decision Service
 

Try Corticon Now
About creating a JSON request message for a Decision Service
A standardized JSONObject can be passed in to ICcServer.execute(…). The JSONObject has name-value pair of "Objects":<JSONArray>. The Corticon Server will translate JSONObjects that are inside the JSONArray under the name of "Objects". The JSONArray must contain JSONObjects that represent Root Entities of the payload.

Basic structure of JSON payload

{
"Objects": [<JSONArray>
],
"__metadataRoot": {
<execution property>: “<value”,
.
.
}
}

__metadataRoot (optional)

This optional Attribute inside the main JSONObject can contain execution specific parameters. (Note that the initial characters are TWO underscores.) These parameters are used only for that execution, and will override a Decision Service or CcServer level properties. The following properties are supported:
*#restrictInfoRuleMessages
*#restrictWarningRuleMessages
*#restrictViolationRuleMessages
*#restrictResponseToRuleMessagesOnly
*#locale
The following example uses these properties in __metadataRoot:
{
"Objects": [<JSONArray>
],
"__metadataRoot": {
"#restrictInfoRuleMessages": "true",
"#restrictViolationRuleMessages": "true",
"#restrictResponseToRuleMessagesOnly": "true"

}
}

Root Level Entities

All JSONObjects inside the JSONArray under Attribute “Objects” are considered Root Level Entities.
Referred to as “Root”, because the Entity doesn’t have any Parent Entity. “Entity” is a JSONObject of data that maps to the Corticon Vocabulary Entity, which can be on the Root of the payload or it can be an Associated Entity, which is referred to as an Association. Associated Entities can either be Embedded Associations or Referenced Associations. The difference between these two types will be covered later in the document.
All Root Entities and embedded Association Entities must have an Attribute called __metadata that at minimum describes the type of the Entity. The “__metadata” is a String Attribute name with a value of a JSONObject. Inside this JSONObject, additional name-value pairs are added to describe that Entity.
Mandatory:
#type : This is the Entity type as defined in the Vocabulary.
Optional:
#id: A unique String value for each Entity. The #id field can be used in a Referenced Association where an Association can point to an existing Entity that is in the payload. If Referenced Associations are going to be used in the payload, then a #id must be defined for that Associated Entity. Referenced Associations will be covered later in the document.
If #id is not supplied in the payload, during execution of rules, a unique value will be set for each Entity. This is done during initial translation from JSON to Corticon Data Objects (CDOs). This is needed because Corticon does not know whether the rules will manipulate the Associations in such a way that #id values are needed. The output returned to the user will always contain #id value regardless if it was originally part of the “__metadata”.
Example of Root Level Entity with __metadata:
{
"Objects": [{
"dMarketValueBeforeTrade": "10216333.000000",
"price": "950.000000",
"__metadata": {
"#id": "Trade_id_1",
"#type": "Trade"
}

}],
}

JSON Entity Attribute and Association name-value pairs

All Entities can contain Attribute name-value pairs along with Association Role name-value pairs.
Attribute name-value pairs:
Each JSON Entity can have any number of Attribute name-value pairings. The Attribute names inside the JSON Entity correspond to what has been defined in the Vocabulary for that JSON Entity type. The Attribute name inside the JSON Entity is used to look up the corresponding Vocabulary Attribute for that Vocabulary Entity type. If JSON Entity Attributes don’t match with any Vocabulary Entity Attribute, then the JSON Entity Attribute is ignored, and won’t be used by the rules.
The “value” associate with “name” doesn’t have to be a String. However, the “value” must be of proper form to be converted into the Datatype as defined in the Vocabulary Attribute’s Datatype.
The JSON Datatypes that can be used as a “value” are:
*String
*Boolean
*Double
*Int
*Long
For a Date “value”, use a String to represent the Date, which will be converted into a proper Date object for rule processing.
If the “value” cannot be properly converted into the Vocabulary Attribute’s Datatype, a CcServerExecutionException will be thrown informing the user that the CcServer failed to convert the JSON “values”.
Example of Attribute name-value pairs:
There is one Attribute, “price”, with a corresponding value. Based on the __metadata : #type, these Attribute values are looked up under the Vocabulary Trade Entity.

Association name-value pairs

Each JSON Entity can have any number of Association name-value pairings. The Association names inside the JSON Entity correspond to an Vocabulary Entity Association Role Name, defined in the Vocabulary for that JSON Entity type. Like the Attribute, as described above, Association names inside the JSON Entity are used to look up the corresponding Vocabulary Association for that Vocabulary Entity type. If JSON Entity Association names don’t match with any Vocabulary Entity Association Role Name, then the JSON Entity Association is ignored, and won’t be used by the rules.
The “value” associate with “name” can be either a JSONObject or a JSONArray (of other JSON Objects). However, it is possible that if the original “value” was a JSONObject, a JSONArray may be in the output. If there is a rule that does a += operator on the Association, the JSONObject will be converted into a JSONArray so that multiple JSONObjects can be associated with that “name”.
Also, the Associated JSONObject, the “value”, can be a Referenced Associated Object, which points to another JSONObject in the payload. In this scenario, a “ref_id” is use to point to the intended Entity. As described above, the #type value is not needed when a Referenced Associated Object is used because the “type” can be inferred by the Rules Engine.
Example of Embedded Association name-value pairs:
There is one Association, “transaction”, with a corresponding JSON Object as a value. This is an Imbedded Association, which is an Entity under another Entity. The Transaction Entity, as defined by its __metadata : #type = Transaction is associated with Trade through a Role Name of “transaction”
Example of Referenced Association name-value pairs:

XML Element Name overrides for Attributes and Association names

JSON Entity Attribute names are first matched against XML Name overrides, which are defined in the Vocabulary Attribute. If no XML Element Name is defined, then JSON Entity Attribute names are matched directly against the Vocabulary Attribute name.
Much like the Attribute’s XML Element Name override, Associations also have an XML Element Override.