According to the official IBM redbook related to Content Navigator, the External Data Services (a.k.a. EDS) is “an interface that IBM Content Navigator provides to access data from external data sources. EDS can be used to define field validation criteria, prefill the field values, or other custom properties for existing repository metadata during delivery or change of documents or folders.”. Actually, this is a more powerful aplication service than that.

The Web Application structure

The EDS sample provided with the redbook implements 2 type of HttpServlet :

• the GetObjectTypesServlet servlet, implementing the doGet method,
• the UpdateObjectTypeServlet servlet, implementing the doPost method.

The GetObjectTypesServlet servlet

This servlet is triggered to define which document class must be handle by the EDS servlet. When called, this process will return a JSON array string, listing each document or folder class symbolic name which will call the EDS on specific actions.

[ {"symbolicName" : "document_class"}, {"symbolicName" : "another_document_class"} ]

The External Data Services plugin, during it’s initialisation, will query this servlet (using the “http(s)://hostname:port/context_root/types” url) and retrieve all symbolic names. When adding or editing an object using Content Navigator, if this object symbolic name is part of the servlet response, the doPost method from the UpdateObjectTypeServlet servlet will be triggered.

The UpdateObjectTypeServlet servlet

When triggering some specific events (adding / editing a document), Content Navigator will call the update servlet to process values (if the object document class is part of the GetObjectTypesServlet symbolic name’s array).

How to know my object (as a Document or a Folder) status and it’s status?

When calling the EDS, Content Navigator send a complete json object, with the following informations :

• the object identifier which is currently edited (or null if this is a new object),
• the client context, with some useful informations as the client locale, the user id, the Object Store identifier (on Content Platform Engine side), the current desktop,
• the repository identifier (on Content Navigator side),
• the request mode,
• all the object properties, as a JSON array filled with JSON object, providing a pair of key <> value objects,

With all this informations, Content Navigator will send, using the requested uri, the document class currently in use.

Ok, so I have my request, what can I fetch from it ?

The properties array

The properties array will contains, for each property definition attached to the document class, the symbolic name of this property, and a potential value already set (like, for example, a default value provided directly to a property definition or the entry template used to create / edit the object).

The request mode

This JSON property indicates if we are in a whole new object or if we are currently editing an existing object. The request mode can be set by Content Navigator to the following values :

• initialNewObject : this value is set when creating an object and calling the EDS for the first time,
• initialExistingObject : this value is set when accessing the edit page for a specific object,
• inProgressChanges : this value is set when setting / editing properties, if there is dependent properties (as, for example, a choice list depending from another choice list),
• finalNewObject : this value is set when adding effectively a new object,
• finalEditingObject : this value is set when saving an existing object,

When the EDS is triggered, you can know the actual context of a specific call. You can set specific values when the object is created but not saved (for example a date), or verifying all provided informations before sending them to the Content Platform Engine (and providing some error messages if needed).

The client context

Finally, this part can be useful if you have to handle a multilingual application. You will be able, with this JSON object, to know the client locale (when, for example, returning choice lists) or the client identifier (for calling process requiring a specific authentication).

So, I know how to use my datas, what can be returned to Content Navigator ?

Content Navigator, when calling the EDS, will wait for some informations. After processing EDS values, you can write in the associated HttpServletResponse a JSON object containing :

• an externalDataIdentifier (provided in the initial request),
• a JSON array in the properties, containing JSON objects, one object per property.

The properties array

Using this array, you can send back to Content Navigator a set of properties to define :

• the property symbolic name, defined with the symbolicName JSON key,
• the value to set to the property, defined with the value JSON key,
• a set of keys, as customValidationError / customInvalidItems to add specific controls, required / hidden to define the property as required or hidden,
• the display mode to apply to this specific property, can be
  • readonly to display the property as read only (can not be modified),
  • readwrite to display the property as editable,
• a choice list to apply, defined with the choiceList JSON key,
• the dependent property (if applicable), defined with the hasDependendProperties JSON key,
• the dependent on property (if applicable), defined with the dependentOn JSON key
• the dependent value property (if applicable), defined with the dependentValue JSON key,

A dependent property ? Why ?

When defining choice lists, it can be nice to apply some filters on lists, for example when providing a list a country (England, France), and displaying, on country selection, a list of subdivisions applying to the selected country. You can set the hasDependentProperties value to “true” for the country property, and set the dependentOn value to “country” and dependentValue value to “England” or “France”. With those instructions, Content Navigator will be able to filter drop down choices when selecting another element in the “parent” drop down.

I strongly recommend to get the IBM RedBook about developing with IBM Content Navigator, there is a lot of useful informations about the EDS !