Response to a request for case data

Draft comment:
This topic is shared by BAW, CP4BA. Last updated on 2025-03-13 12:15

The external data service responds to a POST method that was submitted by the workflow REST API. The response payload contains values for the properties that are managed by the service.

Response content

The response to the request must include a JSON payload that contains the following parameters:

{
  "externalDataIdentifier" : "<opaque identifier meaningful to service>",

  "properties":
  [
    {
      "symbolicName"   : "<symbolic_name>",   
      "value"           : <potential new value>,
      "customValidationError" : "Description of an invalid reason",
      "customInvalidItems" : [0,3,4,8], // invalid multi-value items
      "displayMode"     : "<readonly/readwrite>",
      "required"      : <true or false>,
      "hidden"          : <true or false>,
      "maxValue"      : <overridden max value>,
      "minValue"      : <overridden min value>,
      "maxLength"      : <underlying max>,

      "choiceList"   : 
      {
        "displayName"   : "<display_name>",
        "choices"      : 
        [
          {
            "displayName"   : "<name>",
            "value"   : <value>
          },

          {
            "displayName"     : "<name>",
            "value"   : <value>
          },

          // More choices ...
        ]
      }

      "hasDependentProperties" : <true or false>,

    }

    // More properties ...

  ]

}

Table 1. Response parameters for the POST method
Name	Type	Required?	Description
externalData Identifier	String	Yes	The identifier provides contextual information to indicate the state of the data that the service is returning. You implement this parameter with values that are meaningful for your data source. Typically, the parameter references the specific configurations that define attributes other than the property value such as the minimum value, maximum value, or the choice list. These configurations can be selected dynamically based on other property values. In this situation, the service can use the externalDataIdentifier parameter to determine that the configuration changed since the previous call. If the external data service does not modify property attributes dynamically, you might not need to capture the data state. In this situation, you might implement the parameter to return a fixed string value. If the external data service returns data that is dynamic, you must capture the data state. For example, the service might manage a property whose value or other attributes are determined by the value of another property. In this situation, you must implement the parameter to return a value that references the specific configuration that was used to determine the value or other attributes of the dependent property. The parameter must capture enough information to identify changes in property data when the externalDataIdentifier parameter is returned to the service in an inProgressChanges request. For example, assume that a list of conditions is used to select a set of configurations based on the working property values. The data that is captured in the externalDataIdentifier parameter might include the indexes of the matching conditions.
properties	Array	Yes	An array that contains values for the properties that are managed by the external data service. For each property, you can specify the symbolic name and the attributes, such as value, choice list, and maximum length.

Property attributes

The Properties parameter contains the following attributes for each property that is managed by the external data service. The external data service can determine many of these values dynamically so that the service can return a different value in each response.

Table 2. Attributes of properties in the response payload
Name	Type	Required?	Description
symbolicName	String	Yes	The symbolic name of the property. The name must match the symbolic name that was specified in the request payload.
value	Determined by setting in the case type	No	The value of the property. The value that is set by the external data service must correspond to the data type that is specified for the property in the case type. The external data service can determine the property value dynamically based on the values of another other property. If the service does not specify a value, the current working value for the property is unchanged.
custom Validation Error	String	No	A message that describes why a property value is invalid. You can configure the external data service to validate the current value of a property. If the value is invalid, the service can leave the value unchanged and return an error message in the customValidationError parameter. For example, the service might determine that an account number is invalid. However, you do not want the service to replace the account number. Instead, you can configure the service to return an error message in the customValidationError parameter. If this parameter is included in the response, the property value is deemed invalid. However, the absence of this attribute indicates only that the parameter passed the validation by the external data service. The value might still be invalid based on attributes that are not validated by the service.
custom Invalid Items	Array of indexes	No	An array of indexes for a list of values for a multi-valued property. When the external data service validates a multi-valued property, it can return this parameter to indicate the specific values that are invalid. If a multi-valued property is invalid and this parameter is not set, the property value as a whole is considered invalid. This attribute is applicable only if the customValidationError parameter indicates that the property is invalid.
displayMode	String	No	A string that specifies whether Case Client is to display the property value as read-only. The external data service can set this parameter to one of the following values: readonly The user can view the property value but cannot modify it. readwrite The case worker can modify the property value. This setting is the default value. If the property value is set to readonly in the case type, the external data service cannot make the value writable. In this situation, a value of readwrite is ignored.
required	Boolean	No	A Boolean value that is set to true to indicate that a value is required for the property. The external data service can determine this setting dynamically based on the values of other properties. However, the service cannot override the required parameter if it is set to true in the case type.
hidden	Boolean	No	A Boolean value that is set to true to indicate that the property is to be hidden in Case Client. The external data service can determine this setting dynamically based on the values of other properties. If this parameter is not specified, the value specified in the case type is used.
maxValue	Integer, float, or date-time	No	A number that indicates the maximum value of the property. The external data service can determine this setting dynamically based on the values of other properties. If a maximum value is specified for the property in Content Platform Engine, the service cannot make the setting less restrictive. That is, the service can set the maximum only to a smaller value. It cannot increase the maximum value. For example, if the maximum value in Content Platform Engine is 100, the service can set the value to 50, but not to 150.
minValue	Integer, float, or date-time	No	A number that indicates the minimum value of the property. The external data service can determine this setting dynamically based on the values of other properties. If a minimum value is specified for the property in Content Platform Engine, the service cannot make the setting less restrictive. That is, the service can set the minimum only to a larger value. It cannot decrease the minimum value. For example, if the minimum value in Content Platform Engine is 100, the service can set the value to 150, but not to 50.
maxLength	Integer	No	A number that indicates the maximum length of the property value. The external data service can determine this setting dynamically based on the values of other properties. If a maximum length is specified for the property in Content Platform Engine, the service cannot make the setting less restrictive. That is, the service can set the maximum length only to a smaller value. It cannot increase the maximum length. For example, if the maximum length in Content Platform Engine is 100, the service can set the value to 50, but not to 150.
choiceList	Object	No	An array that defines a list of choices for the property value. The external data service can specify a choice list only if one is not defined for the property in Content Platform Engine. The service can determine the choices in the list dynamically based on the values of other properties. The choiceList value can contain a flat list of choices: `"choiceList" : { "displayName" : "<display name for the choice list>", "choices" : [ { "displayName" : "<display name for a specific choice> "value" : <value> }, { "displayName" : "<display name for a specific choice>", "value" : <value> }, // More choices ... ] }`
hasDependent Properties	Boolean	No	A Boolean value that is set to true if other properties depend on the value of this property. When this parameter is set to true, the POST method is called to update the dependent properties based on the new value whenever this property is updated. By default, this parameter is set to false.