Agile Curam Development Requirements Gathering: Temporal Evidence

Since Curam 4.5, it comes with a replacement to the Case Evidence Tree API called the Temporal Evidence Framework.  This framework is a significant improvement in terms of development and ease of use over the previous framework.  Kudos to Curam for providing us a way out of that previous API.

I won't be talking about the UI of the evidence framework, that is fully documented in the Documentation Center.  I would be focusing more on how to do analysis of requirements and converting them to evidence forms and structures.

There are some properties of evidence that a BA should be aware of and take advantage of.

• Evidences can have parent-child relationships
• Evidences can have attribution dates.
• Evidences can be validated.
• Attribution dates vs. Effective Dates.
• Evidences can be associated with integrated case and optionally a participant
• Evidences have approval cycles

Requirements needed

There are two inputs that would help you get the analysis done on this task.

• Rules analysis which would give you a list of evidence that the rules actually require.
• Actual forms used by the client right now, this would give you a template to understand how to layout the evidence forms.

By combining the two you can determine which of the actual forms to convert into evidence forms.

Naive requirements analysis

The typical approach when creating evidence is to start with an actual form and just build the evidence form from it.  This should only be considered as a starting point.

Some things with actual evidence forms:

• One-to-many data.  Since an actual form does not have the concept of parent-child relationships, you'd get some blocks which capture information that should be moved into a child evidence record.
• Header data. These should be identified and removed from the actual evidence form.  An evidence is already associated with either a case or a participant.  There is no need to capture the information again.
• Approval signature blocks. These should be done through the evidence approval cycle.

Following that you may end up with evidence that is not captured on any actual evidence forms.  From this avoid the following traps:

• One benefit/product/etc. associated with an evidence.  By doing that you're creating additional evidence workspaces making it harder for the user to manage their data.
• Creating a new evidence for the missing information.  You should leverage the existing forms that you already have and just augment it with new fields.

Attribution Dates vs. Effective Dates

The framework has the concept of both effective date and attribution dates.  Attribution dates are basically start and end dates for an evidence.  Effective dates show when an evidence has actually changed.

Effective dates are used if you want to see how an evidence changes over time.  It is a bit more tedious on the end user because he has to enter two evidence records one when the person is eligible and another when he is not.  Effective dates are always present, they can be empty, but the field must not be removed.

Attribution dates should be used if you are defining something that can actually begin or end.

The use of effective dates should be used when you are only trying to capture a change in circumstance.  Effective dates are used when you need to visually see the history of changes over time.

Effective dates cannot be set unless the evidence has become active.

There is no reason why you couldn't do both.  The Sample Sporting Grant does both.

Validations

Put validations only for sanity checks on mandatory fields and structural checks.  Let the business rules handle business level validations.  This keeps the validation logic simple.

Evidence forms ideally should not have any mandatory fields.  This gives a user the flexibility to enter in whatever data he has now and fill in the rest later.

Rather than enforcing mandatory fields on save, have an on-save validation which checks if something needs to be mandatory on final it will show warnings to indicate to the user that the evidence form that they have filled in is not complete.  Another validation on-activate will ensure that everything must be correct.  The developers need only to change one from just a warning to a full error on the two events.

Although format checks should be done on save.  If the user enters data, it should be in the correct form.

The following would be an example of validation analysis for an evidence form.

Field	Format Requirements	Mandatory
Actual Cost	x >= 0	yes
Estimated Cost	x >= 0	no
Director		yes

Refactoring Evidence Forms

Once you have finished capturing what you require in evidence.  An analyst needs to refactor the evidence screens so it is more beneficial to the user.  They can work with a user interface specialist to do this.

There would be times when evidence forms have a common block.  Take the following example:

• Evidence Type A has the following fields:
  • medical expense item code
  • medical expense cost
  • doctor's note provided
• Evidence Type B has the following fields:
  • travel expense item code
  • travel expense cost
  • insurance report provided
• Evidence Type C has the following fields:
  • dental expense item code
  • dental expense cost
  • insurance report provided

I could refactor it as

• Living Expenses evidence has the following fields:
  • expense type code
  • expense item code
  • expense cost
• Associated documentation evidence which is a child evidence of living expenses.  It has the following fields:
  • Associated documentation type
  • Provided indicator

Doing that I only have one evidence workspace to deal with which lists all my living expenses.  This works well if the screens are very similar in nature except for a type discriminator which can be passed when creating a new evidence.  You can do that by having "New Medical Expense" rather than "New" in the evidence workspace screen.

Participant Level or Integrated Case Level

To determine whether an evidence should be in the participant or case level ask the following questions:

• Does the evidence have a notion of a participant?
• Is it associated with more than one case member?  If so, chances are it is a case level evidence.
• Can the evidence be used in other cases?

What you may notice is most evidence would be associated with the participant.  So let's talk about when would it be in the case?

• The evidence needs to has to apply to the primary client and only the primary client of an integrated case.  Then maybe it should be associated with the case.
• The evidence does not apply to any client at all.  Then it has to be associated with the case.
• Something that would deal with more than one case member.  Then it has to be associated with a case.

Examples of case level

• Benefits Veto evidence.  This evidence specifies the benefits the primary client will receive regardless of what the other rules engine say.  This one can be approved only by the Prime Minister.
• Prenuptial Agreement evidence.  This evidence specifies the arrangements between two case members before they get married.  Although they can be two different evidence instances.

Big Caveat

Unfortunately, Curam does not provide us with a facility of associating only with a participant.  Everything is still captured within the context of a case.

Sample Evidence information capture forms

The following shows some of the analysis work products that would come out.

The following is the top level view of all the evidence types.

Evidence Form	Approval Requirements	Attribution Dates	IC Types Associated	Person Assoc
Income Report		yes	Income Support Rehabilitation	yes
Special Circumstance Benefit	Director or 2 supervisors	no	Rehabilitation	no
Medical Incident Report	Medical supervisor	start date only	Income Support Rehabilitation	yes

You also need to tabulate all the products that would actually need the evidence so have a product evidence link list.

Product Name

• Evidence Type 1
• Evidence Type 2
• Evidence Type 3

Finally you need to specify what fields an evidence form has and what validations if any there are.  Just remember validations on save come first before activate.  Keep the required fields  on save to a minimum as well.  So something like this would help out:

Evidence Form

Field	Type	Validation On Save	Validation On Activate
Participant	Case Participant	required
Expense Amount	Money		> 0
Expense Type	Expense Type		not blank

The data source

Determining where to get the data is pretty simple.

• If data exists already in the core tables.  Use it.  If you want it to reassess automatically just extend the existing code to perform the reassessment if needed.
• If you need to track things that change over time, use evidence.  A majority of non-core data is going to be here.
• Use new entities if it needs its own lifecycle (DO NOT try to push it in as evidence)

Approvals

Evidences has approval support built in, you can use it in lieu of putting in a "approved by" field in your evidence.

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.