Create Rules for Business Objects

Most applications require rules for business objects to execute business logic that deals with the data. For each business object in your application, you can create business rules that validate objects and fields and that trigger actions based on events or field changes.

To define business rules for each business object, you can create:
  • Object and Field triggers that let you react to data events (for example, when a record is inserted, updated, or deleted). You can use the trigger designer to visually define the conditions and actions that will be executed in those events, or write custom Groovy scripts that define more complex logic.
  • Object and field validators that make sure data at the field or record level is correct.
  • Object functions that encapsulate logic relating to a business object.

Business rules always run on the server and work the same way no matter how a business object is updated (whether through REST API calls or Groovy scripts).

About Adding Business Rules

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

On the Business Objects page, you use the Business Rules tab to create and edit business rules for your 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 check box.
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.

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.

Access the Current User's Details in Your Groovy Script

The recommended way to access the current username in your Groovy script is adf.context.getSecurityContext().getUserName(). The only method in the UserProfile object that returns a non-null result is getUserName(), which is the same value as what is returned from the API above. There is no reason to use UserProfile when using Groovy in Visual Builder. For more details, see Referencing Information About the Current User in the Groovy Scripting Reference.

Triggers for Business Objects

Triggers are scripts that you can write to complement the default processing logic for 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.

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 a sequence is adding or updating a record in the business object. When you create a trigger, you specify the trigger event and the actions that are then executed. You can refine the sequence so that actions are executed only when some criteria is 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.
  2. Select the object's Business Rules tab.
  3. Click the Object Triggers tab to see a list of all object triggers that are defined for the business object.
  4. Click + New Object Trigger, and in the Create Object Trigger dialog box, enter a name to identify the trigger, and select a 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 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 + 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 Group 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 (such as create a record or perform a process task action) 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 Properties pane 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

    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

    When you define Groovy code for object triggers, you have the option of overriding the default Groovy timeout specified in the Timeout Override field.

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

Field Triggers

You can create a field-level trigger to define conditions that apply whenever a specific 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.
  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 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 + 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 Group 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 Properties pane 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.

    Click Code Editor to view the read-only code that is generated by the designer.

    When you define Groovy code for field triggers, you have the option of overriding the default Groovy timeout specified in the Timeout Override field.

  10. When you are finished designing the trigger, click the Field Triggers tab 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. Note that the sender's email address is always nobody@oracle.com and cannot be changed.
    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 drop-down 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 Properties pane.
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

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 optionally override the default Groovy timeout specified in the Timeout Override field.

    It's possible to modify all of 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.

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.

    You can optionally override the default Groovy timeout specified in the Timeout Override field.

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

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.

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 object's Business Rules tab.

  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 enter 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. In the Properties pane, click Parameters and add parameters for your function.
    Description of bo-object-function.png follows
    Description of the illustration bo-object-function.png

    When you are done, click All Properties.

  7. 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.

    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 this default behavior by changing some of the properties in the Properties pane.
    • 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 you do not enable this property, then the object function can only be called by some other script on the Department object.

      If you call an object function via REST API from an external system, you'll need to set the value of the Content-Type header to application/vnd.oracle.adf.action+json. Note that this Content-type value is not the same as the value used for actions on a business object, for example, a POST action (application/vnd.oracle.adf.resourceitem+json).

      When the Callable by External Systems property is enabled, you can optionally override the default Groovy timeout specified in the Timeout Override field.

    • 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.

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

Log Diagnostic Messages From Your Scripts

When you're developing rules for a business object, you can add a print or println function to custom Groovy code when you want messages logged by your own script to be written to the diagnostic log.

For example, you might have a Before Update trigger script that calls several object functions. You can add the print or println function to your object functions to print a message to the log each time the function is called.

  • If you're using the code editor, you can add a print or println statement. The former writes its value without any newline character, while the latter writes its value along with a newline. For example:
    // Write a diagnostic message to the log
    println("[In: BeforeUpdate] Status = ${Status}")
  • 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.

You can now enable logging to see the functions that were triggered based on the messages, as well as any runtime exceptions. Note that you don't need to do anything special to log trigger starts and trigger ends; these actions are always recorded in the logs.