Welcome to the OPA Hub!

Tag Archives: Entities

JavaScript Extensions with a Live Entity-based Chart in Oracle Policy Modelling

JavaScript Extensions with a Live Entity-based Chart in Oracle Policy Modelling

One of the most interesting questions I have been asked during my current assignment in beautiful Madrid has been the following :

“How can I make a Chart”

Well, that’s easy I said : pick your Charting platform (for example, you might choose D3 as the charting library as it is well-known and incredibly powerful. Or alternatively you could manipulate SVG arcs and lines yourself if you want to, to achieve the same thing.

“How can I make a Chart based on Oracle Policy Automation data”

Well, that’s easy I said : you even have an example in the Oracle Policy Automation Example Projects, called the Loan Advisor. You can see a screenshot from that project, right here:

JavaScript Extensions with a Live Entity-based Chart : Intro

Digging deeper into that Project, we discover that the attributes that are used to create the chart are global :

JavaScript Extensions with a Live Entity-based Chart : Intro 2

“How can I make a Chart that uses Entity data”

Well that’s easy I said, you could hook up the D3 library to the entity, and use a similar system to our custom Entity Container example to retrieve the data. After all, the Pie Chart in D3  accepts any array of data organized into labels and values. You may remember in that example, we sought the name of the entity using EntityId and then iterated through the instances in the Entity to display them.

But upon investigation this is not really satisfactory. Adding an instance to the entity container does not refresh the Chart. In fact, you have to navigate forward and then backwards to get the Chart to refresh. That’s because, of course, your new “instance” does not actually exist yet. It does not get added into the entity.instances[i] list until you leave the current screen.

“How Can I make JavaScript Extensions with a Live Entity-based Chart in Oracle Policy Modelling”

You will have guessed by now that my entourage here is pretty demanding! So here goes. Firstly, the scenario. I have created an Entity called the payment. It has two attributes, the identifier, a text attribute, and the payment amount, a currency or number as you wish.

The goal : on ONE Screen, enter data and view a live chart that updates live, without changing Screens, as data is added or removed.

To experiment further with this, I also decided to create another Entity called the shadow payment. This is a copy of the original, created by the simple rule in Word that follows:

JavaScript Extensions with a Live Entity-based Chart Intro 3

The idea was to test if it would work both on inferred and normal entity instances. It seemed to, so you could probably use the code with either. To enable my shadow entities, I set up the relationship for the above Word rules to function properly.

JavaScript Extensions with a Live Entity-based Chart in Oracle Policy Modelling Intro 5

The Code Concept

Now we come to the code itself. This is, as I always state clearly, just code that I have hacked together to see if a concept had the ability to be taken further. It is in no way production or even unit test ready. That’s your problem. But I hope you find it interesting and inspiring.

Another note, I have seen that this “code view” messes with some characters. The OPA Hub Shop has a PDF version which you can use to compare and correct anything that looks wrong, notably the > and < characters don’t show up correctly here.

The code uses D3 for the pie chart, and the explanation follows after the code. Pop D3 in a JS file in the resources folder, as well as the D3 library.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
/**
 * Richard Napier The OPA Hub Website April 2018
 * Educational Example of Custom D3 Chart Extension with live refresh on a screen
 * I will remember this is for demonstration and educational purposes only
 */
 
OraclePolicyAutomation.AddExtension({
	customContainer: function (control) {
		if (control.getProperty("name") === "xChart") {
 
			return {
				mount: function (el) {
 
				},
				update: function (el) {
 
					if (document.readyState == "complete") {
 
						var entity = control._source.screen.serverState.shadowpayment;
						var myFlatList = [];
						var myObject;
 
						var width = 300, //width
						height = 300, //height
						radius = 150, //radius
 
						color = d3.scaleOrdinal(d3.schemeCategory10);
						var size = Object.keys(entity).length;
 
						for (i = 1; i &lt; size+1; i++) {
							myObject = new Object();
							myObject.label =control._source.screen.serverState.shadowpayment["@_@opa-rel-target={payment[the payment" + i + "]}/global[global]"].shadow_payment;
							myObject.value = control._source.screen.serverState.shadowpayment["@_@opa-rel-target={payment[the payment" + i + "]}/global[global]"].shadow_amount;
							myFlatList.push(myObject);
							//console.log(" Flattened the list - item " + i);
						}
						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;
						});
					}
				}
			}
		}
	}
});

