Create Rules for Business Objects

Most applications require rules for business objects that are more complex than can be expressed in a simple validation expression on a field. For each custom business object in your application, you can create custom rules that validate objects and fields and that trigger actions.

About Adding Business Rules

You can use the trigger designer and code editors in the Business Rules tab to create business rules for your custom business objects.

On the Business Objects page, you use the Business Rules tab to create and edit business rules for your custom business objects. The rules for the selected business object are grouped under the following tabs in the Business Rules tab:

  • Object Triggers

  • Field Triggers

  • Object Validators

  • Field Validators

  • Object Functions

Each tab displays a list of the existing business rules and contains a button for creating a new rule. For each business rule you can use the Business Rules options menu to copy and delete rules or to open the editor. You can toggle the state of a rule by selecting and deselecting the Active checkbox.
Description of bo-rules.png follows
Description of the illustration bo-rules.png

To add a new rule for a business object, select the object for which you want to add your rule and then open the Business Rules tab. In the Business Rules tab, open the tab for the type of rule that you want to add and click the button to create a new rule, for example, New Field Trigger. When creating a rule, you need to specify a name, and, depending on the type, you might also need to specify other rule properties.

Note:

You can only add business rules for custom business objects.

To define validation rules and object functions, you can use a code editor to write your Groovy scripts. To create triggers, you use the trigger designer, a visual editor for creating sequences that execute actions on your business objects. For additional help on writing Groovy scripts, see the Groovy Scripting Reference.

About Triggers for Business Objects

Triggers are scripts that you can write to complement the default processing logic for custom business objects. A trigger defines behavior that happens in response to a specific business object event, for example, inserting or updating a record, or in response to a field value change.

In the Business Rules tab of a business object, an object trigger refers to the sequence of actions that starts when a specific event occurs.

A field trigger refers to the sequence of actions that starts when a field value changes.

The trigger designer provides a visual representation of your sequence where you can define the conditions that determine the actions that will be executed. For each criterion you can assemble a list of actions composed of functions and Groovy scripts.

About Object Triggers

You can create an object trigger to specify a sequence of actions that starts when a specific event occurs.

A typical event triggering the sequence is adding or updating a record in the business object. When you create a trigger you specify the triggering event and the actions that are then executed. You can refine the sequence so that actions are executed only when some criteria are met. A sequence can define multiple criteria and multiple actions.

To create an object trigger for a business object:

  1. Select the business object to which you want to add an object trigger.

    Triggers can be defined only for custom business objects.

  2. Select the Business Rules tab of the business object.

  3. Click the Object Triggers tab to see a list of all object triggers that are defined for the business object.

  4. Click New Trigger, and in the Create Trigger dialog box, type a name to identify the trigger, and select the Start Event for the sequence. You can modify these later if you want.
    Description of bo-trigger-create.png follows
    Description of the illustration bo-trigger-create.png

  5. Click Create Object Trigger in the dialog box to open the trigger designer.

    You use the designer to build a sequence of criteria and actions that are triggered by the Start Event. No criteria or actions are defined when you first open the designer.
    Description of bo-trigger-designer.png follows
    Description of the illustration bo-trigger-designer.png

  6. Click Create New Criteria (the plus sign) and choose a criteria type.

    Three types of criteria are available in the dialog box. If you select Execute Conditionally, you can define the conditions that must be met to execute actions that you define. If the conditions are not met, the actions are skipped and the sequence advances to the next step.
    Description of bo-trigger-criteria.png follows
    Description of the illustration bo-trigger-criteria.png

  7. If you specify Execute Conditionally, follow the instructions to build conditions for the trigger.

  8. Click the Add Actions box, then specify a Name for the Action Trigger and click Add Actions.

    The Configure Actions page opens when you click Add Actions. You can add one or more actions to the list by dragging predefined functions and custom Groovy scripts into the list.
    Description of bo-trigger-add-actions.png follows
    Description of the illustration bo-trigger-add-actions.png

    If you drag Custom Groovy Code into the list of actions, you’ll need to click Edit Custom Code and type your script in the editor. If you drag Send eMail Notification into the list, you’ll need to specify email details such as the recipients, the sender and the contents of the message.

  9. Click Done when you complete your list of actions.

    You can continue to add more criteria nodes and actions to build up the sequence for the trigger. When you select a criteria node in your sequence you can use the Property Inspector to edit the criteria name, type and conditions. Depending on the criteria type that you select, you might need to specify conditions that need to be satisfied before the corresponding actions are executed. You can use the Conditions Builder to set conditions, or you can use the code editor to write custom code.
    Description of bo-trigger-criteria-done.png follows
    Description of the illustration bo-trigger-criteria-done.png

    You can click Code Editor to view the read-only code that is generated by the designer.
    Description of bo-trigger-code.png follows
    Description of the illustration bo-trigger-code.png

  10. When you are finished designing the trigger, click the Object Triggers tab to return to the Object Triggers page.

