Agile Curam Development Requirements Gathering: Rules and Evidence

To be honest, Curam provides an excellent document called the Rules Definition Guide in their Documentation Center that would be a good read for any Business Analyst dealing with Rules.  This blog will not rehash what is written there, but my knowledge is based on what was written in that document and other business rule specifications I have seen in other projects.

Although the focus is on Curam, this can be applied to any other rules engine analysis work.

Which to do first: Rules or Evidence?

That's usually one of the first questions.  The answer to this is neither.  If you're thinking of rules and evidence you're thinking way too far ahead.  That's a good thing.

The starting point for any rules/evidence work is policy.  Policy can be in the form of a legislation or an existing manual.  This sets up a guideline for you to work with.

Policies tend to be very large documents.  It is best that before you try and extract information from the policies you break it up into logical chunks.  Usually chapters and subchapters are sufficient.

Most policies will tell you what conditions you have to meet and what are the outcome based on those conditions.  This will be the data that gets put into the catalogue.

The catalogue

The catalogue is an interim work product.  It should contain a list of conditions and outcome and links to the sub-policies.  This is predominantly a copy and paste from a policy document.

The catalogue would have the following sections.

• Policy Map - which maps out the policy document and how it is broken into sub-policies for the use of the analysis.
• For each sub-policy, table containing the following columns:
  • Sub Policy ID - A unique identifier for the sub-policy.  (e.g. PO-1.1)
  • Condition ID - A unique identifier for the condition. (e.g. PO-1.1-1)
  • Condition text.
  • Condition Analysis
    • Input data required for the condition (not necessarily where to get it, but what they are).
    • The outcome of the condition.

Here is an example of a conditions that may appear in a policy document.

A senior citizen with no living siblings will receive $100 times their age if they have paid CCSIB premiums for at least 5 years.

A senior citizen with living siblings will receive $100 times their age if they have paid CCSIB premiums for at least 10 years.

The analysis can be broken up into a more formal table format.  However, since this is an interim piece of work, you can get away with just creative highlighting.  For example:

A senior citizen with no living siblings will receive $100 times their age if they have paid CCSIB premiums for at least 5 years.

What I have done was underline each individual input data and bolded the outcomes.  If you keep things consistent you should be able to get away with that approach with the client.  Just remind them that this an interim work product but one of the first step in analysis.

If you need a formal table format, you can use the following:

Condition ID	Policy ID	Policy Text	Data Elements	Outcomes	Analysis
P001-C001	P001	A senior citizen with no living siblings will receive $100 times their age if they have paid CCSIB premiums for at least 5 years.	senior citizen no living siblings age paid CCSIB premiums for the last 5 years	receive $100 times age
P001-C002	P001	This benefit cannot be removed by any future government			Statement.  Not a rule
P001-C003	P001	Part of a clan	part of a clan		Missing outcome.

There was an emphasis on interim, because this catalogue is useless for development and just a regurgitation of the policy from the client.  It is also highly likely that not everything can be covered in policies.

As a BA you have to add value in order for development to be able to use it.  So the next step is to convert what you have into a decision table.

The decision table

The decision table is a table that collects all the information from the catalogue and places them into a tabular format.  A group of condition results in a decision table.  The following shows a decision table for a condition group.

Conditions satisfied:

• PO-1.1-1
• PO-1.1-2
• PO-1.1-3
• PO-1.1-4
• PO-1.1-5

Input Data Name	Input Data Formula
senior	CN-PO-1.1-1	Y	Y	N	N	N
citizen	CN-PO-3.1-1	Y	Y	N	Y	N
no living siblings	CD052	Y	N	Y	Y	N
paid CCSIB premiums for at least 5 years	EV042 >= 5 years	Y	-	-	-	Y
paid CCSIB premiums for at least 10 years	EV042 >= 10 years	N	Y	Y	Y	N
paid MCSB premiums for at least 10 years	EV? < 10 years	-	-	-	Y	Y
Outcome	Outcome ID
Receive $100 times their age	OC412	X	X	X
Receive $200 times their age	OC413				X	X

 

The Input Data Name specifies the input data as per the condition record from the catalogue.  The outcome data is information required by the outcome calculation.

The Input Data Formula is a formula that represents the information in the input data name.  The formula may consist of an ID to point to some input data with a few simple calculations if needed.  This prevents having to create several input data records where the only difference is one parameter.

The formula does not show where to get the data, but it is best the Input Data ID represents the possible source in this example we used CD for core data, CN for other conditions, EV or evidence data.  Information on where to get the data is in the I/O catalogue which is described later.

