MultiFields Business Rule

Many OIPA screens allow for the definition of one or more related fields where multiple instances of those related fields are needed. This requires a two dimensional presentation of fields. For example, a screen or transaction may need the entry and listing of multiple licenses where each license has one or more pieces of related data. This structure is called multifield. On supported screen where a multifield is needed, the screen or transaction references a business rule containing the multifield definition. This page describes the XML elements that define one or more multifield structures. Each structure must provide a unique name so that each multifields' data value is properly associated to the correct structure for. This eliminates ambiguity where a field name may be repeated across multiple multifield structures within the same business rule.

The presentation of a multifield structure allows the user to select the number of instances needed for data entry. Configuration can dynamically manipulate the maximum number of presented instances. When a screen presents a view of persisted multifield data by default the number of instances is set by the number of structure instances in the persistence. This maximum can also be dynamically altered as desired. For presentation needs, the first instance that displays can be dynamically set to a value other than the first instance.

Segment definition (SegmentName rule) for Group business employs an inheritance feature that merges all Product/Plan hierarchy levels Segment definitions. When multiple levels of Segment definition exists, the definition in the lowest override where a multifield invocation exists is the rule that provides definition for the multifield presentation. The lowest level might contain a blank invocation of a multifield rule which then displays no multifield structure(s). In addition, the MultiField business rule may have multiple definitions across the Product/Plan hierarchy. This definition is also resolved by the inheritance feature which will merge all of the multifield definitions of a single named multifield structure defined across the Product/Plan hierarchy to complete a presentation of that structure. Each uniquely named structure across the hierarchy aggregates its own set of fields using the same inheritance function.

MultiFields Business Rule: Elements and Attributes
Element Attribute Parent Element Description Element / Attribute Values
<MultiFields>    

Required:

The opening and closing tag of the MultiFields rule.

  
<MultiField>   <MultiFields>

Required, Repeatable:

This element defines a structure where functionally related fields can be presented repeatedly as a group for user entry or data modification or data viewing.  This element is repeated to define multiple structures for different sets of functionally related fields.  Each structure must be defined with a unique <Name> element value.

  
<Name>   <MultiField>

Required:

This element provides a name for the <MultiField> structure to associate persisted data to the correct structure where multiple structures are defined in this rule.  The element's value can be different than <Title> and must be unique in this rule.

  • literal
<Title>   <MultiField>

Optional:

This element defines the title for the displayed section presented by this structure.

  • MultiFields

    • default

  • literal
<ComboDisplay>   <MultiField>

Optional:

Each multifield structure present a "Number of Fields" combo box for user entry.  This field allows the user to select the number of structure instances the screen should present.  This element provides a custom label for the combo box..

  • Number of Fields

    • default

  • literal
<Start>   <MultiField>

Required:

This specifies the starting option value for the "Number of Fields" combo box.  The value of this element can be 0. 

ScreenMath and Actions can reference this field's value as "MultifieldStart" for reading and assigning value.  During an ONCHANGE event, if this value will be altered, it should be assigned a value after "MultifieldEnd".

  • literal

    • this must be an integer

  • SQL statement

    • the result of this SQL statement must be an integer value

    • the statement may include reference to a parent screen's field without prefix

  • Activity:[field name]

    • access is limited to Activity fields

  • math variable

    • variable name must be prefixed with a math ID
<End>   <MultiField>

Required:

This specifies the ending option value for the "Number of Fields" combo box.  The value of this element can be 0.

ScreenMath and Actions can reference this field's value as "MultifieldEnd" for reading and assigning value.  During an ONCHANGE event, if this value will be altered, it should be assigned a value before "MultifieldStart".

  • literal

    • this must be an integer

  • SQL statement

    • the result of this SQL statement must be an integer value

    • the statement may include reference to a parent screen's field without prefix

  • Activity:[field name]

    • access is limited to Activity fields 

  • math variable

    • variable name must be prefixed with a math ID; [id]:[variable]
<Fields>   <MultiField>

Required:

See Common Elements ActionEvents definition page.

  
<Events>   <MultiField>

Optional:

This element is applicable when invoked by parent rules ClassScreen, SegmentName and ClientRelationshipScreen.  ScreenMath and Actions invoked by an Event can reference a built-in system variable named MultiValueFieldIndex.  The system variable can be read for a value or assigned a value with references to the first instance being the value 0. 

See Common Elements ActionEvents definition page.

  
<ScreenMath>   <MultiField>

Optional:

