Creating an external data service for IBM Content Navigator

Use the EDS REST protocol to create an external data service that specifies requests to get data from an external data source to customize field properties and manage property behavior in IBM Content Navigator. You implement an external data service as a web application.

Before you begin

Understand which properties and areas in IBM Content Navigator you can customize through an external data service.

Review the specifications for defining an object types request and a particular object type request.

You need the following skills to implement an external data service:

Java™
Java 2 Platform, Enterprise Edition
Implement a web application with two services, for example, two Java servlets
Read and write JSON

About this task

As you design your service, consider the following tips to improve the usability of your choice lists and other field properties:

Reduce the size of choice lists by adding properties that can narrow subsequent lists: For example, you can use questions to narrow the scope of the list, or use dependencies between properties to break long choice lists into shorter choice lists.
Create dependent choice lists: Dependent choice list values are replaced with a different list depending on the value that is selected in the preceding parent list. For example, you can set up Region and Branch Office choice lists, where the Branch Office list depends on the Region list selection. If the user selects a different region, the Branch Office list is cleared and populated by a different list of branch offices.
Implement custom validation so that users can immediately resolve any errors in data entry.: For example, if you implement text fields that have character restrictions, instead of using a custom validation error message to display only a description of the error, you can also provide users with a list of the unsupported characters so that users can avoid typing those characters in the future.

Procedure

To create an external data service:

Create a service that gets the list of classes to be handled by the external data service. For workflow information, you create a service that gets the list of registered service types instead of classes.
For example, you might create a GetObjectTypes service:
- Request: GET /types?repositoryId=repository_Id.
- Response:
```
[
	{
		“symbolicName” : “object_type_or_service_type”
	}
	// More object types
]
```
  This service is invoked with the GET request, which provides the repository ID. The response in this example is an array of name values in a JSON file. This list must contain all the classes that are to be supported by the external data service.

Create a service that gets current attributes and values for each class that is included in the service that you created in the previous step. This service gets current attributes and values for a class and then returns information about those properties to the middle tier services.

The data that is posted is JSON, and the response is also JSON.

For example, you might create an UpdateObjectType servlet that handles a POST method with a URL of the form /type/object_type_name:

Request:

POST /type/class_name_or_item_type_name
		
{
	"repositoryId":"target_repository",
	"objectId" : "if_an_existing_instance,_the_GUID_or_PID",
	"requestMode" : "indicates_context_that_info_is_being_requested",
	"externalDataIdentifier" : "opaque_identifier_meaningful_to_service",
	"properties":
	[
		{
			"symbolicName" : "symbolic_name", 
			"value" : "the_current_value",
		}
		// More properties ...
	]
}

Response:

{
  "externalDataIdentifier": "opaque_identifier_meaningful_to_the_service", 
  "properties": 
		[
     {
       "symbolicName": "symbolic_name",
       "choiceList": 
       {
         "displayName": "display_name",
         "choices": 
         [{
             "displayName": "name",
             "value": value
           },
           // More choices in the choice list
         ]
				}
     }
		 // More properties
   ]
}

What to do next

After you write the external data service, you must deploy and start your service in the web application server, and register the EDSSupportPlugin plug-in in the IBM Content Navigator administration tool.