tips for polishing your opa 10.4 rulebase tips for polishing your opa 10.4 rulebase author jasmine...

Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |

Tips for Polishing Your OPA Rulebase Oracle Policy Automation 10.4

Jasmine Lee Principal Solution Specialist Last updated: 18 November 2014


Introduction

• Audience – People who work with OPA rulebases. It is assumed the reader has already had OPA training and is familiar with using OPA.

• Purpose – Provide ideas and suggestions for polishing your rulebase, and direct you to relevant articles in the Oracle Policy Modeling User Guide

• Software version – Slide deck prepared for Oracle Policy Modeling 10.4

• Acronyms

– OPA – Oracle Policy Automation

– OPM – Oracle Policy Modeling

– OWD – Oracle Web Determinations

• File paths - Instructions in this deck assume OPM is installed to the default location (C:\Program Files\Oracle), and that your rule project is set up in the default location (C:\projects\<project name>\)

Tip: OPM User Guide can be found via the Help menu

in OPM and on OPA OTN

http://www.oracle.com/technetwork/apps-tech/policy-automation/overview/index.html


Example Projects

• OPM has examples which demonstrate many of the features discussed in this deck

• If OPM is installed in the default location, project zips of the demos are here: C:\Program Files (x86)\Oracle\Policy Modeling\examples

• See the OPM User Guide article Example Rulebases for descriptions of the examples, and instructions on setting them up on your local machine

3

Example rulebases


Tips for Polishing Your Rulebase

• Substitution and Sentence Generation

– Name Substitution

– Gender Pronoun Substitution

– Second Person Sentence Generation

– Substituting Names in Headings and Labels

• Screen Configuration

– Labels on Interview Screens

– Visibility of Summary Screen Elements

• User Input

– Default Values for Attributes on Screens

– Validating User Input – Event rules

– Validating User Input – Properties File

• Improving the Decision Report

– Trimming Explanations – Attributes

– Trimming Explanations – Relationships

– Intermediate Attributes

– Set Default Decision Report Expansion Level

– Structural Elements

– Intermediate Attributes

4

• Enhancing Web Determinations

– Data Review Screen

– Progress Stages

– Hiding the Status Bar

– Changing the Default Date Format in OWD

– Changing the OWD Banner (image)

– Changing the OWD Banner (text)

– Configuring the OWD Labels

– Commentary/Help Text

– Document Generation using BI Publisher

• Language Support

– Adding a Verb to the Default Verb List

– Adding a Translation Layer

– Language of Standard OWD Labels

– Configuring the Locale Selection Screen

– Writing Rules in Other Languages


messages.<locale>.properties

• Some tips in this deck refer to the messages.<locale>.properties files. This slide describes where to find these files in the default project structure.

• What is it? messages.<locale>.properties are useful configuration files which allow the rule author to easily define some elements of OWD such as default OWD labels and buttons.

• The specific messages.<locale>.properties file for your rule project is dependent on the Project Language, e.g.

– If Project Language is “English”, the applicable configuration file is messages.en.properties

– Some languages have additional region specific versions, e.g. messages.en-GB.properties for British English

– Default location: C:\projects\<project name>\Release\webdeterminations\WEBINF\classes\ configuration\messages.<locale>.properties

5


appearance.properties

• Some tips in this deck refer to the appearance.properties files. This slide describes where to find this file in the default project structure.

• What is it? appearance.properties is a useful configuration file which allows the rule author to define elements of the OWD interface such as whether to hide/display the save/close/restart buttons, the progress stages, etc. It also specifies some elements of the look and feel, such as the body background colour, body text colour, etc.

• The default location of the appearance.properties file is:

– C:\projects\<project name>\Release\webdeterminations\WEBINF\classes\configuration\ appearance.properties

6


Substitution and Sentence Generation

7


Name Substitution

• Personalizes the interview for a more user-friendly experience

• Collect the person’s name at start of the interview, then substitute the name in later questions, e.g.

– “Does the person have insurance?” becomes “Does Homer have insurance?”

• Particularly important when using entities, e.g.

– “Is the child a full-time student?” becomes “Is Bart a full-time student?”, “Is Lisa a full-time student?”, etc.

• Substituted name automatically appears in attribute text on summary screen, question text and in decision reports

• If first and last name collected separately, use string concatenation to combine if full name needed for substitution