Review of JavaScript Extensions with a Live Entity-based Chart

Line 8 : This is a Custom Container. So make sure that you drop a container into your Screen, and in the container make sure you add your Entity. In my example, I displayed both the original the payment entity, for the user to add or delete records, as well as the shadow payment which I leveraged to draw the pie chart.

Line 19 ; This example uses control._source.screen.serverState.shadowpayment. This JavaScript object contains the instances of your entity, and is updated as new instances are added, before you leave the page. Of course the name is the technical name  of your entity so don’t forget to add that to your Data tab.

Line 27 : Selecting a standard set of colors from the D3 color categories

Line 28: Finding how many objects are inside the control._source.screen.serverState.shadowpayment object. Each instance is a child object.

Lines 32 and 33 : Creating dynamically the identifiers of each row to select the label and the value using the names of the attributes in your entity, and copying them into a flat object with values and labels

Line 37 : Set the flat list as the data source for the Pie Chart

Line 40 : Add the Chart into the Container

Line 41 : Add the pie chart, setting the origin to the center of the Container, and hooking up to the data we created

Line 50 and beyond : Using D3, draw the arcs and fills that make the Pie Chart by going through the total set of data and dividing the pie into the right number of pieces.

This is the result, in full Hollywood glory, of JavaScript Extensions with a Live Entity-based Chart in Oracle Policy Modelling.

The PDF version is on the OPA Hub Shop, just search for the Pie Chart example.

We will of course be revisiting this to investigate making it more robust, but it’s a good starting point. Have fun and see you soon!

OPA 12 – It’s all in the Natural Language Text

OPA 12 – It’s all in the Natural Language Text

I suppose this article could have just as easily been about Oracle Policy Modelling 10 as well. But since I was teaching version 12 I decided to use it for the screenshots. I also was teaching a group of French students so the examples are in French and English. Ultimately the same challenges occur no matter what language you are using, provided that language uses definite articles in the same way. Natural Language is not always natural.

Consider the following :

An Entity called “the contact” or “l’interlocuteur”.

OPA 12 - Contact Entity Natural Language

As you can see, the Relationship Text has been changed to “tous les interlocuteurs” or “all the contacts” instead of the standard “all instances of the contact” or “toutes les instances de l’interlocuteur”. I see a lot of students working in this way. However there are some side effects of using this kind of wording…

Let’s imagine that every contact has a telephone number, and we want to check that the telephone number has been entered. The first part is fine, we can write the following rule to assign a Boolean value depending on whether we have a telephone number or not, and let’s build a rule that uses Entity Quantifiers to look at the different contacts.

When is Natural Language really Natural?OPA 12 - For Each of the Contacts Natural Language

In English we would have something like

OPA For Each Contact in English Natural Language

We are using the longest version of the “natural language” Function “ForAll“. And it looks a bit, well, long-winded. So we might try one of the other versions:

OPA 12 - For Each of the Contacts EN Part Two Natural Language

That’s even worse. In French too it’s almost comical …

OPA 12 - For Each of the Contacts FR Part Two Natural Language

That’s even worse. So let us try a different approach. We decide to modify the Relationship Text and remove the “all” to leave only “the contacts” or “les interlocuteurs”. So now our rules look a bit more “natural language” when we use the ForAll function in it’s long form.

OPA 12 - For Each of the Contacts EN Part Three Natural Language

OPA 12 - For Each of the Contacts FR Part Three Natural Language

Of course I can hear people saying, why don’t you just use ForAll or PourTous – that is, the terse or short version of the function? It does of course depend on your environment, but a non-technical user is going to be far more comfortable using a natural language-based solution.

Have fun improving your text, until next time

Rich@rd

OPA – Entities Adventures #9 Testing using What If

What If?

Back in the Workshop now with all our different chapters, things are getting more and more complex. But one feature of the Policy Modelling user interface that we do not cover in the standard training course can come to our rescue. I’m talking about the What If Analysis feature. This is based on Microsoft Excel and reasonably easy to explain to a non-technical user, so it can be leverage to prove that a use case has been understood, or as a tool for working with the business to understand each other.

