The Form Lifecycle: Control and Action Processing

As described in The Form Helper Library, iCM forms carry out some actions browser-side, some server-side, and some in both.

As each page of your form is requested, loaded, interacted with and submitted, the following cycle takes place.

The cycle starts at the top, with a browser making a request to your site for a form. The form is then rendered in the first blue block, and appears to the user at the beginning of the first green block.

Form Action Processing

The action fields you add to a form are, by default, processed when the page of the form they are on is submitted and successfully validated. This means that actions will be executed between pages and on the final page of a form.

As a general rule, actions are processed in the order they have been added to the page. However, as explained below, the processing order also depends on the category of action, and whether or not an action field has an action execution skeleton property of its own.

Action Categories

Action fields fall into two main categories. It's important to understand which category your form actions fall into if you want the result of one action to influence the behaviour of a subsequent action.

The first category, field level actions, have action execution skeletons of their own. They are executed first, in the order they have been added to the form. All of these actions will be processed before those in the second category.

The second category, form service actions, are actions that are passed back to the forms service to be executed. They are executed in the order they have been added to the form.

The third category is processed by the website frameworks. It is rarely used and will be documented alongside those field types where necessary.

The field level actions are:

• Basic Script Action
• Workflow Complete, Message and Start Actions
• User Create, Create Login, Set Password, Update Groups and Update Login Actions

The form service actions are:

• Confirmation
• Database Save
• Data Integration (the Talend job upload)
• Email
• History Write/Reporting
• Redirect (and Redirect via Post)
• XML over HTTP

Example Processing Orders

These example show common combinations of actions and the order they will be executed in.

Example 1

Execution order:

1. Script Action 1
2. Script Action 2
3. Email Action

Example 2

Execution order:

1. Script Action 1
2. Script Action 2
3. Email Action

The email action is processed by the forms service, so even though it appears first on the page, the two script actions are processed first because they are field level actions.

Example 3

Execution order:

1. Script Action 1
2. Start Workflow Action
3. Script Action 2
4. Email Action
5. Database Save Action

In this example the script and workflow actions are processed first, as page level actions, in the order they appear on the page. Once complete the email and database save actions are processed by the forms service.

Errors During Action Processing

All of the field level action fields have a property to "Stop Processing on Error". If this is true (the default) and the action generates an error, all subsequent action processing is stopped. If set as false the error will be traced, but will otherwise be ignored - subsequent actions will still be processed.

If a field level action errors and stops processing, all of the remaining field actions, and all form service actions, won't be processed.

Consider these actions:

The third field, the script action, generates an error and stops processing. That results in the workflow starting (because it appears before the script action) and all other actions being cancelled. The database save action is not processed because, even though it is placed first, it is a form service action so would be processed after the workflow and script actions.

If an error occurs during the processing of a form service action no further form service actions (those placed after it on the form) are processed - the field level actions will have already been processed.

Action Results

When an action completes (whether successful or not) information is passed back to the form in the ACTIONRESULT_ context variable.

Results can be accessed using the helper.utilGetActionResults helper function. See the various form action field pages for examples.

When processing stops as the result of an error the form session ends.

Payment Fields - Interrupting Actions

Payment fields interrupt normal action processing. When a page with a payment field is submitted, the user is redirected to the payment provider, performs some actions on that site, and is then redirected back to your site.

Actions before and after a payment field, as placed on the page, are processed as blocks. That means that field and form service actions may be processed, then the redirect occurs, then the remaining field and forms service actions are processed. Depending on the response from the payment provider, you may want your form and the remaining actions to behave differently.

As a general rule we recommend placing payment fields as one of the first actions on a form. There's a more detailed discussion about using payment fields and handling responses in Using the Form Payment Fields.

Payment Field Example

Execution order:

1. Script Action 1
2. Email Action 1
3. Payment Action
4. Script Action 2
5. Database Save Action

The two actions before the payment field are executed as a block, obeying the process ordering rules described above. The payment redirect action is processed and the user returned to the form. The remaining script and database save actions are processed.

The Control Phase

The control phase determines which page of the form will be displayed next. Almost all of the behaviour relating to the control skeletons is encapsulated within the form family, particularly the wizard field type.

All buttons that can trigger a submission have a "name" property in the generated HTML that includes one of a fixed set of values. Unlike other fields, the actual name of the field you enter in the forms designer is not used. The format of the button names is:

<FORMNAME>_FORMACTION_<ACTION>

For example, on a form called "My Form", a "next" button would be called MYFORM_FORMACTION_NEXT

The full set of submission actions and their names are: