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.