This element is applicable when invoked by parent rules ClassScreen, SegmentName and ClientRelationshipScreen.  This structure can reference a built-in system variable name MultiValueFieldIndex.  The system variable can be read for a value or assigned a value with references to the first instance being the value 0.

See Common Elements ActionEvents definition page.

  
<Actions>   <MultiField>

Optional:

This element is applicable when invoked by parent rules ClassScreen, SegmentName and ClientRelationshipScreen.  This structure can reference a built-in system variable named MultiValueFieldIndex.  The system variable can be read for a value or assigned a value with references to the first instance being the value 0.

See Common Elements ActionEvents definition page.

  

XML Schema

<MultiFields>
    <MultiField>
        <Name>[literal]</Name>
        <Title>MultiFields | [literal]</Title>
        <ComboDisplay>Number of Fields | [literal]</ComboDisplay>
        <Start>[integer | sql | variable | field]</Start>
        <End>[integer | sql | variable | field]</End>
        <Fields>. . .</Fields>
        <Events>. . .</Events>
        <ScreanMath>. . .</ScreanMath>
        <Actions>. . .</Actions>
    </MultiField>
    <MultiField>. . .</MultiField>
</MultiFields>

XML Example - Single Structure

<MultiFields>
    <MultiField>
        <Title>Agent Relationship Details</Title>
        <ComboDisplay>Agent Relationship Details</ComboDisplay>
        <Start>0</Start>
        <End>SELECT COUNT(*) FROM AsClientRelationship JOIN AsClient ON AsClient.ClientGUID = AsClientRelationship.SecondaryClientGUID JOIN AsGroupCustomer ON AsGroupCustomer.ClientGUID = AsClientRelationship.PrimaryClientGUID WHERE AsClientRelationship.SecondaryClientGUID = '[Client:ClientGUID]' AND AsClientRelationship.PrimaryRelationshipType = 'BROKER' AND AsClientRelationship.RecordStatusCode = 'ACTIVE'</End>
        <Fields>
            <Field>
                <Name>RelatedGroupCustomers</Name>
                <Display>Related Group Customers</Display>
                <DataType>Combo</DataType>
                <Query TYPE="SQL">SELECT AsClient.ClientGUID, AsClient.CompanyName FROM AsClient JOIN AsClientRelationship ON AsClientRelationship.PrimaryClientGUID = AsClient.ClientGUID WHERE AsClientRelationship.SecondaryClientGUID = '[Client:ClientGUID]' AND AsClientRelationship.PrimaryRelationshipType = 'BROKER' AND AsClientRelationship.RecordStatusCode = 'ACTIVE'</Query>
            </Field>
            <Field>
                <Name>CurrentAgent</Name>
                <Display>Current Agent</Display>
                <DataType>Combo</DataType>
                <Query TYPE="SQL">SELECT AsClient.ClientGUID, AsClient.FirstName ||','|| AsClient.LastName ||' '|| AsClientRelationship.EffectiveFrom FROM AsClientRelationship JOIN AsClient ON AsClient.ClientGUID = AsClientRelationship.SecondaryClientGUID WHERE AsClientRelationship.PrimaryClientGUID = '0B215D17-CDA4-47A4-BCA8-D3B0D29CBEB3' AND AsClientRelationship.PrimaryRelationshipType = 'BROKER' AND AsClientRelationship.RecordStatusCode = 'ACTIVE' AND AsClientRelationship.SecondaryClientGUID = '[Client:ClientGUID]'</Query>
                <Expanded>Yes</Expanded>
            </Field>
            <Field>
                <Name>NewAgent</Name>
                <Display>New Agent</Display>
                <DataType>Combo</DataType>
                <Query TYPE="SQL">SELECT AsClient.ClientGUID, AsClient.FirstName ||','|| AsClient.LastName ||' '|| AsClientRelationship.EffectiveFrom FROM AsClient JOIN AsClientRelationship ON AsClientRelationship.PrimaryClientGUID = AsClient.ClientGUID WHERE AsClientRelationship.PrimaryClientGUID = '0B215D17-CDA4-47A4-BCA8-D3B0D29CBEB3' AND AsClientRelationship.PrimaryRelationshipType = 'BROKER' AND AsClientRelationship.RecordStatusCode = 'ACTIVE' AND AsClientRelationship.SecondaryClientGUID = '[Client:ClientGUID]' AND AsClientRelationship.EffectiveFrom >= TO_DATE('02/01/2013', 'MM/DD/YYYY')</Query>
                <Expanded>Yes</Expanded>
            </Field>
        </Fields>
        <Events>
            <Event TYPE="ONCHANGE" FIELD="RelatedGroupCustomers">
                <ActionSet ID="ReloadCurrentAgent"/>
            </Event>
        </Events>
        <Actions>
            <ActionSet ID="ReloadCurrentAgent">
                <Action ACTIONTYPE="ASSIGN" FIELD="NewAgent">SELECT AsClient.ClientGUID, AsClient.FirstName ||','|| AsClient.LastName ||' '|| AsClientRelationship.EffectiveFrom FROM AsClientRelationship JOIN AsClient ON AsClient.ClientGUID = AsClientRelationship.SecondaryClientGUID WHERE AsClientRelationship.PrimaryClientGUID = '[EventScreenMath:SMRelatedGroupCustomers]' AND AsClientRelationship.PrimaryRelationshipType = 'BROKER' AND AsClientRelationship.RecordStatusCode = 'ACTIVE' AND AsClientRelationship.SecondaryClientGUID <> '[Client:ClientGUID]'</Action>
            </ActionSet>
        </Actions>
    </MultiField>
