Document Generator Plugin Overview

Users require a transcript when going through any interview, so that they have:

 

The client system running the Web Determination interview needs to be able to provide this, and also be able to define what data from the interview session is displayed in the transcript, and how it is displayed (layout).

Oracle Policy Modeling allows rulebase authors to create reports of the Web Determination interview, accessible by the user from the Summary screen. With the report links, users can view and download information transcript about the interview session as a document.

The Document Generator plugin is an Engine Session plugin to the Interview Engine that allows plugin developers to generate those documents in any document type, and also define the document layout and which session data is displayed. A Document Generator is known by the document type it provides; for example, HTML, PDF, XML and so on.

By default, Web Determinations ships with two Document Generators for HTML and PDF. For more information about using these, see the topic, Use the default Document Generator.

Multiple Document Generators can be used together during a Web Determinations interview session, allowing users to view the interview transcript in various formats. This is different to other plugins where only one plugin can be used during an interview session; for example, Data Adaptor plugins.  Each Document Generator provides a specific document type, therefore it is imperative that all Document Generators registered during a Web Determinations interview, must provide unique document types.

Go to:

Common Scenarios

Document Generator and the Web Determination Architecture

Developing a Document Generator for a specific project/implementation

Miscellaneous Notes

See also:

Use the Default Document Generator

Document Generator - Pseudo Code

Document Generator - Sample Code

Common Scenarios

The following are brief descriptions of common implementation scenarios that use the Document Generator:

Downloadable Web Determinations Interview transcripts

If there is an official paper form in use for whatever purpose, that can be filled-out online via Web Determinations.  When the Web Determinations interview is complete, the Summary screen includes a download link for the form to save for your records.  It is important that the downloaded form be exactly the same as the official blank paper version with the blanks filled in. The form is generated using the PDF of the blank form as a template, with the interview data filled in in the appropriate places.

Email or save-to-datasource transcript

This is a variation of downloading the transcript, where a client's department can choose to allow the user to email the transcript to an email address, or allow the client's department to save the transcript to a Content Management System or a database.

Customized Summary pages without using Custom Screens

After an interview is completed, a client's department would like to show the citizen a summary webpage describing the outcome, a decision report on why that outcome occurred, and arbitrary summary data from the interview that the department determines to be important. This is not really different from a custom screen, but the department would like to generate the aforementioned 'complicated' summary page using simple configurable templates rather than coding up a custom screen themselves.

Document Generator and the Web Determination Architecture

This section details how the Document Generator fits into the Web Determinations architecture, and how to use it in the Web Determinations environment

How Web Determinations uses Document Generator plugins by default

For a Document Generator (for example, HTMLDocumentGenerator) to be used during a Web Determinations interview, the rulebase author must first provide the user with a Document link. Document links are displayed in the Summary screen via the Oracle Policy Modeling screen authoring, and are associated with a Document Type. The Document Type (doctype) of the link must match the doctype that the Document Generator plugin provides (in this case HTML).

Assuming that a HTML Document link is available to the user in a hypothetical Web Determinations interview, the Document Generator is invoked when the user clicks on that Document link in the Summary screen. When the link is clicked, the following occurs:

  1. Web Determinations retrieves a list of all the Document Generators registered on the current interview session
  2. Web Determinations then checks each Document Generator in the list to see if any has a doctype that matches the doctype (HTML) of the link.
  3. If a Document Generator is found, the generateDocument() is called, which returns a TypedInputStream (InputStream wrapper). This returns the (HTML) document to the user for viewing and download
  4. If a Document Generator is not found (for example, because that specific Document Generator had errors being loaded during Web Determinations startup), then an error will be displayed to the user. 

Document Generator plugin and other Web Determination Extensions

Other ways in which Document Generators is used in Web Determinations is through other Introduction to Web Determinations Extensions.The Document Generator is accessible via the InterviewSession object, so only Web Determinations Extensions with access to this object or its parent object 'SessionContext' may use Document Generators.

Because document links are specific document actions that are supposed to return binary responses, only Custom Screens can be used to call a Document Generator and return its InputStream as a binary Response. 

Another way of using a Document Generator InputStream is by using an Event Handler to generate a document from a Document Generator, and then using the file; for example, email it or save onto a datasource such as a filesystem or database.

The following is a piece of sample code to generate documents:

TypedInputStream document = interviewSession.getDocumentGeneratorService().generateDocument(documentType, parameters);

An event is fired when the user initiates a document generation action. This event is called 'OnGenerateDocumentEvent', and allows the event handler to override the normal document output from the Document Generator. If the event handler populates the 'replacement document' member in the event itself, Web Determinations will use the replacement document instead of the normal document output.

Error Handling

An IOException can be thrown by a Document Generator plugin, and this will result in an error page containing a message specific to the IOException, being displayed. For non-IO exceptions such as a connection error to a database, other standard plugin exceptions can be raised. For more information, refer to the topic, Web Determinations Extensions - Technical Details

Document Generator Class Methods

A Document Generator plugin implements the DocumentGeneratorPlugin interface, which in turn extends the DataAdaptor interface as well as the InterviewSessionPlugin interface. When implemented, he DocumentGeneratorPlugin interface requires the following:

 

Method Signature
Description
TypedInputStream generateDocument(
InterviewSession session,
DocumentGenerationParameters parameters)
  • The InterviewSession contains information about the current Web Determinations interview such as the rulebase and instance data.
  • The DocumentGenerationParameters contains a list of parameters that can be read and used by the Document Generator, and any attributes that should have their Decision Reports generated with the document.
  • The parameters in the DocumentGenerationParameters during default process are the path for:
    • template file - usually an XSL file to transform XML to the default HTML and PDF documents. This value is from the template field of the Document item which the user clicked in the Web Determinations interview Summary screen to call this method.
    • configuration file - the configuration file which the plugin will use to modify document generation parameters. This may or may not be empty
  • an object of TypedInputStream is returned, which is commonly returned by Web Determinations to the user as a downloadable binary file
String getDocumentType()
  • returns the document type that the current Document Generator is responsible for processing and generating.

Developing a Document Generator for a specific project/implementation

This section explains the various approaches on designing and developing a Document Generator plugin for a specific project/implementation.

Factors to consider when designing a Document Generator plugin

When designing a Document Generator plugin, consider the following:

 

Essentially, the Document Generator plugin needs to have the following functionality:

Programming the method 'generateDocument()'

It is important to understand the two input arguments for the DocumentGenerator method 'generateDocument()'.

1. InterviewSession

The InterviewSession object is useful for the instance data provided by the user during the Web Determinations interview. The InterviewSession object can also provide the rulebase used, rulebase model data, locale, and so on. More information about the InterviewSession can be found in Web Determinations Extensions - Technical Details#About the InterviewSession

2. DocumentGeneratorParameters

The DocumentGeneratorParameters object have the following members:

Using the input arguments

The InterviewSession object contains the important instance data provided by the user. Sample code to extract instance data in the InterviewSession can be found in Understanding the InterviewSession.

Document styling and layout can be programmed into the Document Generator plugin, or for maintainability and flexibility it can be stored in a 'template file' that is read by the Document Generator when generating the document.

Programmatic logic to control layout, styling, data, metadata, and so on, can use all the data available, but notably the rulebase model data, instance data, and the attributes in the DecisionReportTargets list

Miscellaneous Notes