Stepper triggers

In a stepper, it is possible to automate data changes using triggers and enrichers.

Data changes run when certain events take place in a stepper, such as when a user enters a stepper or a step, modifies a field value, or exits a step.

Triggers and enrichers in steppers

Automated data transformations include:

Stepper triggers, which execute database procedure calls when the stepper starts or finishes.
Step triggers, which execute enrichers or database procedure calls when the user enters, exits, or performs certain operations in the step.
Form step enrichers, which execute enrichers when the user opens a form step or modifies data in a form step.

Triggers refer either to enrichers or database procedures.

Create stepper triggers

A stepper trigger can execute a procedure declared in the model. Unlike procedures, enrichers cannot be attached to the stepper. This is because enrichers always affect an individual record and must therefore be attached to the relevant step. Procedures may be attached to steps or to the stepper itself.

To create a stepper trigger:

In the Stepper editor, scroll down to the Triggers table.
In the table toolbar, select the Add Stepper Procedure Trigger button.
The Create New Stepper Trigger wizard opens.
In the Stepper Trigger wizard step, enter the following values:
- Name: internal name of the object.
- Procedure: select a database function defined as a procedure in the model.
- Event: select the event that should cause this procedure to run.
Click Next.
The Configure Procedure step of the wizard displays the arguments of the selected procedure.
For each argument, click the Edit Expression button to create a SemQL expression that will be bound to the argument.
Click Finish to close the wizard.
A stepper trigger is created
Select this stepper trigger and use the Move Up and Move Down buttons in the toolbar to arrange the list of triggers. Triggers are executed based on their order in the list for a specific event.

Create step triggers

A step trigger can execute either a procedure or an enricher on specific step events.

To create a step trigger:

In the Stepper editor, scroll down to the Steps tree table.
Select the step you want to modify.
In the Properties view, select the Step Triggers finger tab.
This tab shows a table with the list of triggers for the step.
In the table toolbar, select the Add Step Procedure Trigger button or the Add Step Enricher Trigger button.
The Create New Step Trigger wizard opens.
In the Step Trigger wizard step, enter the following values:
- Name: internal name of the object.
- Procedure/Enricher: select a database function declared as a procedure or an enricher.
- Event: select the event that should cause this procedure or enricher to run.
If you create a step procedure trigger:
1. Click Next.
  The Configure Procedure step of the wizard displays the arguments of the selected procedure.
2. For each argument, click the Edit Expression button to create a SemQL expression that will be bound to the argument.
Click Finish to close the wizard.
A step trigger is created
Select this step trigger and then use the Move Up and Move Down buttons in the toolbar to arrange the list of triggers. Triggers are executed based on their order in the list for a specific event.

Configure form step enrichers

A form step enricher executes an enricher when the user enters a form or modifies the value of a form field.

To configure step enrichers:

In the Stepper editor, scroll down to the Steps tree table.
Select the form step you want to modify.
In the Properties view, select the Form Step Enricher finger tab.
This tab shows a table with the list of enrichers defined for the fields that appear for this form step.
Click the Synchronize Form Step Enrichers button in the table toolbar to refresh the list with new enrichers.

Check the appropriate option to run enrichers:

On Form Open: when the user opens the form.

With this option selected, the enricher is triggered every time a user opens the form, including when resuming the stepper or returning from another step.
On Data Change: when the user changes the value of an attribute that is an input for the enricher.

Data changes are detected when the user exits a field, makes a selection within a field (e.g., in drop-down menus), or after a certain period following user input while still in the field.

On Button Click: when the user clicks the Run <Enricher name> button to call one or several enrichers while authoring or editing form fields.

Enabling this option for an enricher displays the Run <Enricher name> button beside each configured output field of that enricher. If multiple enrichers apply to a single field value, clicking the button sequentially executes all enrichers for that field, following the standard enricher execution process. In such cases, the button tooltip indicates the enrichers' names to be executed in a comma-separated list (e.g., Run <Enricher #1>, <Enricher #2>, <Enricher #3>).