</MultiFields>

XML Example - Multiple structures

<MultiFields>
    <MultiField>
        <Name>TextTestMF</Name>
        <Title>Text Test</Title>
        <ComboDisplay>Text Test</ComboDisplay>
        <Start>Activity:FirstInstance</Start>
        <End>Activity:LastInstance</End>
        <Fields>
            <Field>
                <Name>TextTest1</Name>
                <Display>Text Test 1</Display>
                <DataType>Text</DataType>
            </Field>
            <Field>
                <Name>TextTest2</Name>
                <Display>Text Test 2</Display>
                <DataType>Text</DataType>
            </Field>
            <Field>
                <Name>TextTest3</Name>
                <Display>Text Test 3</Display>
                <DataType>Text</DataType>
            </Field>
            <Field>
                <Name>TextTest4</Name>
                <Display>Text Test 4</Display>
                <DataType>Text</DataType>
                <Default>Test4</Default>
            </Field>
            <Field>
                <Name>TextTest5</Name>
                <Display>Text Test 5</Display>
                <DataType>Text</DataType>
                <Default/>
            </Field>
            <Field>
                <Name>TextTest6</Name>
                <Display>Text Test 6</Display>
                <DataType>Text</DataType>
                <Default/>
            </Field>
        </Fields>
        <Events>
            <Event TYPE="ONLOAD">
                <ActionSet ID="TestTextActionOnLoad"/>
            </Event>
            <Event TYPE="ONCHANGE" FIELD="TextTest1">
                <ActionSet ID="TestTextActionOnChange"/>
                <ActionSet ID="TestTextAction"/>
            </Event>
            <Event TYPE="ONSUBMIT">
                <ActionSet ID="TestTextActionOnSubmit"/>
            </Event>
            <Event TYPE="CALLEDEVENT" ID="MFTestTextEventOnChange">
                <ActionSet ID="MFActionOnChange"/>
            </Event>
            <Event TYPE="CALLEDEVENT" ID="MFTextEventOnLoad">
                <Math ID="EventScreenMath"/>
                <ActionSet ID="MFScreenActionOnLoad"/>
            </Event>
        </Events>
        <ScreenMath>
            <Math ID="EventScreenMath" GLOBAL="No">
                <MathVariables>
                    <MathVariable VARIABLENAME="TextValue" TYPE="VALUE" DATATYPE="TEXT">LocalScreenMath</MathVariable>
                </MathVariables>
            </Math>
        </ScreenMath>
        <Actions>
            <ActionSet ID="MFScreenActionOnLoad">
                <Action ACTIONTYPE="ASSIGN" FIELD="TextTest6">EventScreenMath:TextValue</Action>
            </ActionSet>
            <ActionSet ID="TestTextActionOnLoad">
                <Action ACTIONTYPE="ASSIGN" FIELD="TextTest5">GlobalScreenMath:ValueFromScreenMath</Action>
                <Action ACTIONTYPE="HIDE" FIELD="TextTest3"/>
                <Action ACTIONTYPE="DISABLE" FIELD="TextTest4"/>
            </ActionSet>
            <ActionSet ID="TestTextActionOnChange">
                <Condition IF="IsEmpty( TextTest1 ) And MultiValueFieldIndex=1">
                    <Action ACTIONTYPE="ERROR">TextTest1 $$$MultiValueFieldIndex$$$ cannot be empty.</Action>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1 = 'Test'">
                    <Action ACTIONTYPE="ERROR">TextTest1 $$$MultiValueFieldIndex$$$ cannot be Test.</Action>
                </Condition>
                <Action ACTIONTYPE="ASSIGN" FIELD="TextTest4">'Text4'</Action>
                <Action ACTIONTYPE="HIDE" FIELD="TextTest3"/>
                <Action ACTIONTYPE="DISABLE" FIELD="TextTest4"/>
            </ActionSet>
            <ActionSet ID="MFActionOnChange">
                <Condition IF=" Not IsEmpty(TextTest1) And TextTest1='Hide'">
                    <Action ACTIONTYPE="HIDE" FIELD="TextTest2"/>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1='Show'">
                    <Action ACTIONTYPE="SHOW" FIELD="TextTest2"/>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1='Disable'">
                    <Action ACTIONTYPE="DISABLE" FIELD="TextTest2"/>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1='Enable'">
                    <Action ACTIONTYPE="ENABLE" FIELD="TextTest2"/>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1='Assign'">
                    <Action ACTIONTYPE="ASSIGN" FIELD="TextTest2">'Text2'</Action>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1='ReadOnly'">
                    <Action ACTIONTYPE="READONLY" FIELD="TextTest2"/>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1 = 'Test'">
                    <Action ACTIONTYPE="ERROR">TextTest1 $$$MultiValueFieldIndex$$$ cannot be Test.</Action>
                </Condition>
            </ActionSet>
            <ActionSet ID="TestTextActionOnSubmit">
                <Condition IF="IsEmpty( TextTest1 ) And MultiValueFieldIndex=1">
                    <Action ACTIONTYPE="ERROR">TextTest1 $$$MultiValueFieldIndex$$$ cannot be empty.</Action>
                </Condition>
                <Condition IF="Not IsEmpty(TextTest1) And TextTest1 = 'Test'">
                    <Action ACTIONTYPE="ERROR">TextTest1 $$$MultiValueFieldIndex$$$ cannot be Test.</Action>
                </Condition>
            </ActionSet>
            <ActionSet ID="TestTextAction">
                <Condition IF="TextTest1 = 'Errors' and MultiValueFieldIndex=2">
                    <Action ACTIONTYPE="HIDE" FIELD="TextTest4"/>
                    <Action ACTIONTYPE="ERROR" FIELD="TextTest2">TextTest2 $$$MultiValueFieldIndex$$$ Error Message.</Action>
                    <Action ACTIONTYPE="WARNING" FIELD="TextTest5">TextTest3 $$$MultiValueFieldIndex$$$ Warning Message</Action>
                </Condition>
            </ActionSet>
        </Actions>
    </MultiField>
    <MultiField>
        <Name>CheckTestMF</Name>
        <Title>Check Test</Title>
        <ComboDisplay>Check Test</ComboDisplay>
        <Start>0</Start>
        <End>2</End>
        <Fields>
            <Field>
                <Name>CheckboxTest1</Name>
                <Display>Checkbox Test 1</Display>
                <DataType>Check</DataType>
            </Field>
            <Field>
                <Name>CheckboxTest2</Name>
                <Display>Checkbox Test 2</Display>
                <DataType>Check</DataType>
            </Field>
            <Field>
                <Name>CheckboxTest3</Name>
                <Display>Checkbox Test 3</Display>
                <DataType>Check</DataType>
            </Field>
            <Field>
                <Name>CheckboxTest4</Name>
                <Display>Checkbox Test 4</Display>
                <DataType>Check</DataType>
            </Field>
        </Fields>
        <Events>
            <Event TYPE="ONLOAD">
                <ActionSet ID="TestCheckActionOnLoad"/>
            </Event>
            <Event TYPE="CALLEDEVENT" ID="MFCheckEventOnLoad">
                <ActionSet ID="MFActionOnLoad"/>
            </Event>
        </Events>
        <Actions>
            <ActionSet ID="MFActionOnLoad">
                <Action ACTIONTYPE="WARNING">CheckBoxTest1 is checked now</Action>
                <Action ACTIONTYPE="ASSIGN" FIELD="CheckboxTest1">'CHECKED'</Action>
                <Action ACTIONTYPE="DISABLE" FIELD="CheckboxTest1"/>
            </ActionSet>
            <ActionSet ID="TestCheckActionOnLoad">
                <Action ACTIONTYPE="ASSIGN" FIELD="CheckboxTest2">'CHECKED'</Action>
                <Action ACTIONTYPE="HIDE" FIELD="CheckboxTest3"/>
                <Action ACTIONTYPE="DISABLE" FIELD="CheckboxTest4"/>
            </ActionSet>
        </Actions>
    </MultiField>
</MultiFields>