Events Pane

Action Events provide the ability to perform actions on a field when an event occurs on the screen. Configuration is done by establishing user events and linking them to Action Sets via ID attributes. When the user selects something in OIPA an event invokes a set of Action Sets that change fields or display messages.

There are various types of Action Events that can be configured.

  • create custom error and warning messages that appear to the end user after the system validates what was entered.

  • change whether fields are enabled or disabled when an event occurs.

  • change whether fields are hidden or displayed.

  • change a field’s data according to the value in a trigger field.

Configuration is performed through the Events pane located on the menu bar across the top of the Configuration Area.

Please see the XML Configuration Guide, which can be accessed from the Help menu, for a list of all elements, attributes and values needed for configuration. View Transaction Rules | Transaction Elements | ActionEvents.

Important   Events can also be configured in Multifields. Refer to the Multifield Events section of the help for information.

Events tab on Configuration Area Menu bar

Events Pane

High Level Steps to Configure Action Events

  1. Configure the fields that the actions can be applied to.

  2. Configure the event that needs to occur to invoke the actions. This must be done in the XML Source pane as no visual configuration is available at this time.If events are configured within the <Multifield> tags, then some additional consideration is required. Refer to Multifield Events for additional information.

  3. Configure the ScreenMath to define the math that is available for use when an event is invoked. Either global or local math can be used by fields.

  4. Identify the set of actions, ScreenMath, QuerySets and/or ActionSet, that are configured in the event.

    • If changing field data, configure a QuerySet that defines the data used to populate combo boxes according to a trigger field’s value.

    • If creating errors, warnings or controlling a field, configure an ActionSet that defines the action to be performed on a field.

Configure an Event

The events section identifies the type of event that needs to occur to invoke a set of actions. It also identifies the field that is connected to the event.

The available event types that can invoke an action are:

  • ONLOAD: runs the event on the initial load of the screen.

  • ONCHANGE: runs the event when a trigger field is changed. OnChange will recognize a change to the specified field's value but not a change to its currency code.

  • ONSUBMIT: processes the event when the final submission on the screen is selected.

Steps to Configure an Event

Events can be configured directly in the XML using the XML Source pane or they can be configured in the Events pane with the help of visual configuration tools. The Events pane also provides a way to see the individual parts of Events and Actions configuration without the additional transaction XML. Click an Action from the Event Navigator window to the left of the Configuration Area to add the opening tag to the configuration. If configuration already exists for the Action or Event, that configuration will display in the Event pane.

  1. Check-out the transaction, segment or business rule's XML file.

  2. Click the Events tab. The Event Navigator window will open.

  3. Double-click the Events node. The opening tag for Events will display in the Configuration Area.

  4. Configure the event. Identify the event TYPE and, if applicable, the FIELD that the event applies to.

  5. Configure any combination of Math, ActionSets and/or QuerySets. Each action ID attribute must have a matching action.

  6. Check-in the file to save the changes to the database.

Events and Actions XML sample

Events XML

Event XML Sample

Event TYPE, FIELD and IDs

ScreenMath

Configure the <ScreenMath> section in order to perform field math to support actions. In <ScreenMath> configure <Math> sub-elements that are each identified with an ID so that events may locate it for use. This is different from the <Math> section, because it provides the ability to perform calculations for the Fields section. ScreenMath is not available for use in the main transaction <Math> section.

The <ScreenMath> is identified through a configurable ID and can include two types of <Math>:

  • Global ScreenMath: All fields can use math in this section. It is only loaded on the initial load of the screen and cannot use field values.

  • Local ScreenMath: This is invoked when indicated by an action. Fields may be used; however, the configuror must be aware that the ScreenMath logic must be configured in such a way as to ensure that all fields being used take into consideration all of the calls to the use of the ScreenMath for that ID.

There can only be one GLOBAL ScreenMath section. The GLOBAL attribute with a value of Yes indicates to the system that the math is global. Without the GLOBAL attribute the system identities the <Math> as local. The global ScreenMath is available in the local ScreenMath section. Local ScreenMath is not available in global ScreenMath. When naming ScreenMath do not name global and local math the same. If the names are the same, the local math will take precedence.

Important   Refer to the Screen Math Considerations page for additional configuration guidelines.

ScreenMath XML Example

Screen Math XML

Steps to Configure Screen Math

  1. Check-out the transaction, segment or business rule's XML file.

  2. Click the Events tab. The Event Navigator window will open.

  3. Right-click the Screen Math node and select New Math Section.

  4. Enter the Section ID, which is the name of the ScreenMath.

  5. Check the Global box if the math being configuring is global math.

  6. Select Finish.

  7. Configure the math section by dragging and dropping math variables from the Palette window.

  8. Check-in the XML file to save the changes to the database.

ScreenMath

Global Screen Math on Events Pane

Important   View the ScreenMath XML from the XML Source pane. See image below.

Screen Math Viewed from XML Source Pane

Screen Math XML from XML Source Pane

Define Actions