8

OPM User’s Guide

• Text substitution principles

• Change the text of an interview question or sentence:

• Substitute the actual value of a variable for its text

• Set up substitution

• Combine multiple text strings into a single text variable


Gender Pronoun Substitution

• May be used in combination, or in isolation, with name substitution to personalize the interview for a more user-friendly experience, and to provide more natural language text

• Gender pronoun substitution requires collecting gender

9

OPM User’s Guide


• Substitute a gender pronoun for a text variable

• Collect the gender of a person

• See also the articles for Name Substitution on the previous slide

Original rule generically refers to “the applicant”

In combination with name substitution, “Has the applicant submitted the applicant’s tax return?” becomes “Has Homer submitted his tax return?”


Second Person Sentence Generation

• Similar concept to name substitution, but sentences/questions generated in second person rather than third person

• Requires name substitution to be set up first

10

OPM User’s Guide

• Change the text of an interview question or sentence

• Display interview questions in second person form

• Also see the articles for Name Substitution

Example: Instead of “Does the applicant have health

insurance?” it displays “Do you have health insurance?”


OPM User’s Guide


• Substitute an attribute value into text on screens

Substituting Names in Headings and Labels

• Variable values (e.g. person’s name, age, etc.) can be substituted into headings and labels on interview screens

• Requires name substitution to be set up first

• Note: Substitution does not apply to Progress Stages. If using substitution in screen headings which appear in Progress Stages, put the screen in a subfolder to avoid headings such as “%name%’s Car” appearing in Progress Stages.

11

Example screen heading: “Homer’s Car” instead of “Car”

Example: The person’s name and age were collected on a previous

screen, and those values have been substituted into label text

on the School screen


Screen Configuration

12


Labels on Interview Screens

• Labels can:

– be added to provide context and additional info

– be used as additional headings and subheadings

– include raw text, as well as HTML

– have conditional visibility

– contain substitution

13

OPM User’s Guide

• Create, modify or delete a question screen:

• Add labels to question screens

• Change how interview data is summarized and reviewed:

• Add a label to the summary screen

Example label


Visibility of Summary Screen Elements

• It is common to hide/display screen elements based on logic

• Examples:

– Display additional labels at the end of the Web Determinations interview (but have the labels hidden initially)

– Display different additional labels depending on the value of particular determinations

– Display a goal to investigate at the start of the assessment, but then hide it at the end

• Achieved through the use of visibility attributes

14

OPM User’s Guide

• Hide, display and disable an interview screen element:

• Control the visibility of summary screen elements


User Input

15


Default Values for Attributes on Screens

• Can set default values for attributes on interview screens

– Defaults can be specific values, or can be dynamically determined based on previously collected data, or inferred from rules

• Reduces the typing/clicking required to complete an interview

16

OPM User’s Guide

• Customize interview user input options

• Specify a default value for an input

• Specify a dynamic default for an input

All currency values have been defaulted to $0.

User only needs to edit the fields for which they have income. Reduces

manual data entry.


Validating User Input – Event Rules

• Error event and Warning event rules may be used where there is conditional logic associated with the validation, e.g.

– Display the message “Please check the dates of birth. You have indicated that your date of birth is after your child’s date of birth.” if the applicant’s date of birth > the child’s date of birth

• Error event: Error message is displayed and the user is prevented from continuing until the situation that triggered the event is no longer present

• Warning event: Warning message is displayed, but the user is able to click past and continue the interview

17

OPM User’s Guide

• Validate user input using errors and warnings

• Write an error event rule

• Write a warning event rule


Validating User Input – Properties File

• Validation with regular expressions and min/max can be done in the Properties file

– Error message may be configured on a per attribute basis

• Use min/max values if there is no conditional logic for triggering the error, e.g.

– ‘the person’s age’ field could have a minimum allowable value of 0 and a maximum of 120

• Use regular expressions to validate the format of an input such as an email address, an SSN, a TFN, a NINO or a PHN, e.g.

– ^[0-9]{3}-?[0-9]{2}-?[0-9]{4}$ is a basic SSN validation – allows for NNN-NN-NNNN and NNNNNNNNN

18

OPM User’s Guide

• Validate user input using errors and warnings

• Specify minimum and maximum values

• Use regular expressions

Other info

• http://en.wikipedia.org/wiki/Regular_expression

