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 Using System Error Details

The sections below illustrate three methods for configuring custom error rules. When you configure custom rules to deal with errors, the order in which error handlers are applied is smallest to largest (rule > view > form > SmartForms). See the Considerations for more information and other considerations.

Use one of the following events in a rule and select in Error.

Events
When the Form raises an event
When the View executes a method

Under the line containing in Error, add conditions and actions to the rule to respond to an error on a view or a form. A common action is showing a message to the user. Configure the message by using system values from the Context Browser along with any additional details you may want to add.

Follow the steps below to configure the rule shown above.

  1. Go to Rules and click Add Rule.
  2. In the Events tab, select When the View executes a method in the View Events section, and then click the link. In the list of available methods, select in Error. To set up the same event on a form, select the When the Form raises an event in the Form Events section and then select the in Error method.
  3. Select the Actions tab and then select Show a message in the Notifications section. Click configure to configure the message.
  4. 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.
  5. This rule shows a message when an error occurs on the view. Click OK to save the rule.

Use the if an error occurred condition to stop the execution of a rule when 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.

  1. Go to Rules, select the default When Create Button is Clicked rule and click Edit Rule.
  2. In the Conditions tab, select Error occurred in the Error Handling section.
  3. Select the Actions tab, select Show a message in the Notifications section and then click configure.
  4. 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.
  5. 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 to the user and the rule stops executing.
  6. Add the workflow start rule as a separate statement if errors do not occur. To do this, go to the Workflow Interaction section and select Start a Workflow, then click the dotted line below select Workflow to select the workflow you want to start. The Select a Workflow dialog opens.
  7. In the Select a Workflow dialog, select a workflow and click OK.
  8. Click the dotted line as shown below 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.
  9. Once you configure your workflow, hover over the rule action and click the icon as shown below to move the statement down and create a new execution block.
  10. The workflow action is now separate and executes if errors do not occur when the Create button is clicked.

Use one of the actions below and select in Error.

Actions
Execute a method on the View
Execute a Form method

Use this if you want to raise a custom error that is not the result of an error with the rule, view, or form. Add conditions and actions to the rule to create your business logic. For example, you can raise an error when a condition is false or when a value does not fall within a range of values. You configure the rule to show a message about the error and how to fix it.

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 to show an error message. Follow the steps below to configure the rule.

  1. Go to Rules, select the default When Save Button is Clicked rule and click Edit Rule.
  2. In the Conditions tab, select an advanced condition is true in the Custom Conditions section.
  3. 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 the an advanced condition link as shown in the second image below to configure the condition.

  4. 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.
  5. 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.
  6. Select Else in the Logical Conditions section.
  7. Click to the right of the else statement to highlight the line, select the Actions tab, and select Execute a method on the View in the SmartObject Interaction section. Choose in Error for the method to execute and click configure to configure the method.
  8. Type text for the error message, detail, and type to display when the error is shown. Click Finish.
  9. 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.
  • When you create a custom error rule, use conditions to check the validity of the error. If the error context is not what you expect to see in runtime, you may not be showing helpful information when an error occurs.
  • When an error happens in a view that is contained in a form, the SmartForms error handler uses the view’s error handling first and, if nothing is found in the view, it then moves to the form's error handling. If no error handling is specified, general SmartForms error handling applies.
  • A smallest to largest order is used when handling errors. Where the error happens is where the order starts. For example, if an error happens in a rule, the order is:
    1. Use the error handler in the rule
    2. If not found, use the error handler in the view
    3. If not found, use the error handler in the form
    4. If not found, use the standard SmartForms error handler