Common JSON payload for cases and case types

The IBM® Case Manager REST protocol defines a JSON payload that is used in the methods that get or return information about a case or case type. This payload is also used by the external data service to obtain case information from an external data source.

The common JSON payload is used by methods for the following IBM Case Manager REST protocol resources:

Particular solution resource: The GET method uses the common payload to return a list of case types and the case type properties that are defined for a solution.
List of case types resource: The GET method uses the common payload to return a list of case types that are defined for a solution.
Particular case type resource: The GET method uses the common payload to return detailed property information for a case type.; The POST method uses the common payload to use the current property values to update information for dependent properties.
Cases resource: The POST method uses the common payload to create a case.
Particular case instance resource: The GET method uses the common payload to return information about a case.; The POST method uses the common payload to create a case by splitting an existing case.; The PUT method uses the common payload to update case information.

Payload parameters

The following code shows the structure of the full payload. However, not all methods use all parameters. See the specific method for the parameters that it uses in the payload.

{
"TargetObjectStore" : "<target object store name>",
"CaseType" : "<case type symbolic name>",
"CaseFolderId" : "<GUID of case folder>",
"DisplayName" : "<name displayed for  case type>",
"Description" : "<description of case type",
"CaseTitleProperty": "<property used as case title>",
"CaseIdentifier": "<case identifier>",
"ExternalDataIdentifier" : "<opaque data>",
"Properties":
[
{
   "SymbolicName"           : "<symbolic name>",
   "DisplayName"            : "<display name>",
   "Value"                  : <current property value>,
   "OriginalValue"          : <original property value>,
   "DisplayMode"            : "<readonly/readwrite>",
   "CustomValidationError"  : "<text of error>",
   "CustomInvalidItems"     : [<array of indexes>],
   "Description"            : "<property description>",
   "PropertyType"           : "<property type>",   
   "Cardinality"            : "<single or multiple>",
   "Updatability"           : "<settability as defined in CE>",   
   "Required"               : <required flag>,
   "Queryable"              : <true or false>,
   "Orderable"              : <true or false>,
   "Hidden"                 : <hidden flag>,
   "Inherited"              : <true or false>,
   "DefaultValue"           : <default property value>,
   "MaxValue"               : <maximum property value>,
   "MinValue"               : <minimum property value>,
   "MaxLength"              : <integer maximum length>,
   "HasDependentProperties" : <true or false>,
   "ChoiceList"             : 
      {
      "DisplayName"         : "<display name for choic list>",
      "Choices"             : 
            [
         {
            "ChoiceName"    : "<display name for choice>"
            "Value"         : <integer or string>
         },
      ]
   }
}

// ... additional properties

]
"ClientContext":
{
    "<key>":<value">,
    \\ additional key value pairs
}
}

The common JSON payload has the following attributes:

Table 1. Parameters for the common JSON payload
Parameter	Type	Description
TargetObjectStore	String	The symbolic name of the object store that contains the case. A symbolic name is called a unique identifier in IBM Case Manager.
CaseType	String	The symbolic name that is assigned to the case type.
ReturnUpdates	Boolean	A Boolean value that indicates whether the method is to return the property values after the case is created or updated. Set this parameter to true so that the method returns the case property values. By default, this parameter is set to false.
CaseFolderId	String	The GUID that identifies the root folder of an existing case.
DisplayName	String	The name that is displayed for the case in Case Manager Client.
Description	String	The description of the case.
CaseTitle Property	String	The name of the property that is used for the title of the case. By default, this parameter is set to CmAcmCaseIdentifier.
CaseIdentifier		The value of the CmAcmCaseIdentifier property for the case.
ExternalData Identifier	String	A string that provides contextual information to indicate the state of the data that was returned by an external data service. The value of this parameter is set by an external data service. Typically, the service sets the parameter to reference the specific configurations that were used to define the attributes other than the property value. These attributes include settings for the minimum value, maximum value, choice list, and so on.Case Manager Client maintains the value or the parameter, but it does not change the value or parameter. The ExternalDataIdentifier parameter is required for the POST method of the particular case type resource. It is recommended that you include the ExternalDataIdentifier parameter in the payload whenever a method creates or updates a case. If you do not include the parameter, the IBM Case Manager REST protocol must establish another identifier internally.
Properties	Array	An array of JSON objects that represent the properties that have external data to merge with the underlying information. For a description of the attributes that can be included for each property, see Table 2.
ClientContext	JSON object	An object that contains a series of key value pairs that specify contextual information for a specific work item. This parameter is used to send information to an external data service when a case worker opens the work item.

Property attributes

You can include the following attributes for each property that is defined in the Properties parameter in the JSON payload.

