Oracle Web Determinations Template Reference Guide

The purpose of this guide is to provide information about the Oracle Web Determinations templates in relation to how they are used to construct screens during an interview. This is intended to assist potential template developers in navigating the Oracle Web Determinations templates, explaining the design concepts behind the file structure and template architecture implementations, and the data available to templates from the Interview Engine.

The structure is as follows:

 

Sections 1 and 2 provide basic and core knowledge of the Oracle Web Determinations screens and templates.

Section 3 contains information on what templates are used for each screen. The information from the first two sections is useful to know, because it helps to understand what the screens are, and where the templates are located.

Section 4 is useful for an understanding of what data/information from the Interview Engine is available to Oracle Web Determinations templates

 

Note:

Oracle Web Determinations templates rely on the Apache Velocity template engine. It is important to be familiar with the Velocity templating language; see the Velocity Templates Developer Guide.

Section 1 - Oracle Web Determinations interview screens

Commonly encountered interview screens

When a user goes through an Oracle Web Determinations interview, he/she will most likely encounter the screens below. These screens provide the core functionality of Oracle Web Determinations - conducting an investigation and allowing traceability for goals that have been determined successfully

 

The screens below may also be encountered depending on the Oracle Web Determinations setup, rulebase complexity, and other factors:

List of interview screens

The following is a list of all of the screens available in Oracle Web Determinations, and a description of each one:

 

Screen name Description
Rulebase Select Displayed - when there are multiple rulebases and the user enters the Oracle Web Determinations webapp base URL.
Locale Select Displayed - when the user selects a rulebase, and the rulebase has more than one locale.
Summary Screen Displayed - when the user finishes investigating a goal, or the user clicks on the Summary link in the menu bar, or when the user starts a rulebase interview.
Data Review Displayed - when the user clicks on the Data Review link in the menu bar.
Decision Report Displayed - when the user clicks on the [Why] link next to a Goal that has been successfully investigated.
Question Screen - Automatic Displayed - during an investigation of a Goal, an Automatic screen is displayed if an attribute does not belong to an authored screen and needs to be asked for the determination of the current Goal.
Question Screen - Authored Displayed - during an investigation of a Goal or a Flow, attributes that need to be asked and belongs to an authored screen is displayed. The key difference between Automatic and Authored is that Authored usually has multiple attributes per screen, Automatic screens can only ask one attribute per screen.
Entity Collect Displayed - if the rulebase has Entities that need to be collected for the current Goal, the interview will present an Entity Collect screen to gather Entity Instances. Can be Automatic or Authored question screen.
Relationship Reference Displayed - if the rulebase has a many-to-many relationship between two Entities and the two Entities need to be collected for the current goal Can be Automatic or Authored question screen.
Load Screen Displayed - if the user clicks on the Load button.
Save Screen Displayed - if the user clicks on Save As, or in certain circumstances the Save screen.
Load and Save Success Displayed - when the user successfully saves or loads a session.
Close/Restart Session Displayed - when the user attempts to close or restart the current session.
Error/Fail Page Displayed - when there is a general error, or failure to perform a certain action such as save, load, restart or close.
Commentary popup Displayed - when the Oracle Web Determinations has been setup so the commentary opens in a new window instead of a frame. Clicking on a commentary link opens this popup.

 

Section 2 - Oracle Web Determinations template file structure

The Oracle Web Determinations templates are located in the following filepath (the template parent folder):

<OWD webapp>/WEB-INF/classes/templates

 

As an example, for a local Tomcat install it would be:

C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\web-determinations\WEB-INF\classes\templates

 

Base/Main templates

Base templates are templates that have the <html> tag. Therefore they are never included by any other template (unless that template is simply a 'proxy').

The base templates are most or all of the templates that are located directly under the template parent folder.

Template directory structure explained

templates folder - the templates folder contains all the base template files, and also contain sub-folders that categorize the templates.

controls sub-folder - contains all the templates to render each control type. The name of the template maps to the classname of the Control object that depends on it (since the Interview Engine renders a screen by rendering Control objects inside the current Screen object). Note that some controls are used in screens other than the Question screen.

