Agile Curam Development Requirements Gathering: Rules and Evidence

tag:blogger.com,1999:blog-6666038.post-56643604510250910402008-02-07T09:59:00.001-05:002008-02-27T21:29:08.459-05:00Agile Curam Development Requirements Gathering: Rules and EvidenceTo 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. <h2>Which to do first: Rules or Evidence?</h2> That's usually one of the first questions.  The answer to this is neither.  If you're thinking of rules and <a href="http://www.trajano.net/2008/02/agile-curam-development-requirements_27.html">evidence</a> 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. <h2>The catalogue</h2> 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. <ul> <li>Policy Map - which maps out the policy document and how it is broken into sub-policies for the use of the analysis. <li>For each sub-policy, table containing the following columns: <ul> <li>Sub Policy ID - A unique identifier for the sub-policy.  (e.g. PO-1.1) <li>Condition ID - A unique identifier for the condition. (e.g. PO-1.1-1) <li>Condition text. <li>Condition Analysis <ul> <li>Input data required for the condition (not necessarily where to get it, but what they are). <li>The outcome of the condition.</li></ul></li></ul></li></ul> Here is an example of a conditions that may appear in a policy document. <blockquote> 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.</blockquote> 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: <blockquote> A senior citizen with no living siblings will receive $100 times their age if they have paid CCSIB premiums for at least 5 years.</blockquote> 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: <table cellspacing="0" cellpadding="2" width="593" border="1"> <tbody> <tr> <td valign="top" width="104">Condition ID</td> <td valign="top" width="100">Policy ID</td> <td valign="top" width="102">Policy Text</td> <td valign="top" width="95">Data Elements</td> <td valign="top" width="95">Outcomes</td> <td valign="top" width="95">Analysis</td></tr> <tr> <td valign="top" width="107">P001-C001</td> <td valign="top" width="100">P001</td> <td valign="top" width="105">A senior citizen with no living siblings will receive $100 times their age if they have paid CCSIB premiums for at least 5 years.</td> <td valign="top" width="94"> <ul> <li>senior citizen <li>no living siblings <li>age <li>paid CCSIB premiums for the last 5 years</li></ul></td> <td valign="top" width="94">receive $100 times age</td> <td valign="top" width="94"> </td></tr> <tr> <td valign="top" width="109">P001-C002</td> <td valign="top" width="100">P001</td> <td valign="top" width="107">This benefit cannot be removed by any future government</td> <td valign="top" width="93"> </td> <td valign="top" width="94"> </td> <td valign="top" width="95">Statement.  Not a rule</td></tr> <tr> <td valign="top" width="109">P001-C003</td> <td valign="top" width="100">P001</td> <td valign="top" width="107">Part of a clan</td> <td valign="top" width="93"> <ul> <li>part of a clan</li></ul></td> <td valign="top" width="94"> </td> <td valign="top" width="95">Missing outcome.</td></tr></tbody></table> 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. <h2>The decision table</h2> The <a href="http://en.wikipedia.org/wiki/Decision_tables">decision table</a> 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: <ul> <li>PO-1.1-1 <li>PO-1.1-2 <li>PO-1.1-3 <li>PO-1.1-4 <li>PO-1.1-5</li></ul> <table cellspacing="0" cellpadding="2" width="477" border="1"> <tbody> <tr> <td valign="top" width="111">Input Data Name</td> <td valign="top" width="102">Input Data Formula</td> <td valign="top" width="55"></td> <td valign="top" width="55"></td> <td valign="top" width="51"></td> <td valign="top" width="51"></td> <td valign="top" width="50"></td></tr> <tr> <td valign="top" width="114">senior</td> <td valign="top" width="104">CN-PO-1.1-1</td> <td valign="top" width="55">Y</td> <td valign="top" width="55">Y</td> <td valign="top" width="51">N</td> <td valign="top" width="51">N</td> <td valign="top" width="50">N</td></tr> <tr> <td valign="top" width="114">citizen</td> <td valign="top" width="106">CN-PO-3.1-1</td> <td valign="top" width="55">Y</td> <td valign="top" width="55">Y</td> <td valign="top" width="50">N</td> <td valign="top" width="50">Y</td> <td valign="top" width="49">N</td></tr> <tr> <td valign="top" width="115">no living siblings</td> <td valign="top" width="107">CD052</td> <td valign="top" width="55">Y</td> <td valign="top" width="55">N</td> <td valign="top" width="50">Y</td> <td valign="top" width="50">Y</td> <td valign="top" width="49">N</td></tr> <tr> <td valign="top" width="114">paid CCSIB premiums for at least 5 years</td> <td valign="top" width="109">EV042 >= 5 years</td> <td valign="top" width="55">Y</td> <td valign="top" width="55">-</td> <td valign="top" width="50">-</td> <td valign="top" width="50">-</td> <td valign="top" width="49">Y</td></tr> <tr> <td valign="top" width="114">paid CCSIB premiums for at least 10 years</td> <td valign="top" width="109">EV042 >= 10 years</td> <td valign="top" width="55">N</td> <td valign="top" width="55">Y</td> <td valign="top" width="50">Y</td> <td valign="top" width="50">Y</td> <td valign="top" width="49">N</td></tr> <tr> <td valign="top" width="114">paid MCSB premiums for at least 10 years</td> <td valign="top" width="109">EV? < 10 years</td> <td valign="top" width="55">-</td> <td valign="top" width="55">-</td> <td valign="top" width="50">-</td> <td valign="top" width="50">Y</td> <td valign="top" width="49">Y</td></tr> <tr> <td valign="top" width="114"> </td> <td valign="top" width="109"> </td> <td valign="top" width="55"> </td> <td valign="top" width="55"> </td> <td valign="top" width="50"> </td> <td valign="top" width="50"> </td> <td valign="top" width="49"> </td></tr> <tr> <td valign="top" width="114">Outcome</td> <td valign="top" width="109">Outcome ID</td> <td valign="top" width="55"> </td> <td valign="top" width="55"> </td> <td valign="top" width="50"> </td> <td valign="top" width="50"> </td> <td valign="top" width="49"> </td></tr> <tr> <td valign="top" width="114">Receive $100 times their age</td> <td valign="top" width="109">OC412</td> <td valign="top" width="55">X</td> <td valign="top" width="55">X</td> <td valign="top" width="50">X</td> <td valign="top" width="50"> </td> <td valign="top" width="49"> </td></tr> <tr> <td valign="top" width="114">Receive $200 times their age</td> <td valign="top" width="109">OC413</td> <td valign="top" width="55"> </td> <td valign="top" width="55"> </td> <td valign="top" width="50"> </td> <td valign="top" width="50">X</td> <td valign="top" width="49">X</td></tr></tbody></table>   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: <table cellspacing="0" cellpadding="2" width="484" border="1"> <tbody> <tr> <td valign="top" width="114">years paid paid CCSIB premiums</td> <td valign="top" width="109">EV042 </td> <td valign="top" width="55">>=5</td> <td valign="top" width="55">>=10</td> <td valign="top" width="50">>=10</td> <td valign="top" width="50">>=10</td> <td valign="top" width="49">>=5</td></tr></tbody></table>   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 <a href="http://www.cems.uwe.ac.uk/jharney/table.html">http://www.cems.uwe.ac.uk/jharney/table.html</a> 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. <h2>The I/O catalogue</h2> 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: <ul> <li>Core data - these are provided by Curam core such as Person Details, Relationships, Case Header Data, Related case information. <li>Evidence - these are additional information that are captured as part of the Integrated Case. <li>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.</li></ul> The following tables would illustrate how to capture the information for input data: <table cellspacing="0" cellpadding="2" width="500" border="1"> <tbody> <tr> <td valign="top" width="183">Input Data ID</td> <td valign="top" width="162">Input Data Name</td> <td valign="top" width="153">Calculation</td></tr> <tr> <td valign="top" width="181">CN005</td> <td valign="top" width="160">date of birth</td> <td valign="top" width="157">Person.dateOfBirth</td></tr> <tr> <td valign="top" width="180">CN042</td> <td valign="top" width="160">no living siblings</td> <td valign="top" width="161">Person.dateOfDeath defined for all ConcernRoleRelationship relations where type is sibling</td></tr> <tr> <td valign="top" width="180">CN006</td> <td valign="top" width="160">age</td> <td valign="top" width="161">Current Date - Person.dateOfBirth</td></tr></tbody></table>   <table cellspacing="0" cellpadding="2" width="501" border="1"> <tbody> <tr> <td valign="top" width="120">Input Data ID</td> <td valign="top" width="124">Input Data Name</td> <td valign="top" width="84">Evidence Form</td> <td valign="top" width="171">Evidence Field</td></tr> <tr> <td valign="top" width="119">EV042</td> <td valign="top" width="122">years paid CCSIB premiums </td> <td valign="top" width="83">CCSIB</td> <td valign="top" width="174">Years Paid</td></tr></tbody></table>   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: <table cellspacing="0" cellpadding="2" width="501" border="1"> <tbody> <tr> <td valign="top" width="120">Outcome Data ID</td> <td valign="top" width="124">Outcome Data Name</td> <td valign="top" width="84">Objective Type</td> <td valign="top" width="171">Objective Value Formula</td></tr> <tr> <td valign="top" width="119">OC412</td> <td valign="top" width="122">$100 x age</td> <td valign="top" width="83">Money</td> <td valign="top" width="174">CN006 x 100</td></tr> <tr> <td valign="top" width="119">OC413</td> <td valign="top" width="122">$200 x age</td> <td valign="top" width="83">Money</td> <td valign="top" width="174">CN006 x 200</td></tr> <tr> <td valign="top" width="119">OC501</td> <td valign="top" width="122">Food Delivery</td> <td valign="top" width="83">Product Delivery</td> <td valign="top" width="174">"FOODDELIVERY"</td></tr> <tr> <td valign="top" width="119">OC001</td> <td valign="top" width="122">General Eligibility</td> <td valign="top" width="83">Assessment</td> <td valign="top" width="174"> </td></tr></tbody></table>   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. <h2>That's All Folks</h2> 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. <h2>Conclusion: Be agile</h2> 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. Archimedes Trajanohttp://www.blogger.com/profile/15993184075121538415noreply@blogger.com