Now that you have implemented rule classes to describe the structure of your product, you can start to implement the rule classes which calculate the eligibility and entitlement results for a given product delivery case.
For each product period that you are creating, you must create a rule class which is responsible for calculating the eligibility and entitlement for a case, i.e. which objectives must be created on the case and their entitlement.
Typically the eligibility and entitlement calculations for your product will be different across product periods (because it was these differences which led you to identify multiple product periods in the first place). However, it is likely that large swathes of the eligibility/entitlement logic are identical between product periods and you should consider factoring your rule classes so that common logic is implemented and maintained in a single place, just as you would do in most kinds of development work.
In a development environment, initially it is recommended that you do just enough implementation work for eligibility and entitlement calculations so that you can view your product in a development database and assure yourself that you can create cases against it and see early eligibility/entitlement results.
You can then return to the non-trivial task of fleshing out your eligibility/entitlement calculation rules to provide the full logic required by your business requirements.
You will require the following rule classes:
The default eligibility and entitlement rule set created for the benefit product by the dynamic product wizard will already contain each of these rule classes, but they should be edited to meet your product requirements prior to product use.
Your rule class to calculate a case's eligibility/entitlement must ultimately extend from the ProductEligibilityEntitlementRuleSet.AbstractCase interface rule class. For ease of upgrades, it is recommended that your rule class extends the DefaultProductEligibilityEntitlementRuleSet.DefaultCase rule class which provides default implementations. The default eligibility and entitlement rule set that is automatically created for benefit products by the dynamic product wizard will already contain a rule class which extends the DefaultProductEligibilityEntitlementRuleSet.DefaultCase rule class.
Here is a description of the attributes inherited from AbstractCase:
| Rule Attribute name | Data type | Description |
|---|---|---|
| productDeliveryCase | ProductDeliveryCase | The controlling rule object which is responsible for splicing together the determination result from the contributions made by the product period. Passed in when the instance of AbstractCase is created. |
| isEligibleTimeline | Timeline of Boolean | The varying overall eligibility of the case. |
| objectiveTimelines | List of AbstractObjectiveTimeline | The objectives created for this case. |
Create a rule class which extends DefaultProductEligibilityEntitlementRuleSet.DefaultCase. The default eligibility and entitlement rule set that is automatically created for benefit products by the dynamic product wizard will name the rule class in line with the newly created product. The default name of the rule class is ProductNameWithBlankSpacesRemoved Case. If you are creating a new eligibility and entitlement rule set, the rule class should be named in line with your product, e.g. ProductName Case (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).
The value of productDeliveryCase will be automatically set to be the Engine's rule object for the overall case. This rule object can be used to access information about the case, such as its unique identifier.
You must provide an implementation for isEligibleTimeline. The isEligibleTimeline is created by default within the default eligibility and entitlement rule set that is automatically created for benefit products by the dynamic product wizard, but should be edited prior to use in line with your product requirements. Typically this implementation will be non-trivial (and in fact its implementation may well be the bulk of the effort in the development of your product), as it is responsible for ultimately calculating your case's overall eligibility during the product period, and its full implementation will need to access data about the case (e.g. using rule objects for evidence recorded on the case) and/or product-wide data such as rates. The implementation may involve the creation of many "calculator" rule classes which provide interim calculated results required to perform the complex calculations dictated by your business requirements for case eligibility on your product.
In a development environment, you may choose to initially implement a very simple cut-down version of your eligibility rules, e.g. that the case is eligible whenever the claimant fits into one of a number of very broad categories, or (even more simply) that the case is always eligible. Once you have completed the skeleton implementation of your eligibility rules and checked that cases can be created against it, then you can return to the much-longer development task of implementation your full eligibility rules, which will involve the creation of other rule classes, e.g. which map to your custom evidence types, or which provide intermediate calculation results.
The inherited implementation of objectiveTimelines returns an empty list (i.e. your case never has any objectives at all); leave this implementation for now and you will return to it once you have created your objective instance and tag instance classes.
Each objective rule object created for your case will be an AbstractObjectiveTimeline, which is responsible for calculating the periods when the case is entitled to the objective.
For each type of objective supported by your product (for example, a Personal Benefit Allowance or a Child Benefit Allowance), you must create a rule class which must ultimately extend from the ProductEligibilityEntitlementRuleSet.AbstractObjectiveTimeline interface rule class. For ease of upgrades, it is recommended that your rule class extends the DefaultProductEligibilityEntitlementRuleSet.DefaultObjectiveTimeline rule class which provides default implementations. This rule class will already have been created for each type of objective within the default eligibility and entitlement rule set that is automatically created for benefit products by the dynamic product wizard, but they should be edited in line with your product requirements prior to product use.
Here is a description of the attributes inherited from AbstractObjectiveTimeline:
| Rule Attribute name | Data type | Description |
|---|---|---|
| objectiveType | AbstractObjectiveType | The type of this objective timeline. |
| isEntitledTimeline | Timeline of Boolean | The varying entitlement to this objective. The value of this timeline is only taken into account during periods when the case is eligible. |
| targetIDTimeline | Timeline of Long | The varying ID of the target participant (e.g. Person, Service Supplier, Product Provider, Employer, etc.) which is targeted by this objective. |
| tagTimelines | List of AbstractTagTimeline | The frequencies at which this objective can be delivered. |
| relatedReferenceTimeline | Timeline of String | The varying reference to additional business-specific information relating to this objective. The relatedReference attribute can be used to store information that will help distinguish the difference between one instance of a rules objective and another, which may be important for financial processing to explain the breakdown of a payment. The length of this identifier must be no more than the number of characters dictated by the RELATED_REFERENCE_TEXT domain (which by default is 4000 characters). |
| description | Localizable message | A description of this objective instance |
For each objective type supported by your product, create a rule class which extends DefaultProductEligibilityEntitlementRuleSet.DefaultObjectiveTimeline. The default eligibility and entitlement rule set that is automatically created for benefit products by the dynamic product wizard will already contain two rule classes which extend the DefaultProductEligibilityEntitlementRuleSet.DefaultObjectiveTimeline rule class. These two default rule classes are named PersonalBenefitAllowanceObjectiveTimeline and ChildBenefitAllowanceObjectiveTimeline. If you are writing a new rule class, again the name of your rule class should be in line with the name of your objective type (ObjectiveTypeName ObjectiveTimeline), to ease development and maintenance, e.g. PersonalBenefitAllowanceObjectiveTimeline or ChildBenefitAllowanceObjectiveTimeline.
The inherited implementation of tagTimelines returns an empty list (i.e. your objective has no supported frequencies at which it can be delivered); leave this implementation for now and you will return to it once you have created your objective tag instance rule classes.
Implement the other rule attributes on the rule class. Typically the bulk of the work is in the implementation of isEntitledTimeline, the complexity of which depends on your requirements. For some types of objective, the objective is always attained whenever the case is eligible; for other types of objective, the case is only entitled to the objective if the circumstances of the case allow it.
Some types of objective will require additional context in order to calculate their entitlement. For any additional context required, create extra rule attributes to hold the context. Later when you create instances of your objective rule class, the <create> expressions will need to pass in the values for these "context" rule attributes.
Each objective rule object created for your case needs to list its supported tags (as instances of AbstractTagTimeline which are responsible for calculating the values at which the objective can be delivered).
For each type of tag supported by each type of objective supported by your product (for example, a weekly delivery of a Personal Benefit Allowance or a daily delivery of a Child Benefit Allowance), you must create a rule class which must ultimately extend from the ProductEligibilityEntitlementRuleSet.AbstractTagTimeline interface rule class. For ease of upgrades, it is recommended that your rule class extends the DefaultProductEligibilityEntitlementRuleSet.DefaultTagTimeline rule class which provides default implementations. The default eligibility and entitlement rule set created for benefit products by the dynamic product wizard will already contain four such rule classes each of which extends the DefaultProductEligibilityEntitlementRuleSet.DefaultTagTimeline rule class. These default rule classes should be edited or added to in line with your product requirements prior to product use.
Here is a description of the attributes inherited from AbstractTagTimeline:
| Rule Attribute name | Data type | Description |
|---|---|---|
| tagType | AbstractTagType | The type of this tag timeline. |
| valueTimeline | Timeline of Object | The varying value of this tag timeline. When converted to a String, the length of this value must be no more than the number of characters dictated by the RULES_OBJECT_TAG_VALUE domain (which by default is 1024 characters). |
For each tag type supported by your product, create a rule class which extends DefaultProductEligibilityEntitlementRuleSet. DefaultTagTimeline. Again the name of your rule class should be in line with the name of your tag type (TagTypeName TagTimeline), to ease development and maintenance, e.g. PersonalBenefitAllowanceWeeklyDeliveryTagTimeline or ChildBenefitAllowanceDailyDeliveryTagTimeline. The four default tag timeline rule classes that are defined in the default eligibility and entitlement rule set created for benefit products by the dynamic product wizard are PersonalBenefitAllowanceDailyDeliveryTagTimeline, PersonalBenefitAllowanceWeeklyDeliveryTagTimeline, PersonalBenefitAllowanceMonthlyDeliveryTagTimeline and ChildBenefitAllowanceDailyDeliveryTagTimeline.
The inherited implementation of tagTimelines returns an empty list; leave this implementation for now and you will return to it once you have created your objective tag instance rule classes.
Implement the tagType rule attribute, typically to just <create> an instance of the appropriate tag type rule class (see Write the Product Structure Rule Classes).
Implement the valueTimeline rule attribute to calculate the varying value of the tag. The complexity of the implementation will hinge on the complexity of your requirements; some objectives have fixed value tags (e.g. the payment value on any attained objective is identical across cases - the payment amount does not take into account any circumstances on the case), whereas for other objectives, the amount to pay for an attained objective varies according to the circumstances of the case (e.g. reductions in payment amounts due to means tests). It is also possible for the implementation of a tag's value for one frequency to lean on the calculation for a related tag for a different frequency (see the example in Identify the rules that determine the values at which an objective can be delivered).
The implementation of valueTimeline may require that extra context is passed in when the tag timeline is created. If required, create additional rule attributes to hold this context. Later when you create instances of your tag rule class, the <create> expressions will need to pass in the values for these "context" rule attributes.
Now that you have created rule classes for your objective instances and tag instances, you must implement how each objective instance will create its tag instances.
The default implementation of tagTimelines inherited from DefaultProductEligibilityEntitlementRuleSet.DefaultObjectiveTimeline returns an empty list - i.e. no tags are supported for the objective.
For each objective instance rule class that you created, you must now override and implement its inherited tagTimelines attribute to create a list of instances of the rule classes which represent its tag instances. Typically this list is a <fixedlist> where each member in the list is a simple <create> expression.
For example, for the PersonalBenefitAllowanceObjectiveTimeline rule class, its implementation of tagTimelines, in pseudo-code, would be:
When creating tags, you will need to pass in any additional context required by that tag (by specifying values to set in the <create> expressions). In turn, this additional context may give rise to additional "context" rule attributes being required on the objective rule class itself.
For example, if the value of an objective's tag depends on total income of the person targeted by the objective, then the tag instance rule class may require the person to be set as a context rule attribute; in turn, the objective instance rule class will need such a rule attribute in order to pass it to the tag instance at creation time.
Now that you have created rule classes for your objective instances, you must implement how the case calculates which objectives are available.
The default implementation of objectiveTimelines inherited from DefaultProductEligibilityEntitlementRuleSet.DefaultCase returns an empty list - i.e. the case has no objective instances at all.
For your case rule class that you created, you must now override and implement its inherited objectiveTimelines attribute to create a list of instances of the rule classes which represent its objective instances. This attribute will already have been created within the default eligibility and entitlement rule set that is created for benefit products by the dynamic product wizard, but it should be edited prior to product use.
If your product contains only single objectives, your implementation of objectiveTimelines will typically be a <fixedlist> where each member in the list is a <create> expression, e.g. (in pseudo-code):
If your product has multiple objective instances of a given type, your implementation of objectiveTimelines will typically be a <dynamiclist> to create an objective instance for each object of a particular kind, e.g.
Your product may contain a mixture of single objective instances and multiple objective instances (and indeed many different types of multiple objectives for different types), 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 objectives to their own rule attribute before joining the lists together, e.g.
You must create an objective instance for any objective which could in theory be attained at some point in the case lifetime, even if for some or all of the case lifetime it is not attained.
For example, if a product has an objective type is aimed at paying child benefit for each child on the case, then at some point those children will each become adults but possibly remain resident in the household. At that point, the objective for that person (who was a child, but now an adult) will not longer be attained; but it still must be listed in the simple list of objective timelines for the case. As such, typically each person (rather than just each child) in the household should have a child benefit objective instance created for them; however, for a person who was already an adult when the case began will never be entitled to that objective.
When creating objective instances, you will need to pass in any additional context required by that objective instance (by specifying values to set in the <create> expressions).
For example, if the case requires there to be one objective targeted at each person in the household, then the objective instance rule class may require the person to be set as a context rule attribute; when creating the multiple objectives, the implementation of objectiveTimelines will have to create an objective for each person in the household, and pass that person to the objective instance so that it can use that person as its target.
Your output data from eligibility/entitlement calculations are centered around CER Timelines. For example, the isEligibleTimeline for the case and the isEntitledTimeline for your objectives are both timelines of Boolean values.
In general, most of your input data into eligibility/entitlement calculations is already in timeline format, as populated by the Active Succession Set Rule Object Converter (see Active Succession Set Rule Objects).
Typically, then, your rules for eligibility/entitlement calculations will generally transform input timelines into output timelines (via intermediate timelines). CER contains a number of expressions for manipulating timelines, but given the nature of eligibility/entitlement calculations, the expressions you should expect to see most commonly are <timelineoperation> and <intervalvalue>.
Use of other CER expressions for creating timelines is rare, but may be useful: