You are here: Configuration Overview > Configuration Standards > General Structure and Best Practices

Oracle® Insurance XML Configuration Guide Release 9.4.1.0 E23637_01

# General Structure & Best Practices

General sequence of the transaction elements should be as follows:

1. EffectiveDate

2. Allocations (if applicable)

3. Suspense

4. Withholding

5. Valuation (if applicable)

6. Fields

7. Events

8. MultiFields

9. Validation

10. Math

11. Assignments (if applicable)

12. ActivityAmounts (if applicable)

13. Spawns

## Syntax standards according to the General Structure

1. EffectiveDate

   The `EffectiveDate` element should be the first tag in a transaction.

   The `EffectiveDate` of spawned transactions, when that spawned activity is only ever SYSTEM generated, should be Disabled.

Allocation order of elements should be:

- FundAllocation

- AllocationFrom

- Allocation

- DefaultAllocation

2. Allocations (if applicable)

   Use the OVERRIDABLE attribute to allow users to bypass suspense requirements.

3. Suspense

4. Withholding

   When withholding is needed, use the ``<Withholding> </Withholding>`` tags instead of creating fields for withholding.

5. Valuation

   Do not include the <Valuation> tag in a transaction, if valuation is not necessary.

6. Fields

1. The order of field tags is:

   <Name>

   <Display>

   <ToolTip>

   <DataType>

   <Query>

   <Calculated>

   <DefaultValue>

   <RoleAssignments>

   <Tag>

   <Disabled>

   <Hidden>

2. The <DefaultValue> tag and the <Calculated> tag may not be present at the same time. Use one or the other.

3. If a field is hidden, do not include a <Disabled> tag.

4. If a field is not hidden, do not include <Hidden> tag.

5. If a field is not disabled, do not include <Disabled> tag.

6. Hidden fields that are independent of other fields should be placed at the end of the <Fields> section.

   Note: An exception would be when the value of a hidden field is needed in a following field.

7. Suggestions for field names are listed below. This applies to MathVariable names as well.

- Capitalize the first letter of each word.

  Example: DateOfDeath not DateofDeath.

- Exception is the use of upper case in SQL reserved words.

- Exception is the use of upper case for Validation error messages that appear to the user.

8. Do not use spaces or underscores.

   Example: DateOfBirth not Date_of_Birth.

9. Do not abbreviate unless the resulting word is extremely long. In that case, abbreviate but retain the meaning of word.

   Examples: PolicyAnniversary not PolAnniv. NextMonRemainIssueChg for NextMonthaversaryRemainingIssueCharge.

10. Add abbreviated words to the Data Dictionary so that the meaning remains clear.

11. Field name and display value should be the same if possible.

    Example: <Name>IssueDate</Name>, <Display>Issue Date</Display> not <Display>Date of Issue</Display>

12. Filler fields should be blank for the display and DataType.

13. Combo boxes and radio buttons:

- In a combo box, start with 00 for the value followed by 01, 02, etc.

- Always use a two-digit format: 00, 01, 02, 03, etc.

- The 00 value should always stand for a not applicable value or for a Select an Option value in a combo box.

- It may not always make sense to start off a combo box with a 00 value. Please use your judgment or consult your lead B.A.

- A combo box with a defaulted selection or one whose entry is non-required should not have a 00 selection.

- Radio buttons should have a 00 value for the negative response and 01 for the affirmative response.

- The above bullet point can apply to a combo box as well.

7. Events

8. Multifields

1. Casts the parameter as an array of text values.

2. Throws an error if the object cannot be cast properly.

9. Validations

10. Math

1. General Math best practices:

- Within the <Math> section, any MathVariable constants should come first.

- Don't define MathVariables that aren't used in the system.

- A MathVariable should define its VARIABLENAME and TYPE attributes (in that order) prior to any other attribute.

Example: <MathVariable VARIABLENAME=”Example” TYPE=”SQL” DEFAULT =”01” DATATYPE=”TEXT”>

- Consolidate logic into a single MathVariable where appropriate.

Example: Where an intermediate calculation value is not needed, don’t break the calculation into many steps.

- Only use ROUND when there is a reason.

- Use DATATYPE="DECIMAL" when dealing with integers larger than 2,147,483,648 in math configuration. In OIPA, the maximum value of an integer is 231 or 2,147,483,648. If a user tries to use an integer value larger than the maximum, it will cause an error.

- The <MathVariable> tag can use a LOG="Yes" attribute, which will log results to AsActivityMath. When using logging, remember that the system performs all logging at the end of transaction processing. Therefore, only the ending value of a MathVariable is logged. Although the configuration allows the LOG attribute on any use of a variable in the configuration, the intermediate values are not logged, even if LOG="Yes" occurs multiple times for the same variable. In such a case, to avoid confusion it is best to specify the LOG attribute only for the last use of the variable. Another method is to create a "Log Section" at the bottom of the configuration that specifies all math variables to be logged.

2. When defining the TYPE for a MathVariable use:

