Develop a template for an interview document

Develop a template for an interview document

An RTF template is used to generate the interview document. This RTF file is created in Microsoft Word using the BI Publisher Template Builder. The Template Builder is a tool that simplifies the development of RTF templates.

Note: If you cannot see the BI Publisher Ribbon in your Microsoft Word document after you open it from Policy Modeling, you need to install BI Publisher Desktop. For more information, see Download BI Publisher.

 

There are 4 steps in the process of developing a template for an interview document:

  1. Create a template file
  2. Load the XML data into the file
  3. Design the template
  4. Preview the document

 

If you are familiar with developing BI Publisher templates and just need to know the format to use for the fields, refer to the BI Publisher code for Oracle Policy Modeling topic.

Create a template file

A default RTF template is created automatically when you add a new document to your screens file. This file, <project name>_Template.rtf, is located in the \include\templates\<locale> folder for the project.

Alternatively, you can reuse an existing RTF template file, but make sure that you select that file in the Template field in the Document editor in your screens file (it will then be automatically copied into the include\templates\<locale> folder).

Open a template file

The template file can be opened for editing in Word by clicking on the Edit button in the Document editor in the screens file in Oracle Policy Modeling:

 

 

Alternatively, you can open the template file from its location in the project under \include\templates\<locale> using Microsoft Word or Windows Explorer.

Load the XML data

In order to add fields to your template you first need to load data into the BI Publisher Template Builder in Word. The simplest way to do this is to import the XML schema file (XSD) that you created when you added the document to your screens file.

Load the XML schema

  1. On the BI Publisher toolbar, select XML Schema:



  2. In the dialog box, select the XML schema file (XSD) that you exported when you added the document to your screens file. You will be told when this data has been loaded successfully.

NOTE: Sample data can also be loaded and used in the development of the template. You would only do this though if you needed to see the full list of fields that are generated. Typically, you will only want to include the text and/or the formatted value of the attributes in the session in your template in which case the XML schema, rather than the sample XML, is considerably more user-friendly. TIP: Even if you do want other field types in your template that are not included in the XML schema, you can use one of the fields for the attribute that is in the schema and customize it to be what you need (see below).

Design the template

In addition to normal Word components, a template can include:

Insert a field

Fields in BI Publisher are used to display values and properties of attributes (global and entity-level), decision reports and conditional text.

