Use the default Document Generator

Document Generators allow users to download and save a document with data from a Web Determinations interview. The document is usually a transcript of the interview for record keeping, but can be any document that requires data from the interview to be embedded in it, such as a pre-filled form, letter of advice or even a specially formatted web page.

The default Document Generator allows users to save and print a transcript of their Web Determinations interview in the following formats:

HTML
PDF
XLS
RTF
XML (for debugging)

This topic describes the process necessary to create and debug a basic Interview containing a Document Generation link. Following all the steps in this tutorial will require the following:

Oracle Policy Modeling (you are expected to have installed Oracle Policy Modeling and have previous experience authoring rulebases).
Java application server (this tutorial uses Tomcat).
1 hour (this tutorial should take no longer but can take considerably less).

Go to:

Set up the Document Generation server

Author a basic rulebase

Add document generation capabilities

Summary

Set up the Document Generation server

The first and most important step to take before using the default Document Generation plugin, is to deploy the Document Generation server. This server acts as a wrapped for the BI Publisher Document Generation Engine and without it you will only be able to produce XML files from your document links.

If you already have a working Java application server then please deploy the document-generation-server.war file to this server, making a note of the resultant end-point.

If you don’t have a working Java Application Server, or don’t understand what one is, then the following steps will guide you through installing one.

Install Tomcat:

Use a browser of your choice and proceed to http://tomcat.apache.org/.
On the left you should see a section of links under the Download header; click on the Tomcat 6.0 link – this is the version of Tomcat that we will be using for this tutorial.
Scroll down and find the 32-bit/64-bit Windows Service Installer link – download this file to an easily accessible location.
Launch the installer you have just downloaded; you will be asked to accept a license agreement, which you should read, then asked which components you wish to install. The default of a “Normal” install is fine!
On the next page, make a note of the HTTP/1.1 Connector Port that you choose; this is important as you will need it later.
Proceed through the rest of the installer, making a note of the directory you choose to install Tomcat to, and once it has completed ensure you Run Apache Tomcat. You will likely see a dialog box pop up similar to the one below which indicates that Tomcat is starting up
You should also see a new Tray Icon which, if Tomcat starts up successfully, will display a “Play” symbol as shown below. If Tomcat fails to start and a “Stop” symbol is shown inside the icon, you will need to get in touch with your support team to help you determine why this is happening.
Good! Bad!

Deploy the Document Generation server:

Now that Tomcat has been installed and is running, it’s time to deploy the Document Generation Server as follows:

Locate the Document Generation server; by default it is located in Program Files\Oracle\Policy Modeling\templates\document-generation-server as a file called document-generation-server.war .
Once you have located this file, deploying it is just a case of copying it into the right directory. Navigate to the directory you installed Tomcat to and there you should see a sub directory called webapps.
Copy the document-generation-server.war file into this directory and wait for a few seconds. The first indication that it has been deployed successfully is a new folder that should appear called document-generation-server.
Remember the HTTP/1.1 Connector Port you made a note of earlier? You’ll need that now. Go to http://localhost:8080/document-generation-server (substituting 8080 for the Port you’ve got written down if it is different) where you should see the following, indicating that the deployment has been successful.

Author a basic rulebase

We are now going to author a very quick rulebase that we can use to test out the new Document Generation capabilities found since 10.3.0.

If you already have a working rulebase that you wish to use, you can skip this section and go directly to Add document generation capabilities.

Instead of walking step by step through the process for authoring the rulebase, you will just be given the information required to replicate it on your system.

Rules:

The person is eligible for a fake benefit if

The person is of appropriate age and

The person’s earnings are under the threshold

The person is of appropriate age if

The person’s current age > 59

The person’s current age = YearDifference(the person’s date of birth, the current date)

The person’s earnings are under the threshold if

The person’s yearly income <= 25,000

Data model:

Screens:

Add document generation capabilities

In order to add document generation to our rulebase, we need to do three things:

Create a Document Definition in the Screens file.
Access the automatically generated Document Template, that is used by BI Publisher to define the format and contents of the generated document.
Create a Document link, generally placed on the Summary screen post-interview, to allow access to our generated document.

