Sometimes just running through an interview isn’t enough; you need a way to provide users with some or all of:
Oracle Policy Modeling allows rulebase authors to create documents from interviews performed in either Web Determinations or the Determinations Server. These documents are accessible either by links inserted into interactive screens, or programmatically by way of the Determinations Server API.
Providing such a document is the responsibility of the Document Generator plugin, which since Oracle Policy Automation (OPA) v10.3.0, is based on Oracle Business Intelligence Publisher (BI Publisher). The version of BI Publisher used was upgraded in OPA 10.4 Update 5 from v11.1.1.3 to v11.1.1.7 and then updated in OPA 10.4 Update 7 from v11.1.1.7 to v11.1.1.9.
With this support, users can view and download transcripts about the interview session in a variety of different formats. Oracle Policy Automation ships with support for HTML, RTF, PDF and Excel documents out of the box, though this functionality can be extended through the use of a Custom plugin.
The Document Generator plugin is an Engine Session plugin to the Interview Engine that allows rule authors to generate those documents in a given type, and also define the document layout and which session data is displayed.
Only one Document Generator plugin is used by the Engine at any one point and while by default, Web Determinations ships with a BI Publisher Document Generator plugin, this can be replaced by a Custom plugin. For more information about using the default plugin, see the topic, Use the Default Document Generator.
When providing a Custom Document Generator plugin it is still possible to call the BI Publisher plugin, therefore providing a way to easily extend the Document Generation ability of Web Determinations without losing existing functionality.
Document Generator and the Web Determination architecture
Developing a Document Generator for a specific project/implementation
Use the Default Document Generator
Document Generator - sample code
The following are brief descriptions of common implementation scenarios that use the Document Generator:
Often Web Determinations is used in places where an official form already exists. One common scenario is self service applications in which potential clients can use Web Determinations to conduct a guided interview to assess their eligibility for a range of benefits and services.
When the Web Determinations interview is complete, the Summary screen includes a download link for the form that has been pre-populated with information provided during the interview and which the user is able to print, sign and send off in order to have their claim processed. This is especially useful when the user must provide additional evidence with their application, that it is not possible to validate in an online interview.
In many situations where there is interaction with a customer, it can be beneficial to provide them with a summary of either the changes they have made or the advice they have received in the form of a letter.
Take the example of a call center where a person has called to advise of a change in circumstances. The call center agent uses a Web Determinations interview to collect the change in circumstance information and determine what effect that has on the client’s current situation. At the conclusion of the interview, the agent can then use the document generation process to generate a letter detailing the change of circumstance information and its effect, which can then be mailed or e-mailed to the client.
While the data adaptors give you the ability to save the current state of user entered information in an interview, it may not always be possible to record the full audit trail of why the decision was made, or to do so in a human readable format.
Where, for auditing purposes, it is required that a breakdown of the interview including decision reports be saved out, the document generation process can be used to provide a document that can be saved for later retrieval. This document would be fully customizable to a format best suiting the purposes of the audit.
This section details how the Document Generator fits into the Web Determinations architecture, and how to use it in the Web Determinations environment. It is important to note the following terms:
BIPublisherDocumentGenerator - the Interview Engine Plugin providing default document generation.
BI Publisher FOP Engine - a set of Java Libraries used to compile templates and render documents.
Document Generation Server - a Java Servlet wrapping the BI Publisher FOP Engine, used by both the Java and .Net BIPublisherDocumentGenerator plugins
DocumentTemplate - an object containing the parameters required to generate a document, including the document’s id, name and the location of the template it uses
RTF Template - the template produced in Word which is compiled by the BI Publisher FOP Engine and used to generate documents.
Only one Document Generator is ever “active” in the Engine at once. By default this is the BIPublisherDocumentGenerator, and this is replaced when a Custom Document Generator Plugin is detected and loaded.
The plugin itself is responsible for generating XML from the session and maintaining a list of templates, but it only acts as a proxy for the document generation process. The actual generation of a given document from the session XML and template is done by the Document Generation server.
In this way it is possible to have one back-end FOP Engine being used by multiple Web Determination and Determination Server deployments, thus reducing infrastructure and licensing overheads.
The two most common ways of calling the Document Generator are via either a link in a Web Determinations interview, defined by a rule author, or via the Generate Document method of the Determinations Server. These two methods both follow the same procedure.
Each time a new InterviewSession is instantiated it creates a new instance of the BI Publisher plugin. This instance is created based on the target URL of the Document Generation server and the locale of the session.
When a document is requested, a call is made to the Interview Session’s GenerateDocument method, with the ID of the DocumentTemplate to be generated and a flag indicating whether or not only the session XML should be returned (GenerateXml).
If this flag is set then the plugin bypasses the template compilation check and document generation stage, instead returning the session XML straight back to the user in place of the document. This is useful for producing sample XML that can be imported into the BI Publisher Authoring plugin for Word.
Assuming the DocumentTemplate can be found, a check is made to see if the RTF template is available. This template must be compiled before it can be used by the BI Publisher FOP Engine and this compilation process occurs automatically when a template is used for the first time. Compiled versions of the templates are cached in the BIPublisherDocumentGenerator plugin, and used for subsequent requests until a change to the deployed rulebase is detected. At this point, the template is flagged to be reloaded and recompiled on the next request.
Assuming a successful call to the Document Generation server, the document is returned as a TypedInputStream, for either display to the end user or transmission by the Determinations Server.
Since the plugin is accessible via the InterviewSession it is also possible to trigger document generation from custom plugins and event handlers. This is especially useful in cases where you wish to save or forward the generated document automatically.
When calling the generateDocument method of an InterviewSession the only required parameter is the public id of the document you wish to generate. This is defined by the rule authors when the document is added to the Screens file. A list of DocumentTemplates is also available through the InterviewRulebase object itself by calling the getDocumentRegistry method with the appropriate locale.
The following is a piece of sample code to generate a document with the id of “final_report” from an InterviewSession object stored in iSession (Note that the second argument indicates we do not wish for the session XML to be returned in place of the document):
TypedInputStream document = iSession.generateDocument(“final_report”, false);
A Document Generator plugin implements the DocumentGeneratorPlugin interface, which in turn extends the InterviewSessionPlugin interface. When implemented, the DocumentGeneratorPlugin interface requires the following methods:
|
Method Signature |
Description |
|---|---|
|
TypedInputStream generateDocument( InterviewSession session, DocumentTemplate parameters, Boolean generateXml) |
|
|
String getInstance() |
|
This section explains the various approaches on designing and developing a Document Generator plugin for a specific project/implementation.
When designing a Document Generator plugin, consider the following:
Essentially, the Document Generator plugin needs to have the following functionality:
It is important to understand the three input arguments for the DocumentGenerator method generateDocument().
- Strings Id, Name, Template, Type
- These strings define the basic identifying information for the DocumentTemplate and detail where the template to be used is stored.
- Booleans includeUserSet, includeGoal, includeIntermediate
- These booleans define which subset of attributes should be included in the generated document.
- DecisionReportTarget[] includedDecisionReports
- A list of attributes or relationships that should be taken note of by the Document Generator. Each Document item in the screens file (when in Oracle Policy Modeling Screen authoring) has a list of attributes for 'Decision Reporting'. How a Document Generator uses this list of attributes is up to the implementor of that Document Generator - it can be simply ignored, or decision reports for each of the attributes generated in the document, or maybe even just a subset of the attributes in the list.
- Map customProps
- A map containing any custom properties set for the document when it was created in Oracle Policy Modeling.
The BIPublisherDocumentGenerator class contains a static method generateXml which can be used by Custom Document Generators to translate a given session into xml format based on a DocumentTemplate object. This can be useful when designing a custom document generator as it bypasses the need to worry about session formatting and allows the document generator to focus on transforming the session xml into the appropriate output format.