Wednesday, 30 April 2014

Tutorial: Migrating OPA projects to Cloud

In this tutorial we will be going through the steps on how to migrate Oracle Policy Automation projects from version 10.4 (On Premise OPA) to 11 (Cloud based OPA).

Why we need to migrate manually our OPA projects

The main driver behind the manual steps highlighted below is that at this stage there is no automated migration tool that allows users of OPM 10.4 to use their rulebases in OPA 11 (Cloud version). Attempting to open a 10.4 rulebase with OPA 11 will spawn an instance of the OPM 10.4 software making it impossible to upload the rulebase to the Oracle Hub.

What OPA files do we need to amend

As of the 29/04/2014 the files to be amended so to allow OPM Cloud version to accept our 10.4 rulebase are:
  1. the .prj - the rulebase project file
  2. the Interview.xint - default interview definition look up for OPA Cloud
  3. all the rule files stored in doc will have to be converted to docx - OPM Cloud appears not to support binary based word documents

Manual amendments to the OPA project file (.prj)

The first line of the OPA XML project definition file declares the project version, we need to amend it so to be compatible with the OPM cloud version.

The project file (line 1 excerpt) before:
<rulebase-project product-version="10.4.2.18" schema-version="1"> 
The project file (line 1 excerpt) after the amendment:
<rulebase-project schema-version="1" product-version="11.2.0.171">
By changing the product-version we are able to open the project in OPM Cloud.

Convert the doc and xsl OPA rules to docx and xslx

OPM Cloud edition does not support binary based doc formats I created a small perl script that uses the word converter and excel converters distributed by Microsoft so to convert all rules at once. Create a file with the content:
use strict;
use warnings;
use 5.10.1;
my $dir = ".";
my @doc_files = glob "$dir\\*.doc";
foreach (@doc_files){
my $doc_file_name = $_;
my $docx_file_name = $doc_file_name . 'x';
my $command = '"C:\Program Files (x86)\Microsoft Office\Office12\Wordconv.exe" -oice -nme '. $doc_file_name . '" "' . $docx_file_name . '"';
system($command);
}
my @xls_files = glob "$dir\\*.xls";
foreach (@xls_files ){
my $xls_file_name = $_;
my $xlsx_file_name = $xls_file_name . 'x';
my $command = '"C:\Program Files (x86)\Microsoft Office\Office12\excelcnv.exe" -oice "'. $xls_file_name . '" "' . $xlsx_file_name . '"';
print $command;
system($command);
}
and save as 'convertBinaryToXML.pl'.

Note: the script above has been successfully tested on Strawberry Perl on a Windows 7 operating system only. Should you want to run it on any *nix operating system amend the path definitions.

Drop in a bog standard OPA Interview definition (Interview.xint)

After the amendment to the project file we will be able to open the project. OPM Cloud will be looking for a Interview definition file in the root directory . If unable to find the file OPM will present us with an error. Create a file with the content:
<?xml version="1.0" encoding="utf-8"?>
<interview product-version="11.2.0.171">
  <documents />
  <screens />
  <screen-order ID="" />
</interview>
 and save it in the Project root directory with the name 'Interview.xint'.
Doing this will allow us to successfully open the rulebase and if no errors are encountered upload it to the Hub. If you are presented with errors we potentially have to follow two more steps.

Errors in the data model

OPM Cloud attempts to automatically infer attribute types. If the attribute name or its usage does not give enough clues to the engine to successfully recognise the type it will throw an error. To solve this errors we need to navigate to the 'Data' tab and (in the top section of the client) we will be displayed with the offending attribute. At this point double clicking on the attribute and selecting the attribute manually will fix the issue. Just to provide an idea of how often this issues may occur in the example rulebase we used for the FATCA automation efforts only six attributes weren't correctly recognised over 2534 total attributes.

Errors in the rules

OPM Cloud seems to be slightly more picky in the way it interprets rules. During the conversion of FATCA from OPM 10.4 to OPM Cloud version I was presented with two kind of errors:
  1. Some space separated inline attribute declarations were converted into Tabs. I believe this is an issue in the Word and Excel converters. Nonetheless, a search and replace fixes the problem.
  2. Some of the rules had no explicit 'or' and 'and' at the end of every filtering clause. OPM Cloud complained about these and they had to be amended manually also*.
Note: This amendments should be conducted by somebody that has great knowledge of the rules structure and the policy they are modelling.

Conclusion

In this tutorial we have gone through the steps that allow the migration of OPM rulebases from the version 10.4 to 11 Cloud Edition. With a few very simple steps we are able to open, test and upload the rulebase to the Oracle Cloud enabling clients to have a smooth transition and upgrade path.
Migrating from OPA On Premise to OPA On Cloud may come with some behavioural caveats. After such a migration has been conducted a full regression has to be run on the rulebase to make sure behaviour has not been modified. In a rulebase with a full suite of Unit Tests the regression should be as simple as re-running the tests.