Table 2. Property attributes in the common JSON payload
Attribute	Type	Description
SymbolicName	string	The symbolic name of the property.
DisplayName	string	The name that is displayed for the property in Case Manager Client.
Value	Boolean, datetime, float, integer, string, object	The value of the property. The value is returned in various response payloads based on the type of case the call is referencing, to indicate the current or working property value. For a new case, the value starts out with a default value, which can be null. For an existing case, the value starts out with the current value on the case. An external data service can override this value. For a new case, the new value becomes the new working value before the case is created, and for an existing case it becomes the working value before the case is saved. The user can also modify the working value. The value can take various forms, depending on the type of property: null a string a Boolean an integer or a float for a datetime type, a value in W3C format (for example, `2012-10-31T18:30:10`) for an ID type, a string GUID for a multivalued type, an array of the appropriate non-null type for an object-valued type, another JSON object with information about the object that this property refers to
OriginalValue	Boolean, datetime, float, integer, string, object	The value currently persisted for the property in the repository. The IBM Case Manager REST protocol uses the OriginalValue parameter to determine whether the value that is specified by external data service is different from the value in the repository. This parameter can be specified in certain input payloads and is preserved in the response payload, regardless of whether the property value is modified. If not present in an input payload, it is not preserved in the response payload.
DisplayMode	string	A string that is returned by an external data service to specify whether Case Manager Client is to display the property value as read-only. An external data service can determine what the value of a property must be. If a value is predetermined, the field is rendered read-only from the user's perspective, but that value is saved when the case is saved or created. This mode is ignored if Updatability is not `readwrite` or `oncreate` for a new case. This mode has the following options: `readonly` The field is rendered as read-only, and the specified value is saved as the value of the property. `readwrite` The default setting. The field is be rendered writable, but Updatability takes preference.
Custom Validation Error	string	A message produced by an external data service, explaining why the existing value is invalid. An external data service can validate the current property values. It can leave an invalid value as-is and put a message in this field. The presence of this attribute indicates that the value is considered invalid by an external data service. The absence of this attribute indicates only that there is not an external data service that considers this property value to be invalid. The client can still consider the other attributes of the property when providing feedback to the user about the state of the property. An example use case is a customer ID property. An external data service can determine that the value of the property does not represent a valid customer ID without automatically modifying the value to a valid ID. In that case, the external data service can provide a custom validation error message.
Custom Invalid Items	array of indexes	A list of items on a multivalue list that are invalid, given as an array of indexes into the multivalue list of values. If an external data service validates a property value and the property is multivalue, it can also indicate the individual items of the multivalue list that are invalid. This attribute is applicable only if CustomValidationError indicates that the property is invalid. It does not need to be present even for a multivalue property. If CustomValidationError indicates that the property is invalid and this attribute is missing, then the entire property, rather than just individual items, should be considered invalid.
Description	string	The description of the property.
PropertyType	string	The data type of the property: integer float boolean string datetime id object
Cardinality	string	One of the following values that indicates whether the property contains a single value or multiple values: single multi
Updatability	string	One of the following values that indicates whether a case worker can modify the property value: readonly Indicates that a case worker can read the property value but cannot modify the value. readwrite Indicates that a case worker can read and modify the property value. oncreate Indicates that a case worker can modify the property value only when creating a case.
Required	Boolean	A Boolean value that is set to true to indicate that a value is required for the property.
Queryable	Boolean	A Boolean value that is set to true if the property can be used in a query condition.
Orderable	Boolean	A Boolean value that is set to true if the property can be used in an Order By clause in a query condition.
Hidden	Boolean	A Boolean value that is set to true to indicate that the property is to be hidden in Case Manager Client.
Inherited	Boolean	A Boolean value that is set to true if this property is inherited from the superclass of the class.
DefaultValue	Boolean, datetime, float, integer, string, object	The default value that is specified for the property in Case Manager Builder. If no value is specified, this parameter is set to null.
MaxValue	datetime, float, integer	A number that indicates the maximum value of the property.
MinValue	datetime, float, integer	A number that indicates the minimum value of the property.
MaxLength	integer	A number that indicates the maximum length of the property value.
ChoiceList	object	A JSON object that contains array that defines a list of choices for the property value. The ChoiceList value can contain a flat list of choices: `"ChoiceList" : { "DisplayName" : "<display name for choice list>", "Choices" : [ { "DisplayName" : "<display name for choice 1> "Value" : <value> }, { "DisplayName" : "<display name for choice 2>", "Value" : <value> }, // More choices ... ] }`
HasDependent Properties	Boolean	A Boolean value that is set to true by an external data service if other properties depend on the value of this property.

Currently, the only object-valued properties (OVPs) returned by this protocol are OVPs with single values. List and enum type OVPs are not supported. The protocol supports retrieving OVPs but does not support updating OVPs.

A non-null OVP value is represented in the JSON as in the following example:

"Value": {
		"Type": "reference",
		"ObjectStoreIdentity": "{DE6FC95A-3E90-42E2-9F3B-8B74C3945733}",
		"ClassIdentity": "{557F0B86-5C74-4F6D-BEA7-2B8C5476DBCF}",
		"ObjectIdentity": "{A9FC8EEC-FC7F-4B53-A5A0-73FC1E774FA7}"
},

Type: Currently always "reference". Indicates that the other attributes of the JSON object define a reference to an object in the repository.

ObjectStoreIdentity: Indicates an identity for the object store that holds the object. Property values returned from the protocol always have an Object Store ID (GUID) as this value.

ClassIdentity: Identifies the class of the object. Property values returned from the protocol always have a Class ID (GUID) as this value.

ObjectIdentity: Identifies the object itself. Property values returned from the protocol always have an ID (GUID) as this value.