includes sub-folder - as the name implies, contains templates that are 'included' by all base templates. It contains Javascript includes and also page components that is displayed in most screens such as the header, footer, and bars.

investigation sub-folder - contains templates that are mostly used during 'investigation'; that is, Question screens.

session_control sub-folder - contains templates that are used for saving and loading a session. Some of the templates are 'proxy' templates in that they simply include a base template such as the 'generic_screen.vm'.

Directory and File Listing

Below is a listing of the folder and file structure under the template parent folder. The underlined text are folders and the bold text are important templates

 

Template descriptions

Below are descriptions for some of the templates that are important or would benefit from further explanation:

 

Template name Description
generic_screen.vm Template used for generic form-based screens such as the load or save as screens
frameset.vm Used when commentary is available for the rulebase, and commentary is displayed as frames.
main.vm.css Contains the CSS for each screen displayed (added inside the HTML head tag), added as a VTL reference $css-text in base templates.
question_screen.vm Used as the base template for any question screen (both authored and automatic)
investigation/form.vm Template included by any base screen that will display a 'form'.
confirm_end_session_screen.vm Template used by the Restart and Close (session) functions.
includes/javascript-init.vm Contains one Javascript function that is called by each base template for any 'Javascript initialisation' procedures.
includes/javascript-browser-workarounds.vm Contains Javascript functions that is solely for browser workarounds.
includes/global-velocity.vm Included by every base template, useful for setting Velocity variables that should be available in all templates.
investigation/identifier-text.vm Displays the attribute identifier next to the Control label of an attribute; for example, 'applicant_age'.
investigation/input-style-override.vm Implements the CSS Class and CSS Style 'override' from the Oracle Policy Modeling Screen Authoring. Included by many control templates.
investigation/Link.vm Used for various non-commentary links such as the link for documents (in the Summary screen) and the link in Load/Save Successful.
investigation/control-text.vm Displays the label of an input control depending on commentary availability and setting (setting - to frame or popup window).
investigation/error.vm and
investigation/warning.vm
Used by the screen-messages.vm and controlMessages.vm to display warning and error messages during an interview.
controls/ButtonGroup.vm Used in screens that have groups of buttons, such as the Save and Cancel buttons in the Save As screen.

 

Section 3 - Oracle Web Determinations template architecture

This section describes how the template files are used by the Templating Engine to build an Interview screen.

The Oracle Web Determinations template architecture explained

Oracle Web Determinations templates rely on one of the base templates as the 'skeleton' of a screen; for example, the Summary screen relies on the summary_screen.vm template as it's skeleton/foundation.

The following is a sequence diagram that demonstrates at a high level how Oracle Web Determinations decides which 'base' template' to use for the next screen:

 

 

To get a better understanding of how Oracle Web Determinations generates screens using templates, here is a run-through of a sample scenario and the process that Oracle Web Determinations goes through to generate the HTML for the screen using templates. The sample scenario starts at the point where a user answers the last Question screen with input data that completes the goal investigation, thus triggering Oracle Web Determinations to return the Summary screen as the next screen:

  1. The user provides the input for the current Question screen and submits.
  2. Oracle Web Determinations receives the input data, and determines that the goal has been completed; as a result, the next screen to be displayed is the Summary screen.
  3. The Summary screen (in Object form) inside Oracle Web Determinations, is mapped to the summary_screen.vm base template. Oracle Web Determinations uses the summary_screen.vm base template as the skeleton.
  4. Oracle Web Determinations processes the summary_screen.vm template through the Velocity Template Engine to turn it into HTM; Velocity variables and (sub)templates to be parsed and attached are processed to HTML text.
  5. The Summary screen HTML is generated, and Oracle Web Determinations returns it via HTTP response to the user.

 

From the above scenario, steps 3 and 4 are the key steps. In these two steps, Oracle Web Determinations has determined the base template file for the next screen, and processes it through the Velocity Template engine to parse it from the template format to a full HTML format.

It should also be noted that Oracle Web Determinations base templates are really made up of sub-templates (which themselves also use sub-templates). Having sub-templates promotes re-use, so that the same component for different screen elements are reused and can be changed from one sub-template file; for example, the header.