There are two types of actions: (Use any combination of the options listed below.)

  • QuerySets identifies a set of action configuration to be used for the event.

  • ActionSets identifies a set of query configuration to be used for the event.

Actions and Currency Considerations

Actions can be configured to compare currency values and assign new ones to fields. Some common operations include comparing money to money fields using the less than expression, comparing currency math variables, assigning a currency code to a math variable or field and assigninga value from a money field to another with like currency codes.

Keep in mind the following points when using currency in Actions.

  • IsEmpty() just checks for the presence of a numeric value, the currency code is ignored.
  • Comparisons of named fields or math variables use the attached currency codes in addition to their numeric values; the associated currency code values must be the same or the system will throw a stack trace indicating the currency codes are incompatible.

  • The Currency Code of a field can be found using the syntax of "FieldName:CurrencyCode".

  • The Currency Code of a math variable can be found using the function “GetCurrencyCode ()”.

  • Action type ASSIGN will carry the Currency Code of the math variable or field when assigning a value provided the source currency is permitted for the target field. It cannot target changes to the currency code independent of the Money field.

  • Action type ASSIGN should validate the source currency code against that of the target. If the currency code of the target does not allow the currency of the source, the system will throw a stack trace indicating the currency codes are incompatible. The Currency code of the target is defined in the <Currency> element of the field or in its absence, the plan or company default currency using standard best match logic.

  • Action type ASSIGN will only accept Money fields or CURRENCY math variables as assignment values for Money fields.

QuerySets

QuerySets allow combo boxes to load with a SQL statement, as well as define a set of hard coded combo box options. <QuerySet> is a sub-element of <Actions> and each <QuerySet> is identified with an ID attribute that the <Event> section uses to locate the correct configuration.

When configuring the change of combo box data, make sure to use the FIELD attribute in the corresponding <Event> section for the trigger field. In the <QuerySet> sub-element use the FIELD attribute for the field that will have its data changed.

Conditional logic can also be written in this section.

  • Compare single values by writing expressions. Please see the V9 XML Configuration topic in this help system for a list of all elements, attributes and values needed for configuration. View Common Elements | Operations Available for Expression Writing.

  • Use available functions.

  • Use Global and Local math (Must use MathID prefix).

  • Compare dates.

QuerySet XML Sample

QuerySet XML

Steps to Configure Action with QuerySets

  1. Check-out the transaction, segment or business rule's XML file.

  2. Click the Events tab. The Event Navigator window will open.

  3. Double-click the Actions node. The XML data will open on the Configuration Area.

  4. Configure the action by defining the QuerySets needed for the event. A sample is shown above.

  5. Check-in the file to save the changes to the database.

ActionSets

ActionSets allow for the configuration of errors and warnings, enabling fields, disabling fields, hiding fields, displaying fields and assigning a value to a field. <ActionSet> is a sub-element of the <Actions> and each <ActionSet> is identified with an ID attribute that the <Event> section uses to locate the correct configuration.

There is also the ability to write conditional logic in the section. Available logic includes:

  • Compare single values by writing expressions.

  • Use available functions.

  • Use global and local math (must use MathID prefix).

  • Compare dates.

Available actions are:

  • Error: Provides an error message to the user. The user will not be able to proceed until all errors are fixed.

  • Warning: Provides a warning message to the user. The user will be able to proceed even with warnings on the screen.

  • Enable: The user can key in a field value.

  • Disable: The user cannot key in a field value and the fields background color changes.

  • ReadOnly: The user cannot key in a field value but the fields background color does not change.

  • Show: The user will see the field.

  • Hide: The user will not see the field.

  • Assign: Allows a value to be set based on the change of a different field. Assign does not have an option to set a value and then re-execute the OnLoad or OnChange of the field being set.

Within the Actions tags for <Action ACTIONTYPE="ERROR"> or <Action ACTIONTYPE="WARNING> , a validation message can be added. Within this element, a screen math variable or activity field name may be substituted in the validation message to display an actual value from the activity. In the example below, a field or screen math variable is named “Amount”. The validation verifies that the amount is greater than 100.00. In the Error message $$$Amount$$$ would be used in the configuration validation message to display the value in the Amount field or screen math variable. If using an activity field name or math variable in the Actions/Events validation, a prefix is not required. The validation would then read, “Payment Amount of 40000.00 must be less than 100.00.” The configuration in the <Actions> sections would be similar to the example below:

<Action ACTIONTYPE="ERROR">Payment Amount of $$$Amount$$$$ must be less than 100.00.</Action>

Steps to Configure Action with ActionSet

  1. Check-out the transaction, segment or business rule's XML file.

  2. Click the Events tab. The Event Navigator window will open.

  3. Double-click the Actions node. The XML data will open on the Configuration Area.

  4. Configure the action by defining the ActionSets needed for the event.

  5. Check-in the file to save the changes to the database.

Important   Additionally, Group Elements such as Class, SegmentName, Agreement, Client Relationship, Group Customer can all utilize Action/Events (in conjunction with MultiFields Rule) for validation/warnings/error messaging.