External data services for Datacap Navigator
You can use the IBM® Content Navigator external data services (EDS) REST protocol to get data such as files or database tables from an external source. You can use the external data to customize field properties and manage property behavior in Datacap Navigator.
When you create an external data service, the data is integrated with Datacap field values and other field properties, and you continue to store and maintain the data only in the original, authoritative data source.
An advantage to using an external data service is that you do not need to modify the Datacap source code to customize field values and behavior. Upgrades and other major changes to Datacap do not affect the field data that is obtained by an external data service. The data and external data service are located separately from Datacap source code.
Where external data services can be implemented
You can implement external data services for the following fields in Datacap Navigator:
- Fields on the verify page
- Batch level fields in the start panel and batch editor panel
- Extra fields in the start panel and batch editor panel
- Batch attributes in the start panel and batch editor panel
You can use external data services to customize the following field properties and property behaviors:
- Look up values in a database to create choice lists
- Create choice lists by using existing data that is managed in a different content repository or data source outside of Datacap.
- For example, you can use values in a file that is located and managed in an external server or repository.
- Prefill properties
- Specify prefilled properties and default values.
- For example, you can prefill fields with custom default values that are based on a particular field ID, authenticated user, or the application.
- Set DataType variable
- Specify the DataType variable for a field so that you can specify different editors when you create custom panel. For more information about DataType variable, see DataType.
- Set minimum and maximum values
- Specify an integer, float, or date to define the maximum or minimum value for a field.
- Set read-only status
- Set a field to be read-only.
- For example, you might create a property that requires a particular value. To prevent users from entering a different value that could cause an error, you can specify the correct default value and make that property read-only.
- Set required status
- Set a property to be a required field. When you use this attribute on a property, an asterisk appears in the user interface to indicate that the field is required. Users cannot proceed from the page or dialog box unless the field contains a value.
- Set hidden status
- Hide a property from the user interface.
- Show a custom message or provide assistance when users enter values
into a property field. Restriction: You cannot use custom validation for object properties, reference attributes, read-only properties, hidden properties, or search criteria.
- For example, you might create a choice list that dynamically determines subsequent text input fields to present in a form. To hide a property that does not apply in a particular situation, you can use the hidden attribute.
- Implement field validation and error checking
- Show a custom message or provide assistance when users enter values
into a property field. Restriction: You cannot use custom validation for object properties, reference attributes, read-only properties, hidden properties, or search criteria.
EDS REST protocol specifications
- Object types resource
- The object type resource represents the names of the Datacap applications to get for the external data service. Example
response for Datacap Navigator:
[ {"symbolicName": "TravelDocs"}, {"symbolicName": "FastClaim"} ] - For more information, see Object types resource.
- Particular object type resource
The particular object type resource represents the properties for which property values are obtained from an external data source. When the user scans a batch, edits a batch, or verifies a batch of a particular Datacap application, the EDS REST protocol uses the particular object type resource to obtain data for the corresponding Datacap application from the external data source.
- Request modes
- initialNewObject is supported.
- Response payload
- The following parameters are supported: choiceList, format, formatDescription, required, and value.
For more information, see Particular object type resource.
Request modes
The following request modes are supported by Datacap Navigator:| Request mode | Datacap action |
|---|---|
| initialExistingObject | Create batch Get batch list Get page file Get data file |
| inProgressChanges | Get dependent attribute information Save page file Save data file |
| finalExistingObject | Save page file Save data file Save batch attributes |
For more information, see Request modes.
Sample external data service
A sample external data service and JSON files are installed by default in the C:\datacap\tmweb.java\samples directory. To download the latest version of the sample external data service and JSON files, including all fixes and updates, see: EDS sample for Datacap Navigator.
To deploy the EDS sample, see Deploying the sample external data service.
In the sample external data service, the values for a choice list are used from an external data source.
The sample service is implemented against the TravelDocs sample application. You can use the sample service as an example and as a starting point for your own external data service. The sample service consists of a GetObjectTypes servlet, an UpdateObjectTypes servlet, the object types resource JSON file, JSON files as the data source, and the web.xml deployment file.
The application name is set as the objectType, and you can add a symbolicName for each field (page field, batch level field, or extra field) in the application. For more information, see the TravelDocs_PropertyData.json and ObjectTypes.json files that are provided with the sample service.
Modify the sample external data service as required for your application. Then, deploy the service in the web application server as follows.
- Deploy the DatacapEDSService application into your application container.
- Deploy edsPlugin into IBM Content Navigator. edsPlugin is a plug-in that is provided with IBM Content Navigator. Confirm that edsPlugin is enabled after deployment.
- Edit edsPlugin. Point the edsPlugin configuration URL to the external data service, for example: http://IP_address:port/DatacapEDSService.
- Log out and log on to the desktop in which you want to use the external data service.