About Field Triggers

You can create a field-level trigger to define conditions that apply whenever a specific custom business object field changes in value.

In contrast to an object trigger, which defines conditions that apply when a specific event happens, a field trigger applies conditions when a field value changes.

To create a field-level trigger for a business object:

  1. Select the business object to which you want to add a trigger.

    Triggers can be defined only for custom business objects.

  2. Select the Business Rules tab of the business object.

  3. Click the Field Triggers tab to see a list of all field triggers that are defined for the business object.

  4. Click New Field Trigger, and in the Create Field Trigger dialog box, enter a name to identify the trigger, and select the field name from the Field drop-down list..
    Description of bo-field-trigger-create.png follows
    Description of the illustration bo-field-trigger-create.png

  5. Click Create Field Trigger in the dialog box to open the trigger designer.

    You use the designer to build a sequence of criteria and actions that are triggered by a change in the field value. No criteria or actions are defined when you first open the designer.

  6. Click Create New Criteria (the plus sign) and choose a criteria type.

  7. If you specify Execute Conditionally, follow the instructions to build conditions for the trigger.

  8. Click the Add Actions box, then specify a Name for the Action Trigger and click Add Actions.

    The Configure Actions page opens when you click Add Actions. You can add one or more actions to the list by dragging predefined functions and custom Groovy scripts into the list.

    If you drag Custom Groovy Code into the list of actions, you’ll need to click Edit Custom Code and type your script in the editor. If you drag Send eMail Notification into the list, you’ll need to specify email details such as the recipients, the sender and the contents of the message.

  9. Click Done when you complete your list of actions.

    You can continue to add more criteria nodes and actions to build up the sequence for the trigger. When you select a criteria node in your sequence you can use the Property Inspector to edit the criteria name, type and conditions. Depending on the criteria type that you select, you might need to specify conditions that need to be satisfied before the corresponding actions are executed. You can use the Conditions Builder to set conditions, or you can use the code editor to write custom code.

    You can click Code Editor to view the read-only code that is generated by the designer.

  10. When you are finished designing the trigger, click the Field Triggers tab again to return to the Field Triggers page.

Add an Action to Send Email Notifications

Drag Send eMail Notification into your list of actions when you want to send an email notification that is triggered by a business object event.

If you add Send eMail Notification to your list of actions, you’ll need to specify the email template for the message and the message recipients in the Configure Actions dialog box. You can create your own email template or use an existing one.

To add a Send eMail Notification action to your list of actions:

  1. For new and existing triggers, click Add Actions in the trigger designer to open the Configure Actions dialog box.

    The Send eMail Notification action is available in the list of Suggested actions and under Other Scripting actions.
    Description of bo-trigger-email1.png follows
    Description of the illustration bo-trigger-email1.png

  2. Drag the Send eMail Notification action into the list.

    After adding the action to the list, select the email template that you want to use, and then specify the email Recipients.
    Description of bo-trigger-email2.png follows
    Description of the illustration bo-trigger-email2.png

  3. Select the email template.

    You can select an existing email template from the dropdown list or create a new email template. If you select an existing template, you can click Edit to modify the template.
    Description of bo-trigger-email3.png follows
    Description of the illustration bo-trigger-email3.png

    Depending on the template that you select, you might need to supply additional parameters that are used when generating the email. For example, you might want to specify a reference as a parameter used to generate the email subject or in the body of the message. If a template uses parameters, you’ll need to define the values of the parameters, or you can edit the template to remove the parameters that you do not want to use. Parameter values can be a static value, a Groovy expression or a reference to a field in the business object. In the following example, you could replace Parameter1 and Parameter2 with field names from your business object.
    Description of bo-trigger-email4.png follows
    Description of the illustration bo-trigger-email4.png

  4. Define values for the Recipients.

    You can use static values for the Recipients, or the values can be generated with a Groovy expression or reference to a field in the business object. You can use the drop-down list next to the Recipients field to select the type of value in the field.
    Description of bo-trigger-email5.png follows
    Description of the illustration bo-trigger-email5.png

