Welcome to the OPA Hub!


Category Archives: Tutorial

Table Headers Tabular Layout Trick 7

Table Headers : Tabular Layout Trick

Table Headers : Tabular Layout Trick

There is always much discussion when users first discover the Interview tab. Let’s be honest – not all of the comments are exactly positive. It all feels a bit, well, basic.

There are a number of things that catch you out at first (and indeed, later). So let’s take a moment to study tabular layouts and a common issue.

For this example I’m going to use the same project (Credit and Visa Cards) as the previous post, since that gives us two entities to work with.

Tabular Layout

Let’s consider that you want to display both entities using tabular layout. You create a Screen and set them both to tabular display. But let’s assume that you want to display the Visa Card with a couple of specifics. You want to include the provider of the credit card. So let’s set that up as a Value List and use an attribute on the Credit Card, and infer it on the Visa Card:

Table Headers Tabular Layout Trick 1So, with that now done, we want to display the Visa Card provider in the Entity Collect (as it is an inferred entity, we cannot use an Entity Collect). But we want to display it as a label as you can see in this screenshot (we added a name to the attribute as you saw in step one so we can reference it in our Screen:

Table Headers Tabular Layout Trick 2Notice how we added a label and used that to display the text of the provider? Using a label ensures three things

  1. It is read-only
  2. If the user is tabbing from input to input, the cursor will not get stuck in that field
  3. It doesn’t look like a read-only input, just a label (which is what we want).

But the downside is that the label does not have a table header in that column, since the Interview designer only adds those for Inputs:

Table Headers Tabular Layout Trick 4

I find it a shame that we cannot put table headers in this “tabular” column, since in HTML a table should have column headers. In fact if we take a moment to inspect this table in the browser, we note that annoying, there is a table header in the table:

Table Headers Tabular Layout Trick 5

So, we need to get that table header populated with our chosen text. But how shall we do it? We don’t want to create an Entity Container extension, since that would mean we have to do the whole thing from top to bottom. So we only want a little tiny change. We have a couple of choices.

  1. Create a Style Extension for the Entity Collect
  2. Create a Label Extension for stealth modification

Let’s try the first option, since it reveals some interesting facts about Styling Extensions. Firstly, get ready by doing the following; change the text associated with your entity in the Interview by double-clicking where the rectangle is, and entering whatever text you would like to display in the missing header.

Then add a compound Styling Extension to your Project. Tabular Containers allow for nested styling, like this:

OraclePolicyAutomation.AddExtension({
style: {
tabularContainer: function (control) {
if (control.getProperty("name") === "xContainer") {
style: {
headerRow:
YOUR STUFF GOES HERE
 
}
}
}
 
}
});

Notice the “headerRow” is a child of “tabularContainer”. And notice the line that says YOUR STUFF GOES HERE. Now for an interesting fact about Styling Extensions. They behave, to a reasonable degree, just like Control Extensions. They are really one and the same thing – the main difference of course is the handlers that are exposed in Control and Interview Extensions.

Drop jQuery into your resources folder, and then replace YOUR STUFF GOES HERE with the following line:

$("#opaCtl4th0").text(control.getCaption());

Of course, the jQuery selector may be different for you but it is easy to find the “header” I illustrated in the previous screenshots. Open your Project in a real Browser (Ctrl+F5) for debugging and take a look at the results:

Final Header Result

Our Styling Extension has added the text to the header, drawing it from the Interview Screen Entity Container definition, and we have it where we want it. Of course, you could style it as well.

But it goes to show that Styling Extensions are really not very different to Control Extensions!

Fun with Aliases and Strings #2

Fun with Aliases and Strings #2

Returning to the ” Aliases and Strings”  theme of the previous post, where we looked into an example of String concatenation. Just a reminder, in the previous article you created the entity model and set up a couple of relationships, before using a rule to decide if the ticker tape instance is a member of a relationship called  the next ticker tapes.

So here is the continuation of the document you saw in the previous steps:

Aliases and Strings #2

The first part should look reasonably familiar, since it builds on the example with the next ticker tapes. But is uses the second relationship, called the closest ticker tape. Note the wording closest ticker tape not ticker tapes. We are aiming for the closest one, or if you prefer, the next one in line. So for ticker tape number 3, the closest would be number 4.

Dodgey Ticker

We again use an alias, but things get a bit sticky in the following parts. Where did the further ticker tape come from? Well, perhaps unsurprisingly, it’s another alias. You see, we already used the other ticker tape in the conclusion so we need to use another word : in this case further was my personal choice, but it could have been another word that meant something in this context. So by now we have the following, expressed in conversational style :

Compare ticker tape A (with other tapes, let’s say B, C and D). B,C or D will be called the closest ticker tape if the following is true.

  1. B,C or D have an ID that is higher than the ID for A
  2. Using the next ticker tapes as your starting point (so, B C and D)
  3. Compare them (so B compared to C, B compared to D etc) to this rule
  4. Is B’s ID is less than or equal to C (for example)?

So we end up with the ticker tape that is in the next ticker tapes AND has an ID that is less than or equal to the other next ticker tapes. So it is the closest one.

I’m reminded of this excellent conversation from Monty Python since it can get a bit confusing at first:

video

The final rule concerns whichever ticker tape has the longest string. And that string is what you are about to create, for each and every instance of your entity.

We’re coming with you!

You will generate a string of text for each of the entity instances (so, for each of the ticker tape instances). And this string will be the driver of a logical loop.

Firstly, let’s set your scene and remind of the context:

  1. “Text 1”
  2. “Text 2”
  3. “Text 3”

Each ticker tape has a text message, for example “Text 1” . This message should be concatenated with the other text messages to form a long “final” string. Each should have a comma inserted between them, into the final string, and of course a “.” at the end. Just to make a nice tidy “final” string. It might look like “Text 1, Text 2, Text 3.”.

Aliases and Strings #2

So each instance has a text string, and a “final text”. The “final text” will be the ticker tape text string concatenated with the closest ticker tape’s text string, plus a comma if required – for example if there are no “next ticker tapes” for a given tape, it’s because we have reached the end of the instances (number 4 , if there is no number 5).

The following attributes give us the numbers used in the table above:

Aliases and Strings #2

And the final (final) global attribute:

Final String Result

Aliases and Strings #2

In the next part of this series, there will be a chance to look back on the techniques, observe the warning message and generally investigate your logical loop.

Aliases and Strings part three will be with you in a few days, In the meantime of course you can read the online help here.

Excel as an OPA Data Connection #2

Excel as an OPA Data Connection #2

So, following on from the previous post in this ” Excel as an OPA Data Connection” series, we have been investigating using Excel as both the Metadata and Data storage for a prototype Connection. The goal being that if I want to quickly model something and show it to a prospect I can do everything in Excel, and do not need any other software.

The previous post laid out the architecture, and highlighted that we would be putting the Excel on a Web Server and using a Web Service to open and manipulate the Excel file. Once again, this is just a bit of an interesting concept and is not at all for real-life use, especially as Microsoft has explicitly stated that remote automation with Microsoft Office is not a good idea (nor is it supported).

Excel as an OPA Data Connection : Common Points

In our Web Service code, the three main endpoints (GetMetadata, Load and Save) have a great deal in common. They all manipulate either DataTables (Load and Save) or MetaTables (GetMetadata) and in the case of DataTables they have Row(s) and DataField(s) whilst the MetaTables have MetaFields.  Essentially your job is to build these into a hierarchy, and they form the response that is sent back to Oracle Policy Automation.

In the screenshot below, the Excel data range is being parsed into a series of Metafields for the GetMetadata response, and we are setting the different tags of our SOAP response. I took a shortcut in the prototype and no matter which metadata you ask for you get all the fields back in the response.

 Excel as an OPA Data Connection GetMetadata

Excel as an OPA Data Connection : Context

In the case of the Load and Save, they receive either loadrequest.context or saverequest.context which will contain any URL argument items you want to pass into the Service (for example, in a Load, you will pass an ID which will correspond to the row of data you want). You can pass in as many as you want.

In the screenshot below, you can see that both the Load and Save have the context object available. In the code, since it is a prototype, we assume the only context element is the one we are looking for.

 Excel as an OPA Data Connection Context

Excel as an OPA Data Connection : Load and Save

In the case of a Load request, you will send back the Tables and Row(s) and Fields for the Interview. In the case of a Save request, since we are only handling updates in our prototype,  we send back the Row and Fields as the response, marking them as “input” fields. We are not using Load after Submit in our case, so there are no “output” fields to send back. If we were to handle inserts, we would have to send back the Row and Fields in that case as well, plus the ID of the new record for example in a Load after Submit.

In the screenshot below I am testing the Load Response, hard coding some values into the fields. Note the “TEST” value at the top. In the finished version of course, these are replaced with Excel Cell contents.

 Excel as an OPA Data Connection Load Example

Since the entire Web Service is written in Visual Basic, it is a great learning opportunity to be able to dump the XML requests and responses to files, in order to better understand what Oracle Policy Automation is sending or receiving. In the screenshot below, a Save Request being sent to the Web Service.

 Excel as an OPA Data Connection XML Example

Excel as an OPA Data Connection : Attribute Types

One area where you can get quite confused is the different ways to indicate what kind of attribute you are working with. In the request for a save, for example, there are field types for each attribute which are actually constants (0,1,2,3,4 and so on, one for each type). When building the save response I needed to then map that number to an AttributeTypeEnum (another constant value) and set the ItemElementName to get the “<date-val>” or “<text-val>” tags that you need. It took a while to work out the logic. Between MetaFields that say they are “STRING” and DataFields that say they are “text-val” it can get a bit boring!

Here’s the sort of thing I mean, checking the fieldtype and mapping to the AttributeEnumType:

Excel as an OPA Data Connection : Video

Rather than keep on writing, let’s have a video to put it all together and see the adventure in the flesh, doing what it is supposed to do!  This was great fun, and is definitely a cool way to learn more about the Connector API and what would be needed when building an integration. Of course, these days we have Integration Cloud and so many more managed tools and services but I am of the opinion that it is better to be over-informed than under-informed. Speaking of which, if you need to read the official Connector API Overview, you will find it here.

Of course there is more that could be done. As described above, the first thing will be to implement record creation. Then, perhaps, a child table or two using the same basic principle. Who knows, one day when I have more time I might come back to it.

If anyone wants the Visual Studio Project and code, then just leave a Comment. Have fun!

 

 

 

We Have A Winner! OPA Hub Complete Quiz – February 2019

We Have A Winner! OPA Hub Complete Quiz – February 2019

It is with uncommon pleasure that I can announce the winner of the OPA Hub Complete Quiz – February 2019. More about the winner in a moment, but just in case you didn’t know it already, we are now running a regular Prize Quiz. It has 100 questions and a maximum time of 90 minutes. The questions are in fact the collection of 10 different quizzes we already have – so if you did well in those quizzes then you will probably do very well in the OPA Hub Complete Quiz.

OPA Hub Complete Quiz BannerThe Quiz will now be refreshed with more questions (we aim to build a pool of about 250 questions by the end of the year) and restarted with a fresh leaderboard very soon. Watch this space to find out when the next Prize Quiz goes live. I guess I am also saying that you shouldn’t do the Complete Quiz until I restart it, because you would not be entered in the Prize Draw.

So what are the prizes?

  • First Place (Highest Score, and in case of identical score, the fastest to complete the Quiz will will a USD $50 Amazon Voucher
  • Second Place will win a stunning new OPA Hub Website T-Shirt
  • Third Place will win a stunning new OPA Hub Mug

And so, on to the…

Winner of the Inaugural OPA Hub Complete Quiz

Ladies and Gentlemen, I give you Allen Pak of Speridian Technologies, an experienced Rules Consultant. I’m hoping (s)he is reading this, and will get in touch to let us know the delivery address for the Amazon Voucher. And because Allen was the only winner this time, (s)he will also get a T-Shirt and Mug just because we are feeling generous. I hope (s)he will send us a photo of the T-Shirt and Mug in action. Please let us know size for the T-shirt too!

Congratulations to Allen. If you want to get practicing for the next Prize Quiz, start here.

Dynamic Charts in Container Controls Example Image

Dynamic Charts in Container Controls

Dynamic Charts in Container Controls

As many of you know, we try to provide JavaScript Extension examples for you to experiment with in your own Projects. A while ago, we looked at an interesting question about using Dynamic Charts in Container Controls – basically to display a chart (which is the sort of thing it was designed for),  but to also include the capability to update the chart live as the data is edited on the same Screen. A quick animation will give you the idea:

The example is an interesting one, on account of it allowing us to talk about the difference between viewing data that exists already, versus using data that has just been created.

To keep it simple, we can think of server-side data and client-side data. Server-side data, for example used in Container Controls, represents the data that has been collected in a previous Screen. It’s already been seen by the determination server.

Client-side data is information that has been entered on the current Screen before the Next button has been clicked. So as far as the determination process is concerned it is “not quite there yet”.

The same concepts exist in the world of JavaScript extensions. For example, consider the difference between these two keys : mount and update from the updated  Container Control example that is available here.

 return {
                mount: function(el) {
                    console.log("Starting customContainer Mount");
                    if (document.readyState == 'complete') {
                        var rows = [];
                        for (i = 0; i &lt; entities.length; i++) {
                            entity = entities[i];
                            if (entity.entityId === "payment") {
                                break;
                            }
                        }
                        rows = entity.instances;
                        var myFlatList = [];
                        var myObject;
                        var width = 300,
                            height = 300,
                            radius = 150,
                            color = d3.scaleOrdinal(d3.schemeCategory10);
                        var size = rows.length;
                        for (i = 1; i &lt; size + 1; i++) {
                            myObject = new Object();
                            myObject.label = control._source.screen.serverState.payment['the payment' + i].payment;
                            myObject.value = control._source.screen.serverState.payment['the payment' + i].amount;
                            myFlatList.push(myObject);
                        }
                        data = myFlatList;
                        var vis = d3.select(el);
                        vis.select('svg').remove();
                        var vis = d3.select(el)
                            .append('svg')
                            .data([data])
                            .attr('width', width)
                            .attr('height', height)
                            .append('g')
                            .attr('transform', 'translate(' + (width / 2) + ',' + (height / 2) + ')');
                        var arc = d3.arc().outerRadius(radius)
                            .innerRadius(0);
                        var pie = d3.pie()
                            .value(function(d) {
                                return d.value;
                            });
                        var arcs = vis.selectAll('g.slice')
                            .data(pie)
                            .enter()
                            .append('svg:g')
                            .attr('class', 'slice');
                        arcs.append('svg:path')
                            .attr('fill', function(d, i) {
                                return color(i);
                            })
                            .attr("d", arc);
                        arcs.append('svg:text')
                            .attr('transform', function(d) {
                                d.innerRadius = 0;
                                d.outerRadius = radius;
                                return "translate(" + arc.centroid(d) + ")";
                            })
                            .attr('text-anchor', 'middle')
                            .text(function(d, i) {
                                return data[i].label;
                            });
                        console.log("Ending customContainer Update");
                    }
                    console.log("Ending customContainer Mount");
                },
                update: function(el) {
                    console.log("Starting customContainer Update");
                    var myFlatList = [];
                    var myObject;
                    entity = control._source.publicInterface._source.screen.clientState.payment;
                    var rows = [];
                    rows = entity;
                    for (var key in entity) {
                        if (!rows.hasOwnProperty(key)) continue;
                        var obj = rows[key];
                        for (var prop in obj) {
                            if (!obj.hasOwnProperty(prop)) continue;
                            myObject = new Object();
                            myObject.label = obj.payment;
                            myObject.value = obj.amount;
                        }
                        if (myObject.label != "") {
                            myFlatList.push(myObject);
                        }
                    }
                    var width = 300,
                        height = 300,
                        radius = 150,
                        color = d3.scaleOrdinal(d3.schemeCategory10);
                    data = myFlatList;
                    var vis = d3.select(el);
                    vis.select('svg').remove();
                    var vis = d3.select(el)
                        .append('svg')
                        .data([data])
                        .attr('width', width)
                        .attr('height', height)
                        .append('g')
                        .attr('transform', 'translate(' + (width / 2) + ',' + (height / 2) + ')');
                    var arc = d3.arc().outerRadius(radius)
                        .innerRadius(0);
                    var pie = d3.pie()
                        .value(function(d) {
                            return d.value;
                        });
                    var arcs = vis.selectAll('g.slice')
                        .data(pie)
                        .enter()
                        .append('svg:g')
                        .attr('class', 'slice');
                    arcs.append('svg:path')
                        .attr('fill', function(d, i) {
                            return color(i);
                        })
                        .attr("d", arc);
                    arcs.append('svg:text')
                        .attr('transform', function(d) {
                            d.innerRadius = 0;
                            d.outerRadius = radius;
                            return "translate(" + arc.centroid(d) + ")";
                        })
                        .attr('text-anchor', 'middle')
                        .text(function(d, i) {
                            return data[i].label;
                        });
                    console.log("Ending customContainer Update");
                },

Notice that the mount key uses the server-side data : when we draw the Control, we can only draw what is already available to us. But in the update, we want to take into account the new data entered by the user, so we look for the client-side data. So now we can be more specific : you can access clientstate and serverstate information which can help you work with previously entered or just-entered dynamic information.

Hope you have fun building your Dynamic Charts in Container Controls! We’ve updated the Shop example to include the complete Zip File.

Dynamic Charts in Container Controls Example Image

Showing a Loading Image During Entity Creation

Showing a Loading Image During Entity Creation

When a user is entering some information into Entity attributes, it is entirely possible that one of those entity attributes may take its information from a Search extension. For example, you are entering instances of the Person entity and each Person has a location, so you want to select the location using a Search extension.

The Search, given that it is perhaps an Ajax call, could take some time. So you want to signal to the user that there is nothing to worry about, but they need to wait. Typically this is done through some sort of icon or image being displayed, much in the style of the Windows egg-timer or similar. This probably will also need a CSS style rule or two, in order to make it a bit funky.

We want to make sure that this is displayed in the right place, even if the user is creating several instances of the same entity. I mean that the icon should be displayed in the correct area of the screen, especially if you have instances whose screen layout takes up some space.

Anyway as always a picture is worth a thousand words. Here is the instance collection form:

Showing a Loading Image During Entity CreationWhen you have several on the screen, it might look like this:

Showing a Loading Image During Entity Creation

The Destination attribute is a Search extension that helps the user search for a Train Station in the United Kingdom. It take a few seconds for the search to happen.

So our timer needs to be shown in the right place whenever the user is searching. It needs to be instance A or B for example, depending on the instance the user is working on.

Showing a Loading Image During Entity Creation

In the example above the user has typed the Search criteria. The loader is shown in the centre of the instance while the search is happening. So we are Showing a Loading Image During Entity Creation.

Showing a Loading Image During Entity Creation

When the search data is returned, as in the example above, the user should no longer see the loader and the operation can continue as normal.

If the user moves to another instance, then the process should start again but the loader should be instance-aware and show in the correct place so as not to confuse.

Showing a Loading Image During Entity CreationTo do this we can use the Search extension, and add a little bit of extra code to

  • Check to see if we have already displayed the special icon
  •  If we have not, create it, center it on the instance we are working on, show it and make the Search
  • If the icon already exists, move it to the correct instance and show it then make the Search
  • When the search data is returned, hide the icon until the next time.

This example will work with non-tabular forms. I’ll be back with a second post investigating them in a couple of days.

You can find this simple example (with all the usual caveats and reminders that this is just for fun) in the OPA Hub Shop.  The official documentation is here, as always. Thanks to Shankar for the great example of Showing a Loading Image During Entity Creation!

Siebel CRM as a custom Search source

Siebel CRM as a custom Search source

This post is inspired by a conversation I’ve been having over the last few days with another OPA consultant (thanks Prashil!) . Although as it turned out, the requirement had nothing to do with Siebel (that will teach me to not assume anything!), the concept of making REST calls to a CRM or CRM-like data source has been on my mind. But how can I use Siebel CRM as a custom Search source?

In this example, we will use Siebel 2018 as the source of a custom Search box. Along the way we will see how the Siebel CRM REST API sends us data and what we can do with it. At the same time, we will indulge in some trickery to not show everything we have in our Search results to the user. It will mean we create two JavaScript extensions, a Search and a Full Input.

Firstly, the Siebel 2018 instance in question is using the standard REST API, and it is the standard Component called Account which we will be querying. In many public services, Account is used to store partner organizations, external suppliers and so on. It is a very common component. The base URL for the REST calls in my case will be something like the following

https://XXXX:9001/siebel/v1.0/data/Account/Account/?fields=Name,Location&?ChildLinks=None&searchspec=([Name] LIKE '"

There are three things to note here.

Firstly I am only interested in two fields (the third field I need, Id, is actually going to be included automatically anyway).

Secondly I am using a Search Specification with Siebel standard syntax to search using the Name of the Account. So if I type “ABC”, it will look for Accounts starting with ABC.

And finally, the URL string needs to be capped with the following to finish it “*’)” so that there is a wildcard search for ABC Inc, ABC Corp. and so on. The URL also includes an argument regarding child links in the output to reduce volume.

Siebel CRM as a custom Search source

The information returned in a standard output will consist of a series of data.items. So we can iterate over the data.items and for each item, we can get the Item.Name, Item.Location and Item.Id. Since Siebel paginates its output, we are actually only going to get a maximum of ten records unless we add another URL argument and make further calls to Siebel (to get page 2, page 3 and so on). But for a query result, a ceiling of 10 is pretty good for Siebel CRM as a custom Search source.

As a side note, this example – you have noticed – is using the Siebel REST API in its unvarnished, naked form. Obviously you would do well to control / restrict access and authenticate consumers in real life. We’ve seen in previous examples that we can pass headers in our Ajax call when Oracle Policy Automation asks for data from a Search source.

In the Commit callback we will update three attributes with the values of the Siebel Fields I just mentioned. Now, at the moment, if you want to update an Oracle Policy Automation Attribute in a JavaScript extension, that attribute needs to be on the active Screen for it to work. So what happens if you don’t want to show that value to the end user, but you still want to capture it for future use in your rules?

One approach (which I am using for demonstration purposes only you understand, as usual) will be to create an invisible Input, so that we can add our data to the Screen without the user seeing it. To do this you might use a fullCustomInput extension. This is different from the customInput, because it manages the Question Text and the Input control. So we can place it on our page and format the whole thing – even perhaps make it disappear.

Siebel CRM as a custom Search sourceThe two examples working together are shown in the video below, and I have added a more appropriate fullCustomInput example, as well as the Siebel customSearch example, to the OPA Hub Shop. I am also in the process of adding them to the Template Generator, so you will be able to generate a fullCustomInput and a sample Siebel customSearch yourself as well.

Have fun with Siebel CRM as a custom Search source, and as always the official documentation is your guide.

What is Happening Here – Date Function with Wrong Date

What is Happening Here – Date Function with Wrong Date

See if you can guess : What is Happening Here?

Below is a project written in Oracle Policy Automation 12 (this was actually in 12.18B but it has no bearing on the example). It has only one attribute : the date of the next visit. This is written as follows:

The date of the next visit= YearEnd (AddYears(the current date;1))

The date you are running the Debugger, the current date is November 19, 2018. The rule should perform a simple assignment, taking the current date, adding a year and then using that as the input for the YearEnd function. So :

YearEnd(November 19, 2019)

This should give the value of December 31 2019. Also, there are no other attributes in this project. There are no JavaScript extensions, no custom controls, no CSS or other additions. The project is being built using English language. The project does not have any translations, forms, or anything else inside it. But the Debugger  session of the Oracle Policy Automation Interview displays the following:

OPA 12 - What is Happening Here

The date is incorrectly showing 12/31/20. So what is happening here? Even more fun, the Data tab of the Debugger shows the following:

OPA 12 - What is Happening Here

The value is correct on the right, wrong on the left. So what has happened to the Oracle Policy Automation project in this example?

You are free to give the answer, if you know it, in the comments. I will come back in a couple of days and explain. And before you ask, yes, I can across this in the real world yesterday and it is not a bug, it did not require a Service Request, and somebody had done something. The behavior is entirely reproducible I would imagine in any language.

Sometimes you want to write about something (in my case, I wanted to look at Silent and Hidden settings) but life gets in the way. This was such an amusing thing (with hindsight) that I decided to write about it instead.

Enjoy this and hopefully you will immediately have spotted the possible culprit. You can peruse the documentation online here.

Guest Post : Time Based Reasoning Worked Example

Guest Post : Time Based Reasoning Worked Example

It’s with great pleasure that I introduce you to Evert Fernandes, CTO at Magia Consulting UK Ltd. A self-confessed OPA geek, Evert has stepped up and written this article about Time Based Reasoning (and hopefully some more ) for the OPA Hub Website. Thank you Evert and…over to you!

Time Based Reasoning (TBR) – also known as Temporal Reasoning – is one of those subjects that new OPA developers tend to struggle with. It’s a more advanced subject that – once mastered – can provide huge benefits to your project.

In this article I will try to explain what TBR is, present a use case and provide a walk-through on turning the use case into rules.

So, what exactly is Time Based Reasoning?

Time Based Reasoning allows the rule developer to create rules that include attributes which contain values that are subject to change over time.

It is able to conclude rules like:

  • What’s the amount of daily benefit the citizen was entitled to on June 26th, 2017?

Time Based Reasoning Worked Example

Let’s have a look at the following use case:

“How much benefit is the citizen entitled to between 01-01-2017 and 31-12-2017 (inclusive)”

The following rules apply:

  • If the person is not married, the daily allowance is $10. If the person is married the allowance is $14
  • The person can only claim benefit if the daily income is less than $200.

For the sake of simplicity, we will only look at a binary relationship status, married and single. The real world is more nuanced and complicated, but feel free to expand on this example. 😉

As you can see, the mix of variables already creates quite a complex and fluid situation, especially considering that any of the variables are subject to change over the period in question (01/01/2017 – 31-12-2017).

So, let’s start by looking at the first element and create some rules:

OPA 12 - Time Based Reasoning Worked Example 1

There are a number of things happening in these rules, let’s take a closer look.

First of all, a rule table has been created (ALT + Z) to determine the daily allowance amount based on marriage status, $14 when married and $10 when single. The single status is implied by the ‘otherwise’ conclusion, i.e. the person is single because the person is not married.

The second rule calculates the total allowance over the time period, starting on January 1st 2017 and ending on January 1st 2018. The reason the end date is January 1st 2018 and not December 31st 2017 is because the end date is not included, so we simply add a day.

The function is called IntervalDailySum and takes in three parameters:

  • The start date (inclusive) of the period over which the calculation needs to take place;
  • the end date (exclusive) of the period over which the calculation needs to take place;
  • the rule text of the attribute over which the total daily allowance over the period needs to be calculated.

In this example, we provide hard coded values for the start and end dates. In the real world, the start and end dates will most likely come from date attributes.

We now need to test the rules. In order to do this, we start the OPM debugger and head to the data tab:

OPA 12 - Time Based Reasoning Worked Example

As you can see, not a lot is happening here. Let’s give the citizen a marital status by setting the value of ‘The citizen is married’ to ‘True’.

OPA 12 - Time Based Reasoning Worked Example

So far, so good. We have a marital status and OPA is able to work out the total allowance (365 days x $14 = $5110).

Let’s now assume that the person was single at the start of 2017, got married on March 1st 2017 and was single again on September 1st 2017 (don’t worry, they’re still friends! 😉).

How do we enter that data? OPA provides a handy feature called ‘Change Points’ to handle this.

Let’s reset the value for the citizen marital status:

OPA 12 - Time Based Reasoning Worked Example

Click on ‘Change Points’:

OPA 12 - Time Based Reasoning Worked Example

What this allows us to do is to take the attribute and set different values for different slices of time.

You can use ‘Add’ to add a new change point. Once a new point is created, you can set the date and value at that point in time.

Let’s add two change points. One on March 1st 2017 with a value of True and the other on September 1st 2017 with a value of False. Use the Date picker below the change point list to pick the dates.

OPA 12 - Time Based Reasoning Worked Example

The eagle eyed among you may have spotted that I’ve set the value at the top to ‘False’.

What this is saying is:

  • Until March 1st 2017, the value is False.
  • Between March 1st 2017 (inclusive and August 31st 2017 (inclusive), the value is ‘True’.
  • From September 1st 2017 and after, the value is ‘False’.

So, click ‘OK’ and let’s inspect the effect of our handiwork in the debugger:

OPA 12 - Time Based Reasoning Worked Example

There’s a lot more information here and one of the first things you’ll notice is that the total allowance has changed from $5110 to $4386.

If we break down the individual periods, you will see why:

  • January 1st – February 28th = 59 days x $10 (Single rate) = $590.
  • March 1st – August 31st = 184 days x $14 (Married rate) = $2576.
  • September 1st – December 31st = 122 days x $10 = $1220.

$590 + $2576 + $1220 = $4386!

Have a play with different dates and change points and you will find OPA is very good at working this stuff out for you.

OPA also offers a way to visualize this data. Right click the ‘the daily allowance for the citizen’ attribute and select ‘Show in Temporal Visualization’:

OPA 12 - Time Based Reasoning Worked Example

A new tab will appear top left named ‘Temporal Visualization’. If you click it, you will see:

OPA 12 - Time Based Reasoning Worked Example

This visualization confirms that we start off with $10/day, changing to $14/day from March 1st and changing back to $10/day on September 1st.

Time to complicate things a little by adding another variable to the mix in the shape of the daily income.

Let’s assume that the citizen started 2017 with a daily income of $150. Then later in the year the income rose to $250 and later yet, the income dropped to $180.

In order to deal with this new variable, we will change the rule that calculates the daily allowance to include the daily income for the citizen:

OPA 12 - Time Based Reasoning Worked Example

Remember that OPA will evaluate top down, so first it will check to see if the person is married and whether the daily income is less than $200. If this is false, it will check to see if the income is less than $200 and finally, if the citizen is not married and the daily income is greater or equal to $200, the ‘otherwise’ clause will apply.

Make sure the updated rule validates by pressing the ‘Validate’ button.

Now let’s start a debug session and have a look at the outcomes.

Start your debug session and navigate to the ‘data’ tab.

Supply the exact same values as the first example, making sure to set up the change points correctly.

Fun fact: Chances are that OPA still has your previous values in memory, saving you the need to re-enter them!

Check to see that you’re still getting the correct values.

You should see something like this:

OPA 12 - Time Based Reasoning Worked Example

Let’s set the value and change points for the daily income:

OPA 12 - Time Based Reasoning Worked Example

Click ‘OK’ and inspect the values in the data screen:

OPA 12 - Time Based Reasoning Worked Example

As you can see, the total allowance has now been set to $1926 (down from $4386).

We can have a look at what’s been happening in the Temporal Visualization tab.

Make sure the following attributes are shown by going to the debug data tab and right-clicking and selecting ‘Show in Temporal Visualization‘:

  • the daily income for the citizen
  • the citizen is married
  • the daily allowance for the citizen

Go to the ‘Temporal Visualization’ tab. You should see something like this:

OPA 12 - Time Based Reasoning Worked ExampleOPA 12 - Time Based Reasoning Worked Example

As you can see, there’s quite a bit going on here and the daily allowance for the citizen will vary based on marital status and income.

What you will hopefully be able to see is that, when it comes to dealing with changing circumstances, things can get quite complicated quite quickly. In the example we only dealt with two variables but throw in more variables and working out the right amounts would become very complex! Utilizing the out-of-the-box OPA temporal reasoning functionality allows you to manage the complexity of dealing with changing circumstances over time.

More information on Temporal Reasoning can be found in the OPA documentation:

https://documentation.custhelp.com/euf/assets/devdocs/cloud18c/PolicyAutomation/en/Default.htm#Guides/Policy_Modeling_User_Guide/Temporal_reasoning/Temporal_reasoning.htm

or in the Function Reference:

https://documentation.custhelp.com/euf/assets/devdocs/cloud18c/PolicyAutomation/en/Default.htm#Guides/Policy_Modeling_User_Guide/Work_with_rules/Function_references/FunctionReference.en-US.html

Finally for those who were wondering, the daily amount that the user is entitled to on June 26th is…

OPA 12 - Temporal Reasoning Worked Example

OPA 12 - Temporal Reasoning Worked Examplewhich is $14!

Thanks to Evert for his time and excellent article abut Time Based Reasoning. Readers who what to look at more Time Based Reasoning articles can search here.

Until the next time. If you want to write for the OPA Hub Website, reach out via our Contact Page.

Extension Code Generators for JavaScript

Extension Code Generators for JavaScript

Over on my other home (https://siebelhub.com) we use and promote the use of Code Generators : because most of the JavaScript people need to create is in fact very structured, because of the underlying extension architecture. You don’t write just any code, you write code the way you have to write it. So how to write Extension Code?

[Update 1 November 2018 : I added fullCustomInput as an option. I also added more explicit logging – so if you use multiple files you can see which is doing what. I also tidied up a few things]

It struck me the other day that this is equally true now for Oracle Policy Modeling – JavaScript extensions have a very well defined structure, and as I said above : you don’t write just any code – you write it the way you have to write it, in order to fit into the underlying architecture of our beloved interview.js.

Since I find myself often repeating the same JavaScript task over and over again – for example I need to create 2 custom Labels for 2 different projects or customers – I do a lot of cutting and pasting. But that often goes wrong as I forget I’ve renamed something or changed a variable somewhere.

So I decided to create a Code Generator – a sort of tool to create templates of code that I can use to create new files. And I decided to use Oracle Policy Automation for the job. Here is the sort of thing I am talking about:

Extension Code

By answering a few questions about the code you want to write, the Project generates a template for you to copy and paste into a new Text File and there you have your code to start writing something interesting. There is a Copy to Clipboard button at the bottom of the code.

In the end, I decided to add a few things to the examples to act as learning tools:

  1. The Input Control has Validate and Update options that help understand the way these Keys actually are supposed to work. Validate throws an error message to the user if the text entered does not match a specific validation rule.
  2. The Update Key shows how update is fired whenever anything on the Screen is updated. Useful for updating your Control in response to other activity on the Screen. As an example, the color of the Input changes each time Update is fired.

The Extension Code Generator also includes the custom Search as templates with the following options:

  1. Search lets you choose from a series of standard searches (Airlines, Railways Stations, etc) as well as allowing you to configure your own REST call and lets you add any Headers you need to make your call.

Here is a video that will hopefully shed some more light on what this Project does (or tries to do)!

This seemed like a fun thing to do in Oracle Policy Automation – if you would like a copy of the (18C) project then please leave a comment and I will tell you all about it’s foibles :).