Once clicked, the Run <Enricher name> button is replaced with a Reset Run <Enricher name> button. Select this button if you wish to revert the enriched fields to their initial, pre-enriched state.

Stepper events

This section lists the various events that may cause triggers to start for steps and steppers. For the detailed list of events and their corresponding user actions, see Stepper events.

Events for steppers

A user may exit a stepper using different actions:

Finish: the user completes the stepper and submits the records for certification.
Close > Discard: the user completes the stepper and discards all its content. The stepper is canceled and cannot be resumed.
Close > Saved: the user completes the stepper and saves its content for later. They can resume this stepper later.

The following events occur once when a user enters or exits a stepper.

Stepper - Start: runs when the stepper starts.
Stepper - Finish (Pre Validation): runs once when the user finishes the stepper, before stepper validations.
Stepper - Finish (Post Validation): runs once when the user finishes the stepper, after stepper validations.
Stepper - Close (Discard): runs once when the user closes the stepper and discards data changes.
Stepper - Close (Saved): runs once when the user closes the stepper and saves the draft.

Events for steps

A user may exit a step using different actions:

By clicking the Continue or Back buttons.
By clicking a step in the header to jump to that step (for a non-linear stepper).
By clicking the Close button to navigate one level up in the stepper.

The event behaviors differ between collection steps and form steps:

Event on steps apply to both collection steps and form steps.
Events specifically designated for collection steps do not apply to form steps.
Events used in form steps run once for the record handled in the form step.
Events used in collection steps have two flavors, indicated with (Each) or (Once):
- (Each): this type of event runs once for each record in the collection step. It gives access to the attributes of these records.
- (Once): this type of event runs once for all records in the collection step. It gives access to the attributes of the parent record of these records. From this parent, you can use the SemQL any or all syntax.

For the detailed sequence of events triggered for each user action, see Stepper events.

The following events occur depending on user actions for form and collection steps:

Step - Enter (Once): runs once when a step is entered.
Step - Enter (Each): runs for each record when a step is entered.
Collection Step - Add Child: runs whenever a child record is added to this collection (directly or through the Add another button of a child step).
Collection Step - Copy Child (Once): runs once when a child record is copied in this collection. The CopiedFrom built-in attribute, which contains the ID of the source record that was copied, can be used in this trigger.
Collection Step - Copy Child (Each): runs for each copied record, when a copy child record action is performed in this collection. The CopiedFrom built-in attribute, which contains the ID of the source record that was copied, can be used in this trigger.
Collection Step - Edit Child (Once): runs once when a child record is edited on this collection (directly or through the Edit next button of a child step).
Collection Step - Edit Child (Each): runs for each record when a child record is edited on this collection (directly or through the Edit next button of a child step).
Collection Step - Import (Once): runs once when a user completes an import.
Collection Step - Import (Each): runs for each imported record, when a user completes an import.
Collection Step - Remove Child (Once): runs once when child records are removed from this collection.
Collection Step - Remove Child (Each): runs for each record when child records are removed from this collection.
Step - Continue (Once): runs once when a user clicks the Continue button.
Step - Continue (Each): runs for each record when a user clicks the Continue button.
Step - Back (Once): runs once when a user clicks the Back button.
Step - Back (Each): runs for each record when a user clicks the Back button.
Step - Close (Once): runs once when a user clicks the Close button on a step (whether to get back to the parent collection or to close the stepper).
Step - Close (Each): runs for each record when a user clicks the Close button on a step (whether to get back to the parent collection or to close the stepper).
Step - Exit (Pre validation - Once): runs once when a user exits a step, before data validation.
Step - Exit (Pre validation - Each): runs for each record when a user exits a step, before data validation.
Step - Exit (Post validation - Once): runs once when a user exits a step, after data validation.
Step - Exit (Post validation - Each): runs for each record when a user exits a step, after data validation.
Collection Step - Close Child (Once): run whenever a child step of this collection is closed.
Collection Step - Close Child (Each): runs whenever a child step of this collection is closed.