Convert a Trigger to Editable Code

To edit the entire trigger script in a code editor instead of using the visual trigger designer, you need to convert the script generated by the trigger designer.

When you create a trigger script in the visual trigger designer, you build up the sequence by creating groups of actions that are performed when criteria are met. The trigger designer provides tools to help you build the sequence, and you can use custom code to define criteria and actions individually, but you cannot edit the entire trigger script. If you want to freely edit the entire script in a code editor, you need to convert to code the script generated by the trigger designer.

Note:

You will not be able to edit the trigger script in the visual trigger designer after it is converted to code. After a script is converted, it cannot be converted back to script that can be edited in the visual designer.

You can view the entire script generated by the trigger designer by clicking Code Editor in the designer. The script displayed in the code editor is read-only. To edit the script in a code editor, click Convert to Custom Code Trigger.
Description of bo-trigger-code-convert.png follows
Description of the illustration bo-trigger-code-convert.png

Build Conditions for Triggers

If you select Execute Conditionally as the criteria type for a trigger, the Conditions Builder can help you specify the conditions that need to be satisfied before the actions are executed.

When you set a criterion to execute conditionally, you use the Conditions Builder to define the set of conditions that determine when actions will be executed. You open the Conditions Builder by selecting the criterion in the designer and clicking Add Conditions in the Property Inspector.
Description of bo-trigger-condition-build.png follows
Description of the illustration bo-trigger-condition-build.png

To set up conditions in the Conditions Builder, you must select a field, select an operator, and set a value. The Condition Builder provides menus for selecting the fields in the business object, selecting operators, and helping you specify values. When specifying values, you can choose to use a static value, a field reference or an expression. You can create complex conditions by adding multiple conditions and grouping conditions together.
Description of bo-trigger-condition-add.png follows
Description of the illustration bo-trigger-condition-add.png

About Object Validators for Business Objects

An object-level validation rule is a constraint you can define on any custom object. The rule is used to evaluate the object when attempting to submit an object.

An object-level rule is appropriate when validation requires using two or more fields. Validation using an object-level rule ensures that regardless of the order in which the user assigns the values, the rule will be consistently enforced.

The expression or script that defines the rule must return a boolean value that indicates whether the object is valid. The object is saved if all the rules validating the object return true. If any of the rules return false, the error message of the failed rule is displayed and the object is not saved. If the rule returns true, then the object validation will succeed so long as all other object-level rules on the same object return true. For example, this type of validation would be needed when specifying a value for one field in a form requires that a value is also assigned to another field (for example, selecting ‘High’ in a Priority field requires a name is entered in the Assignee field).

To create a validation rule for a business object:

  1. Select the business object for which you want to create the rule.

  2. Select the Business Rules tab of the business object.

  3. Click the Object Validators tab.
    Description of bo-object-validators.png follows
    Description of the illustration bo-object-validators.png

    You see a list of all object validators that are defined for the business object.

  4. Click + New Object Validator and enter a validator name to identify the rule, and then enter the error message to be displayed if validation fails. You can modify these later if you want.

  5. Click Create Object Validator in the dialog box to open the editor.

  6. Create your rule by typing in the editor and by using the business object fields and functions in the palettes. Use the palettes to help you add fields and functions that you might use to create your rule.

    Click the arrow next to the function or field in the palette to insert it at your insert cursor in the editor. When you select a function in the palette, a description of the function and an example of how to use it are displayed in the palette. Any object functions that you created for the business object will be listed in the Functions palette.

  7. Click the Object Validators tab again to apply your rule to the object and exit the editor.

About Field Validators for Business Objects

A field-level validation rule is a constraint you can define on any custom field. The rule is used to evaluate the value of the corresponding field each time a new value is submitted.

A field-level rule is appropriate when the rule that is to be enforced depends only on the new value being set. At runtime your field validation rule is executed before the field’s value is saved.

The expression or script that defines the rule must return a boolean value. The value is saved if all the rules validating the field return true. If any of the rules returns false, the error message of the failed rule is displayed and the new value is not saved. For example, when a form has several fields, the values for all the fields must pass all the validation rules before any new values are saved.