The use of this functionality starts with a new file in your Project:

OPA - What If Initial View

As you will have seen, the first time you open it can be quite a disappointment. What you need to do is proceed first to an initial setup, then to some data entry. Begin by clicking the Add Worksheet button on the top left, and adding Worksheets for any Entities that you intend to work with. It will end up looking like something like this, using our Workshop as the example:-

OPA - What if Added Entities

Now we proceed to each of the Worksheets and click the Add Column button. We add any attribute we intend to enter data for, as well as any inferred attributes we want to see the results for after our analysis. Notice the color coding for the columns to make it easy to see which are conditions and which are conclusions.

OPA - What If Added Columns

As in the example above, the colors indicate:

  1. Black is an identifier for the Entity on this tab. In our case here, the customer.
  2. Blur is an identifier for another Entity in the Rulebase. In this case, the Global Entity as well as the customer’s car.
  3. Green is a base attribute
  4. Brown is an inferred attribute

Entering the correct data can be a little daunting, since in many cases you will need to remember for example that car #1 is the Fiat, and mechanic #1 is Bob and so on. But you quickly get the hang of it. Common traps include

  • failing to compile your documents before clicking the Analyze button
  • failing to add information to the Global tab.

Remember that all your Entities will fold up into the parent Global, so there will need to a record on the Global tab. Go ahead and click the Analyze button and see what happens. For the purposes of demonstration, enter one car, one mechanic, one customer and one set of wheel-covers. For inspiration here is a carousel of What If Analysis Worksheets with some example data, and the results (ie, these screenshots were taken after clicking the Analyze button.

Hopefully you will see from the carousel that the inferred attributes have been updated following the Analyze button being clicked. Of course why stop there with only one car and one customer. Not only can we enter many of them for our Global Case #1, we can create many Global Cases, and associate our Entity Instances with a different Global Case.

Furthermore once you have built your complex What If scenario, you can export it to a Policy Modelling Test Case file for further testing.

Have fun, until next time

Rich@rd

OPA – Entities Adventures #8 IsMemberOf()

More Functions

Policy Automation has a vast array of Functions that can be called into service at one time or another. Many of them are very specific and we will try and discover a few more of them before the end of this series.

But we can take this opportunity to share with you a couple of “cheatsheets” that we give out sometimes in the Policy Automation training courses. These are PDF files with examples of lots of useful Functions from Oracle Policy Automation.

If you get Error 500 just click the Back button and try again

[stamper_download_button_for_wp_user file_url=”http://www.theopahub.com/mainfiles/OPAL/STRING/TextFunctions.pdf” button_text=”Download Text Functions Now”]

[stamper_download_button_for_wp_user file_url=”http://www.theopahub.com/mainfiles/OPAL/DATETIME/DateAndTime.pdf” button_text=”Download Date Time Functions Now”]

The Workshop

In this episode we will consider another key function

1) The IsMemberOf Function

This function can be useful in determining membership of a Reference Relationship. It is called “inferred membership”

To begin let us examine the scenario for the IsMemberOf function.

IsMemberOf

The IsMemberOf function (or “is a member of”) can be used in two different ways. Firstly as a conclusion, but also as a condition. Let us take a look at them both in a practical example.

Back at our Workshop we want to find out which cars are Italian, since they may require expert care and attention. We might be tempted to write something like this almost straight away, so simple this function sounds.

Hopefully you can see there is a problem. The New Attribute dialog box which appears when you click Compile is showing two boolean Attributes. That does not sound like what we need to make this work. In fact we need firstly to create our “Italian cars” – specifically we need a Relationship to hold the cars we are looking for.

When we compile our simple rule after this, there is a difference:-

And likewise, our Word document shows that the IsMemberOf function is now correctly included in our conclusion.

If we build and debug our rulebase, and populate the new Boolean Attribute “The car is serviced weekly” for each car in the workshop, we will be able to see the results as shown below.

Notice the yellow icon and the nature of the relationship – it is inferred and cannot be directly changed. Only by editing the Boolean Attribute can we change the members of the “Italian Cars”.

IsMemberOf as a Condition

The same function can also be used as a Condition. For example :

The syntax is straightforward as you can see.

Conclusion

The IsMemberOf function gives us flexibility to create inferred relationships.

OPA – Entities Adventures #7 Scope in OPA …

Back to the Workshop!

In this episode, we will look at the subject of cross-entity reasoning again to investigate some functions which we do not cover in the Policy Automation training. Firstly though, we need to talk about Scope.

Scope

Many users of Policy Automation will be familiar (and not in a good way) with “X is not in scope. You may need to use an alias when referring to the X”. It’s one of those errors that most people will get in the construction of rules. To make matters worse, sometimes juggling the rules and changing the order, or moving them into different files, and the error goes away. So what is going on?

Firstly, we need to understand how the Word Compiler works. For it is the Word Compiler we need to think about. The Word Compiler works from top to bottom down the page. And as it works down the page, it uses the entity instances defined in the previous line, as the scope of the current line. Let’s extend our rulebase and focus on customer satisfaction to demonstrate.

Add two new entities, the customer, and the wheelcover. Make sure the wheelcover is a child of the Car entity.

Add the relevant Reference Relationships and make sure the Relationship Text is suitably friendly

Scope in our Word Document Example

Now Consider the following piece of rule text from Microsoft Word. Notice the “cascading logic”.

In the Conclusion, we set up the initial scope as the Customer. In the first line we proceed to “narrow” the Scope to the Customer’s Car. This is acceptable as there is a Relationship defined with the Customer as the Source and the Car as the Target, and it is One to One.

In the next line, we scope down to the Car’s Wheelcovers. Again, as the Customer’s Car was in scope in the previous line, this is acceptable as the Car has a Child Entity called the Wheelcover and there is a Reference Relationship in place. Finally in the last line we have a condition that references the Wheelcover, since it is in Scope.

For completion we show both the terse and the long form. Since the Word document may continue to have further rules in it, you always need to be vigilant about setting scope clearly in each of your rules.

In addition, we need to choose the correct function depending on the nature of the Relationship. In this respect the Function Reference is useful.

In the next episode we will continue our Workshop and build out the various logic we promised a few chapters ago, as well as continuing our Function discovery.

Until next time!

OPA – Entities Adventures #6 Cross Entity Reasoning

Cross-Entity Reasoning

Once again we return to the Cars and Mechanics in the mythical Workshop. The first part of this post will review the French version of the work done in the previous episode, and then we will undertake some cross-entity reasoning using the various functions at our disposal. Catch up with the rest of the series (12345)

The French version looks like this in the Web Determination window. First off, the basic structure is exactly the same and there are no challenges to report.

OPA - French Workshop

Eagle-eyed viewers will notice there is a problem (that we raised earlier in the context of Gender but now is as good a time as any) concerning the title of the page. In fact, despite the Project being French Language and French Region, all the labels are in English (“Data Review”, “Assessment Summary” etc.). You could be forgiven for thinking these came from the “Appearances Property File” in your Release folder:

OPA - Messages FR Properties

But no. The titles that I just mentioned are generated when you add a Screens File to your Project. So even though we have a French Project with French as the Rule Language, we get English titles!

OPA - Titles in English

Common Trap Number #10 – Screen Titles in the wrong language

Irritatingly enough the way to fix this (if it can really be called fixing) is to switch the Language of Policy Modelling to French before you start, in which case when you add a Screens File you will see valid Titles:

OPA - French Screens Titles

Then you can switch the editing language back to English and at least you have the right titles in your Screens File. (Tools > Options > UI Language). I know it sounds silly but there are many occasions when you want to create a Project in another language but you don’t want Policy Modelling User Interface to be in that Language.

Switching back to the English version of our Project, we can now get into some more Functions, specifically cross-Entity functions. These functions are designed to cope with the need to cross from Car to Mechanic in a rule. For example

Consider the fact that Mechanics exist in several types – Expert, Confirmed and Novice. We want to write rules that say

The Car will be ready on time if the Car’s Mechanic is an Expert.

The Workshop is running efficiently if at least 2 cars are being repaired by Experts

The Car, the Mechanic – these are our Entities. The Workshop, our “singleton parent Entity” is the standard Global parent Entiity proviided by Policy Automation.

Let’s look at the Function Reference for the For function that will be useful in our case. We are able to reason cross-Entity, as long as the Relationship type is correct (and between Car and Mechanic it is Many-to-One), and there is only one Condition (the Mechanic is an Expert.

Assuming you take a moment to create an Attribute “The Mechanic’s level” of type Text, then you could examine the following from the Function Reference and get writing.

OPA - For Function Reference

As is often the case, there are long and short versions. There is nothing stopping you using one, or other of these versions as you prefer, interchangeably. But look closely and you will see the definition of the Function has some differences. The short or “terse” version “For (relationship, expression)” looks like this when we write it out: The following should compile.

OPA - For Terse Version

 

Common Trap #11 Assuming All Versions of Functions have the same syntax

But suppose you decided to write using the Long form, “in the case of“. The Function Reference gives a slightly different explanation for that version, if you look closely. It says “in the case of relationship, attribute”. Which is not the same thing as the previous example, And indeed, the example below does not compile.

OPA - For Long Version Error

 

The following example does however, Notice how in this example we have changed the “level” to be a Boolean attribute rather than a Text attribute. It would appear from the Function Reference that the long version is only possible with a Boolean. And that may mean you end up creating an intermediate rule like this:

OPA - For Function Intermediate RuleAnd that may be something you do not need or wish to do, so you decide to use the terse version. But before you give up on the long version, you see there is a third option in the Function Reference “<val>, in the case of <relationship>”. Interestingy, the “<val>” acronym appears only once on the entire list of Functions. And it is far from clear what it actually means. So best to avoid that.

Next time, we will continue and use some other Functions!

 

OPA – Entities Adventures #5 Entity Functions…

Entity Functions

Moving forward in our investigation of the Oracle Policy Modelling and the Entities we have created, we can now begin to leverage some of the common Entity Functions. Consider the following requirements

For each car in the garage, indicate if it is

  • Being worked on
  • Requires parts to be ordered

At the same time, indicate the profit expected from each vehicle. Based on this figure

  • Indicate cars worth repairing, for each mechanic

How can we decide if a vehicle is being worked on? In the Policy Automation class which I teach very often, we create an Attribute “the car is being worked on” (Boolean). In the example in this post, we will use another method which may or may not be appropriate for your business requirement.

First let us consider the nature of the relationship. Each car can have 0 or 1 mechanic. A mechanic can have many cars. So our first attempt might be using the Exists function, which can detect at least one of a specific Relationship, and can apply one condition.

OPA - Entity Exists

The initial result is promising since with populated data and Relationships known, the Debugger displays:

OPA - Car Entity Being Worked On

The downsides are that the Attribute value will be “Unknown” if the Relationship is unknown, which can confuse the User. Observe the Debugger showing the result below.

OPA - Car Entity Not being Worked On

So the second attempt might be to use an Intermediate Attribute. Given that the Car can have 0 or 1 mechanic (or be unknown), we could use the InstanceCount function to count the number of Mechanics working on a given Car.

OPA - Car Entity Worked On Part 2

So in the above, the Car’s workforce, a number Attribute, is used to find out the number of Mechanics working on a given Car. The other Conclusion leverages this. The result looks promising, in that the lack of a specified Mechanic gives us a “False” value.

OPA - Car Entity Not Being Worked On Debugger 2

But in the case where a Relationship is known, but there are no Mechanics assigned, such as the example below, which is obviously quite possible in a Workshop:

OPA - Car Entity Relationship Known but no Mechanic

Running our rule gives the following in the Debugger:

OPA - Car Entity Workload False Result

Clearly this is, for this contrived example, not the hoped-for behavior. After all, there is nobody working on the Car instance in this case. So our final approach might be the following:

OPA - Car Entity Relationship Final VersionWhich behaves as we would hope in the Debugger.

OPA - Car Entiity Final Result Relationship

The examples above are designed not to explain how to run a Workshop or repair your Car, rather to make you think about these useful Entity Functions. Let’s move on to another example.

We need to calculate which cars need parts to be ordered. We will base ourselves on the simple idea that cars that are older than 10 years of age, and that have nobody working on them, and that have a repair cost that does not exceed the value of the Car, will need to have parts ordered since they are not kept in the Workshop. Again, this is a spurious example for the sake of this post.

Firstly, let’s add two new Attributes to the Car Entity – the car’s residual value, and the car’s estimated repair cost:

OPA - Car Entity New Attributes

Then we can leverage the all keyword to create the following rule, with InstanceCountIf to count the number of Car instances that meet the condition.

OPA - Car Needs Parts

Finally we will highlight a further interesting example. Having calculated  the total number of cars requiring parts, let us calculate the total number of cars worth repairing per mechanic. InstanceCountIf is used in the training course ,for the purposes of demonstration, with Containment Relationships, but it is usable with a Reference Relationship as well,

OPA - Cars Worth Repairing

 

In our next chapter we will investigate reasoning across entities and the various functions that you can use, plus we will take a look at the French version which we didn’t have time for in this post.

OPA – Entities Adventures #3 Entity Relationships…

Reference Relationships

In the previous post we laid some groundwork for our Mechanic and Car Entities. Now we are ready to implement a couple of Reference Relationships. You can think of Reference Relationships as any relationship that is not Containment – basically it is any Relationship that you create, that is not created by the Policy Modelling application.

OPA - New Relationship Step One

Create a Relationship between the Mechanic and the Car. The Source is the Mechanic, and the Target is the Car, so begin by selecting the Mechanic and right-clicking the Relationship area on the right. Enter the correct kind of Relationship, and the relevant text as shown in the example below.

OPA - Create Relationship Step Two

 

In this example we have created a 1-Many relationship and the text we have written reflects that in English. The text of the relationship is often used in Functions with Entities as we will see in a moment.

Relationship Type

We need to pay close attention to the type of Relationship Type, since certain functions do not work with certain Relationship Types. Let us put all of this in to practice now by adding a useful Attribute to the Car for our business logic. Add “the car’s age”  as an Attribute. Make sure that the Attribute is definitely in the correct context – note “Entity” in the top right-hand corner.

OPA - Car Age Attribute

Now we can begin to focus on the rules we can write thanks to this hard work. Let’s begin with the obvious ones. Note in the following example, that the relationship text is the function’s argument – so your text must match exactly. For the purposes of clarity I have added a new Word Document in this Project, but that is not necessary.

OPA - Function InstanceCount

 

Counting based on a Reference Relationship

Remember to create a number Attribute the mechanic’s workload. Creating the Attribute with the text that includes “the mechanic” ensures that Policy Modelling understands that this is an Attribute that can be applied to each Mechanic.

OPA - Add Mechanic Workload

Compare this new rule with the example we created in the previous post :

The total number of cars in the workshop = the number of all the cars 

The above rule counts cars, but all the cars. The relationship text tells Policy Modelling which relationship is the source of the information. So now, let us Build and Debug without Screens. With Build and Debug we can review and edit the data as well as save it for later use.

OPA - Add Instances of Mechanic and Car

I have added three cars and three mechanics. The only inferred Attributes that have been updated will be the orignal Attriibutes from the previous post, which leverage the Containment Relationshiip. These are populated automatically.

OPA - Global Inferred Attributes

Defining Reference Relationships

The other Attriibutes that we have just added are not yet delivering any values. Why? Because Reference Relationships will simply be “Unknown” until we actively declare which Car is for which Mechanic.

OPA - The Mechanics Cars

OPA - The Mechanics Cars Step Two

In short, these Relationships will need to be specified. If the Relationship data is “Unknown”, so therefore the Attributes that derive their value from Entity Relationship-based Functions, are “Unknown”.

OPA - Final Mechanic Count Cars

 

When we take a moment to select the different Cars and define their Mechanic (or vice-versa), then we get the result we are expecting. But notice that we only will see results when we have removed all  the uncertainty – in short the three Mechanics need to explicitly be defined as having 0,1,2 or 3 cars. Then the function can reliably provide the information we need.

Zut alors!

Switching to our French version, most of the behavior is identical, however the rules written using the same basic structure are less grammatically acceptable. Take the following Reference Relationship, as before, only in French.

OPA - Voitures Reference Relationship

And then the rule we build refering to it:

OPA - Reference Relationship Instance Count French

Sadly the rule is considerably less grammatically correct than the English version. It might be tempting to change the Reference Relationship text and thus be able to write a more grammatically natural rule:

OPA - Tempting Change OPA - Tempting Change 2

But it probably will just complicate matters. Even in the Debug we can begin to see that “voitures du mécanicien” without the article “Les” will probably have negative impact when we write rules later. Generally, we always should include a definite article “The” or equivalent in our Entity and Attribute so that writing rules will be more natural (there are other reasons).

OPA - French Debug with Highlights

In this case, since the Attribute “La charge de travail du mécanicien” is grammatically acceptable we can decide to make changes to the Decision Report to make it as optimally readable as possible. As we will see in the next post, where we will also add some new features to our Web Determination and experiment with Substitution.

 

 

 

OPA – Entities Adventures #2 Question Screens…

Back to the Workshop

So we return to our Rulebase with Mechanics and Cars. Eagle-eyed readers will see this is an adapted version of an exercise in the Policy Automation training course. The version we are using here has different relationships and attributes than the one in the course. I am not intending to copy the material used in the course.

Next Steps

In the previous post we set up our Entities and experimented wth some Containment Relationship text. Now we can begin to study our Entiities in more detail and create / edit Attributes to extend the model.

Fire up the Debugger using Build and Debug without Screens. Let’s look at the output in the Debugger. Go ahead and right-click the “all the cars” icon and choose Add Instance.

OPA - Entities Create Instance

Since the car currently has only one Attribute, you don’t have much choice as to what to enter – just double-click the green bar and type something like “Ford Fiesta”.

OPA - Create Car Instance

 

Which brings us to the question – just what is this information we are entering? Where did it come from, and what issues may we have?

The Attriibute you are entering was created automatically when you created the Entity definition. It is the “identifying attribute”. If this was the Mechanic, maybe it would be his or her name, or employee Id. Since it is the car, what would it be? I’ll hasard a guess and say why not the car registration plate, since it is unique and a useful way to distinguish between all those cars in the workshop. Of course our Car Entity will have a Make and Model as well, no doubt. So let us correct all of this and spot a couple of other traps along the way.

Back out of the creation and Click Build > Stop Debugging. Now double-click the Attriibute and let us review. We want this to represent the Car Registration. So go ahead and change the text. And observe :

OPA - Car Registration Identifying Attribute

Common trap #4. The Car is not a he or a she (despite what some drivers thiink!). It is impersonal – an “It” if you will. Failure to update the Default Gender will of course make for strange output in the Decision Report and Debugger.

OPA - Car Gender Error

 

Take the opportunity to give the Attribute a public name as well. Now we have spoken about the Car Entity, what about the Mechanic – for the Mechanic there is another one to think about.

Common trap #5 The Mechanic needs to be defined as male or female (depending on your business scenario, this may not be useful for our Rulebase, but there are many situations where it is!). To set up the “Gender Attribute” is quite simple. We have covered it before so just visit this post and resume when the Mechanic has a Gender Attriibute defined. Your Mechanic Entity should now have 2 Attributes and should look like this.

OPA - Mechanic Gender

Note that we have also edited the Attribute Text for the Identifying Attriibute since the Mechanic’s name, in our case, will be enough to differentiate between them.

The Gender Attribute will come in very handy later on in the Web Determination and Decision Report for our Rulebase, Let’s now extend our Rulebase by adding a second rule to our Word Document. Make sure you create the Attribute as a Number and that you create it in the Properties Files (that could even be common trap #5b). The creation of the Attribute will look like this:

OPA - Attribute Creation in Word Document

And the Rules should look like this now.

OPA - All the Mechanics

Now that job is done, we can begin to investigate the Gender Attribute. Firstly, we need to create a Screen File in our Project, and Create a Question Screen inside it.

OPA - Mechanic Basic Question Screen

Check your own project against the screenshot. If you are seeing “Who is the mechanic’s name?” then you need to edit the Attribute to “impersonal”, or if you chose to keep the original Attribute Text “the mechanic” then you will see that instead. Notice the new icon to show the Gender Attribute.

Build and run your Web Determination, and click the link referring to Mechanics. Add a Mechanic using the Add New Instance button.

Ignore any warnings you might get at this stage since our Interview is not really ready yet, so it has no real goals.

OPA - Create Mechanic Screen Basic

Excellent – Policy Automation has given us the two radio buttons and has shown it understands this is a Gender Attribute.

Common trap #6 Asssuming that this is going to work in different languages.

As you may know, in this demonstration sequence we have also been maintaining a parallel version in French.

OPA - French Version of Project

Having entered the different Entities, Attributes, Rules in Word and having now created the Question Screen in the Screens File, this is what we get when we run the French Web Determination.

OPA - French Mechanic Screen Basic

I’m sure you can spot the issue. To correct this we could go to the Question Screen, and the Gender Attribute Question, and change the Display Values for the List of Values.

OPA - French Gender List of Values

 

And so finally we get good output when we Build and Run our Web Determination.

OPA - French Mechanic Screen Basic Improved

This editing of the Display Values may come in handy of course even if you are not working in a different language. The solution to the “male/ female” issue can be found in Part Six if you can wait that long.

In the next post in this series we will get our Reference Relationships up and running. Until next time!

OPA – Entities Adventures – Setting up Entities

Entities in Policy Automation

One of the funnest parts of the Oracle Policy Automation Training which I regularly deliver are the “Entity” chapters. These chapters (sadly rather short, and positioned right at the end of the week, limiting the time we can spend on them) introduce something that most students have already guessed at long before we get there: There must be more than just creating attributes and writing rules – what happens when I have two members of the same family, or three cars, or five Service Requests….

You can insert any typical Enterprise Software entity model in the end of the phrase above. Since this is such an interesting and sometimes challenging part of the course, I thought we could have some fun looking at entity functions, attributes and so on in a series of posts.

Getting Started

So let’s set the scene : consider the following entity diagram:

OPA Cars Workshops Model Start

We will build it in the next few posts, and then extend and manipulate it in various ways to demonstrate Entity Functions and more.

So starting from scratch, let’s look at a couple of common traps to begin with.

Creating the Entities

Beginning with a new Project and a new Properties File, create two new Entities that are children of the Global Entity.

Common trap 1 : There is, in this model, no need to create a “singleton” Entity for the workshop. Any atttribute that belongs to the “workshop” can be added to the Global Entity.

 

OPA - Car and Mechanic Entities

 

 

Common trap 2 : As soon as you create the Entities, remember to edit the “Containment Relationship” text. If you want to create rules to count or sum mechanics or cars, then you probably want to be writing rules like this :

OPA - Total Number of Cars Long Text

OPA - Total Number of Cars Short Text

 

 

 

But if you go ahead and try it now, the only thing that will work is the following text, or the long version of it. The problem is the default Containment Relationshop text is something like “All instances of XXX” (where XXX is the Entity name).

OPA - Total Number of Cars with Containment Relationship Text Demonstration

 

 

So you would in this case be advised to change the Containment Relationship Text from the default as shown above, to something a little more friendly.

OPA - Containment Relationship Text Edited

 

 

Doing this right now has many advantages, not least readability, but also avoiding common build errors such as “Entity XXX is defined twice”.

If you are writing your Rulebase and rules in another language, watch out for more of the same. For example, the same Entities built in French would give us the following basic grammatical error in the standard Containment Relationship text:

 

OPA - Entity Model French Grammar

“Toutes les instances du mécanicien” would at least be grammatically correct, although as in English this would be unfriendly for business users. So we would change the Containment Relationship text to “toutes les voitures” and “tous les mécaniciens” –  then we could write the following rule without hindrance.

OPA - French Rule with Containment Relationship Text Edited Short Version

 

 

Common trap 3 – Never assume that in two different languages, the syntax will be correctly shown in the Function Reference. A close look in the French Function Reference gives us two versions of the InstanceCount, one long and one short, as is often the case:

OPA - Error in Function Reference FR and EN

 

 

For the purposes of comparison I have put the English and French side by side. There is an error in the French Function Reference mentioning that the Entity (ent) is the required input argument for the function, when in fact it is the Relationship Text (relationship) that is required, as correctly stated in the English version.

In the next post we will continue to work with our Entities and add some attributes and rules to the mix. Until next time.

Entities Adventures 1