Product Development Tutorial
This tutorial gives an overview of product development within OpenUnderwriter.
This tutorial describes the process of making an update to an existing product definition. Using the FreightPlus demonstration product as a starting point, it adds a new question to the product's quotation screens and modifies the product's rating rules to take the answer to the new question into account during rating.
The FreightPlus product is concerned with quoting for personal shipping insurance. While simple, it does represent a real world solution developed for one of OpenUnderwriter's clients. The additional question which will be added describes the type of commodity that is being shipped. The type will affect the premium. For example, the premium for refrigerated goods will be higher than that for dry goods. Four types of commodities are used: Dry, Refrigerated, Live and Other.
An running instance of OpenUnderwriter, version 2.0 or later, running on localhost.
A text editor. Notepad is fine on windows as is TextEdit (or vi, emacs) on a Mac.
A Excel compatible spreadsheet editor. Excel itself is fine, as are Libra office or OpenOffice.
|For simplicity this tutorial only requires using a text editor for updating most product resources. However, product development is normally carried out using some kind of IDE. Eclipse, NetBeans or InteliiJ are recommended. The features that these tools offer, like syntax highlighting, make it far easier to edit product resources.|
The Product Development Sandpit
The sandpit screen is a feature of OpenUnderwriter that provides an environment where products can be executed and debugged. This tutorial will make extensive use of this feature. The sandpit can be opened using the following URL:
Use the login:
|Katie is one of a number of demonstration users who are created in a default installation. Katie is setup in the role of "Product Developer", and as such she has access to the sandpit. Other users, depending on their roles, may or may not have access.|
Once logged in, the following sandpit screen will be displayed.
The main area of this screen is given over to displaying the product screens. No product is selected yet, so at this point it is blank. Above this is a panel that allows you to select products to work on and control various aspects of the process.
Freight Plus Product Walkthrough
Now select "
AIL.Demo.FreightPlus" in the Product? drop down, and "
QuotationPageFlow" in the PageFlow? drop down.
After a short delay as the product is loaded, OpenUnderwriter will display the product's first page, the "Welcome" page. The product panel now shows exactly the same questions and options that a user would see when they visit the site for a FreightPlus quotation.
The FreightPlus product generates quotations for personal freight transportation insurance. With the product in it's default state only 4 questions need to be answered before a quotation or referral is presented. Over the course of the next sections in this tutorial an additional question will be added.
For now, carry on with the quotation process by selecting the following options.
Now hit "Quote" and the quote will be rated. In this case the next screen displayed is the quotation screen, including the premium and some options for what to do next.
From there you can Save the quote so you can return to it later, or Requote which will take you back to the first page, but pre-fill it with the answers your originally gave. Hitting Quote Document will generate a quotation document, and Confirm and Pay will take you to further screens where you enter policy holder and payment information. Quit will restart the pageflow.
Hit "Quit" to return to quit this quotation and restart the pageflow.
If values are entered on the first screen for which a quote cannot be produced, a referral is generated. Entering the following values will have that effect.
Hitting quote with these values will take you to the referral screen:
In this case the only options are to Requote or Quit which have the same effect as they did on the quotation page.
Product Development Environment
All the aspects of the FreightPlus product that have been seen so far are configurable. And all are defined as part of a product definition. Product definitions are held within OpenUnderwriter's document library and can be accessed as files from your desktop.
On a Mac, use Finder to connect to a server:
http://localhost:8080/webdav/global/document_library/Product/AIL/Demo/FreightPlus as the server address, and click "Connect".
Enter the username
email@example.com with the password
katie, and click "Connect".
A new Finder window will open displaying the product definition.
From the Windows Start menu, right click on "Computer" and select "Map network drive...".
Select any free drive letter (P: for product is logical), and enter
http://localhost:8080/webdav/global/document_library/Product/AIL/Demo/FreightPlus as the folder URL. Check the "Connect using different credentials", and click "Finish".
Enter the username
firstname.lastname@example.org with the password
katie, and click "OK".
An explorer window will open displaying the product definition:
Adding the new question
To add a question to a product the product's pageflow is updated to define where the new question should appear and how it should be worded, and the product's model is updated to define how the answer is stored and any validations that should be applied to it.
In the product definition, open the file
PageFlows/QuotationPageFlow.xml in a text editor.
This file contains defines the questions that will be asked. There are four at the moment (highlighted above). Add a new question by inserting the following text as shown in the screenshot below:
<question title="What category of commodity are you shipping?" binding="/asset/attribute[id='commodity']" />
The following screenshot shows the modified file with the new line highlighted.
Save the file.
Now open the file
Model/Quotation.xml in a text editor.
This file defines the structure of the quotation. This structure is modified to add a place to store the result from the new question, and to define the valid values for the answer. Add the following line as shown in the screenshot below:
<attribute id="commodity" value="?" format="choice,options=-1#?|1#Dry|2#Refrigerated|3#Live|4#Other" />
Save the file.
Testing the new question
The changes made in the previous section are immediately picked up. Return to the sandpit, and the new question is now displayed including appropriate values in for the answer.
|If you had quit your browser session, login and open the FreightPlus product in the sandpit as before. Otherwise, hit the green restart button () on the sandpit or refresh the browser to pick up the new question.|
With the question added and the model updated to hold the answer, the next step is to take this new information into account during rating. The following changes will be made:
- A commodity type of Refrigerated will attract a 10% loading, Live will attract a 15% loading. Other will cause a referral. Selecting Dry will leave the behaviour unchanged.
The rating rules for FreightPlus are defined in the form of a spreadsheet. Changing the rules to take into account the new information simply involves editing that spreadsheet. From the product definition folder, open the file Rules/PolicyRating.xls in Excel, Libra Office or a similar tool.
The spreadsheet is broken into tables. In this case there are two, one (very long) table detailing rating by destination and mode of transport, and another further down which handles the answer to the "Would you like cover for shipping delay?" question.
Each table is layer out with conditions on the left, and actions on the right. At the top of the first table are the rules covering UK destinations, then European Union etc. The first few rows say, in effect:
If the destination is UK and the mode of transport is Road, then apply a premium rate of 0.5%.
If the destination is UK and the mode of transport is Rail, then apply a premium rate to 0.4%.
If the destination is UK and the mode of transport is Sea, then refer the quotation.
If the destination is UK and the mode of transport is Air, then refer the quotation.
A new table will be added at the end of the spreadsheet to include the new rules for commodity.
To make the spreadsheet more readable, especially when it may be shared with non-technical users, the control rows which allow OpenUnderwriter to interpret the spreadsheet's content are normally hidden. Click the + sign next to the destinations rating table to reveal the control rows.
Take a copy of first 9 rows (rows 40-48) of the table.
Paste a copy of these rows at the end of the spreadsheet.
For the purposes of this rating change only one condition column is needed, so delete the 1st column of cells in the new table taking care not to delete anything from the 1st row.
The basic structure of the table is now in place, but the cells need to be edited to match the new rating conditions. Ignoring the control cells (in blue) update the other cells to the values shown below.
|The "Dry" row is not really necessary as it has no actions associated with it, but including all of the possible values helps readability.|
The last step is to update control information. The control information provides an enormous amount of flexibility and power, but for now simply paste the following values into the cells shown:
$AssessmentSheetArgRet.addLoading("$2", "total premium", "total premium", new Rate("$1"));
|The styles used in the spreadsheet aren't important to OpenUnderwriter, but they do make a huge difference to readability. Deleting the formatting in cell E197, and hiding rows 197 to 200 makes the purpose of the rules clearer. In a commercial setting it is quite common to need a non-technical user to sign-off on changes. This is made easier without the distraction of technical information.|
The spreadsheet changes are now complete. Saving it will make the new rules instantly active.
Testing the new rating
Return to the sandpit and start a new FreightPlus quotation. The session will probably have time-out by now so it will be necessary to login again and return to the sandpit.
Enter the values below and hit the Quote button.
The premium is now showing as £110. This suggests that a 10% loading has been added for the Refrigerated commodity option as would be hoped. However, that can be confirmed by switching the sandpit into its "Assessment Sheet" view.
In the sandpit's control panel, switch the View from Wizard to Assessment sheet.
The assessment sheet records how OpenUnderwriter arrived at the premium of £110, or in the case of a referral or a decline it would detail how the system arrived at that conclusion. This information is stored with the quote itself so it forms part of the historical record.
In this case the assessment sheet shows that a "base premium" of £10 was initially arrived at. The new commodity rule then added a loading to the premium of 10%. It would seem that this should have lead to a total premium of £11, but the total premium is actually shown as £110. What's going on?
Looking further down the assessment sheet, there is a note. FreightPlus defines a minimum premium rule which will automatically adjust the base premium up to £100 if it falls below that value. That rule has fired and adjusted the premium. It also inserted this note to explain the apparently strange result.
The note refers to the "'31' control line". This is a reference to the row in the rating spreadsheet that defines the rule. As it is considered to be a control line the row is normally hidden, but returning to the spreadsheet and unhiding that section revels the following.
Thank you for using this tutorial, we hope it was helpful to you. Please consider commenting on our forum or giving us a thumbs up on facebook, linkedin or twitter if you have found this tutorial and OpenUnderwriter useful.