First of all, apologies for the atrocious titles - they are automagically generating by the new blogging platform, and I can't help myself in using some of these ridiculous titles ? Anyway, the subject of this post is how to use the External Data Transaction feature of Documaker Interactive. You might also know this capability by some other names, such as data pull or systems integration, but what this means is that we can start a new transaction in Documaker Interactive, and then engage the EDT capability to pull data from an external system for population into our new transaction. The definition in the ODEE 12.6 Administration Guide on page 55 states that:
"Documaker Interactive provides the ability to initiate a new document with a data source to provide variable content and form triggering information. The goal is to allow users to create new documents within Documaker Interactive without having to enter all data by hand if it is already available in an external system."
Side Note: I've tested this with the 12.6 system, but the feature has been around for a while. If you need to stand up a system to test this, you can get going quickly with my Green Field series to stand up a 12.3, 12.4, 12.5, or 12.6 system.
The use-case definition for this feature is succinct: "a document generation must support the ability to retrieve data from an external source, either a system or file, to augment or enrich data provided by the user." To satisfy the use case, Documaker Interactive (DI) consumes a web service that must implement three specific methods. This web service, which is a custom integration component, is not part of base product and is expected to be developed and implemented by the customer or integrator.
DI expects the web service to provide the following methods:
- getKeys: This method provides an HTML form to facilitate key data entry. The form should supply all key data inputs necessary to facilitate integration and data retrieval from the customer system(s). DI uses this method to present a form to the user for collecting the data.
- getData: This method performs the actual integration to customer system(s). DI invokes this method and sents a byte buffer containing the user-entered key data. This method must be customized to perform the necessary functions required to use the key data for the purpose of collecting additional data from external systems, form that data into an acceptable XML document that conforms to the Documaker extract file schema for the resource library, and return the XML data as a byte array.
- validateFile: This method is invoked when the external source is a file, and provides a mechanism to validate that the file conforms to any requirements stipulated by the customer. This method is used only for validation and not for enrichment.
By now you've probably grasped the idea that DI invokes a web service method (getKeys) that hands DI an HTML form for user data input. This data input is then handed off to another web service method (getData) that is responsible for integrating to external systems for obtaining additional data, which is returned to DI. DI then uses that data to generate documents with filled-in fields. There is an additional option that allows the user to get a file from a file system and submit to DI. DI will then invoke a web service method (validateFile) to ensure that the file meets any implementation-specific criteria. This means that there are two possible ways to use EDT that are differentiated by the source of the data: external system data, or external file data.
Creating a Web Service
The integration web service can be any web service on any container you choose. It is likely that you'll be integrating with an ESB or SOA architecture to orchestrate requests. Regardless of how the integration is done, you will need to implement the web service methods described above. The easiest way to do this is to start with a WSDL for these methods and use top-down methods for web service development. You can grab my sample WSDL, and use your favorite IDE to whip up the services that conform to the WSDL. Oracle has a handy tutorial on top-down web service design with JDeveloper 12c. Write your code and deploy to your preferred container (WebLogic, right? ?) and then you're ready to go. If you're really lost, I have a sample on GitHub that is a basic stub that illustrates the built web service - you'll need to modify the methods getForm(), validateFile(), and getData() methods in ExternalDataTransaction.java to meet your specifications and requirements.
Enabling the EDT Features
To enable the EDT features within DI, you'll need to add the EDT abilities to an ability set. This exposes the buttons within DI for EDT to all users who belong to groups ("entities") which have been assigned an ability set containing the EDT abilities. You will need to know some information prior to getting starting, so here's a handy checklist:
- Which abilities are needed? External Data ability provides the button to obtain external system data. External Data File provides the button to obtain external data from a file.
- Which users need this ability? You will need to know which group(s) of users require this ability. Remember that DI assigns abilities in a collection called an ability set which is granted to a group of users, called entities. Ability sets are not assigned individually to users. This answer will guide you in determining the remaining answers.
- Which entities will be assigned this ability? Recalling the previous question, this is the list of entities that are groups of users which require this ability.
- Which ability sets will receive this ability? If your DI implementation is like the reference implementation, you likely have the standard ability sets, in which case Drafters is your probable choice. You may have a special subgroup of users that will have this ability, in which case you'll want to have those users added to a new group which is then mapped to a new ability set that will have this ability.
With the above answers in hand:
- Open Documaker Administrator
- Select Entities and Ability Sets tab
- Select Define Ability Sets
- Select the ability set (e.g. Drafters) and click Edit, or create a new one.
- Check the Accessible, Editable, and Visible properties for the abilities you need (recall the External Data and External Data File abilities.
Next, you'll need to tell DI where your custom web service has been deployed.
- Open the Documaker Administrator and select the Configuration tab.
- Locate your Documaker system and expand it, then expand the Assembly Line you wish to modify.
- Locate the Correspondence application and select it, then click Configure.
- Select the Configuration, and Systems, then selected your Documaker system.
- Expand the system and select the Correspondence application, and click Configure.
- Locate and select the context-category-group EDTCLIENT - EDT_CLIENT_DATA - EDT_CLIENT_DATA.
- You'll see the properties for this group listed. Edit the settings:
- (class) - Do not change the value of this property. It must be oracle.documaker.idocumaker.bean.EDTClientData.
- edtDialogTitle - set this to be the title of the dialog box shown to the user for entering key data.
- fileDialogTitle - set this to be the title of the dialog box shown to the user for selecting an external data file to import.
- edtServiceAddress - this is the endpoint of the integration web service that you developed and deployed in the section Create a Web Service. You'll need to modify this value to match the host and server to which you deploy the service, making sure the port and context are all correct.
- Click Save.
- Locate and select the context-category-group PUBLICLIENT - PUBLISH_CLIENT_DATA - PUBLISH_CLIENT_DATA.
- You'll see the properties listed. Verify that the settings are as shown:
- (class) - Do not change this value. It must be oracle.documaker.idocumaker.psclient.PublishServiceData.
- publishServiceAddress - this correlates to the endpoint of your DWS web service. Verify the host and port settings, and the remainder of the URL is correct for your assembly line.
- Click save.
Amazingly, that's it! You should now be able to restart the managed server where DI is deployed (e.g. idm_server or wherever you have deployed DI). Once the system starts up, login with a user that is a member of a group that has the assigned ability set for the appropriate type of external data you are going to test. Start a new transaction and you should have see the button(s) available to retrieve data and populate your forms. A few helpful key hints:
- Make sure the data returned from getData() matches your MRL extract data dictionary structure! This is a must, because DI actually invokes Documaker to process the data, so it will need to conform to that structure.
- Make sure your DWS implementation is available, e.g. up and running. DI uses it in this scenario in the first bullet.
- If you run into trouble, talk to your Oracle Documaker consultant or head over to the Oracle Documaker community for assistance.