http://en.wikipedia.org/wiki/Regular_expression

http://en.wikipedia.org/wiki/Regular_expression


Improving the Decision Report

19


Trimming Decision Reports – Attributes

• Decision Reports automatically generated based on logic, language and structure of the rules can be extremely verbose

• Can ‘trim’ Decision Reports using Silent and Invisible parameters

– Silent: Hide all logic nested below the attribute

– Invisible: Hide the attribute only

• Silent and Invisible parameters can be:

– Attached at the rule level, so only a particular attribute/branch of logic is affected

– Attached to the attribute globally so they apply whenever that attribute appears in a Decision Report

20

OPA User’s Guide

• Hide information in a decision report

• Hide all attributes in the decision report below a particular attribute

• Hide a particular attribute in the decision report

• Cut off a decision report above a particular attribute


OPM User’s Guide

• Hide information in a decision report

• Hide a relationship in the decision report

Trimming Decision Reports – Relationships

• Silent and Invisible can be applied to relationships

– See examples below with a containment relationship (the household members) and an inferred relationship (the children)

21

No trimming

Invisible on containment relationship

Silent and Invisible on inferred relationship

Invisible set on both relationships

Invisible on containment relationship

Silent on inferred relationship

Invisible set on the containment relationship


Set Default Decision Report Expansion Level

• Default expansion level for Decision Reports in Web Determinations can be set in the appearance.properties file

• Default expansion level is 2:

– decision-report-default-depth = 2

• For pre-10.4 behaviour, i.e. display all levels of the Decision Report, set depth to 0:

– decision-report-default-depth = 0

22


OPM User’s Guide

• Model the structure of legislation:

• Use structural elements to model legislative structure

• Use keywords to customize automatic structural attributes

Structural Elements

• Structural elements in legislation (e.g. section, paragraph, article) and policy (e.g. chapter, guideline) can be captured in rules

• OPA can automatically generate the structural attribute

• Default form is “section x is satisfied”, but this can be configured

23


Intermediate Attributes

• Intermediate attributes can be added to make the decision report more meaningful

– These two examples have identical core logic, but Example 2 has a more meaningful decision report due to the inclusion of intermediate attributes

24

OPM User’s Guide

• Design a decision report

• Add more information to a decision report

• Add intermediate rules

• Improve the wording of a rule

• Replace grouping operators with new attributes

Example 1 Example 2


Enhancing Web Determinations

25


Data Review Screen

• Data Review Screen displays the questions asked during the interview and the answers provided

• Data Review Screen in OWD is generated from the Screen Order definition in the screens file

– Screens in OWD Data Review appear in order defined in ‘Screen Order’

• If no Screen Order is defined in the screens file, the screens will appear in a random order in the Default Data Review Screen in Web Determinations

26

OPM User’s Guide

• Change how interview data is summarized and reviewed:

• Change the order of screens on the data review screen

• Change the title of the data review screen


Progress Stages

• Displays ‘stage’ at top of interview screen. Current stage appears in bold.

• Not a navigation tool. Only works if Screen Order has been defined in screens file

• Can turn off in appearance.properties file:

– show-progress-stages = false

• If question screens grouped into sub-folders in the screens file, the subfolders will be used as the progress stages

27

OPM User’s Guide

• Test an interview or screen flow

• Investigate a goal in Web Determinations

• Progress stages

Progress Stages are visible by default if

Screen Order is defined


OPM User’s Guide

• Change the layout or appearance of interview screens

• Show/hide features used for debugging

• Status bar

Hiding the Status Bar

• Status bar appears in top right area of OWD, showing: rulebase name, locale, user id, and case ID (for saved cases) for current session

• Can hide status bar with setting in appearance.properties file:

– show-status-bar = false

28

Status bar visible by default

Status bar hidden

Each element of the Status Bar can be individually hidden/displayed. See # status bar options in appearance.properties


Changing the Default Date Format in OWD

• By default, the date format is based on the Region setting for the rulebase, e.g. if ‘English (US)’ the dates are month-day-year, whereas if ‘English (UK)’ the dates are day-month-year

• To use different input/output date formats, add the following configuration lines to application.properties and specify the desired formats, e.g.

– input-date-formats = yyyy-MM-dd, d MMM yyyy

– output-date-format = d MMM yyyy

