Oracle® XML Configuration Guide Release 9.7.0.0 E39062-01

General Structure & Best Practices

Sequence of Transaction Elements

The general sequence of the transaction elements should be as follows (follow the links for more information on best practices for configuring these elements):

1. EffectiveDate

2. Allocations (if applicable)

3. Valuation (if applicable)

4. Suspense

5. ValuesBlock

6. Withholding

7. AllowComments

8. Transitions

9. MultiSuspense

10. Address

11. Fields

12. Events

13. MultiFields

14. Math

15. Assignments (if applicable)

16. Spawns

Syntax and Configuration Standards for Transaction Elements

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.

Allocations (if applicable)

Allocation order of elements should be:

• FundAllocation

• AllocationFrom

• Allocation

• DefaultAllocation

Suspense

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

Withholding

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

Valuation

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

Fields

1. The order of field tags is:

   • <Name>
   • <Display>
   • <DataType>
   • <Group>
   • <Currency>
   • <Value>
   • <DefaultCurrency>
   • <DefaultValue>
   • <Query>
   • <Calculated>
   • <Required>
   • <Disabled>
   • <Hidden>
   • <Expanded>
   • <ClearOnRecycle>

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 disabled, do not include a <Hidden> tag.

5. If a field is required, do not include <Hidden> and <Disabled> tags.

6. If a field is either hidden or disabled, do not include a <Required> tag.

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

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

9. 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 as a source of data in a non-hidden field.  

10. The Required element applies only to the following screens: 

    • Activities

    • Address

    • Client

    • ClientGroup

    • ClientWithholding

    • Inquiry

    • Policy

    • PolicyWithholding

    • Role

    • Segments

    • Suspense

11. The Required element is not valid if the DataType is Identifier or Check.

12. Validation for required fields is performed when a screen is saved (or submitted). If a required field is blank or null it fails validation, and any validation specified by the Validation element is not performed.

13. If a user is prevented by the security configuration from entering data in a required field, the screen will not pass validation when submitted.

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

15. Do not use spaces or underscores.

    Example: DateOfBirth not Date_of_Birth.

16. 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.  

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

18. 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>

19. Filler fields should have a DataType value of Blank, and no Display element.

20. Combo boxes and radio buttons:

• 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.

• 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 should not have a 00 selection.

• Radio buttons should have a 00 value for the negative response and 01 for the affirmative response. This can apply to a combo box as well.

21. Fields of DataType TextArea are available for all screens supporting the <Fields> element. Note the following:

• Fields of the TextArea data type are not available as criteria fields in search screens. TextArea fields configured on a search screen will be ignored.

• The TextArea data type is not supported within the <Table> element regardless of the rule in which it is configured.

• The field entry section of an InquiryScreen does not support the TextArea data type. However, the TextArea data type is supported in the results section if it displays fields but not a data grid.

• There is no absolute maximum to the length of a TextArea field; the number of characters entered may be limited by specifying the <Length> element.

• There is no minimum number of Unicode characters for the TextArea datatype.

22. Avoid having the same value for the <Name> tag for more than one <Field>. If multiple fields have the same name, the display, recording of the field value and action/events on the field will not be able to differentiate between the multiple instances.

Math

1. General Math best practices:

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

• Do notdefine MathVariables that are notused elsewhere by the system configuration or the OIPA user.

• 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 2³¹ or 2,147,483,648. If a user tries to use an integer value larger than the maximum, it will cause an error.

• When using logging (with the LOG="Yes" attribute), 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 MathVariable names, the following practices are recommended:

• Use only alphanumeric characters — letters, digits, and underscore ('_'). Do not use spaces.

• The first character of a MathVariable name should be a letter. The underscore is allowed, but not recommended.

• By convention, the dollar sign is not used and should be avoided.

• After the first character, any combination of letters, digits, and underscores is allowed.

• The maximum length of a MathVariable name is database-dependent. A safe length is 25 characters, but maximum length of up to 36 characters may be allowed in certain installations.

• Use descriptive variable names, with full words if possible instead of abbreviations that may not be meaningful to others.