Sometimes we don't have the any input data information defined yet, in which case we indicate it by a "?" on the ID to remind us to get the information.

One word of advice, try to use what is in the core rather than creating new evidences.  The information in the core tend to be things that do not really change over time and can be shared with other parts of your application.  Evidences are usually not shared outside the integrated case it is associated with.

One other thing to avoid: you may be tempted to just put some of the conditions like this:

years paid paid CCSIB premiums

EV042

>=5

>=10

>=10

>=10

>=5

 

You may have a harder time normalizing the decision table later.  So avoid that.

The Outcome specifies the outcome as per the condition record from the catalogue.  The Outcome ID is a unique identifier for the outcome.  The outcome ID is not a formula, because describing it as a formula in the decision table would make things hard to read.  The detailed information for the outcome will be in the I/O catalogue which is described shortly.

Most documentation regarding rules tables call the outcome as Action, but in Curam speak it is probably best to call this an outcome as the rule engine does not actually start up processes.

Once you have captured your decision table, you can optimize it using the techniques shown in http://www.cems.uwe.ac.uk/jharney/table.html

The conditions satisfied section is just there for the interim.  It is meant as a way for the BA to keep track as to which conditions have been completed, be the rule catalogue will eventually be discontinued in favour of the decision tables and I/O catalogue.  At which point, the section will be reworked as policies satisfied to ensure that any change in policy will trigger a trace back to the proper decision tables.

The I/O catalogue

This catalogue captures the input data and outcomes that were required by the decision tables in the previous section.

For input data, there are three common sources:

• Core data - these are provided by Curam core such as Person Details, Relationships, Case Header Data, Related case information.
• Evidence - these are additional information that are captured as part of the Integrated Case.
• Other conditions - these are other conditions that have been defined.  These could lead to new conditions being developed that were not part of the original policy document.  These are not in the I/O catalogue though.

The following tables would illustrate how to capture the information for input data:

Input Data ID	Input Data Name	Calculation
CN005	date of birth	Person.dateOfBirth
CN042	no living siblings	Person.dateOfDeath defined for all ConcernRoleRelationship relations where type is sibling
CN006	age	Current Date - Person.dateOfBirth

 

Input Data ID	Input Data Name	Evidence Form	Evidence Field
EV042	years paid CCSIB premiums	CCSIB	Years Paid

 

As you can see there are two different ways of writing the input data specifications.  For core data, it tends to be a calculation rather than a direct field because the data tends to be spread out.  It is best to communicate with a Curam developer or someone who knows more about the reference model.  It is recommended that data elements be of different type to distinguish them from calculation descriptions.

Evidence input data tends to be new and so it should be possible to list the exact form and field rather than a calculation.

The Outcome data shows the following information:

Outcome Data ID	Outcome Data Name	Objective Type	Objective Value Formula
OC412	$100 x age	Money	CN006 x 100
OC413	$200 x age	Money	CN006 x 200
OC501	Food Delivery	Product Delivery	"FOODDELIVERY"
OC001	General Eligibility	Assessment

 

Generally an outcome would end up as an objective in Curam terms.  The objectives types are usually money, a product or an assessment.  The formula column shows the formula with reference to some of the input data as well.

That's All Folks

This is as far as the BA would go.  The combination of decision tables and the I/O catalogue would be sufficient information to communicate with the development team.  It also provides a way of communication with the client team as they can visually see what would happen depending on their choices.

At this point the rule catalogue should be discarded in favour of the decision tables and the I/O catalogue.  This is assuming that all the conditions in the rule catalogue are met.

The decision table will be a almost mechanical process to convert to the Curam rules structure.  I say almost because the decision table does not name what the data or rulesets are nor do they group things together.  That is left with the development team as part of their naming conventions.

The I/O catalogue will drive the creation of evidence and loaders.

Conclusion: Be agile

Don't get into analysis paralysis.  You should never ever do this when you think you completed a previous section.  Once you have sufficient information, move onto the next section, if you realize something is missing go back.  There is no harm in updating the previous one.

Business rules are very complicated, and policies are just as complicated.  Policies tend to be vague and make certain assumptions which cannot be translated into code so you need to ensure those get analyzed.

Most likely the little problems would arise in development, but if you have done your job correctly, they should very little and you can fix it with a relatively quick turnaround.

The process defined here will provide sufficient documentation for both the client what is going on and the developer to understand what needs to be done.

The process defined here is general to most rule engines as well, there is very little Curam specific information so it can be used in other non-Curam projects.