• Note: Only applies to date fields where Input Type=Single Edit, and not where Input Type=Year, Month and Day Edits

29

OPA Developer’s Guide

• Technical reference

• Web Determinations configuration files > application. properties file > Input and output formats > Default formatter

• Note: This is the OPA Developer’s Guide, not the OPM User Guide


OPM User’s Guide

• Customize Oracle Web Determinations

• Change the Oracle Web Determinations banner

Changing the OWD Banner (image)

• Replace the ‘Oracle Web Determinations’ banner with the customer’s logo and name, program name, etc.

• Web Determinations banner is comprised of an Oracle graphic (oralogo_small.gif) and the text ‘Web Determinations’

30

To hide banner image, edit appearance.properties: show-header-image = false

Build and Run to see changes in OWD banner

To replace ‘Oracle’ graphic, save new graphic as oralogo_small.gif to default

location: ...\<project name>\Release\web-determinations\WEB-INF\classes\images\ Alternatively, edit ‘header-image’ filename in appearance.properties to other filename


OPM User’s Guide


• Change the Oracle Web Determinations banner

Changing the OWD Banner (text)

• To amend the heading text, edit the “application-name” setting in messages.<locale>.properties:

– application-name = Income Assistance

• To hide the heading text, use this setting in appearance.properties:

– show-application-name = false

• To hide the whole header section, use this setting in appearance.properties, e.g.

– hide-header = true

31

Build and Run to see changes in OWD banner


OPM User’s Guide


• Configure the Oracle Web Determinations labels

Configuring the OWD Labels

• Standard out-of-the-box OWD label text can be modified with the messages.<locale>.properties file, e.g.

– Save As, Load, Restart, Close, Yes, No, Submit, [Why?]

– See messages.<locale>.properties file for full list

• Generally will not need to edit these labels for demos, but configuration options are there if needed

32

Build and Run to see changes to out-of-the-box

OWD labels


OPM User’s Guide

• Create, update or delete interview help

• Localize interview help

Commentary/Help Text

• Commentary is context-sensitive help text

• Commentary can be per screen, per question, or per word within a question

• Configure style of commentary display in appearance.properties file:

– pop-up: opa-commentary-type= popup

– frame: opa-commentary-type= frameset

• Create public names for all base attributes before generating commentary

• Help text can also be attached to labels

33

Click “Age:” and the commentary

window opens up


Document Generation using BI Publisher

• Generate documents from OWD interviews, e.g. letters, claim forms, etc. Available formats: PDF, RTF, HTML, Excel

• Documents may include text, images, graphics, charts, etc.

• Note: Requires installation of BI Publisher Desktop. This is a separate product. It is not part of Oracle Policy Modeling.

34

OPM User’s Guide

• Overview: The process of creating an interview document

• Create, update or delete an interview document

• Develop a template for an interview document

• Localize interview document templates

• BI Publisher code for Oracle Policy Modeling


Language Support

35


Adding a Verb to the Default Verb List

• Default verb list for project is based on ‘project language’ selected when creating the project

• Occasionally you may need a new verb

• If a Boolean won’t parse properly, it’s a sign the statement’s operative verb may not be in the verb list

• Options are to re-word the attribute to use a different operative verb, or add the new verb to the list for the project

36

OPM User’s Guide

• Configure the list of recognized verbs

b1, b2, b3 have a verb underlined. b4 is red with no verb underlined because ‘love’ is not in the default verb list.

Clicking ‘Edit’ shows it cannot be parsed.

Note: The first rule doc where you used the previously unknown verb may not immediately pick up the new

verb after you've added it to the verb list for the project. To force the document to pick up the new

verb, 'strip hidden‘ then re-compile.


OPA User’s Guide

• Create a new language translation for a rulebase

Adding a Translation Layer

• Create one or more translation layers, e.g. rulebase in English, OWD in choice of English, Spanish or French

• Even a partial translation layer is sufficient to demo the concept. Google Translate can be used for basic demos

• Use a (human) translation expert for translation text for real implementations

37

English rulebase … with French translation layer

http://translate.google.com/


Language of Standard OWD Labels

• Standard OWD labels (Close, Restart, Data Review, Copyright, etc.) will display in the Project Language of the rule project if no translation layer exists

• If translation layer(s) present, OWD labels will display in the language chosen on the locale selection screen, e.g. Spanish labels if you’ve chosen to run your English-language rulebase with a Spanish translation layer, or English if you’ve chosen to run it in English.

