Write the Key Decision Factor rule classes

For each type of key decision factor that you have identified, you must create a rule class which must ultimately extend from the ProductKeyDataRuleSet.AbstractKeyDataTimeline interface rule class. For ease of upgrades, it is recommended that your rule class extends the DefaultProductKeyDataRuleSet.DefaultKeyDataTimeline rule class which provides default implementations.

Here is a description of the attributes inherited from AbstractKeyDataTimeline:

Table 1. Rule attributes inherited from `ProductKeyDataRuleSet.AbstractKeyDataTimeline`
Rule Attribute name	Data type	Description
`description`	Localizable message	The identifying description of this key decision factor (as displayed to the user)
`timeline`	Timeline of Object	The single varying value whose changes will be reported as events for this key decision factor.
`keyEvents`	List of `AbstractKeyEvent`	The named events for this key decision factor.

Create a rule class which extends DefaultProductKeyDataRuleSet.DefaultKeyDataTimeline. The rule class should be named in line with your key decision factor (KeyDecisionFactorName KeyDecisionFactor), e.g. TotalHouseholdIncomeKeyDecisionFactor (the Engine does not have any technical constraint on the rule class name - rather a good name for your rule class may make it easier to develop and maintain your rule sets).

Implement a meaningful description attribute for your rule class. For a single key decision factor, a fixed localizable message (typically from a resource file, using CER's ResourceMessage expression) may suffice, e.g. "Total Household Income".

For a multiple key decision factor, the implementation of the description attribute will need to have some variable text, e.g. "Total Person Income for <person-full-name>", typically using CER's <ResourceMessage> expression to substitute variable text for placeholder in a message from a resource file, e.g. "Total Person Income for {0}".

Your key decision factor rule class will typically need some context in order to calculate its events and its description (for key decision factors which support multiple instances). This context will typically be a rule object which will be passed in when an instance of your rule class is created (see sections below). You should identify the context and model rule attribute(s) for the context in your rule class.

For example, if your key decision factor shows the total income for a person, then the context required may be a rule object for that person, so that your key decision factor rule class can use that person's data to calculate total income.

Leave the keyEvents with its inherited implementation; you may revisit it later if required.

The inherited implementation of timeline returns a Timeline with a constant value (and thus has no change events); if your key decision factor has only named events (as supplied by the keyEvents attribute), then do not create an implementation for the timeline attribute.

If your key decision factor does require events for a single varying value, then you must implement the timeline attribute to obtain that value, typically retrieving an existing Timeline attribute from another rule class, perhaps creating a rule object instance based off the context passed in to your key decision factor rule class.

For example, if your key decision factor displays the total income for a person, then:

your key decision factor rule class will have a person attribute, of type Person (another rule class);
your key decision factor rule class will have a personCalculator attribute, which creates a PersonCalculator instance (PersonCalculator is another rule class), passing in the person instance;
your implementation of the timeline attribute on your key decision rule class will retrieve the personCalculator.totalIncome rule attribute value (which is already a Timeline).

Write the Key Event rule classes

For each type of key decision factor that supports named events, you must create a rule class for each type of event. For example, if your key decision factor describes an employment, you might write these rule classes:

EmploymentStartedEvent; and
EmploymentEndedEvent.

For each type of key event that you have identified (if any), you must create a rule class which must ultimately extend from the ProductKeyDataRuleSet.AbstractKeyEvent interface rule class. For ease of upgrades, it is recommended that your rule class extends the DefaultProductKeyDataRuleSet.DefaultKeyEvent rule class which provides default implementations.

Here is a description of the attributes inherited from AbstractKeyEvent:

Table 2. Rule attributes inherited from `ProductKeyDataRuleSet.AbstractKeyEvent`
Rule Attribute name	Data type	Description
`description`	Localizable message	The description of this key event (as displayed to the user)
`date`	Date	The date on which the event occurred (or is expected to occur).

Create a rule class which extends DefaultProductKeyDataRuleSet.DefaultKeyEvent. The rule class should be named in line with your key event (EventName Event), e.g. EmploymentStartedEvent (the Engine does not have any technical constraint on the rule class name - rather a good name for your rule class may make it easier to develop and maintain your rule sets).

Implement a description for your event, which may or may not require context data to be passed into your rule class, e.g.:

(no context required) "Employment started"; or
(age context required) "Customer turned <new age on birthday>".

If the calculation of the date is complex, you may wish to implement a derivation for the date attribute. Otherwise, the value of date can be set by the calling rules when implementing the keyEvents rule attribute (see below).

Tip: Events which have a date of null will not be displayed. This can be useful for optional events such as those for an end date. If you have an EmploymentEndedEvent which applies only if an employment has an end date, then you can simply create an EmploymentEndedEvent instance and set its date to the end date of the employment; if the end date is null (i.e. the employment is ongoing), the event will not display, but if the employment has an end date recorded then the event will have a non-null date and will display.

This treatment of null dates typically results in more maintainable rule logic that the alternative approach whereby there is conditional logic governing which event instances to create.

Relate each Key Decision Factor to its supported Key Events

For each key decision factor rule class, you must consider whether to implement the keyEvents attribute. The inherited implementation of keyEvents returns an empty list; if your key decision factor has only events for a single varying value (as supplied by the timeline attribute), then do not create an implementation for the keyEvents attribute.

If your key decision factor does require named events, then your implementation of keyEvents must create a list of event objects. Depending on your implementation of the key event rule class, the each key event rule object may require additional context to be passed in when it is created.

For a fixed set of events (e.g. a start event and an end event), your implementation of keyEvents will typically be a <fixedlist> where each member in the list is a <create> expression, e.g. (in pseudo-code):

Create a list of AbstractKeyEvent, with members:
- Create an instance of EmploymentStartedEvent, setting date = myEmployment.startDate; and
- Create an instance of EmploymentEndedEvent, setting date = myEmployment.endDate (see tip above about how a null date prevents an event from being displayed).

For some events, there may be an arbitrary number depend on other conditions, such as a number of birthdays. For these types of events, you will need to use other constructs such as <dynamiclist> or <joinlists> to create your list of key events for the key decision factor.

Relate the Case to its supported Key Decision Factors

You must implement the keyDataTimelines attribute on your case rule object to return a list of key decision factors for the case.

If your product contains only single key decision factors, your implementation of keyDataTimelines will typically be a <fixedlist> where each member in the list is a <create> expression, e.g. (in pseudo-code):

Create a list of AbstractKeyDataTimeline, with members:
- Create an instance of TotalHouseholdIncomeKeyDecisionFactor, setting productDeliveryCase be this.productDeliveryCase; and
- Create an instance of ClaimantLifeEvents, setting productDeliveryCase be this.productDeliveryCase.

If your product has multiple key decision factor instances of a given type, your implementation of keyDataTimelines will typically be a <dynamiclist> to create a key decision factor for each object of a particular kind, e.g.:

For each person in the household:
- Create an instance of PersonIncomeKeyDecisionFactor, setting person = current person.

Typically your product may contain a mixture of single key decision factors, and multiple key decision factors (and indeed many different types of multiple key decision factors), in which case you will need to nest the <fixedlist> and <dynamiclist; creations within a <joinlists> expression.

It may be clearer to factor out the creation of different types of events to their own rule attribute before joining the lists together, e.g.:

Create an attribute called singleKeyDecisionFactors, which creates a fixed list of all the single key decision factors for your product;
Create an attribute called personIncomeKeyDecisionFactors, which creates a dynamic list containing one key decision factor per person on the case;
Implement keyDataTimelines to join together the singleKeyDecisionFactors and personIncomeKeyDecisionFactors lists.