Configure a Custom Error Rule

You can use error events, conditions, and actions on a view or form to create custom error rules, such as raise an error when a condition is false. Using custom error rules allow you to create your own business logic and raise an error that is not the result of a standard SmartForms error. Or you can customize a standard error by combining system details with custom text. This topic explains the different methods you can use to create and configure custom error rules.
Custom error message dialog to show system error details

When using anonymous views and forms with Error context fields, these fields contain a generic message with a CorrelationID for added security. For more information see Change in behavior for error handling of anonymous views and forms

Try it yourself!

Configuring the rule

The sections below illustrate three ways to use errors when configuring rules:

Using Events to respond to errors, for example if you want to show a custom message instead of the underlying system error
Using Conditions to check for errors, for example if you want to stop executing actions in a rule if an error occurs
Using Actions to raise an error, for example if you want to raise your own error if a certain condition is met

Error Events

To respond to an error, use the raises an event event, and select in Error as the event to listen for.

Form-level event handling

Under the line containing in Error, add conditions and actions to the rule to respond to an error on a form. For example, you may want to 'intercept' a system error and show a friendlier error message, perhaps including system values from the Context Browser along with additional details you may want to show.

Follow the steps below to configure the rule shown above.

Go to the Rules tab on your form and click Add Rule.
In the Events tab, click When the Form raises an event and then select in Error.
From the Actions tab, select Transfer data. No configuration of the action is required.
The purpose of the empty Transfer data action is to provide a pause when the rule executes, because of a known issue where the in Error event on form level would not execute properly at runtime.
From the Conditions tab, select an advanced condition is true. Click an advanced condition to configure the condition. In this example, you want to check if a system error value contains a specific error number and then show a custom message.
On the Rule Designer page, click Add, then expand the System Values > Error and drag and drop the Error Message value from the Context Browser to the LEFT option.
Select the Contains operator in the OPERATOR field and enter the required error number in the RIGHT field. Click OK.
From the Actions tab, select Show a message. Click configure.
Select Confirmation from the Message Type drop-down and type Workflow Completed in the Title field. Type Workflow is already assigned or completed in the Body and click OK.
This rule shows a different message when an error occurs on the form and the error number is located within the original error message. Click OK to save the rule.

View-level event handling

If you want to listen for error events on a view, select the When the view executed in Error event and configure the rule as required. A common scenario is showing a friendly message to the user. You can configure the message by using system values from the Context Browser along with additional details you may want to add.

Follow the steps below to configure the rule shown above.

Go to the Rules tab on your view and click Add Rule.
In the Events tab, click When the View executes a method and then select in Error.
In the Actions tab, click Show a message and click configure to configure the message.
Select Error from the Message Type drop-down and type An error occurred in the Title field. To use system error values in your message, expand the System Values node in the Context Browser. Then expand the Error node and drag the details you want to use into the Body of the message. You can also combine the system details with custom text as shown below. When you're done configuring the message, click OK.
This rule shows a message when an error occurs on the view. Click OK to save the rule.

Error Condition

Use the if an error occurred condition to conditionally manage the execution of a rule if an error occurs. You can also use the Stop rule execution and Continue to next execution rule actions to determine whether execution of the rule should continue. When you use the if an error occurred condition, the rule stops automatically when there is an error, but it is a good idea to add the Stop rule execution action for discoverability and maintenance. The images below are examples of how you can use the if an error occurred condition with the Stop rule execution and Continue to next execution rule actions. In the first image, rule execution is stopped when the error occurs and the New Customer workflow is not started. In the second image, rule execution is stopped automatically when the error occurs, but then continued so that the Create button is hidden.

Follow the steps below to configure the rule using the Stop rule execution rule action.

Go to the Rules tab, select the default When Create Button is Clicked rule and click Edit Rule.
In the Conditions tab, click Error occurred.
In the Actions tab, click Show a message and then click configure.
Select Error from the Message Type drop-down and type An error occurred in the Title field. To use system error values in your message, expand the System Values node in the Context Browser. Expand the Error node and drag the details you want to use into the Body of the message. You can also combine the system details with custom text as shown below. Click OK.
Go to the Rule Interaction section and select Stop rule execution. The if an error occurred condition causes the rule to stop if an error occurs, but it is a good idea to add this action to your rule so that other people can understand the rule. Rule execution happens in the following order: When the Create button is clicked, the Create method executes and, if an error occurs, a message is shown and the rule stops executing.
Add the workflow start rule as a separate statement if errors do not occur. Click Start a Workflow, then select the workflow you want to start if there are no errors.
Click configure to configure the workflow. For information on how to configure starting a workflow with a rule action, see Manually Integrating Forms with Workflows Using Rule Actions.
Once the workflow configuration is done, hover over the rule action and click the icon as shown below to move the statement down and create a new execution block.
The workflow action is now separate and executes if errors do not occur when the Create button is clicked.

Error Actions

You may want to raise your own error as part of a rule. To do so, use one of the actions below and select in Error.

Execute a method on the View
Execute a Form method

Use this approach if you want to raise a custom error that is not the result of an error with the rule, view, or form. For example, you can raise an error when a condition is false or when a value does not fall within a range of values. Subsequent rules can then handle the error event raised by the view or form.

In the example below, you configure a condition to check if two text boxes are populated when the Save button is clicked. If true, the Save method of the view is executed. If the condition is false, you execute the in Error method. Follow the steps below to configure the rule.

Go to the Rules tab, select the default When Save Button is Clicked rule and click Edit Rule.
In the Conditions tab, click an advanced condition is true.
Hover over the condition and click the icon as shown below to move the statement up one position. You want to execute the Save method if the condition evaluates to true. Click an advanced condition to configure the condition.
In the Rule Designer click Add, expand the view in the Context Browser, expand the Controls, and drag the text box you want to use in the condition to the Left field. Select Is Not Empty from the Operator drop-down.
Click Add again and add another condition for the second text box you want to evaluate. Use the Preview section to verify your logic. This expression evaluates to true if both text boxes are not empty. Click OK.
Click Else in the Logical Conditions section.
Click to the right of the else statement to highlight the line, click the Actions tab, and click Execute a method on the View. Select in Error and click configure to configure the method.
Type text for the error message, detail, and type to display when the error is shown. Click Finish.
The rule checks if both text boxes have values and if they do, executes the Save method. If either or both of the text boxes do not have values, your error is shown. Click OK to save the rule.