Base template and sub template - how it is processed to HTML

This section explains how a base template and its sub-templates hierarchy is parsed by the Velocity Engine to generate the HTML form.

For Oracle Web Determinations, the Velocity Engine provides the following functionality:

 

When the Velocity Engine goes through the base template, it processes the VTL directives of the template.

Example - start_screen.vm (Rulebase Selection screen)

It's much simpler to understand how a base template is processed to generate HTML by demonstrating it using a sample base template. This example provides a run-through of the start_screen.vm base template.

Sub-template parsing

Analyze the start_screen.vm, and it's sub-templates for #parse statements; for example, '#parse("includes/header.vm")'

After analyzing the source for the start_screen.vm templates and all its other sub-templates, it is evident that the base template has one level of sub-templates; that is:

Velocity references as text

In the start_screen.vm template, the following code demonstrates Velocity references used as both HTML metadata (locale, pagedirString) and HTML display data (header-title):

<html lang="${locale}" dir="${pagedirString}">
          <head>
                    <title>${header-title}</title>

Velocity references in conditional directives

From the start_screen.vm template, the following code demonstrates a Velocity reference ($rulebases) used in a for loop. The $rulebases reference is using a Java List that has been exposed by the Interview Engine to this template:

<div class="column">
                <ul>
                #foreach($rulebase in $rulebases)
                                 <li><a name="${rulebase.key}" href="${rulebase.value}">${rulebase.key}</a></li>
                         #if($velocityCount % 23 == 0)
                                 </ul>
                          </div>
                         <div class="column">
                                 <ul>
                         #end
              #end
              </ul>
</div>

From the includes/header.vm, the code below demonstrates a Velocity reference (from appearance.properties file) being used in an if condition:

#if( ${show-application-name} == "true" )
        <p class="application-name">${application-name}</p>
#end

 

With the above explanations, let's follow a detailed step-through for generating HTML from start_screen.vm:

  1. Oracle Web Determinations calls the Velocity Engine to transform the start_screen.vm to HTML.
  2. The Velocity Engine starts to process start_screen.vm, by doing the following:
    1. Parses 'includes/global-velocity.vm' template.
    2. Processes some Velocity conditional statements.
    3. Starts the HTML page itself with the <html> and <head> start tags.
    4. Adds CSS text, then <body> start tag.
    5. Parses the header - includes/header.vm into HTML; after parsing, the HTML is appended to the current HTML page (start_screen.vm) containing the parse directive.
    6. Parses the menu bar - includes/menu-bar.vm into HTML; after parsing, the HTML is appended to the current HTML page (start_screen.vm) containing the parse directive.
    7. HTML content area; process Velocity for loop to generate HTML code for the Rulebase links.
    8. Parses the footer - includes/footer.vm into HTML; after parsing, the HTML is appended to the current HTML page (start_screen.vm) containing the parse directive.

  3. The Velocity Engine completes parsing the start_screen.vm to the completed HTML page.
Add new templates

Adding new templates is useful to ensure that template modifications are maintainable; this is particularly useful when making complex template modifications. Adding and using new template/s is done as follows:

  1. Create the new template file (with file extension of .vm).
  2. Add HTML/template code to the new template.
  3. Use the new (sub)template file by referencing it with the #parse directive. 
  4. Restart Oracle Web Determinations and test to ensure that the new template is being referenced and used correctly.

 

Notes:

Important screens - templates used

The following table contains a useful reference to the important screens and their base template/sub-template hierarchies:

* = may or may not be parsed depending on runtime values

Screen name Screen template hierarchy
Summary Screen
  • summary_screen.vm
    • includes/global-velocity.vm
    • includes/header.vm
    • includes/menu-bar.vm
    • includes/status-bar.vm
    • investigation/screen-title.vm
    • for loop - controls
      • controls/[control type].vm
    • includes/footer.vm
