Events
This screen offers Templates and Events for use with Rule building. Select the Template or Event required to display the Rule Definition on the canvas. Items that are in green are configured, items that are in green with a dotted line still need to be configured, and items in grey cannot be configured until something else has been set. Configure the rule by replacing the green with the relevant setting.
Templates
Templates are a quick way of defining rules based on common actions on Forms and Views. Templates consist of two parts – the what and the when. Selecting a template will prepopulate the events and actions in the Rule Definition
| Type | Template | Example |
|---|---|---|
| View | Execute a method on the View when a control raises an event | Clicking on the refresh button will cause the Get List method to execute on the View |
| View | Open a subform when a control raises an event | Clicking on the new button will open a subform to capture a new record |
| View | Open a subview when a control raises an event | Clicking on the new button will open a subview to capture a new record |
| View | Navigate to another Form when a control raises an event | Clicking on the next button will take you to a different Form |
| View | Save the changes of the editable list when a control raises an event | Clicking on the save button will save all of the changed items in the editable list in a single transaction |
| View | Save the values of a multi-select control when a control raises an event | Clicking on a control will perform an action on checked or unchecked items |
| View | Reload a list control when the View completes an action | After adding a new Region, reload the associated region drop down menu |
| View | Close a subview or subform and execute a method on the View when a subview executes a method | Close the subview or subform after a new employee is created and then refresh the employee list |
| Form | Execute a method on a View when the Form completes an action | After loading the Form, retrieve all of the employees using the Get List method |
| Form | Execute a method on a View when a View completes an action | After the new employee is created, refresh the employee list View |
| Form | Update master and detail values when a control raises an event | Clicking the new button will update all values that have been added, changed or removed |
| Form | Navigate to another Form when a View completes an action |
|
Events
Events are the when a Rule happens
| Type | Template | Example |
|---|---|---|
| View Events | When the View executes a method | When a method has been executed on a specific view, such as when a new item is created |
| View Events | When a View on a subform executes a method | When a record is created on a View opened in a subform |
| View Events | When a View opened in a subform is closing | When the View closes that was opened in a subform |
| Form Events | When the Form raises an event | When a Form is loaded |
| Form Events | When a control on the Form raises an event. See Using Tab navigation to optimize performance | When a button on a Form is clicked |
| View Method | When a View raises an Event | When a button on a View is clicked |
| View Method | When a control on a View raises an event |
|
| Subform Events | When a View on a subform executes a method | When the employee View loads a record |
| Subview Events | When a control on a subview raises an event | When a button on a popup dialog is clicked |
| Subform Events | When a control on a subform raises an event | When a button is clicked on a subform |
| Subform Events | When a control on a View on a subform raises an event | When a cancel button on a View opened in a subform is clicked |
| Subform Events | When a subform executes a method | When a record is created on a Form opened in a subform |
| Subview Events | When a subview executes a method | When a record is created on a View in a Form in a subform |
| Subview Events | When a subview is closing | When the subform closes |
| Subform Events | When a subform is closing | After the Form opened in a subform has closed |
| Parameter Events | When a Form parameter raises an event | When a Form parameter is changed |
| Parameter Events | When a View parameter raises an event | When a View parameter is changed |
| Parameter Events | When a subview parameter raises an event | When a subview parameter is changed |
| Parameter Events | When a subform parameter raises an event | When a subform parameter is changed |
| Parameter Events | When a View parameter on a subform raises an event | When a View parameter on a subform is changed |
| Workflow Events | After the workflow action was submitted | After a workflow item was approved |
| Control Events | When a control on the View raises an event | When the Create button is clicked |
Considerations
-
When using the rule events list item click and list item double click, changes have been made that will affect expected behavior.
Previous behavior:
List item click event and list item double click event executed when double clicking an item.
Current behavior:
List item click and list item double click events are now handled separately and will execute as such. If a rule scenario previously relied on the assumption that the single click will execute together with the double click when using the list item double click event, this scenario will no longer behave as expected. The rule can be changed to execute another rule to incorporate the previous single click.
Configure Rule to execute Picture Events
A Rule can be configured to execute a Picture Event. The Events available are as follows:
- When Picture is [Clicked] - When the control is clicked, the cursor will change to a hand (pointer) if this event is configured on the Picture control and the Rule will execute
- When Picture is [Active] - When the cursor is hovered over the picture (Mouse Over), the Rule will execute
- When Picture is [Not Active] - When the cursor is moved from within the picture to its container (Mouse Out), Rule will execute
The Events are displayed when using the Picture control in the Rule Designer:
See KB001384 - How to use the Picture control Events for examples to use these Events.
Collapse and Expand View Events and Methods
The Collapse and Expand Events and methods have been added to the Rule Designer when using a Rule on a Form. These Events and methods can be used with Actions such as Transfer Data for example or to improve performance. The Load and Initialize methods can be used when expanding the View for example and don't have to be executed when the Form is Initialized. This minimizes the execution time when a Form is Initialized. See KB001387 - How to use the Collapse and Expand View Events.
Post Initialize Event and Method
A feature has been added to events and methods to execute post the initialization of a View or a Form. This feature is useful for example where a Form is initialized and is required to be available to the user while still performing other rule actions such as load methods and get list methods on the Form. It can also be used on Views or Forms with control rule actions that are executed asynchronously. The View or Form will initialize and controls can execute asynchronously post initialization to ensure immediate availability of the View or Form and enhance performance.
The Initialized event and method has been added to the Events and as a View or Form method that can be used through the following:
Events:
When the Form raises and event
When a View raises an event
Actions:
Execute a View method
Execute a Form method
How to use the Initialized event and method
Following is an example of how the Initialized event can be used. The same principle applies when using the Initialized method. The scenario below applies to a Form containing a View. The rule definitions will be executed in the order the images are listed. We moved the population of the Product Drop-Down List down to execute only after the Sales Item View has initialized, in other words post initialization. The sequence of the rule definition execution is explained below:
The Form is initialized, then the View is initialized and the Customer Drop-Down List is populated with data. At this stage the View and Form is available for editing and the user can start typing data into the View. After the View has initialized (post initialization), the Product Drop-Down List is populated with data, meaning while the user is capturing data the Product Drop-Down List will be populated. This rule definition ensures that users can continue using Views and Forms while other rule definitions are still being executed. After the Form is initialized, the View will execute a load method.
Considerations
- The Initialized event will always fire after the Initialize event regardless if there are user actions configured on Initialize or if the Initialize event is disabled or not. Initialized will execute after Initialize even if Initialized is called from any other rule.
- When Initialized is added or removed on different levels, other definitions are not affected. If it exists and the related Initialize event has completed it will run automatically.
Error Handling
An error event and method is now available to be specified on View or Form level. This allows you to specify custom rule actions and conditions to be followed, and the Error system variable category is available for usage. The Error feature can be used in rule actions mappings or in conditions. When an error occurs, it will attempt to find something to resolve the error, if nothing is found to resolve it with, the default error handling will be used. The Stop rule execution and Continue to next execution rule actions can also be used to determine whether execution of the next handler should continue or not. In the Rules Designer, you can also raise your own custom errors via the error method provided. In mappings you can specify the values for the error context that will be used.
The Error event and method has been added to the Events and as a View or Form method that can be used through the following:
Events:
When the Form raises an event
When a View raises an event
Actions:
Execute a View method
Execute a Form method
The error context available consist of the following:
- Error Message
- Error Detail
- Error Type
Potential errors that may occur at runtime and can be handled differently include:
- Cannot execute SmartObject methods
- SmartObject method doesn't exist
- ID does not exist
- ID cannot be loaded
- Can not send a mail
- Can not start a workflow
- Can not access a worklist item
How to use it
- Use one of the following events in a rule and select the error event
Events:
When the Form raises an event
When a View raises an event
- Add conditions and actions to the rule definition as required. One example is to show a message to the user. Configure the message by using the error system values from the Context Browser as shown below or by using your own details.
OR
- Use one of the following actions and select the error method
Actions:
Execute a View method
Execute a Form method
- Configure the error method by providing input mappings
OR
- Use the error occurred condition as shown below
Considerations
- When creating a custom error, it is advised to use conditions to check the validity of the error. Using custom errors can create confusion if the error context is not in sync with the user experience.
- When an error occurs on a View on a Form, the error handler will attempt to handle it via the View’s error handling and then revert to the Form's error handling if nothing was found. In the case of no error handling being specified at all, default error handling will apply.
- The following order is used when searching for error handlers on error conditions (depending on the origin):
- Search for a valid error handler in the rule
- Then search for a valid error handler in the View
- Then search for a valid error handler in the Form
- Then apply the default error handling if nothing was found on the previous levels
Parameter rules
New events and conditions have been added to the Events and Conditions pages in the Rule Designer and appear under the Parameters category. This feature allows a user to set up actions on the change of a parameter rather than use hidden text boxes on Views and Forms as previously.
How to use it
- Use a parameter change event such as When a View parameter raises an event
-
Add parameter conditions and actions to the rule definition as required. One example is to show a message to the user if a View parameter is changed and has a specific value.
Considerations
- The parameter events and conditions are available on View and Form level.
- It is recommended to use the parameter events and conditions where hidden text boxes or data labels were previously used to save values and execute a rule if something changes.
- When a View parameter and Form parameter have the same name; where the View is displayed on the Form, and an OnChange event is configured for either the View or Form parameter, the subsequent rule will only be applied to the parameter used in the rule event
Deleting Events
An existing Event can be deleted by clicking on the red cross next to the Event or in the toolbar.
Then navigate to the Events screen of the Rule Designer to select a new Rule Event to complete the Rule Definition. Alternatively save the rule if you want to configure the event at a later stage. The rule will show as unbound on the rules screen and will not be active until such time as it is edited and an event is configured.
