Advanced Oracle Policy Automation – Entity to Temporal Conversions

Disclaimer: There will be advanced concepts that require the reader to have a firm foundation in OPA.

 

Intro

This post is a simple post to demonstrate more complex Entity to Temporal conversions than is found in the Oracle Help Documentation.

OPA help document on converting entities

These examples use the following OPA entities:

Global

  • The event - This is all the historical events captured in the source system. It includes status, asset, recoupment, payment, and adjustment events.
  • The context - This exists to allow us to compare different assessment dates and different dates of known circumstance.
  • The plan - This is the basic plan for payment OPA gives back to the system.

Recommendation: Consider putting a description of your entities and relationships at the top of rule documents.

It becomes difficult to figure out what is going on without the data model if a lot of entity logic is involved. Don't assume the reader of an OPA rule document will have the data model available for reference in OPM.

See the following example (which we will use) of documenting entities and relationships in a Word document:

Source

Target

Type

Text

Reverse Text

Identifying Attribute

Global

the plan

Containment

the plans

 

the plan id

Global

the context

One to One

the latest context

 

 

Global

the plan

One to One

the first plan

 

 

Global

the event

Containment

the events

 

the event id

Global

the context

Containment

the contexts

 

the context

the context

the event

Many To Many

the asset events

 

 

the context

the event

Many To Many

the payment events

 

 

the context

the event

Many To Many

the case status events

 

 

the context

the event

Many To Many

the recoupment events

 

 

the context

the context

One To One

the prior context

the next context

 

the plan

the plan

One To One

the next plan

the prior plan

 

Example 1 - Entity / Relationship Legend

In our examples, there is an input transaction table of historical data "the event". This event table needs to be turned into temporal attributes.

 

The Event Entity

Per the OPA Warehouse Pattern, we should make entity / temporal conversion a first-class consideration and give it its own Word / Excel document.  So, in our example, we created "Temporal Conversion Rules.docx". (A future blog post on recoupment will provide the full project used for these examples.)

"the event" is our input data, but as in the real world, "the event" entity must be filtered, because the entity serves multiple purposes that can't be combined realistically into one temporal attribute.

Here is a sample of "the event" data taken from my test cases:

the event id

the event start date

the event end date

the event amount

the event record date

the event type

the event status

the event case notes

1

1/12/2015

3/12/2017

1000

1/15/2016

asset

recorded

Client declares asset worth $1000

2

1/15/2016

 

 

1/15/2016

status

active

Case made active by worker

3

2/1/2016

2/1/2016

60

2/1/2016

payment

recorded

First payment per 1/31/2016 determination

4

3/1/2016

3/1/2016

60

3/1/2016

payment

recorded

Second payment per 2/29/2016 determination

5

1/1/2014

4/12/2017

-1000

3/1/2016

asset

recorded

Client small change in prior circumstance - backout

6

1/1/2014

4/12/2017

900

3/1/2016

asset

recorded

Client small change in prior circumstance - new value

7

4/1/2016

4/1/2016

42

4/1/2016

payment

recorded

Third payment per 3/31/2016 determination

8

5/1/2016

5/1/2016

54

5/1/2016

payment

recorded

Fourth payment per 4/30/2016 determination

9

1/1/2013

5/12/2017

-400

5/1/2016

asset

recorded

Client large change in prior circumstance

10

5/31/2016

 

 

6/1/2016

recoupment

full

Client must provide full recoupment

11

6/10/2016

 

 

6/10/2016

status

inactive

Client disenrolls

12

6/30/2016

 

 

7/1/2016

recoupment

arrears

Client is now in arrears. After 90 days, accrues interest.

13

10/31/2016

10/31/2016

  1. 0.66

11/1/2016

adjustment

recorded

Client comes back. We assess interest, however…

14

11/10/2016

 

 

11/10/2016

status

active

Client comes back.

15

11/10/2016

 

 

12/1/2016

recoupment

full

Recoupment now full

16

12/10/2016

12/10/2016

-36.66

12/10/2016

adjustment

recorded

Let’s reset with a forgive.

17

12/10/2016

 

 

12/10/2016

recoupment

not required

stop recoupment logic

18

1/1/2017

1/1/2017

30

1/1/2017

payment

recorded

Normal payment

19

2/1/2017

2/1/2017

45

2/1/2017

payment

recorded

Let's make an incorrect payment due to bad rule

Looking at that data, I decide to create temporal attributes for each event type with the exception that I will make payments and adjustments one temporal attribute. The other columns become either filters or assigned values, if needed.

Also, I want to be able to filter the event input data to only include events up to and including some specific date – a circumstance date. I explain why in a prior blog on "OPA Context Pattern".

Recommendation: when creating temporal attributes from transactional entities, consider filtering on a circumstance date such that rulesets can determine when data was known at a point in time.  This may be necessary for many features such as determining if a rule change impacted a decision or if it was a change in data.

 

The process I uses is as follows:

Step 1

So, step #1 in converting from entity to temporal is to define your relationships. The temporal functions all take a relationship to entities as their first parameter. It follows that you need to be clear about what that relationship points to.

I have four relationships to "the event" entity. The relationships are "the asset events," "the payment events," "the case status events," and "the recoupment events." I put their rules in the temporal conversion document as they are rules about source system data structure and not substantive business rules.

Source

Target

Type

Text

the context

the event

Many To Many

the asset events

the context

the event

Many To Many

the payment events

the context

the event

Many To Many

the case status events

the context

the event

Many To Many

the recoupment events

In Step 1, we classified the temporal events using a relationship. Very simple.  Notice the filters (conditional statements).

Of special importance, notice the filter of "the event record date <= the context circumstance date".  Per the "OPA Context Pattern" this condition allows each context to only see and apply rules against data known at a particular point in time, such as the prior month.

 

Step 2

Step 2 is to either use the temporal functions or a natural language trick to create the temporal attributes per the picture above.

First, let me demonstrate temporal functions.

Conversion to the case status attribute and the historical recoupment status attribute are very simple word tables using the temporal functions. Note that the Oracle help documentation doesn't put the assignments in tables; however not putting the assignment in tables is usually a bug waiting to happen.

Recommendation: Consider being specific about your "otherwise" clauses for the non-Boolean attributes, even if the value is to be uncertain.

 

Now, let me demonstrate the natural language "trick".

The natural language "trick" is subtle.  It uses the "OPA Access Timeline Pattern" discussed in a previous blog. I purposefully demonstrate it with the payments and assets temporal attributes which require a daily summation.

In natural language, I create intermediate temporal "filter" attributes. This gives me additional selection of data beyond the conditions used to create the relationships for temporal functions.

I put these intermediate attributes in each event entity. In this example case, the temporal filter attribute is called "the event needs to be summed."

In this fashion, the temporal conversion may be part of the substantive rules so policy staff can help verify the conditions for event selection. In the substantive rules document, here is the business rule for the intermediate attribute:

 

The result puts a Boolean in each event entity that looks like this:

Then, creating the temporal attribute is a simple assignment as shown below:

 

That will create our last two temporal values from the event table and no temporal functions such as TemporalFromStartDate(a,b,c) were required!

And what will the final four attributes look like in the debugger?