Data Review
  • data_review_screen.vm
    • includes/global-velocity.vm
    • includes/javascript-utilities.vm
    • includes/header.vm
    • includes/menu-bar.vm
    • includes/status-bar.vm
    • investigation/screen-messages.vm
      • includes/warning.vm*
      • includes/error.vm*
    • investigation/screen-title.vm
    • for loop - controls
      • controls/[control type].vm
        • uses DataReviewControl.vm
    • includes/footer.vm
Decision Report
  • question_screen.vm
    • includes/global-velocity.vm
    • includes/javascript-init.vm
    • includes/javascript-browser-workarounds.vm
    • includes/javascript-utilities.vm
    • includes/header.vm
    • includes/menu-bar.vm
    • includes/status-bar.vm
    • includes/stages.vm
    • investigation/screen-title.vm
    • investigation/screen-messages.vm
      • includes/warning.vm*
      • includes/error.vm*
    • investigation/form.vm
      • for loop - controls
        • uses DecisionReportControl.vm
    • includes/footer.vm
Question Screen - Automatic
  • question_screen.vm
    • includes/global-velocity.vm
    • includes/javascript-init.vm
    • includes/javascript-browser-workarounds.vm
    • includes/javascript-utilities.vm
    • includes/header.vm
    • includes/menu-bar.vm
    • includes/status-bar.vm
    • includes/stages.vm
    • investigation/screen-title.vm
    • investigation/screen-messages.vm
      • includes/warning.vm*
      • includes/error.vm*
    • investigation/form.vm
      • for loop - controls
        • controls/[control type].vm
    • includes/footer.vm
Question Screen - Authored
  • question_screen.vm
    • includes/global-velocity.vm
    • includes/javascript-init.vm
    • includes/javascript-browser-workarounds.vm
    • includes/javascript-utilities.vm
    • includes/header.vm
    • includes/menu-bar.vm
    • includes/status-bar.vm
    • includes/stages.vm
    • investigation/screen-title.vm
    • investigation/screen-messages.vm
      • includes/warning.vm*
      • includes/error.vm*
    • investigation/form.vm
      • for loop - controls
        • controls/[control type].vm
    • includes/footer.vm

 

Screens and Base Template mapping

Maps all the screens to a base template as follows:

Screen name Base template
Rulebase Select start_screen.vm
Locale Select locale_selection_screen.vm
Summary Screen summary_screen.vm
Data Review data_review_screen.vm
Decision Report question_screen.vm
Question Screen - Automatic question_screen.vm
Question Screen - Authored question_screen.vm
Load Screen generic_screen.vm (via session_control/list.vm)
Save Screen generic_screen.vm (via session_control/save_as.vm)
Load and Save Success generic_screen.vm
Close/Restart Session confirm_end_session.vm
Error/Fail Page error_screeen.vm
Question Screen with Commentary frameset.vm

 

Default page structure and core layout for the Question screen

The following diagram illustrates the default page structure and core layout for the Question screen:

 


Section 4 - Interview Engine Data available in Templates

The Velocity templates in Oracle Web Determinations have access to variables from property files, and objects/arrays/variables from the Interview Engine during runtime.

Property files

Oracle Web Determinations templates have access to the values of property files that are loaded for the template. Since each property is a key/value pair, Oracle Web Determinations templates simply refer to the property key to access the template.

The following are the property files that each Oracle Web Determinations template has access to during runtime:

Extending Property files for template customizations

It is possible to add properties to the property files, so that configuration settings for new template customizations stay in the property files. It is very simple to add new properties as follows:

  1. Add the property to the appropriate property files; each property file has a certain purpose, so it is a good idea to do this for maintainability.
  2. Use the property in the Oracle Web Determinations templates.
  3. Restart Oracle Web Determinations, and test to ensure that the new property or properties are working.

Interview Engine

The Interview Engine exposes many useful objects and variables to the Oracle Web Determinations templates; for example, it is possible to get the title of the current screen, or instance data of a certain entity's attribute, or the rulebase locale.

Application constants

The Interview Engine exposes various properties that are accessible directly. These properties are application constants that are handy to have direct access to from any template. The following table contains the application constants from the Interview Engine:

 

Property name Description
user-id
  • The user id of the current interview session.
  • Default is guest.