To create a field validation rule for a business object:

  1. Select the business object for which you want to add the new rule.

  2. Select the Business Rules tab of the business object.

  3. Click the Field Validators tab.

    You see a list of all field validators that are defined for the business object.
    Description of bo-field-validators.png follows
    Description of the illustration bo-field-validators.png

  4. Click New Field Validator and type a name to identify the rule, the field that the rule will validate and the error message that is displayed if validation fails. You can modify these later if you want.

  5. Click Create Field Validator in the dialog box to open the editor.

  6. Create your rule by typing in the editor and by using the values and functions in the palettes. Use the palettes to help you add field values and functions that you might use to create your rule.

    Click the arrow next to the function or value in the palette to insert it at your insert cursor in the editor. When you select a function in the palette a description of the function and example of how to use it are displayed in the palette. Any object functions that you created for the business object will be listed in the Functions palette.
    Description of bo-field-validator-edit.png follows
    Description of the illustration bo-field-validator-edit.png

    The Field Values palette contains the variables newValue and oldValue. Your script can use newValue to reference the new value that will be assigned if validation passes. To reference the existing field value, use oldValue.

  7. Click the Field Validators tab again to apply your rule to the field and exit the editor.

About Object Functions for Business Objects

An object function is useful for encapsulating business logic for a specific business object. After you define an object function, you can call the function by name from other scripts related to the business object.

When you create an object function on an object named Department, the following are true by default:

  • Other scripts on the same object can call it.

  • Any script written on another object that obtains a row of type Department can call it.

You can alter some of the default behavior by changing some of the properties in the Property Inspector. If the Callable by External Systems property is enabled, an external system working with a Department object will be able to invoke your object function. Enable this when the business logic it contains should be accessible to external systems. If instead you do not enable this property, then the object function can only be called by some other script on the Department object. Enable the Privileged property to indicate that the object function should run with the data security visibility of a privileged user. This can be necessary to enable the business logic to see rows of business object data when the current user might not have the right to access the data. If the Privileged property is not enabled, the script can only query rows that the current user has the right to access.

To create an object function rule for a business object:

  1. Select the business object for which you want to create the rule.

  2. Select the Business Rules tab of the business object.

  3. Click the Object Functions tab.

    You see a list of all object functions that are defined for the business object.

  4. Click New Object Function and type a name to identify the object function. You can modify this later if you want.

  5. Click Create Object Function in the dialog box to open the editor.

  6. Open the Property Inspector for the rule if not already open and select the Function Return Type from the drop-down list.

  7. In the Property Inspector, click Parameters and specify the parameters for your function. Click All Properties to return to the Property Inspector.
    Description of bo-object-function.png follows
    Description of the illustration bo-object-function.png

  8. Create your function by typing in the editor and by using the Business Object and Functions palettes. Use the palettes to help you add fields and functions that you might use to create your function.

    Click the arrow next to the function or value in the palette to insert it at your insert cursor in the editor. When you select a function in the palette, a description of the function and example of how to use it are displayed in the palette.

  9. Click the Object Functions tab again to add your function and exit the editor.

Log Scripting Events

When you are developing the rules for a business object, you may want to enable logging and use the log viewer to help you see exactly which events are triggered.

For example, you might have a Before Update trigger script that calls several object functions. In the Code Editor for object functions, you can add a println to your object functions to print a message to the log each time the function is called. If you are using the Configure Actions window to create and edit triggers, you can drag the Log Message action in the Other Scripting category into your action group to add a println to the action chain. By looking at the log, you can see the functions that were triggered based on the messages, as well as any exceptions in your script that are written to the log.

In addition to custom messages that you add to your code to log actions, the following actions are always recorded in the logs:

  • Trigger starts

  • Trigger ends

The viewer in the Logs window displays the most recent 250 log entries. The menu in the Logs window contains the following tools for working with the log entries.

Menu Item Description
Filter field Type text in the filter field to filter out messages that do not contain the text.
Enable Logging Deselect this check box to stop logging actions.
Refresh Click to ensure that the most recent log entries are displayed in the log viewer.
Export Click to export your log as a text file to download to your local system.
Clear Click to clear all the entries that are displayed in the viewer.

Enable Logging of Scripting Events

You can enable logging to record the events triggered by your custom business rules.

By default, logging is not enabled. To enable logging:

  1. Click the Logs link at the bottom of the window to open the Logs page.
  2. Select the Enable Logging check box.

After you enable logging, it remains enabled in your session for as long as you are logged in. If your session has expired, after you log in you will need to re-enable logging.