To insert a field into a template:

  1. Put your cursor in the place in your document template where you would like to insert the field. Click the Field button on the BI Publisher menu:



    (If you have not already loaded a data source, you will be prompted to do so now.)
  2. In the Field dialog box, select the field that you want to insert (for example, to insert the text for the global attribute for the claimant's name, select the Name Value field in the Global-instance folder):



  3. Either drag and drop the field to the desired location in your template, or click the Insert button in the Field dialog box. Close the Field dialog box. Your field should look something like this:



IMPORTANT NOTE: For attribute values (formatted for the project region) and attribute text this is all you need to do. For other field types (eg unformatted attribute values, attribute question text, attribute type, decision reports, conditional text etc) you need to customize a BI Publisher field (see below).

Customize a BI Publisher field

The BI Publisher code for all fields, other than attribute values (formatted) and attribute text, needs to be customized.

  1. Follow the steps above for inserting a field into your template. Use either the Value or Text field for the relevant attribute (it does not matter which as you will be customizing the field anyway).
  2. Double-click on the field in the template to open the BI Publisher Properties dialog box. (TIP: If double-clicking the field does not open the BI Publisher Properties dialog, re-load your XML.)
  3. Click on the Advanced tab. The code here needs to be modified to point to the property of the attribute that you want to be displayed (note that the code is case-sensitive). For example, if you wanted to display the attribute question text for the publicly-named 'improvements' attribute, you would enter the Code "<?improvements/@question?>":



  4. Select this text and copy it (Ctrl+C), then paste it (Ctrl+V) into the Text to display field (either on the Properties or Advanced tab).
  5. Click OK. The field in your template should look something like this:



For the format required for other fields, see BI Publisher code for Oracle Policy Modeling.

TIP: The Healthy Eating example rulebase that is installed with Oracle Policy Modeling, contains a Raw Template Example RTF file that you can use to copy and paste the code from for various fields. You just need to replace the attribute id (ie public name) in the code, and update the display text as necessary.

Insert a decision report

To insert a decision report for an attribute into your template there are 3 things you need to do:

  1. In Oracle Policy Modeling, add the attribute to the Decision Reports available for the document.



  2. Somewhere in your template document, have a "decision-report template" field, which tells BI Publisher how to structure and format a decision report. Follow the steps earlier for inserting a field into your template. The field needs to be customized to have the following code specified in the Advanced tab for the field:

    <?template@inlines:decision-report?>
    <?if@inlines:"attribute-node"?>
    <fo:list-block start-indent="{count(ancestor::attribute-node) * 7}mm">
    <fo:list-item>
    <fo:list-item-label>
    <fo:block>*</fo:block>
    </fo:list-item-label>
    <fo:list-item-body>
    <fo:block><xsl:value-of select="@text"/></fo:block>
    </fo:list-item-body>
    </fo:list-item>
    </fo:list-block>
    <?for-each@inlines:./attribute-node?><?call-template:decision-report?><?end for-each?>
    <?end if?>
    <?end template?>

    The Text to display setting (on either the Properties or Advanced tab) should be updated to say decision-report template.
  3. In the place in your template document where you want the decision report to appear, have a "call decision report template" field which specifies the attribute ("attribute_id") to give the decision report on. To do this, follow the steps earlier for inserting a field into your template. The field needs to be customized to have the following code specified in the Advanced tab for the field, where "attribute_id" is replaced by the goal attribute that will be used for the decision report:

    <?for-each:/global-instance/attribute_id/decision-report/*?><?call-template:decision-report?><?end for-each?>

    For example:



    The Text to display setting (either on the Properties or Advanced tab) also needs to be updated to say call decision report template.

    The resulting fields in your template should look like this:


Insert conditional text

You can specify that certain text is only shown when a particular condition is met. Both simple conditions and multiple conditions are supported in BI Publisher. Conditional text can be achieved by:

  1. Using the BI Publisher Conditional Region dialog, or
  2. Manually defining the conditional fields.

 

The Conditional Region dialog can be used when the condition is that an attribute EQUALS a value. It can also be used for greater/less than comparisons for number variables provided you select 'Number' from the drop-down list (see below).

 

To insert conditional text using the Conditional Region dialog:

  1. In your template write the text that you would like displayed under certain conditions.



  2. Select the text.



  3. Click on the Conditional Region button on the BI Publisher menu:



    The following BI Publisher dialog will be displayed:



  4. In the General box, select the attribute whose value you want to base the condition on from the Data field drop-down list. (TIP: Make sure you have the XML schema loaded  in your document, not the sample data, to make it easier to use and find attributes in this drop-down list.)



  5. Also in the General box, select the attribute type from the drop-down list. NOTE: These are BI Publisher types so use "Number" for Oracle Policy Automation number variables and "Date/Text" for Booleans and for all other variable types including currency.



  6. In the Condition 1 box, select the condition that applies to the attribute from the Data field drop-down list.



  7. Also in the Condition 1 box, type in the condition value (formatted).



  8. Click OK. The following BI Publisher fields will appear around the conditional text in your template (C stand for Condition, EC stands for End Condition):



Alternatively, you can manually define your own conditional region by following the format described below.

Simple conditions take the following format:

Multiple conditions take this format:

Note that the conditions in these elements use unformatted attribute values and need to follow a particular syntax (see examples BI Publisher code for Oracle Policy Modeling for more information).

 

To manually insert simple conditional text:

  1. Insert a field for the relevant attribute value into your template.
  2. Double-click on the field in the template to open the BI Publisher Properties dialog box. (TIP: If double-clicking the field does not open the BI Publisher Properties dialog, re-load your XML.)
  3. Click on the Advanced tab. Enter the code for the start of the condition (eg <?if:attribute_id/value='value'?>):



  4. Select the code text and copy it (Ctrl+C), then paste it (Ctrl+V) into the Text to display field. Click OK.
  5. In your template document after the if condition field, enter the text that you want to be displayed when the condition is met.



  6. After the display text, insert another field into your template (just as you did in step 1).
  7. Double-click on the field to open the BI Publisher Properties dialog box.
  8. Click on the Advanced tab. Enter the code for the end of the if condition, ie <?end if?>:



  9. Select the code text and copy it (Ctrl+C), then paste it (Ctrl+V) into the Text to display field. Click OK. Your template should look something like this:

 

Further examples of conditional text, including ones with multiple conditions and conditional formatting, are given in BI Publisher code for Oracle Policy Modeling. The BI Publisher Users Guide also provides further information on conditional formatting.

Insert entity-level attributes

To insert entity-level attributes in your template, you can use the Repeating Group button on the BI Publisher menu:

See the Template Builder for Microsoft Word help file for more information on how to set up your entity attributes in this way.

 

Alternatively, you can add entity-level attribute values and properties by following the format described below.

Entity-level attribute values and properties can be added to template documents in the same way as global attribute values and properties, but the group needs to:

 

To insert an entity-level attribute:

  1. Insert a field for the relevant entity-level attribute value into your template.
  2. Double-click on the field in the template to open the BI Publisher Properties dialog box. (TIP: If double-clicking the field does not open the BI Publisher Properties dialog, re-load your XML.)
  3. Click on the Advanced tab. Enter the code that defines which entity the attribute belongs to, ie <?for-each:entity_id?>:



  4. Select the code text and copy it (Ctrl+C), then paste it (Ctrl+V) into the Text to display field. Click OK.
  5. In your template document, on a new line after the "for-each" field, insert another field for the relevant entity-level attribute into your template (just as you did in step 1). If this field is for a formatted attribute value or attribute text continue on to the next step. If the field is for another type of attribute value/property (eg unformatted attribute value, attribute question text, attribute type) you will need to customize the BI Publisher field.
  6. In your template document, on a new line after the entity-level attribute field, insert another field for the relevant entity-level attribute into your template.
  7. Double-click on the field to open the BI Publisher Properties dialog box.
  8. Enter the code for the end of the "for-each" field, ie <?end for-each?>:



  9. Select the code text and copy it (Ctrl+C), then paste it (Ctrl+V) into the Text to display field. Click OK. Your template should look something like this:


 

Entity-level attributes can be displayed in several different ways.

To have information grouped by entity, have the "for-each" field around the whole group of attribute values/properties in your template document. For example:

<?for-each:child?>

<?child_name_text?>

<?child_rating_overall_text?>

<?child_rating_overall/@question?> <?child_rating_overall_value?>

<?end for-each?>

This would display as:

 

To have information grouped by attribute, have a "for-each" field around each individual attribute value/property in your template document. For instance:

<?for-each:child?> <?child_name_text?> <?end for-each?>

<?for-each:child?> <?child_rating_overall_text?> <?end for-each?>

<?for-each:child?> <?child_rating_overall/@question?> <?child_rating_overall_value?> <?end for-each?>

This would display as:

 

To display entity-level attributes in table form, the first cell in the row needs to start with the <?for-each:entity_id?> field, and the last cell in the same row needs to end with the <?end for-each?> field (with the entity-level attribute fields in between). For example, a table like this in your template document:

This would display as:

 

To display entity-level attributes in table form sorted alphabetically by entity name, follow the directions above but add an additional "sort" element to the opening "for-each" field:

<?sort:entity_name_id_value;'ascending';data-type='text'?>

For example,

This would display as:

 

TIP: Sometimes having the full display text for the "for each" fields at the start and end of the rows can upset the formatting of your table. If so, replace the full display text with an abbreviation (eg "F" for the <?for-each:entity_id?> field, and "E" for the <?end for-each?> field ). See the Combined Form in the Social Services Screening rulebase that is installed with Oracle Policy Modeling for an example of this.

Insert a table

To have a table in your template you can either:

For more information on using the BI Publisher table formats, see the Template Builder for Microsoft Word help file.

Insert a chart

To have a chart in your template you must create it using the Chart button on the BI Publisher menu (you can't use a native Microsoft Word chart).

You then have the option of creating the chart yourself using the Builder, or, if you know the code for the chart that you want, adding the code directly to the Advanced tab.

For more information on inserting a chart using the chart builder, see the Template Builder for Microsoft Word help file.

An example of creating a pie chart by adding code to the Advanced tab is shown in the Raw Template Examples file in the Healthy Eating rulebase that is installed with Oracle Policy Modeling.

Insert a repeating picture

You can have a picture repeated in a document depending on the value of a particular attribute. To do this you need to specify BI Publisher code in the Format AutoShape | Alt Text field for the image in the template.

An example of displaying a number of star images to represent a child's diet rating is shown in the Raw Template Examples file in the Healthy Eating rulebase that is installed with Oracle Policy Modeling.

Preview the document

Using BI Publisher you can preview your RTF template using "real" data. To do this you generate some sample data, then load it into your template and then preview the output.

Generate the sample data

Sample data can be generated from an Oracle Web Determinations session. To do this:

  1. Open the document control on the summary screen.
  2. Select the Generate Xml Data checkbox, then click OK.
  3. Select Build | Build and Debug. In the Debug Options dialog box, select the option to debug With screens, and select the option Build and deploy with built-in Oracle Web Determinations. It is important that you also select the option to Replace deployed version of Web Determinations.
  4. In Web Determinations, enter your data until a conclusion is reached.
  5. On the summary screen, click on the document link. Save the XML file from the session.

NOTE: When the XML data is generated, every attribute with a public name regardless of whether it is known, unknown or uncertain is output. However, entity instances and change point values are only output if they actually exist in the session, so if you don’t have either of these you won’t see them in your sample XML.

Load the sample data

After you have generated your sample data you need to load it into the BI Publisher Template Builder in Word.

  1. On the BI Publisher toolbar, select Sample XML:



  2. In the dialog box, select the XML file that contains your sample data (see above). You will be told when this data has been loaded successfully.

Preview the output

After you have loaded your sample data you can preview the document in your choice of format.

  1. Click on the appropriate Preview option:



  2. Review the generated document:



  3. If necessary, go back to your RTF template file to make any changes. Remember to re-import your XML schema if you want to continue editing your document using the BI Publisher Fields dialog.

If you are having problems with the display of any elements in your document, see the Troubleshooting guide for using BI Publisher with Oracle Policy Modeling.

 

See also: