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):

EffectiveDate
Allocations (if applicable)
Valuation (if applicable)
Suspense
ValuesBlock
Withholding
AllowComments
Transitions
MultiSuspense
Address
Fields
Buttons
Events
ScreenMath
Assignments (if applicable)
MultiFields
Math
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

Valuation

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

Suspense

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

ValuesBlock

When used in transaction configuration, the ValuesBlock element creates a Values section either on the Allocations tab of the Activity Detail or on a separate Values tab on the same screen.

Withholding

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

Address

The Address element provides the ability add and update client addresses via transactions.

Fields

The order of field tags is:
- <Name>
- <Display>
- <DataType>
- <Group>
- <Currency>
- <Value>
- <DefaultCurrency>
- <DefaultValue>
- <Query>
- <Calculated>
- <Required>
- <Disabled>
- <Hidden>
- <Expanded>
- <ClearOnRecycle>
The <DefaultValue> tag and the <Calculated> tag may not be present at the same time. Use one or the other.
If a field is hidden, do not include a <Disabled> tag.
If a field is disabled, do not include a <Hidden> tag.
If a field is required, do not include <Hidden> and <Disabled> tags.
If a field is either hidden or disabled, do not include a <Required> tag.
If a field is not hidden, do not include <Hidden> tag.
If a field is not disabled, do not include <Disabled> tag.
Hidden fields that are independent of other fields should be placed at the end of the <Fields> section.

Note: An exception would be when a hidden field can become a non-hidden field based on actions/events
The Required element applies only to the following screens:
- Activities
- Address
- Client
- ClientGroup
- ClientWithholding
- Inquiry
- Policy
- PolicyWithholding
- Requirements
- Role
- Segments
- Suspense
The Required element is not valid if the DataType is Identifier or Radio.
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.
If a user is prevented by the security configuration from entering data in a required field, the screen will not pass validation when submitted.
The ClearOnRecycle element applies only to Transactions.
The ClearOnRecycle element applies only to Transactions.

Example: <Name>IssueDate</Name>, <Display>Issue Date</Display> not <Display>Date of Issue</Display>
Filler fields should have a DataType value of Blank, and no Display element
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

A combo box with a defaulted selection should not have a 00 selection.

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

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.
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.
Do not have the same value for the <Name> tag for more than one <Field>. If multiple fields have the same name, recording of the field value and action/events on the field will not be able to differentiate between the multiple instances. The data saved from a screen will only have one instance of a duplicated field name
SegmentField, PlanField, ActivityField, ClientField, RoleField and PolicyField names:

Do not use Column names for any Field name

Example: AsSegmentField should not have a Field named ‘EffectiveDate’ since there is an AsSegment Column named ‘EffectiveDate’.

Action / Events / ScreenMath

Actions and events can become a very large section in the configuration so naming each ActionSet and QuerySet with a meaningful name is very helpful, not only to keep track of the completed requirements but also for someone trying to decipher what has been configured.

MathID names for ScreenMath should also have a meaningful name.

By grouping like actions together, the organization of your actions and events will be increased. Use your own discretion on how to group them but you can group by function (assigning field values, disabling, errors, etc)

See the full configuration guide for full details and examples for how to use actions and events.

Standards and best practices described in Math section are applicable to ScreenMath as well unless noted.

Math

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.
- LOGGING
  
  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.”
  
  Do not use logging from within Function, ScreenMath or any CopyBook used by a Screen.
When defining MathVariable names, the following practices are recommended:
- Use only alphanumeric characters - letters, digits
- 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 table columnsnames are reserved words and they cannot be used as mathvariable names
- 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"
When defining the TYPE for a MathVariable use:
- VALUEif 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.
    
    When using FILLBY-FUND to create an array, your transaction/rule must be configured to perform valuation
    
    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
  
  The same rules that apply to TYPE= ”EXPRESSION” apply to TRANSFORM as well.
  
  Note: 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.
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., ''). Use Data Dictionary defined field names for consistency across products.
Use Data Dictionary defined field names for consistency across products.
Capitalize the words AND and OR when writing SQL. Use sentence case And and Or when configuring anything other than SQL statements.
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
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

Pass spawn fields in the same sequence as they are configured in the transaction that is being spawned.
Any GUID fields passed as spawn fields should be disabled in the spawned transaction.
Spawned transactions should use SPAWNCODE=”01” if the spawned transaction is effective on the same day as the spawning transaction.
See AsCode for other spawn code values.
The DataTypes in spawn fields must match the corresponding data types in the receiving fields. System Generated Spawns - Effective Date of the spawned transaction should be disabled.
System Generated Spawns - Effective Date of the spawned transaction should be disabled.

Data Intake File search result table

When a user searches for Data Intake file the result table displays the intake files and the first column in the result table is displayed as a link automatically. The columns in the result table are configured in the IntakeFileSearchScreen rule. So it is recommended to configure FileGuid or FileId as first column in the IntakeFileSearchScreen to display a link on FileGuid. However, there is no restriction on which column should be selected as the first column.