IBM Cúram Social Program Management Eligibility and Entitlement Rules Getting Started Document version 1.0 Niambh Scullion is the Business Analyst for Technical Infrastructure in Cúram. Niambh has worked in Cúram for 9 years. Her current responsibilities are Cúram Search and the CER Editor. She previously worked on the CER Editor as a developer, and on different solutions in Cúram. Joe McAndrew is a Client Solutions Professional working in Cúram. Joe has worked in Cúram for 13 years since Cúram v1.5. Joe has extensive Cúram experience, he has worked as a Technical Product Manager, a solution consultant and a Technical Trainer.
Transcript
IBM Cúram Social Program Management
Eligibility and Entitlement Rules Getting Started
Document version 1.0
Niambh Scullion is the Business Analyst for Technical Infrastructure in
Cúram. Niambh has worked in Cúram for 9 years. Her current
responsibilities are Cúram Search and the CER Editor. She previously
worked on the CER Editor as a developer, and on different solutions in
Cúram.
Joe McAndrew is a Client Solutions Professional working in Cúram. Joe
has worked in Cúram for 13 years since Cúram v1.5. Joe has extensive
Cúram experience, he has worked as a Technical Product Manager, a
22/09/2014 1.1 NS Adding in Eligibility and Entitlement, Display Rules and Key Factor Rules.
23/09/2014 1.2 POR Editorial
15/12/2014 1.3 NS Editorial
8
1 Introduction
The purpose of this document is to provide you with high level information regarding the key Rule Sets that are used within an Eligibility and Entitlement Product.
The article will describe main Rule Sets that are used in an Eligibility and Entitlement Product. It will describe at a high level composition of the Rule Sets, the artifacts involved and concepts that are used in Eligibility and Entitlement Rules. The documentation also describes how Rule output is displayed to users.
This document is not a substitute for training, nor will it explain the Out-Of-The-Box Rules. However, it will help you understand various aspects of CER Eligibility and Entitlement Rules, Decision Rules and Key Factor Rules.
1.1 CER Rules used in Eligibility and Entitlement
CER is used throughout the Cúram Application for many types of calculations, and for displaying results in the Cúram Application
The Rule usage is defined by categories, each category gives a high level description of the Rule function. This document describes the main rules used in an Eligibility and Entitlement Product.
Eligibility and Entitlement determination. When executed Eligibility Rules determine a claimant's eligibility for a product. Once a claimant’s eligibility is determined, the Rules then determine what the claimant is entitled to receive.
Display Rules. The primary goal of Display Rules is specify how results are displayed. Display rules build up an XML file that "sits on top of" the Eligibility and Entitlement rules. The XML file contains a meaningful interpretation of the results of executing the eligibility and entitlement rules.
Key Factor Rules. Key Factor rules are used to display the key factors related to the determination of the client's eligibility and entitlement, for example, displaying the dates on which the amount on the simple evidence entity changed.
Each of the rules identified above are built using Cúram Express Rules (CER) and follow the same implementation guidelines. However the design of the rules may vary between each category.
Eligibility and Entitlement Rules Getting Started
9
2 Eligibility and Entitlement Rules
2.1 Introduction
Eligibility and Entitlement Rules are used to determine what a claimant is entitled to receive while a case is active. Eligibility and Entitlement Rules are composed of two main Rule Class types;
The Eligibility Rule, which determines if a claimant is eligible to receive a benefit.
The Entitlement Rules, also known as Objectives, which determine what the claimant is entitled to receive.
2.2 Artifacts
The following table contains the artifacts that make up the Eligibility and Entitlement Rule Set.
Artifact Database Table Name When Updated
Eligibility and Entitlement Rule Set
CREOLERULESET Addition of a new Eligibility and Entitlement Rule.
Rule Set Property Files
APPRESOURCE Addition of new property files containing Display Names and Descriptions.
Resource Message APPRESOURCE Addition of a new description message file.
Propagators RULEOBJECTPROPAGATORCONFIG Addition of a new rule object propagators.
Name Translation TEXTTRANSLATION Addition of update of the Rule Set name.
Localizable Text LOCALIZABLETEXT Addition of update of the Rule Set name.
10
2.3 Eligibility Analysis
Analysis of Eligibility usually starts with the legislation or policy documents. The Business Analyst will review the legislation or policy documents, and define the eligibility in either CER rules, or an XML Editor.
Typically Business Analysts and Rules Developers work closely to verify requirements for the Rules. When the eligibility has been defined by the Business Analyst, it is helpful for the developer to document test cases prior to implementation in order to ensure their understanding of the requirements is correct.
During implementation, the rules developer should work closely with the Business Analyst to ensure that the rules are not only functionally correct, but that they are understandable in the CER Editor.
2.4 Entitlement Analysis
Entitlement is very tightly coupled with eligibility. Entitlement returns the benefit (monetary or non monetary) that a claimant will receive. Like Eligibility, Entitlement analysis starts with legislation or policy documents.
When looking at Entitlement, it is not unusual that the name of the attribute of the benefit members (eligible participants in a claim) is required. In addition, for each available objective, there may be additional processing required, such as adding amounts, or rate table look ups.
Eligibility and Entitlement Rules Getting Started
11
2.5 Creating an Eligibility Rule Class
Eligibility Rules determine a claimant's eligibility for a product.
To calculate eligibility, create a rule class that extends the Rule Class ‘DefaultProductEligibilityEntitlementRuleSet.DefaultCase’.
The naming convention for Eligibility Rule classes is ProductNameCase. The following attributes must be implemented;
isEligibleTimeline returns a time line of Boolean values returning the claimaint's varying eligibility.
objectiveTimelines returns a list of AbstractObjectiveTimeline, which will return 0 or more objectives a claimant is entitled to receive.
12
2.6 Creating an Entitlement Rule Class
An Eligibility and Entitlement Rule Set must have one or more entitlements. Entitlements can be monetary or can be non-monetary. Entitlement Rules are known as Objectives.
To determine Entitlement a rule class extending DefaultProductEligibilityEntitlementRuleSet.DefaultProduct must be created, this defines the structure of the Rule Set.
Each objective requires the following rule classes to be extended.
The implementation of the inherited attributes describes who receives the objective, the type of objective (benefit or liability), and the frequency at which the objective will be delivered.
This is required for each frequency type, such as daily, weekly, monthly. The role of this rule class is to calculate the delivery of an objective for each frequency type.
2.7 Use the CER Editor to create an Entitlement Rule Class
To create an Eligibility and Entitlement Rule Class using the CER Editor, complete the following steps:
Log in to the admin application.
Select the Rules and Evidence Shortcut.
Click the Cúram Express Rules link.
Click the Actions menu and select the ‘New’ option.
Input the Rule Set name.
Input the Display Name. The Display Name is the localizable name displayed in the list. If the Display Name is not set, then the Rule Set name is displayed.
Click the Search button to retrieve the newly created Rule Set.
Select the Action menu associated with the Rule Set.
Click the ‘Continue Editing’ option.
Click the ‘Technical’ tab on the left side of the CER Editor.
Eligibility and Entitlement Rules Getting Started
13
Click the ‘Class’ button.
Enter the name of the class.
Click the newly created class, to display the properties panel.
Click the ‘Extends’ link.
To extend the DefaultProductEligibilityEntitlementRuleSet class, click on the ‘Change’ link.
Select DefaultProductEligibilityEntitlementRuleSet from the menu.
Click Save.
Select DefaultCase from the menu.
Click Save.
After the Rule Class has been created, the attributes from the parent need to be included in the current Rule Set. To do this, follow the steps below
Click on the newly created Rule Class, the classis highlighted and a new menu appears.
Select ‘Show Inherited Attribute’ from the menu.
Expand the Rule Class to view the inherited attributes.
To override the parent attributes behaviour, complete the following steps:
Double-click on the attribute you want to extend so that it appears in the diagram.
Click the attribute diagram.
Add the custom implementation. When the update is saved the following message is displayed ‘This action will copy one or more inherited attributes, creating new Attribute(s) in the rule class. Continue?’ This message is notifying you that this attribute will be copied into your Rule Class.
Click Yes.
2.8 Using Objectives
An Objective is anything that can be awarded as part of a determination result calculated by CER rules. An eligibility rule set can have multiple objectives. In Cúram products, there is at least one Objective. However where the product interfaces with a third party, who provide the objectives, it is not required to list objectives.
14
2.9 Available Objective Types
Objective types are stored in the CT_RulesTagTypes.ctx codetable. Out-Of-The-Box examples are Money and Assessment. To add new objective types, the code table file must be customized in accordance with the Cúram Development Compliancy Guide.
Financial Products must have at least one objective of type Money.
2.10 Rule Class Code Generation
During compilation each Rule Class is generated in to a Java class.
2.11 Volatile Attributes
A volatile attribute is a data attribute that can change over time, for example a claimant’s income.
A claimant is in employment and receives an income, which is a type of ‘Wage and Salary’. Over a period of time, the income the claimant receives will change, yet the income type of ‘Wages and Salary’ remains the same. On Evidence Entities the startDate is a non-volatile attribute.
Eligibility and Entitlement Rules Getting Started
15
2.12 Participant Data Case
In the Participant Data Case, Participant Data for the Person or Prospect Person is treated as Dynamic Evidence. Examples of Participant Data include Address, Phone Number, Bank Account and Relationships. This information can be configured as Dynamic Evidence and associated with the Participant through a hidden under-lying case, the PDC.
The benefits of treating Participant Data as evidence is the flexibility it gives in terms of sharing data across cases, and maintaining data across cases. You can choose to switch off PDC until you are ready to migrate the data.
2.13 Debugging Eligibility and Entitlement Rules
When a rule class extends a default class in the Eligibility and Entitlement Rule Set, the description attribute is inherited from the root class. The description attribute is formed by using a resource message. The value of the description is output in the SessionDoc.
2.14 The Dependency Manager
If there is a change in Evidence, the Dependency Manager ensures all dependent Rules are re-evaluated.
2.14.1 Propagators and Rule Object Converters
Propagators listen for changes in entities and evidence. When changes occur, the Dependency Manager is notified. Propagators are managed by propagator configuration files.
Rule Object Converters are responsible for retrieving data from the database and converting the data into Rule Objects that can be used by CER.
Propagators and Converters work in pairs. Rule Object Converters retrieve the data, and Propagators listen for changes to that data type.
Rule Object Converters and Propagators use the same configuration file.
2.15 Successions and Corrections
2.15.1 Succession Set Introduction
A succession set is a set of related Evidence; the succession set captures updates to Evidence during the lifetime of that evidence. A succession set is made up of corrections and successions.
16
Succession sets are used to track changes in circumstances when a new version of a piece of evidence is added. They are also used to track corrections, where invalid data is correct.
Succession sets enable you to view updates to a piece of Evidence over a period of time.
2.15.2 Introduction to successions
Each time Evidence is modified and the Effective Date of Change is updated a new succession is added, this piece of evidence supersedes the previous evidence record.
In the table, the top row of this table represents the latest active update. For the purposes of this example the evidence state changes are not included. All evidence is deemed active.
A person has an employment with an organization, and from that employment the person receives a wage of $400 monthly, since 1/1/2009. The person informs a caseworker that they have had two pay rises:
$450 monthly, effective from 1/1/2010, and
$480 monthly, effective from 1/1/2011.
Since these updates require changes to the Effective Date of Change, they cause a new version of the Evidence to be added. The new version supersedes the version that is no longer true.
2.15.3 Introduction to corrections
A correction is where the data on the system does not (and never did) accurately reflect events and circumstances in the real world, and must be corrected.
In this example, the top row of this table represents the latest active update. For the purposes of this example the evidence state changes are not included. All evidence is deemed active.
Eligibility and Entitlement Rules Getting Started
17
The person informs the caseworker that the wage amounts were incorrect for 2010; the wage amount should have been $460 monthly.
The previous version of the Evidence is added to the correction set, and is maintained to show a history of the evidence.
Rows below the top represent corrections for each entry. Each correction made replaces a previous version of the Evidence.
2.15.4 Combined Succession Sets
Combined succession sets are used when there can be no overlapping in the evidence. The Social Security Number (SSN) is a good example of this. A person will only ever have one SSN number.
3 Display Rules
3.1 Introduction
The primary goal of Display Rules is to specify how results are displayed. Display rules build up an XML file that "sits on top of" the Eligibility and Entitlement rules. The XML file contains a meaningful interpretation of the results of executing the eligibility and entitlement rules. The contents of the Display rules are displayed using Dynamic UIM pages.
Eligibility and Entitlement calculations can be reused to display key decision data.
18
3.2 Artifacts
Artifact Table Name When Updated
Display Rules Rule Set CREOLERULESET Addition of a new Display rule.
DynamicUIM APPRESOURCE Addition of a new dynamic UIM page.
Resource Messages APPRESOURCE Addition of a new description message file.
Rule Set Property Files APPRESOURCE Addition of a new properties file containing Display Names and Descriptions.
Propagators RULEOBJECTPROPAGATORCONFIG. Addition of a new rule object propagator.
Name Translation TEXTTRANSLATION Addition of update of the Rule Set name.
Localizable Text LOCALIZABLETEXT Addition of update of the Rule Set name.
3.3 Starting Display Rules Analysis
During the analysis of Eligibility and Entitlement, when there is an understanding of what rule changes are required, we will need to consider how changes should be displayed.
When Business Analysts are analysing the rules, they need to keep the user (i.e. the case worker) in mind. They must consider how the case worker will navigate through the decision, what details should be displayed, and how the information is laid out in the screen.
3.4 Display Rule Class Details
Display rules "sits on top of" the Eligibility and Entitlement rules and calculate decision details that will be displayed to a user.
Class Name Class Name
DefaultProductDecisionDetailsRuleSet.DefaultCase
This will give you the product delivery case attribute.
Creating a rule class that extends AbstractBasicCase will give the functionality to display basic eligibility/entitlement decision details.
Eligibility and Entitlement Rules Getting Started
19
3.5 Changing Display Rules
Display Rules might require updates in line with legislation changes or policy updates. However Display rules can also be updated to meet case worker requirements. For example, if too much or not enough information about a decision is presented to the user.
3.6 Configuring Display Rules
Add a Display element into the attribute Annotation.
<Annotations>
<Display>
</Annotations>
To achieve this in the CER Editor, complete the following steps:
Click the Rule Class, so that the property panel is displayed.
Check the Display option.
The Display rule class must have one or more Display element.
3.7 Display Subscreen
A Display Subscreen is where the page links to another HTML page. To add a Display Subscreen to a Display Rule, add the DisplaySubScreen element in the attribute Annotation.
<Annotations>
<Display/>
<DisplaySubscreen/>
</Annotations>
To achieve this in the CER Editor, complete the following steps;
Click the Rule Class, so that the property panel is displayed.
Check the Display Subscreen option.
3.8 Link Display Rules to a Product Period
Display Rules can be linked to a Product through the Product Administration Home page. To associate Display Rules with an Eligibility and Entitlement Rule Set, complete the following steps:
Log in to the admin application.
Select the Case Shortcut.
Click on the Product Delivery Case link.
20
Click on the relevant Benefit Product.
Click on the Rule Sets tab. The user is presented with published content if present, if available, the user is presented with the ‘Display Categories’, ‘Product Periods’ and ‘Eligibility Determination’ tabs.
To edit an existing Rule Set configuration, select the button ‘Copy for Edit’. This will create an In-Edit version of the Rule configurations.
Select the ‘In-Edit’ section.
Select the ‘Product Period’ tab.
Select the option ‘Associate Decision Details Rule’ from the action item menu.
Select the Display Category and Display Rule from the pop-up.
Click Save.
When a new Display Rule Set is associated with a product period, a new entry is added to the CREOLEPRODUCTPERIODDISPCAT table.
To extract the update from the database, run the target ‘build extractdata’. This target will export the DMX files and associated properties file into the EJBServer/build/dataextractor folder. Copy or merge in updates from the CREOLEPRODUCTPERIODDISPCAT DMX file into custom component.
3.9 Volatile Display Rules
Volatile Display rules are data attributes with values that can change over time, Display rules can contain data values for display which over time can change.
3.10 Resource Messages
Resource Messages can be used to Display any formatted messages to a user.
3.11 Display Categories
Display Categories are the Tabs in the Dynamic UIM pages. The following DMX files are used to store Display Category information.
Table Name When Updated
CREOLEPRODUCTDECISIONDISPCAT The addition of a new Display Name Category.
TEXTTRANSLATION Adding or updating the Display Name value.
LOCALIZABLETEXT Addition of a Display Name Category to the Rule Set.
Eligibility and Entitlement Rules Getting Started
21
3.12 Dynamic UIM Introduction
Dynamic UIM pages present Display Rule Content to the UI. Each Display and Display Subscreen requires a Dynamic UIM file and associated .properties file.
3.13 Cloning Dynamic UIM
An existing Dynamic UIM file must not be cloned. New Dynamic UIM and associated property files should be created and all customizations applied to the new pages.
3.14 Configuring Dynamic UIM
Dynamic Rules are configurable. Updates to Dynamic UIM Pages can be uploaded in the Dynamic UIM Administration Home Page. To modify an existing Dynamic UIM page, complete the following steps:
Log in to the admin application.
Select the Dynamic UIM Shortcut.
Click the Dynamic UIM link.
Search for the Dynamic UIM page.
Select the correct Dynamic UIM page, and select the ‘Edit’ option in the action menu.
More information on Dynamic UIM can be found here.
3.15 Creating a new Dynamic UIM
New Dynamic UIM can be added in the Dynamic UIM workspace by selecting the ‘New’ button.
To persist the change, the new Dynamic UIM pages can be extracted from the database by running the target ‘build extractdata’. New Dynamic UIM content will create a new entry in the APPRESOURCE dmx file. The APPRESOURCE entry will contain the location of the extracted UIM page.
4 Key Factor Rules
4.1 Introduction
Key Factor rules are used to display the key factors related to the determination of the client's eligibility and entitlement, for example, displaying the dates on which the amount on the evidence entity changed.
Key Factor Rules are optional, however they are useful on products where the rules are complex and a lot of evidence is captured.
The configuration of Key Factor Rules enables a caseworker to see at a glance all the data that was used for the resulting determination, and how the determination has changed over time.
4.2 Artifacts
Artifact Table Name When Updated
Key Factor Rule Set CREOLERULESET Addition of a new Key Factor rule.
Resource Messages APPRESOURCE Addition of a new description message file.
Rule Set Property Files APPRESOURCE Addition of a new properties file containing Display Names and Descriptions.
Name Translation TEXTTRANSLATION Addition of update of the Rule Set name.
Localizable Text LOCALIZABLETEXT Addition of update of the Rule Set name.
4.3 Key Factor Rule Class Details
Rule Class Name Rule Class Description
DefaultProductKeyDataRuleSet.DefaultCase The rule class to identify and calculate key decision factors for a case must ultimately extend from DefaultProductKeyDataRuleSet.DefaultCase.
Each key factor that has been identified must have have a rule class extending DefaultProductKeyDataRuleSet.DefaultKeyDataTimeline defined.
DefaultProductKeyDataRuleSet.DefaultKeyEvent
Each key factor that describes an event such as startEmployment or endEmployment these will need a rule class extending DefaultProductKeyDataRuleSet.DefaultKeyEvent.
4.4 Link Key Factor Rules to a Product Period
Key Factor Rules can be linked to a Product though the Product Administration Home page. When a new Product Period is being created, the Key Factor Rule can be associated with the Eligibility and Entitlement Rule Set.
When a new Key Factor Ruleset is associated with a product period, a new entry is added to the CREOLERULECLASSLINK table.
4.5 Designing Key Factor Rules
Once the requirements analysis is complete, the implementation of key factor rules can commence. Calculations implemented in the Eligibility and Entitlement Rules can be reused.
Create a rule class extending DefaultProductKeyDataRuleSet.DefaultCase rule class, which will contain the overall identification and calculation of key factors.
Eligibility and Entitlement Rules Getting Started
23
The following steps describe how to create the classes using the CEREditor:
Open the CER Editor.
Select the ‘Technical Tab’.
Select the ‘Class’ button to create a new class called ‘MyProductCaseKeyData’.
Click the MyProductCaseKeyData class to view the properties.
Click the ‘Edit’ link beside the ‘Extends’ property.
Select the ‘Change’ link in the pop-up.
Select the class ‘DefaultProductKeyDataRuleSet’ from the drop-down list.
Select Save.
Select the Rule Class ‘DefaultCase’ from the Rule Class drop-down list.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. Any references in this document to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 4205 South Miami Boulevard Research Triangle Park, NC 27709 U.S.A. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. If you are viewing this information softcopy, the photographs and color illustrations may not appear.
28
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States, and/or other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Other company, product, or service names may be trademarks or service marks of others.
