Centralizing Your Validation Rules on IBM Content Navigator

External Data Services – Handling Front-End Validations

External Data Services (EDS) is the official supported way to perform front-end validation-type actions for IBM Content Navigator (ICN). In short, EDS is basically the implementation of two web service calls that must respect the protocol specifications. ICN will automatically call the web service at appropriate times with the list of properties and its current value, and update the values based on the return value of the web service on the front-end.

Typical EDS use cases are lookup in database to assign choice lists and/or values to other fields, prefill fields, set read-only fields, hide fields, perform custom validations on specific fields, etc.

Below is a non-exhaustive list of supported object types and actions where ICN will call the EDS if configured:

Supported Object Types

• FileNet P8:

1. Classes
2. Folders
3. Step processors
4. In-baskets

• FileNet P8 Case Manager:

1. Case types

• Content Manager:

1. Item types
2. Folders

• Content Manager OnDemand:

1. Applications

• Datacap:

1. Batches

Supported Actions

• FileNet P8:

1. Add/edit documents
2. Add/edit folders
3. Using entry templates
4. Creating/using searches
5. Starting/using workflows
6. Using in-baskets

• FileNet P8 Case Manager:

1. Create/edit cases

• Content Manager:

1. Add/edit documents
2. Add/edit folders
3. Using entry templates
4. Creating/using searches

• Content Manager OnDemand:

1. Add/edit document
2. Create/using search folders

• Datacap:

1. Create/edit batches
2. Verifying pages
3. Using job monitor

It is crucial to implement EDS in any ICN deployment as ICN is the front-end to your repositories. We always want to sanitize the data before it goes in the backend and EDS helps achieve exactly that. The fact that it is one set of simple protocol to implement which will target multiple objects is a no brainer to invest in for your ICN deployment.

Quick Dive Into EDS REST Protocol Specifications

GET Method – Which Object Type Will EDS be Acting on?

URL: /types?repositoryId=<ICN repository id>

Parameter: repositoryId is the id of the repository configured in ICN.

Expected response: JSON payload with the form:

{
  "types": [
    {
      "symbolicName": "<object type id>",
    },
    …
  ]
}

This web service endpoint is called the first time there is any call to the repository. It is expecting a JSON that describes the object types that ICN needs to call the EDS for the repository that was passed as a parameter.

You may find the official specification on the IBM Knowledge Center here.

POST Method – Handling the Request.

URL: /type/<object type id>

Parameter: <object type id> is the id of the object type where an action is currently being called on.

Request body: JSON string to be parsed with the form:

{
   "repositoryId": "id of the repository being targeted",
   "objectId": "id of the object being targeted",
   "requestMode": "request mode representing the step of the action",
   "externalDataIdentifier": " id for the service",
   "properties": [
     {
       "symbolicName": "id of the field",
       "value": <current value>,
     },
     …
   ],
   "clientContext": {
     "userid": "id of the user logged in",
     "locale": "locale of the browser",
     …
   }
}

The web service endpoint is called any time a supported action is performed on ICN, e.g. adding a document, using a search, etc. It is expecting a JSON that contains an array of the properties with its values and attributes to set. Based on the response, the ICN interface will update accordingly.

Expected response: JSON payload with the form:

{
  "externalDataIdentifier": "id meaningful to the service",
  "properties": [
    {
      "symbolicName": "id of the field",   
      "value": <potential new value>,
      "customValidationError": "error message to display",
      "customInvalidItems": [0, 3, 4, 8], //when invalidating multi-value items
      "displayMode": "readonly/readwrite",
      "required": true/false,
      "hidden": true/false,
      "maxValue": overridden maximum value,
      "minValue": overridden minimum value,
      "maxLength": underlying maximum length,
      "hasDependentProperties": true/false,
      "dependentOn": "id of field it is dependent on",
      "format": "a regular expression to validate the value",
      "formatDescription": "text displayed on the tooltip",
      "choiceList": {
        "displayName": "display name of the choice list",
        "choices": [
          {
            "displayName": "<display name of option>",
            "value": <value of option>
          },
          …
        ]
      }
    },
    …
  ]
}

You may find the official specifications on the IBM Knowledge Center here.

Notes on the POST Method

Request Modes in the Request

The requestMode attribute in the request denotes the step of the object lifecycle. The three steps are: initalNewObject, inProgressChanges, finalNewObject when creating an object and initialExistingObject, inProgressChanges, finalExistingObject when updating an existing object. The EDS will be called at those specific steps.

Here are some typical use cases for the request modes:

• We can use the initialNewObject request mode, to assign default values before the screen to add is shown.
• We can use inProgressChanges to populate values based on an option of a choice list.
•  We can use finalNewObject to assign hidden values, for example description, before committing the changes.

clientContext Object in the Request

The clientContext object in the request is used to provide more information about where the web service call is being made. When implementing, always verify the Knowledge Center for the specific product to see if other attributes are being passed in the clientContext that are relevant, e.g. Case Manager includes many more attributes related to the case in the clientContext. Otherwise, the notable attributes we should be aware of are desktop, locale, and action.

The desktop attribute is simply the ICN desktop id. An example of use is to show/hide fields based on which desktop you are on or set fields to read-only based on the desktop.

The locale can be used to return the correct translated error message when a validation failed.

The action attribute describes the active action that is happening. Example of action that can be passed are: addItem, editProperties, openSearchTemplate, multiEditProperties, workflow, etc. We can use it to determine when not to act on any of the properties, for example when searching.

Attributes of Objects in the Properties Arrays in the Response

Other than the symbolicName attribute, the attributes of the object in the properties array are not required to be present when returning the final response. Only the attributes that pertains to the call should be present. For example, if we want to make a field read-only, then only the displayMode attribute needs to be present.

The hasDependentProperties and dependentOn attributes needs to be set of the appropriate fields for ICN to call EDS with the inProgressChanges requestMode when the value changes.

Considerations when Implementing EDS

• Exclusive or inclusive conditions on the action attribute:

After many implementations, we will notice that in numerous cases, we will add attributes to the response based on the action attribute. We need to be careful on whether we do an inclusion-based or exclusion-based. Exclusion-based might be the fastest way as we only specify when the EDS should not do anything, but if a new action gets introduced, it might cause some errors. Inclusion-based is the safest, but it will be hard to gather a list of all the actions we want the EDS to act on.

• Ability to use other back-ends:

Even though all the samples of EDS provided by IBM are implemented using Java servlets, we can implement it in back-end that supports REST as long as the implementation respects the EDS REST protocol specifications. For example, if we already have web services in NodeJS, we can simply add on to it.

• Integrating with existing web services:

Because we can implement EDS in any backend that supports REST, it is encouraged to integrate the EDS with any existing web services. This would allow the reusability of any validation rule that already exists. For example, if a piece of code already exists for validation a client number, we can certainly leverage it for EDS.

• Specification defines the base, specific product will add their own flavor:

The implementation for FileNet P8 and Content Manager are the one closest to the specification document. If we are looking at Datacap or Case Manager, we will notice that many attributes have been added to support the platform. For those, always refer to the Knowledge Center for the implementation specific to those products.