locale The locale of the current interview session. If the user has not selected a rulebase or locale, this uses the default locale in application.properties.
image-resource-request
  • Used as part of the URI to request image resources in Oracle Web Determinations, together with context-root-path; for example, ${context-root-path}${image-resource-request}/image_name.jpg.

    Note that this does not map to the folder name; for example, <OWD>/WEB-INF/classes/images. The setting of where Oracle Web Determinations should pick up image resources to service image requests is in application.properties.
  • Default is /images.
context-root-path The relative URI path to access the Oracle Web Determinations webapp from the webserver address; for example, if Oracle Web Determinations was set up in a Tomcat environment as 'web-determinations' webapp, the context-root-path is /web-determinations.
resource-request
  • Used as part of the URI to request non-image resources in Oracle Web Determinations, together with context-root-path; for example, ${context-root-path}${resource-request}/reset.css.
  • Similar to image-resource-request; note that the value of this property does not map to a folder name, but instead specifies the 'action' of the REST URL request.
  • Default is /resources.
rulebase Name of the rulebase.
rulebase-version Version of the currently selected rulebase.
rulebase-build-time Time the currently selected rulebase was built, expressed as an ISO 8601 UTC data time.
opm-version Version of Oracle Policy Modeling with which the currently selected rulebase was built.
version Version of the Oracle Web Determinations running; for example, 10.1.0.1.
case-id Current case id attached to the session.
page-uri URI of the current screen.
save-case-uri URI to go to the Save screen. Used by the menu bar Save button.
save-case-as-uri URI to go to the Save As screen. Used by the menu bar Save As button.
summary-screen-uri URI to go to the Summary screen. Used by the menu bar Summary button.
data-review-screen-uri URI to go to the Data Review screen. Used by the menu bar Data Review button.
close-session-uri URI to go to the Close Session screen. Used by the menu bar Close button.
restart-session-uri URI to go to the Restart Session screen. Used by the menu bar Restart button.
load-case-uri URI to go to the Load screen. Used by the menu bar Load button.

 

Screen and interview objects

The Interview Engine exposes many useful objects via the Screen and InterviewSession objects. The InterviewSession object encapsulates other useful objects inside it. These objects need to be accessed via one of the Interview Session's methods and stored in a Velocity variable as follows:

#set $rulebase = $screen.getInterviewSession().getInterviewRulebase().getRulebase()

${rulebase.getLocale()}

 

The following table contains useful objects from the Interview Engine (or more accurately the Class), along with their description, and usage tips. For specific variables and methods of each Class, refer to Interview Engine's API:

 

Object name Description Usage
Screen
  • Contains objects and data pertinent to the current screen displayed.
  • Also encapsulates InterviewSession and SessionContext objects.
  • Useful for accessing interview objects such as InterviewSession and SessionContext.
  • Useful for accessing screen-related objects and data such as current screen controls, id/title, commentary, warning/errors, screen messages.
  • Accessible via the ${screen} Velocity variable.
InterviewSession
  • Encapsulates object containing user-provided instance data from the interview so far (the Instance Data).
  • Encapsulates data about the interview's rulebase (the Rulebase Model Data).
  • See Understand the InterviewSession.
  • Access objects that contain rulebase model and instance data.
  • Access Commentary service which can provide commentary functions such as getting commentary text of a target control.
  • screen.getInterviewSession().
SessionContext
  • Responsible for storing the state of the interview session such as current screen, case ID, errors/warnings, last submit action/values, interview goal.
  • Because this object stores the state of the interview session, it encapsulates InterviewSession as well.
  • Access administrative data about the current interview session such as case ID, errors, last submit action object (SubmitAction).
  • screen.getSessionContext().
Session
  • Contains user-provided instance data from the interview so far (the Instance Data).
  • Access instance data of the current interview session, such as the value of a certain Global attribute to check if it is known or unknown, or to see if a particular entity has entity instances added.
  • interviewSession.getRuleSession().
Rulebase
  • Contains data about the interview's current rulebase (the Rulebase Model Data).
  • Access rulebase model data such as the entities of the rulebase, each entity's attributes, and relationships between entities.
  • interviewSession.getRulebase().getRulebase().