• Translated OWD label text is defined in the messages.<locale>.properties file for the language, e.g. Spanish labels are defined in messages.es.properties

38

If the rulebase Project Language is Spanish,

outofthebox OWD look something like this.


OPM User’s Guide


• Change the locale list in Oracle Web Determinations

Configuring the Locale Selection Screen

• Locale selection screen displays when translation layer(s) exist

• Default display of the locale selection screen can be modified

39

Default display uses rulebase name and localized language names from appearance.properties for existing translation layers

Modify the list heading in the messages.<locale>.properties for the project’s base language: LocaleSelectionTitleInfoMessage=Please select a language:

• Language names can be configured in appearance.properties if required


Writing Rules in Other Languages

• Many languages available out-of-the-box for rule authoring

• Rapid Language Support Tool can be used to develop non-syntactic parser for any other language

• Change language of rule authoring toolbar:

• Function reference in other languages, e.g.

40

OPM User’s Guide

• Write rules in other languages

• Select the user interface language for rule authoring

• Language specific considerations

• Localized function references

Other info

• Rapid Language Support User Guide: C:\Program Files (x86)\Oracle\Policy Modeling\help\opm\OPA RLS User Guide.pdf


Documentation and Further Information

41


OPA User Guides

• Oracle Policy Modeling User’s Guide including: – Rule authoring, configuring screens, defining interviews, debugging, testing and preparing for

deployment.

• Oracle Policy Automation Developer’s Guide for runtime components: – Oracle Web Determinations – deploy web-based interactive interviews, and extend,

customize and integrate as needed

– Oracle Determinations Server – high performance SOAP-based web service for fully auditable determinations and calculations

– Oracle Determinations Engine – Java and .NET API for low-level control over integration of decision-making into applications

– OPA Batch Processor – process a large number of cases in batch; available in both Java and .NET implementations

42

Note: Links are correct at the time of writing. If the URLs change in future, look for them on OPA OTN.

http://docs.oracle.com/html/E54499_01/toc.htm

http://docs.oracle.com/html/E54502_01/toc.htm



OPA Best Practice Guidance

• Best Practice Guide for Rule Developers

– Guidance on topics such rule types, rule structures, attribute parsing, screen configuration, interview flow, and organizing content

• Guide to Designing a Policy Model

– Considerations when designing a policy model. Topics include: creating a design document, policy model goals, source material, clarifying scope, identifying additional functionality, identifying entities and relationships, and design constraints

43

Note: Links are correct at the time of writing. If the URLs change in future, look for them on OPA OTN.

http://www.oracle.com/technetwork/apps-tech/policy-automation/learnmore/policymodelingbestpracticeguide-1371173.pdf

http://www.oracle.com/technetwork/apps-tech/policy-automation/learnmore/opaguidetodesigningapolicymodel-1531936.pdf



Oracle Technology Network

Oracle Policy Automation on the Oracle Technology Network

– Oracle Policy Automation product downloads

– Oracle Policy Automation system requirements

– Oracle Policy Automation installation guides

– Oracle Policy Automation whitepapers

– Oracle Policy Automation datasheets and tutorials

Ask questions about OPA on the OPA OTN forum

44


https://forums.oracle.com/community/developer/english/industries/oracle_policy_automation/oracle_policy_automation_-_general_discussion


OPA Social Media

• OPA on Twitter

• OPA on Facebook

• OPA on LinkedIn

• OPA Discussion Forum

• OPA on YouTube

• OPA Blog

45

http://twitter.com/OracleOPA

http://www.facebook.com/pages/Oracle-Policy-Automation/365522920199101

http://www.linkedin.com/groups/Oracle-Policy-Automation-3431282/about

https://community.oracle.com/community/developer/english/industries/oracle_policy_automation/oracle_policy_automation_-_general_discussion

http://www.youtube.com/user/OraclePAVideos

https://blogs.oracle.com/OPA/

http://www.facebook.com/pages/Oracle-Policy-Automation/365522920199101

https://twitter.com/OracleOPA

http://www.linkedin.com/groups/Oracle-Policy-Automation-3431282/about

http://www.youtube.com/user/OraclePAVideos

https://forums.oracle.com/forums/forum.jspa?forumID=828