These things are done in order below for a simple confirmation letter example.

Add a Document definition:

Right click inside the Screens file and you will see the option to add a New Document. You can place this document anywhere inside the Screens file, though it’s recommended that you place it within a specially created Documents folder, to aid organization.

Clicking the New Document option presents you with the following dialog box, the fields for which are explained below:

Field	Description
Document Name	The name by which you will refer to this document – every effort should be made to ensure it is unique unless specifically required otherwise. Good examples would be: “Advice Letter w/Decision Report”, “Claim Form (Ref:ABC1)”.
Public Name	Similar to an Attribute, Entity or Relationship’s public name, this must be unique and if not specified here, will be auto-generated. Good examples would be: “adv_letter_decision_report”, “claim_form_ABC1”.
Template	This is the template file (in rtf format) associated with the document. All templates should be placed in the include\templates\<locale> folder underneath the main rulebase folder. Adding a new document automatically creates a blank document template.
Document Type	Since templates can be used to generate any support document, it is in this drop down that you decide what the format of the final document you generate should be. If you wish to output XML then see the section on adding Document links to screens and specifically the “Generate Xml” flag.
Decision Reports	Adding entries into the Decision Reports list not only ensures that attribute is present, but that a full decision report is also available for it. Take care not to add unnecessary entries here, as they may slow down the document generation process.
Export Schema	This button allows you to export an XSD representation of the Document Definition. This is important as you will generally need to import this XSD file into the BI Publisher Word plugin in order to use the helper functions and dialogs provided. Remember that this XSD file will be different if you make changes to either your rulebase data model or Included Decision Reports.

If you are following our rulebase example, you will need to enter the following into your new document.

Access the Document template and export the schema:

Templates for the document generation process are automatically created when adding a document and are then enriched using Microsoft Word and the BI Publisher Word plugin. It is beyond the scope of this tutorial to attempt to teach you how to author templates for BI Publisher, but a few important points should be noted.

The XSD file exported using the Export Schema button from the Document dialog box we looked at in the last section can be imported into the BI Publisher Word plugin using the Data -> Load XML Schema… menu option, but this can be very slow!
In the next section we will look at saving XML from the Document Generation process, and importing this into the tool instead using the Data -> Load Sample XML Data… option. Not only is this faster but it also makes it much easier to preview the output document from within Word.

If you are following our example rulebase, you will need to do the following:

Export the Document’s Schema to an easily accessible location; you will need to import this into the BI Publisher Word plugin if you don’t want to be authoring blind!
Click on Edit to begin authoring the template.

For our example rulebase, we can use the following template contents:

Fake Company Inc.

Dear Sir/Madam,

With regards to the person who filled out an online interview with us recently;

for-each eligibile text end eligibile

This is because you told us your Date of Birth was:

for-each dob value end dob

And your yearly income was:

for-each yearly_income value end yearly_income

Thank you!

Smith Smithson

President, CEO, Sole Employee

Add a Document link:

The last step is to give the end user a way to access the document. We do this by adding a Document link to the Summary screen of our rulebase. This link will have a number of options that will already be familiar, and two which are not.

Document

This drop down box allows you to pick the document that you wish to generate when this link is clicked with the list in the format of “Document Name [Public Id]”

Generate Xml Data

When checked, this causes the link to bypass the BI Publisher Document Generation Server, instead returning a raw XML representation of the Session. This is useful not just for debugging purposes, but for importing into the BI Publisher Word plugin.

In our example rulebase, the last step is to add a Document link to our summary screen, as shown below:

Known issue

When following the document link from the Summary screen, if the BI Publisher template's Conditional Region settings have not been correctly defined (for example, an incorrect data type has been used), then the user may encounter a generic error. In such a case, it will be necessary to visit the BI Publisher template and make the appropriate adjustments, referring to the BI Publisher user documentation for assistance.

Summary

There is a lot more to the Document Generation capabilities of Oracle Policy Modeling than could be covered in a short tutorial, but the basic steps covered by this document are fundamental to any use of the default document generation process.

For more information, consult the following topics:

Document Generator plugin overview

Create a Document Generator

Document Generator – sample code

Legacy Document Generation