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 JSON request message has a body that describes the parameters for handling the request payload, and the payload.

Parameters of a JSON Request

{
"name": "string",
"majorVersion": "string",
"minorVersion": "string",
"effectiveTimestamp": "string",
"Objects": [
{}
]
}
where:
*name - the name of the Decision Service -String
*majorVersion - Major version number, optional - String, converted to an integer in Corticon
*minorVersion - Minor version number, optional - String, converted to an integer in Corticon
*effectiveTimeStamp - DateTime of the Decision Service, optional - String
*Objects - JSONArray of JSONObjects that comprises the payload - String

Structure of JSON payload

A JSON payload is a standardized JSONObjectthat can be passed in to ICcServer.execute(…). The payload contains:
*"Objects": [<JSONArray>] where the JSONArray must contain JSONObjects that represent Root Entities of the payload.
*__metadataRoot (optional) - An optional Attribute inside the main JSONObjectthat 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 example shows the supported properties:
{
"Objects": [<JSONArray>
],
"__metadataRoot": {
"#restrictInfoRuleMessages": "true",
"#restrictViolationRuleMessages": "true",
"#restrictResponseToRuleMessagesOnly": "true",
"#locale": "en-US"
}
}

Root Level Entities

All JSONObjects inside the JSONArray under Objects are Root Level Entities.
Every name-value in the JSONObject maps to a Corticon Vocabulary Entity name on the Root of the payload or as an Association Entity, each of which requires a __metadata String attribute with a value of a JSONObject that describes the Entity with name-value pairs.
Mandatory:
#type : 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 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.
The value associated with a name does not 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. 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's 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. Note that:
*The value associated with name can be either a JSONObject or a JSONArray (of other JSONObjects).
*If the original value was a JSONObject, a JSONArray could 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.
*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.
*In an 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 used 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:
In the following example, there is one Association, transactionthat has corresponding JSON Object as a value. It is an Embedded Association -- 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.