- `VALUE` if setting a MathVariable to a constant, whether it is a numeric or non-numeric constant.

  When defining the constant of Checked or UnChecked, the values should always be either CHECKED or UNCHECKED in all capital letters, respectively.

  Example: <MathVariable TYPE="VALUE">CHECKED</MathVariable>

- FIELD if defining the MathVariable to a variable from the <Fields> section or if redefining another MathVariable.

  Note: You must prefix the field name with "Activity:" Example: <MathVariable TYPE="FIELD">Activity:Field1</MathVariable>. Use Valuation:Policy to retrieve values from valuation when possible. Example: When trying to retrieve CashValue from PolicyValues use TYPE=”FIELD” Valuation:Policy:CashValue.

- POLICYFIELD if setting a MathVariable to a value in the policy’s <Fields> section.

- PLANFIELD if setting a MathVariable to a value in the plan’s <Fields> section.

  Use PlanFields any time a particular fact, amount, threshold value, etc., is tied to a product (plan), is static, and is used in a constant fashion across multiple transactions and/or calculations. It should be defined in PlanFields rather than defined repeatedly across transaction or business rule XML. If the information should change, then only one change must be made (to the PlanScreen business rule).

  Use the PlanScreen business rule to define your plan fields.

- EXPRESSION is used in the following situations:

  Use EXPRESSION when performing arithmetic using pre-defined MathVariables, literals or activity fields.

  Example: <MathVariable TYPE="EXPRESSION">Activity:Field1 + Activity:Field2</MathVariable>

  Note: When doing arithmetic with activity fields you must use the prefix Activity:.

  Use EXPRESSION when assigning a new MathVariable to have the value of an existing MathVariable or Activity field.

  Note: EXPRESSION is not to be used with Arrays or Collections as there are other math types defined specifically for use with those data objects.

- FUNCTION if using one of the system’s pre-defined operations. These features aim to provide users with functionality that is frequently used without the need for manually re-configuring the logic.

Do not use double quotes around the parameters. These functions are as follows:

- ToDate()
- ToDecimal()
- ToInteger()
- ToText()
- ANBAgeOf() — Age Nearest Birthday
- CalendarMonthsDiffOf()
- CalendarQuarter()
- CalendarYearsDiffOf()
- DayOf()
- DaysAdd()
- DaysAdd()
- DaysDiffOf()
- DurationOf()
- FullMonthsDiffOf()
- GivesBestDay()
- MaxDateOf()
- MinDateOf()
- MonthOf()
- MonthsAdd()
- MonthsDiffOf()
- NextMultipleMode()
- PolMonthOf()
- QuartersAdd()
- ReplaceDayOfMonth()
- ReplaceMonth()
- ReplaceYear()
- YearBeginOf()
- YearsDiffOf()
- AbsOf()
- MaxOf()
- MinOf()
- PresentValue()
- TruncateNumber()
- ToInteger()
- ToText()
- ANBAgeOf() &endash; Age Nearest Birthday
- CalendarMonthsDiffOf()
- CalendarQuarter()
- CalendarYearsDiffOf()
- DayOf()
- DaysAdd()
- DaysDiffOf()
- DurationOf()
- FullMonthsDiffOf()
- GivesBestDay()
- MaxDateOf()
- MinDateOf()
- MonthOf()
- MonthsAdd()
- MonthsDiffOf()
- NextMultipleMode()
- PolMonthOf()
- QuartersAdd()
- ReplaceDayOfMonth()
- ReplaceMonth()
- ReplaceYear()
- YearBeginOf()
- YearsDiffOf()
- AbsOf()
- MaxOf()
- MinOf()
- PresentValue()
- TruncateNumber()
- IsEmpty()
- TableMult()
- IsAlpha()
- IsAlphaNumeric()
- IsNumeric()

- MATHIF if you want to incorporate if/else logic into your math configuration.

  Single quotes aren’t needed for a MathIF’s IF attribute when evaluating an integer.

  Example: <MathIF IF="PolicyDuration=1"

- IIF is another way to incorporate if/else logic into your math configuration. This TYPE is different from MATHIF in that you can only evaluate a single criterion.

Suggestions for when to use MathIF versus TYPE="IIF":

- Use MathIF when the value(s) of one or more MathVariables is conditional. That is; if the condition is not met, the MathVariables do not need to be defined.
- MathIF also helps avoid multiple IIF’s when the desired result is one value.
- Use IIF if this specific MathVariable always needs to be evaluated but the resulting value is conditional between two values.

- SQL if the value you are trying to obtain is only obtainable by executing a SQL statement.

  Capitalize the key syntactical words when writing SQL statements (i.e., SELECT, FROM, WHERE, AND, JOIN, etc.).

  Use JOIN instead of FROM and multiple table names.

- COLLECTIONVALUE if you are trying to retrieve a value from a COLLECTION.

- NUMERICARRAY, STRINGARRAY, DATEARRAY if you need a list of values. An array should contain the same data types. Only one-dimensional arrays can be created.

Note: Be certain that you define the array with the appropriate DATATYPE. Do not configure a NUMERICARRAY to store text values or dates.

Some examples of using arrays for list values include (but are not limited to):

- Rate information
- Fund information
- Dates
- Segment information

