IBM Content Navigator, Version 2.0.3 Supports:

Response payload to a POST method request payload

The external data service responds to a POST method that was submitted by the EDSSupportPlugin plug-in. 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_the_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_or_readwrite",
      "required": true_or_false,
      "hidden": true_or_false,
      "maxValue": overridden_maximum_value,
      "minValue": overridden_minimum_value,
      "maxLength": underlying_maximum_length,

      "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	No	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. To select configurations dynamically, the service can use the externalDataIdentifier parameter to determine that the configuration changed since the previous call. If you do not implement dynamic behavior or dependencies for any attributes, 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 class	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 class. The external data service can dynamically determine the property value 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 that is performed by the external data service. The value might still be invalid based on attributes that are not validated by the service. Values are validated by using regular expressions. For example, the following regular expression can be used to validate a simple email address: `"\\b[\\w\\.-]+@[\\w\\.-]+\\.\\w{2,4}\\b"` Restriction: You can use custom validation for properties in workflow properties, teamspaces, and entry template properties. You cannot use custom validation for object properties, reference attributes, read-only properties, hidden properties, or search criteria.
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 IBM® Content Navigator 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 user can modify the property value. This setting is the default value. If the property value is set to readonly in the class, the external data service cannot make the value writable. In this situation, a value of readwrite is ignored.
format	String	No	An expression that describes the correct format for values to enter into the property. Uses formatDescription to provide a description for the format parameter.
format Description	String	No	The description that is displayed in a tooltip if the user enters a format that does not match the expression specified in the format parameter.
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 dynamically determine this setting based on the values of other properties. However, the service cannot override the required parameter if the required parameter is set to true in the class.
hidden	Boolean	No	A Boolean value that is set to true to indicate that the property is to be hidden in IBM Content Navigator. The external data service can dynamically determine this setting based on the values of other properties. If this parameter is not specified, the value specified in the class is used. Restriction: You can override a hidden property to be shown by using `hidden:false`. However, IBM CMIS providers filter properties that are defined as hidden, so the property definition is not available to the CMIS connector in IBM Content Navigator. Therefore, you cannot use EDS to override properties that are defined as hidden in a CMIS-provided repository.
maxValue	Integer, float, or date-time	No	A number that indicates the maximum value of the property. The external data service can dynamically determine this setting based on the values of other properties. If a maximum value is specified for the property in the repository, 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 the repository 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 dynamically determine this setting based on the values of other properties. If a minimum value is specified for the property in the repository, 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 the repository 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 characters in the property value. The external data service can dynamically determine this setting based on the values of other properties. If a maximum length is specified for the property in Content 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 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 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 ... ] }` Important: Do not implement choice lists in the Content Engine definitions for the same properties that are associated with the choice lists that you provide by using the external data service. The choiceList value can also use the following special values to empty the choice list or to use the choice list that is defined in the class definition: null `"choiceList": null` Removes the currently assigned choice list, so that no choice list is associated. If valid values are defined for the property, when there is no choice list, IBM Content Navigator dynamically creates a choice list from the valid values. default `"choiceList": "default"` Uses the original choice list that is defined for the property in the class definition, if one exists. If the class definition does not define a choice list, then the `null` handling applies (handles the property as if there is no choice list).
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.