Welcome to the OPA Hub!


Category Archives: Translation

Emergency Reponse example project translation

The Emergency Response example Project translation and adaptation

The Emergency Response example Project translation and adaptation

A couple weeks ago while discussing the long list of example projects that come with the Oracle Policy Modeller, I decided to adapt and translate the Emergency Response to another language (in this case French). Here is the run down of the work on the Emergency Response example project translation.

The idea behind this post just to give you some feedback on the various issues that I encountered. Many of these will be generic to similar exercises in any language,so will be hopefully of interest to the wider community. There is no belief or assumption that this is an exhaustive list, it’s just somebody trying to give some feedback.

I am totally aware that there is a sophisticated translation functionality within Oracle Policy Automation, but when you’re dealing with a customer who speaks multiple languages, and subject matter experts who do not necessarily speak all the national languages, sometimes the choice of language for your project is not something you can control, so building this demonstration project was a useful tool in communicating with some of my customers about the capabilities of the product.

Note : I long for the day when inside a single project, I can have Word documents, in different languages, using some sort of formatting markup.

Firstly let’s just walk through what the Emergency Response example project translation entails by looking at the original. It has a single Word document with essentially three different Business rules :

  • A stack of Booleans, one each for the different hazard warning signs (present yes/no).
  • A couple of rules to decide whether or not to accept a manually entered address if the localisation in the browser did not work
  • Finally, a rule to concatenate latitude and longitude with a URL from the Google maps static API at .com.au 😉

For the purposes of this exercise I choose to work from a document from the Ministère des Transports, de la Mobilité durable
et de l’Électrification des transports in Canada
 which I was able to download in French. So where did the issues occur?

  1. Obviously since the Booleans we were referring to reference hazard warning signs that were specific to a certain country, it was necessary to either adapt, eliminate, or add further rules to identify each of the classification and sub-classifications of hazardous materials. For the time being though I kept the same structure of the Word document.
  2. Since each of the hazardous materials was linked to a image file to display a image toggle , it was obviously necessary to obtain and reference new additional image files and update the image toggle in the interview.
  3. The interview included static text introducing the concepts and explaining the goal so those needed to be translated.
  4. The rule which concatenated the URL relied upon latitude / longitude being number attributes, formatted with a separator that was a period or dot. This is not the case for many regions. Besides, this demonstration project is constructed in 2013. At that stage the JavaScript extension API was not available. It felt like the creation of a pop-up window with a Google map inside it was counter-productive for a project aiming to showcase a mobile-friendly user interface.
  5. The manual address entry – if browser localisation was not available – needed to be updated to respect the format of an address in the country that I was targeting, notably for the postcodes and states.
  6. Finally the project used one static header image which would need to be replaced since it included English text.

Along the way, while working on this little Emergency Response example project translation a couple of other points came up :

  • The output of the existing version was not, in my humble opinion, very friendly for the rule Developer. I converted it to a set of inferred entity instances which allowed for a more detailed output and potentially some additional information like what to do in the presence of certain chemicals. It also helped create a notion of class of Hazard.
  • The slider to select the number of vehicles was transformed into two image sliders , one for light and the other for heavy vehicles. Cosmetic more than anything.

So the Emergency Response example project translation contained one Word and one Excel document, some more image files, a JavaScript extension and a few small modifications to the actual logic based on the legislation and classifications. If anyone wants a copy of the project I’m happy to share it, just leave a note in the comments.

Have a nice day and watch out for the next one!

Emergency Response example project translation

Select Vehicles

Emergency Response example project translation

Select Hazard Signs

Emergency Response example project translation

New GPS Extension

Emergency Response example project translation

Entity Instances

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!

Policy Automation – Jargon Busting – Natural Language

A serious problem in the design of business rules of any kind, or the interpretation of existing legislation or jurisdiction is that most computer programs do not allow us to construct rules in a natural way.

Siebel Tools, for example, lets us use syntax like [Field Name] + [&Property Name] as well as a library of functions. This is hard to “sell” to business users when you want to give them confidence in the translation of the “paper” rules into the “system” rules.

Policy Automation increases our ability to respond to these situations by using “natural language”. This does not mean necessarily that you can copy out existing text word for word, but it does get us a lot closer. Let us see a couple of examples that will introduce key elements of the tools and the practical aspects of rule creation.

Open up your Policy Modelling application, create a new Project called “ODE – Natural”. Set the language to “English American” and the locale to “United States – English”.

Examine the text in the below”Source” document. Notice how the document is broken down into sections. This is a common feature in legal documents. Notice how the document speaks about guests, members and so on.

OPA - Natural Language Members and Guests

Using the “Design” files provided (see the previous post) let us compare. Please note, these files are just for comparison purposes and are not optimized in any way. Right-click the “Design” folder (inside the Documents folder) and select “Add Existing File”. Add both the Excel file and the Word file.

OPA Natural Language Members and Guests Rules

Some features that are important to highlight.

  • The “1” and “2” and (a)…(c)  used to mirror the structure of the source
  • The color-coded structure using strict Formatting
  • The large, clear descriptive headings in the document
  • The full text variable names at the top of the document
  • The need to still use functions (ExtractTimeOfDay for example)

Using the Build menu, select “Build and Run” and the default “Run with Web Determinations” option.

OPA - Natural Language Initial Screen

Observe that when you click on the “Why?” you are told that Section 2 has been satisfied. When correctly formatted using numbers like the example, rules will automatically generate this kind of summary. This is great for reassuring and familiarizing business people with the rules that map to their source documents.

Proceed to the session, answering that you are 18 years old, that you have spent 14 dollars and that you belong to the Paris club, and that your guest has completed the questionnaire. You should see that you are able to invite guests into the club. Click the “Why” link again.

OPA Natural Language Why

Again, the formatting has reproduced the structure of the source. Now replace the existing Word file (Right Click, “Remove File from Project”) with another version “Design2”. Observe how the structure of the Word document is slightly different (but the content is the same). In Policy Modelling, the format of the text is all important, since it tells the engine several things

  • What the conclusions and main goal are
  • What the structure of the logic is (Level 1, Level 2 formatting)
  • How to parse the content of your Word file (where the “questions” are)
  • What text to ignore (Heading, Comments, Blank Lines)

The formatting is achieved by use of the Policy Modelling toolbar. Rerun your “Build and Run” with the same data as before, notice the “Why?” this time matches the original text, because of the changed structure of the file. (Note in the example below, we set the “closing time” of the club to 6pm…)

OPA Natural Language Guest Accepted

In Policy Modelling, there are often multiple ways to write something, but we must balance writing fast (less understandable) and writing well (helping the business understand the correlation with the source text), all the time writing “understandable” sentences for Policy Automation using the correct formatting. We can come close to natural language, far closer than ever before.

Finally, change the computer clock to a “closed” time, or carefully edit the Word document to be “closed”. Rerun and observe you are not even able to begin the question and answers, because :

OPA Natural Language The Club is Closed

This is because of another jargon item, which we will discuss in the next post.

PS – the “club rules” used were inspired by documents like this one.

PPS [Note : Orginal Attached Files that belonged with this post have been removed. If you want them please contact the author]