There are nine ways to create/populate/manipulate arrays (eight via the OPERATION="" and one via TYPE= ""). Here are the eight OPERATIONS:

- FILLBY-LIST

The values inserted into a FILLBY-LIST array can be values contained in math variables and activity fields and/or they can be hard-coded.

When using FILLBY-LIST to insert date or string values into an array, the values must be surrounded by double quotes.

- FILLBY-SQL

Used when you want to fill an array with the results from a SQL statement.

The type of array you are creating and the type of data you are retrieving from your SQL statement must match.

The SQL statement must only return one column from a table.

FILLBY-SQL arrays are commonly used to retrieve point-in-time values from logged math.

- FILLBY-FUND

Used when you want to fill an array with a list of FundGUIDs for a given policy that has cash value.

The plan (product) must have funds configured in order to use this array/operation type.

Once you have your FundGUID, you are able to retrieve additional information about the fund such as AsValuation data, AsFundField data, etc.

- FILLBY-DEPOSIT

Used when you want to fill an array with deposit ValuationGUIDs related to a specific FundGUID.

When using FILLBY-DEPOSIT to create an array, your transaction/rule must be configured to perform valuation and assignment.

Commonly used in conjunction with FILLBY-FUND however all that is really needed is a FundGUID (which can sometimes be obtained by other means)

Some examples of usage include:

- Obtaining Cash Value per deposit.
- Obtaining number of units purchased per deposit.
- Obtaining gain/loss per deposit.

- CREATE

  Used to initialize a MathVariable as an array to later be populated with data.

  Be certain that you define the array with the appropriate DATATYPE.

  Most common example is defining an array prior to performing a loop and then inserting data into the array during each iteration of a loop.

- REPLACE

  Used when you want to replace all elements from an existing array for all the elements in an entirely different and separate array.

  Commonly used with the CREATE method where CREATE is an empty array and then is replaced with an array with elements via REPLACE method.

- COPY

  Used when you want to produce an exact replica of an existing array.

  The new copy must not have the same MathVariable name as the original.

- TRANSFORM

  Used when you want to perform calculations on an array. Note: The same rules that apply to TYPE= ”EXPRESSION” apply to TRANSFORM as well.

  When performing calculations using two or more arrays, the arrays must be the same length.

  You may also use literals.

  There is a feature that can be used with NUMERICARRAY, STRINGARRAY and DATEARRAY via METHOD= ”r;” called EXPAND

  - Use this method when you are trying to repeat the first value and/or all the middle values and/or the last value of an array.
  - You must have at least three elements in an array to use the EXPAND method.
  - Some examples of usage include:

    - Expand an array that does not contain enough elements to perform a calculation with another array.

      Example: Monthly rate stored as a single value (in PLANFIELD) but you need to calculate the value for all 12 months. You would use EXPAND to take the monthly rate and expand it 12 times.

    - Use for varying interest rates into Commutation functions.

3. XPATHs should always use the fully qualified path.

   Example: /Valuation/Policy/FundList/Fund[FundGUID='$$$LoanCreditFundGUID1$$$']/CashValue not //FundList/Fund[FundGUID=’$$$LoanCreditFundGUID1$$$’]/CashValue

4. When using TYPE=”FUNCTION”, do not use double quotes around the fields.

5. Quotes aren’t needed if a MathIF is used when comparing numbers.

   Example: ActiveSegmentCode=01

6. The use of Blank is not needed when blank is a previously defined field. Instead use two single quotes.

7. Use Data Dictionary defined field names for consistency across products.

8. Don’t define MathVariables that aren’t used anywhere.

9. Use Valuation:Policy to retrieve values from valuation when possible.

   When trying to retrieve CashValue from PolicyValues use TYPE=”FIELD” Valuation:Policy:CashValue.

10. Capitalize the words AND and OR when writing SQL. Use sentence case And and Or when configuring anything other then SQL statements.

11. A MathVariable should define its VARIABLENAME and TYPE attributes prior to any other attribute.

    Example: <MathVariable VARIABLENAME=”Example” TYPE=”SQL” DEFAULT =”01”>

12. Only use ROUND when there is a reason.

13. Consolidate logic into a single MathVariable where appropriate.

    Example: Where an intermediate calculation value is not needed, don’t break the calculation into many steps.

14. Suggestions for when to use MathIF versus TYPE="IIF":

    Use MathIF when the value(s) of one or more MathVariables is conditional. That is; if the condition is not met, the MathVariables do not need to be defined.

    MathIF also helps avoid multiple IIF’s when the desired result is one value.

    Use IIF if this specific MathVariable always needs to be evaluated but the resulting value is conditional between two values.

11. Assignments (if applicable)
12. ActivityAmounts (if applicable)
13. Spawns

1. Pass spawn fields in the same sequence as configured in the transaction that is being spawned.

2. Any GUID fields passed as spawn fields should be disabled in the spawned transaction.

3. Spawned transactions should use SPAWNCODE=”01” when the spawned transaction is effective on the same day as the spawning transaction.

4. See AsCode for other spawn code values.

5. DataTypes in spawn fields must match data types in receiving fields.

Copyright © 2009, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices

Open table of contents