• MathVariable names are case sensitive, and using CamelCase-type names helps to make the names more readable and understandable. Underscores may also be used to separate words.

  Example: <MathVariable VARIABLENAME="ActualEndOfMonthDateMV" ...

3. 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 field from the <Fields> section.

  Note: You must prefix the field name with "Activity:" Example: <MathVariable TYPE="FIELD">Activity:Field1</MathVariable>. Use Valuation:Policy to retrieve values from activity 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 or if assigning a value from another MathVariable.  

  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, or if assigning value from another MathVariable.

• 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. A list of available functions is provided in the Functions topic.

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

  When evaluating an integer in a MATHIF, neither single nor double quotes are needed for the IF attribute.

  Example: <MathIF IF="PolicyDuration=1" 

• IIF as another way to incorporate if/else logic into your math configuration. This TYPE is different from MATHIF in that  it always assigns one of two values to a single math variable, depending on whether the logical expression evaluates to true or false.

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

• Use MathIF when one or more MathVariables need to be assigned values only if the logical condition is met.. That is; if the condition is not met, the MathVariables do not need to be defined.

• MathIF also provides a method for setting the values of multiple math variables based on the evaluation of a single expression. In other words, the expression only needs to be evaluated once.  

  Example of MATHIF statement:

  <MathIF IF="A=B">

  <MathVariable VARIABLENAME="MV1" 
  TYPE="EXPRESSION" DATATYPE="INTEGER">1+1</MathVariable>

  <MathVariable VARIABLENAME="MV2" 
  TYPE="EXPRESSION" DATATYPE="INTEGER">2+2</MathVariable>

  </MathIF>

  <MathIF IF="A<>B">

  <MathVariable VARIABLENAME="MV3" 
  TYPE="VALUE" DATATYPE="INTEGER">0</MathVariable>

  <MathVariable VARIABLENAME="MV4" 
  TYPE="VALUE" DATATYPE="INTEGER">10</MathVariable>

  </MathIF>

  Pseudo-code:

  If A = B

  MV1 = 1 + 1

  MV2 = 2 + 2

  Else

  MV3 = 0

  MV4 = 10

  End

• Use IIF when only one math variable needs to be set to either of two values based on the evaluation of the expression.

  Example of IIF statement:

  <MathVariable VARIABLENAME="MV" TYPE="IIF" 
  EXPRESSION="FlatCheck=CHECKED" DATATYPE="INTEGER">01,02</MathVariable>

  Pseudo-code:

  If FlatCheck = CHECKED

  MV = 01

  Else

  MV = 02

  End

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

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

• INTEGERARRAY, 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 various ways to create/populate/manipulate arrays, according to the array type. The OPERATIONS include: 

• 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.

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

5. The use of Blank is not needed in a conditional expression where blank is a previously defined field. Instead use two single quotes (i.e., '').

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

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

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

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

9. When you need to obtain the XML data for the current activity, use the following configuration to help performance:

   <MathVariable VARIABLENAME="ThisPendingActivityXML" TYPE="SQL">
   SELECT XMLData FROM AsActivity WHERE ActivityGUID = '[Activity:ActivityGUID]'
   </MathVariable>

• Always remove the data contained in a math variable as described above before leaving Math as demonstrated by the following configuration.

  <MathVariable VARIABLENAME="ThisPendingActivityXML" TYPE="VALUE"></MathVariable>

  This configuration will avoid writing too much data to the database. In the extreme circumstance that you do need to load a large amount of XML into a variable, this will clear out the variable so it does not write as much data to AsActivity XMLData

10. If a data value is already defined as a field, don’t use a SQL to retrieve the value again from the database. Since this value is already a <Field>, change to TYPE=”FIELD” and reference the data by the name of the field.

Spawns

1. Pass spawn fields in the same sequence as they are 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” if the spawned transaction is effective on the same day as the spawning transaction.  

4. See AsCode for other spawn code values.

5. The DataTypes in spawn fields must match the corresponding data types in the receiving fields.

Copyright © 2009, 2013, Oracle and/or its affiliates. All rights reserved. Legal notices.

Open table of contents