6Object Workflows

This chapter contains the following:

Overview

Automate business processes using object workflows in Application Composer. A business process typically has some kind of action that you want to occur in an application, based on something happening elsewhere in the application. When you create an object workflow, you indicate which business object you're impacting, such as Opportunity. You also indicate the actions that you want to happen in the application, plus the conditions that trigger these actions. Conditions are events. Once those events occur, your configured actions are immediately implemented unless you have defined a time rule (execution schedule) for one or more actions.

This chapter covers:

  • The concepts and terminology used in object workflows.

  • How you set trigger conditions for object workflows using groovy scripts.

  • Configuring event actions such as tasks, e-mail notifications, field updates, business process flows, and outbound messages using object workflows.

  • Creating an approval flow using business process composer and then triggering the approval flow through object workflows.

This topic describes what object workflows are and explains the terminology related to object workflows.

You create object workflows to automate business processes. You create an object workflow with a set of actions, and set a condition to trigger these actions. This trigger is based on events. When the event occurs, all of your configured actions are run immediately unless you have set a time rule for one or more actions.

This figure illustrates how you configure and trigger object workflows.

Configuring and triggering object workflows

Commonly Used Terms

Familiarize yourself with the following terms before you start working with object workflows:

  • Business Object: A business object can be either a standard object delivered with your cloud service or an object that you create based on your business need.

    The business object that you use for configuring the object workflow can be either a parent object or a child object. All attributes available to you for selection when configuring a workflow belong to the object that you select for creating a workflow. This enforces that only the data relevant to the object in context is available for selection. For example, when you define a trigger condition, an expression editor lists only those fields that are relevant to the object that you have selected

  • Active: Indicates whether the workflow is in use. Only those object workflows which are in Active status can trigger event actions.

  • Event Point: An event point is associated with an object and is an instance when an event occurs. Event points are of the following types:

    • When a record is created.

    • When a record is updated.

  • Event Condition: Event point and event condition together serve as a trigger for object workflows. Event condition is an expression that supports logical, math operations, or field-value lookups. By defining an expression, you can prevent the object workflow to trigger each time a record is created or updated. See Expression Builder in this topic for an overview of how expressions are defined.

  • Event Action: An event action determines what action is expected from an object workflow when the conditions set for an object are met.

    Event actions are of the following types:

    • Field Updates.

      Use this action to specify the new values that you want to apply to the existing fields. For example, create a workflow that changes the Priority from Medium to High when the win probability exceeds 60 percent. For more information on field updates, see Object Workflows and Field Updates: How They Work Together.

    • E-Mail Notification.

      Use this action to send automatic e-mail alerts. For example, create a workflow that alerts the sales team that the budget availability date has changed. For more information on e-mail notifications, see Object Workflows and E-Mail Notification: How They Work Together.

    • Task Creation.

      Use this action to create and assign tasks. For example, assign a follow-up task to the owner of an opportunity when the status is still open. For more information on task creation, see Object Workflows and Task Creation: How They Work Together.

    • Outbound Message.

      Use this action to send outbound message to a Web service at a specified endpoint URL. For example, send account details from one system to another. For more information on outbound message, see Object Workflows and Outbound Message: How They Work Together.

    • Business Process Flow.

      Use this action to trigger approval flows. For example, when the Deal Amount exceeds a threshold level, the relevant sales manager receives an approval notification. For more information on business process flow, see Object Workflows and Business Processes: How They Work Together.

    • Groovy Action

      Use this action to trigger a Groovy action from your object workflow. For example, you might trigger a Groovy action to perform cross-object updates, perform post-processing of large object hierarchies, or asynchronously initiate Web services. For more information on Groovy actions, see Groovy Scripts and Object Workflows: How They Work Together.

Here's how you access the page that you use for configuring object workflows. You must be in an active sandbox to configure an object workflow.

  1. Navigate to Application Composer.

  2. On the Overview page of Application Composer, click Object Workflows.

  3. Select Actions > Create.

    The Create Object Workflow page opens. Use this page to start configuring your object workflow.

This figure shows the Create Object Workflow page.

Create Object Workflow page

Execution Schedule

While defining an event action, you can optionally set an execution schedule that governs when an event action should happen. Else, the event actions are run immediately. When multiple event actions are configured, the Field Updates happen first before any other event action is triggered. For event actions other than Field Updates, there is no particular sequence and the event actions are triggered based on whether or how you configure the execution schedule.

You can set a time rule for an event action based on whether that event action must occur after or before the triggering of a workflow or the occurrence of a date, and also specify the time duration in Hours, Days, or Weeks. If you schedule an event action for a time in the past, the event action is executed immediately after it is triggered.

This figure illustrates the execution schedule region.

Execution Schedule

Application Composer

To create object workflows, you use a tool called Application Composer, which is a browser-based tool that enables you to modify and extend your applications. Using Application Composer you can make the changes and see most of those changes take immediate effect in real time.

Note that all action types except E-mail Notifications are sandbox-aware, so any changes you make in Application Composer (such as creating your own fields, objects, triggers, and so on) inside a sandbox are immediately taken into consideration when an object workflow is executed. The exception is that fields you create that are used as tokens in e-mail templates must be published before they can be used.

For more information on how you modify and extend your applications using Application Composer, see Extending Your Applications: How It Works.

Expression Builder

Use the expression builder to write Groovy-based application logic that determines when an object workflow is triggered.

An expression builder supports building logical and math operations, including field lookups that you can optionally use to define trigger conditions. Fields in the expression builder are populated based on the object for which you are defining the workflow. The expression builder displays a warning if your expression contains an invalid attribute name; however, you must confirm whether the attribute name is actually invalid. If an attribute exists which was created at runtime, then you can safely ignore the warning.

This figure illustrates the expression builder, which you can use to define Groovy conditions for object workflows.

Expression builder
Note: Object workflows are not triggered when records are created through file-based import. File-based import bypasses any Groovy validation and trigger logic on an object.

Some examples of the raise conditions you can use include the following:

Example 1:

Status=='IN_PROGRESS' && BudgetAvailableDate==Today() + 30

Example 2:

if (isAttributeChanged('PrimaryContactPartyName') && 
PrimaryContactPartyName =='Business World')  return true;  else  return false; 

Example 3:

WinProb>10 || WinProb<50 

Consider the following when using the expression builder to create conditions:

  • Ensure that you return a valid Boolean as part of your raise condition. Returning a non-boolean value could lead to runtime errors.

  • Use return true or return false to explicitly return the Boolean value and code indentation when the evaluation logic is complex, to minimize risk of runtime errors.

  • For lookup values, use the lookup code instead of the display value.

  • Use <, >, == for comparison.

  • For the event point When a record is updated, avoid redundant calls of the actions by always specifying which field change should trigger the object workflow, using the function isAttributeChanged().

  • Be aware of Groovy-type coercion, if you are not returning an explicit Boolean value.

  • Use the logging capability to debug your condition and review the generated log by selecting Runtime Messages in the Common Setup pane.

For more information on Groovy scripting, see the Groovy Scripting Reference guide.

Illustrated here are a few business scenarios where you employ object workflows to automate business processes.

Scenario

In a sales division, the management plans to set an automated business process where an opportunity must have an initial close date set automatically to 90 days from its date of creation. Being an administrator, you must create an object workflow based on management directions.

This figure illustrates the triggering of the event action for the business scenario.

Object Workflow Example with One Event Action

To create field updates event action:

  1. From the Application Composer main page, select Object Workflows.

  2. Click Create.

  3. Select the Opportunity object and provide a meaningful Name and Description.

  4. Define the trigger condition using When a record is created event point. Use the expression builder to set the event condition as Close Date is Null.

  5. Under Actions, select Field Updates event action.

    This opens the Create Action: Field Updates page where you configure the event action.

    Configuring Field Updates Event Action
  6. Provide the Name and Description for the field updates action and optionally set the Execution Schedule.

  7. Under Field Update Details, select Close Date and set its value to Creation Date plus 90 days.

  8. Save the event action.

When a user creates an opportunity, the workflow is triggered which sets the close date to 90 days from the date of creation.

Scenario

In a sales division, the management plans to set a business process that when an opportunity is updated whose close date is current or past and the status is open, an e-mail notification is automatically sent to specified recipients and the close date is extended by 15 days. Being an administrator, you must create an object workflow based on management directions.

This figure illustrates how you configure multiple event-actions for the business scenario.

Object Workflow Example With Two Event Actions

In this example, you must create a workflow with two event actions, namely, Field Updates and E-Mail Notifications.

  1. From the Application Composer main page, select Object Workflows.

  2. Click Create.

  3. Select the Opportunity object and provide a meaningful Name and Description.

  4. Specify the event point as When a record is updated. Use the expression builder to set an event condition as Close Dateis less than or equal to Current Date and Status is Open.

You are now creating Field Updates event action.

  1. On the Create Object Workflow page, select Field Updates event action.

    This opens the Create Action: Field Updates page.

  2. Provide the Name and Description for the field updates action and optionally set the Execution Schedule for triggering the action.

  3. Under the Field Update Details, select Close Date and set its value to Current Date plus 15 days.

  4. Save the event action.

You are now creating the E-Mail Notification event action.

  1. On the Create Object Workflow page, select E-Mail Notification event action.

    This opens the Create Action: E-Mail Notification page.

    Configuring E-Mail Notification Event Action
  2. Provide the Name and Description for the e-mail notification action and optionally set the Execution Schedule for triggering such notifications.

  3. Search and select an existing E-Mail Template or create one with a related e-mail subject and body.

    When you create a template, you specify action-related text and field tokens that are populated at run time. See: E-Mail Templates: Explained topic.

  4. Locate and specify Specific users under Recipient Types. See: recipient types in E-Mail Templates: Explained topic.

  5. Click Save.

When a user updates an opportunity record which satisfies the trigger condition, an e-mail is sent to the specified recipients and the Close Date is extended by 15 days.

This topic covers how you use object workflows to perform field updates. These updates happen automatically when the associated object workflow is triggered.

A field update is an event action that you configure when creating an object workflow. When you configure more than one event action apart from configuring field updates, field updates always run first, and then other event actions are run in no specific order.

Note: The field update invoked from Object Workflow is a background update by a Web service. If this update is performed while a record is open and you are making other updates, you get an error stating that the record has already been modified. If this happens, exit the record, reopen it, and reenter your updates. If you don't want to do this, you can alternatively use an object level trigger or field trigger on the record.

Here's a summary of how you configure field updates as part of object workflows:

  1. From the Application Composer overview page, select Object Workflows.

  2. Select Actions > Create.

  3. Select an Object and provide a meaningful Name for the workflow.

  4. Define the trigger condition, and select Field Updates event action.

  5. On the Create Action: Field Updates page, provide a Name for the field updates action.

  6. Specify the fields you want to update and the value to which you want to set those fields when the workflow is triggered. Use Update More Fields option to select additional fields to update. See Configuring Object Workflows: Example topic for an example on how you configure field updates.

Note: If you have a record open and a workflow is triggered on a field in that record, you must exit from the record and reopen it to see the updates.

Specifying Display Sequence for Fixed Choice Lists

In a fixed choice list, the list of field values can be either alphabetically arranged or have a display sequence such as High, Medium, or Low. When updating a fixed choice list field that has a display sequence, specify whether you want to populate the field with the next value, or with the previous value, in the list.

For example, for a display sequence of High, Medium, and Low, you can change from High to Medium (populate with next value) or from Low to Medium (populate with previous value) during a field update. Keep in mind, however, that if the current value is Low and you configure using populate with next value in list, the field is not updated because Low is already the last value in the sequence.

Support for Primary and Child Objects

You can configure field updates using either a parent or a child object. When you select a child object when defining an object workflow, you can update fields only in the records of that child object; you cannot update fields in the records of that child object's parent.

For example, when defining a workflow for Opportunity Team, which is a child object of Opportunity, you can configure field updates when a new team member (child record) is added to the Opportunity Team, but you cannot configure field updates for records in the parent Opportunity object.

Additionally, when inserting field tokens while configuring field updates, only those tokens belonging to the selected child object is available for selection. See the Configuring Object Workflows: Example topic for an example of how to insert tokens when configuring field updates.

Object Workflows vs. Triggers

Object workflows are asynchronous. Use object workflows and the Field Updates action only when you need to update a field asynchronously, such as based on a time delay.

If you want changes to be immediately reflected on the user interface at run time, however, use scripting and triggers, such as the Before Update trigger.

Object Workflows and Email Notifications

Email notifications send automated alerts to the specified recipients when the associated object workflow is triggered. You can configure email notifications using either a parent or a child object.

Email Templates

Email notifications are based on the email templates that you create. Email templates define email layouts, and ensure that the notifications triggered by the same type of business event have a consistent look and feel.

Recipient Types

The recipients available for sending the email notifications are contextual. If you're defining a workflow using a parent object, the recipients belong to the parent and its related child objects. If you're defining a workflow using a child object, then the recipients belong only to that child object. Recipient types include:

  • From address

  • To address

  • Reply-to address

  • Cc address

  • Bcc address

You use field tokens to insert runtime values of fields. When inserting such tokens, only those fields belonging to the selected primary or child object are available for selection. See the Configure Object Workflows topic for an example of how to select and insert field tokens.

The following are the recipient types:

  • Fields on record: If the selected object contains user-defined text fields that store emails, you can select those fields to send email notifications (for example, Primary Contact Email under Opportunity object). The user-defined text field can store a single email address or multiple comma-separated email addresses.

  • Relative users on record: Contains relative users who could be either a creator of an opportunity record, a person who last updated a record, a manager or his directs, or a team of resources working on a project, and so on.

  • Roles: Contains users assigned to a particular resource role. The email notification is sent to all enterprise groups or users that have been granted that resource role.

    When selecting a Role, you can optionally apply an additional filter to specify the organization to which that role belongs. For example, if you want to send an email notification to a Sales Director role within a particular organization, specify that organization using the Filter By field in the dialog where you select the role.

  • Resources: Resources associated with the record, such as Created By or Last Updated By.

  • Resource Groups: Groups of resources associated with the records, such as Direct reports of Created By, or Subordinates of Last Updated By.

  • Specific users: Contains details of individual users and their emails.

  • Specific email addresses: Enter individual emails separated by a comma.

Note: The Search function for specific users includes a Search button to initiate the search; for the other recipient types, such as Roles, the application performs an automatic search after you type in your search terms and click or tab out of the search box.

Disable or Enable Notifications

If you have the BPM Workflow System Administrator Role role, then you can disable or enable these notifications for all users. For example, you can disable notifications during testing, to avoid sending test notifications to users, and then enable notifications when ready. For more information, see Disable or Enable Workflow Notifications in the Related Topics.

Tip: If notifications are enabled but workflow emails aren't sending correctly, then check the Application Preferences page on the BPM Worklist Administration tab. Someone might have entered an email address in the Test Notification Email Address field that's no longer needed. Remove that email address and try again.

Here's how you can configure an email notification action as part of an object workflow:

  1. From the Application Composer overview page, select Object Workflows.

  2. Select Actions > Create.

  3. Select an Object and provide a meaningful Name for the object workflow.

  4. Define the trigger condition, and select Email Notification as the event action.

  5. On the Create Action: Email Notification page, provide a Name for the email notification action.

  6. Search for and select an existing email template, or create one.

    When you create a template, you specify action-related text and field tokens that are populated at runtime.

  7. Specify the recipient types.

See the Configure Object Workflows topic for an example of how to configure email notifications and email templates.

This topic describes how you create, manage, and use email templates. You use these email templates for configuring the email notifications action in object workflows. Email templates define the layout of the emails, which ensures that email notifications triggered by the same type of business event for a specific object have a consistent look and feel.

You cannot create email templates while inside an active sandbox.

Configuring Email Templates

You create a template for use with a particular type of object. You then use this template only for that object when configuring email notifications. You can either create email templates or create templates using any email editor, and then upload them for use. You can create email templates, for example, for including your company letterhead in outbound email communications.

You can create email templates in Application Composer in two ways:

  1. When configuring email notification action.

    On the Create Action: Email Notification page, select the Create Email Template icon in the Email Template field.

  2. Using the Email Templates link on the Overview page of the Application Composer.

This figure shows the Create Email Template page.

This figure shows the Create Email Template page

For an example on how you create email templates, see Configuring Object Workflows: Example topic.

Here's what you can or can't do when creating email templates:

  • You can perform basic formatting such as font format, character format, paragraph alignment, bullets and numbering, and so on as in any HTML based email client.

    Templates are automatically converted to plain text for users who cannot view HTML emails.

  • For advanced HTML editing, use the Source Code Editing Mode, which is available as an icon under the Email Body region. Under this mode, the tags are set to visible. You can copy and edit the source code in any HTML editor, and then paste the edited code back. Similarly, you can use the Rich Text Editing Mode, which is available next to the Source Code Editing Mode icon.

  • You can attach artifacts relevant to the email template. Attachments are included in every email, which uses the template that has an attachment. You can also send attachments as links to avoid crowding the inbox of the recipients. An attachment can be a file on a local computer or a shared file in a repository.

    Note: File attachments cannot exceed 10 MB.
  • Specify whether an email template is Active. You can use only Active templates to create email notifications.

  • You can insert fields or functions in the email body. You use functions to insert date, current date and time, or a hyperlink to a record. You can also Browse and then insert the content of a local file in the body of the email template.

  • You can link directly to object details pages using primary key fields of the primary object records or using foreign keys for related objects. You can select these primary key and foreign key fields in the field drop-down list to substitute them into the direct links as tokens. The following objects are supported: Opportunity, Lead, Account, Contact, Household, Activity, and any objects you create. Refer to the description of direct linking for details on how to construct these links.

  • You can specify the tokens or fields, which are populated with the values at run time.

    Note: You can't use fields of type Dynamic Choice List as tokens.
  • Join fields are not available in email templates.

  • You must select Include in Service Payload for custom fields to be available in email templates.

Managing Email Templates

Managing email templates include tasks that enable you to search, view, duplicate, create, edit, or delete a template.

To manage email templates, select the Email Templates link on the Overview page of the Application Composer.

This figure shows the Email Templates page, which you use for managing email templates.

This figure shows the Email Templates page, which
you use for managing email templates

Options available for managing email templates include:

  • Viewing the existing email templates and modifying views.

  • Filtering or querying existing templates including partial search using wildcard.

  • Editing an existing template or creating a duplicate. You cannot change the object for which a template is defined.

  • Creating a template.

  • Detaching the listed templates for a full-page view.

  • Viewing which templates are Active.

    Note: You can use only Active templates for configuring email notifications. Saving does not automatically make the template Active.

Object Workflows and Tasks

You can configure object workflows to trigger auto-creation and assignment of tasks.

You can define tasks action for only those objects that support the creation of tasks. For other objects, the tasks option is disabled.

Here's how you can create a task:

  1. Navigate to Application Composer.

  2. From the Overview page, click Object Workflows.

  3. Click Create.

  4. Select an Object and provide a meaningful Name and Description.

  5. Define the trigger condition using When a record is created or When a record is updated event point.

  6. Under the Actions region, click Create for Tasks Creation.

    This opens the Create Action: Tasks Creation page.

  7. Provide the Name and Description for the event action and optionally set the Execution Schedule.

  8. Use the Task Details region to configure a task based on your requirements. Here's how you can use the tasks details region:

    • Select a Subject and Description, as appropriate, for your task notification.

    • Select the Due Date and Start Date for a task. When you select a date, you can also provide logical conditions for these dates, for example, a Due Date must be 30 days after the Start Date.

    • Select an Owner for the task. The values in this list change depending on the object for which the task is being defined. A task can have only one owner: either an individual person or a single resource. You can search for users by name or user ID. You can store a user's PartyID or GUID in a text field you create and use the value as the task owner.

    • Select the Resources for the task. The values in these lists change depending on the object for which the task is being defined. Resources can be owner, resource team, resource team with different access levels, member functions, and so on. You can store multiple comma-separated PartyIDs or GUIDs in a text field you create and use the values as task resources.

      For example, when an opportunity reaches a Close Date and the status is Open, you can use the task creation action to assign a follow up task to the owner of the opportunity.

    • Select a Primary Contact for the task. You can select one from contacts related to the object record, or specify one by name. If the selected object contains user-defined text fields that store the contact's name or contactID, you can select those fields to be set as primary contact.

    • Select the Type to which a task belongs. This field uses FND lookup for values. The delivered values are call, chat, demo, e-mail, and meeting.

    • Assign a Priority to the task. The default priority is Medium.

  9. If a standard object or an object you created has more than one one-to-many relationships defined through dynamic choice list or reference relationship with the Activity you have chosen, the Related To field appears at the bottom. This Related To field shows the first created relationship as default.

    You can select this field only once for the object in context, after which the field appears as read only.

  10. Save the event action.

Note: If an object for which you're defining this event action contains a customer, that customer is automatically included in the created task.

For an example of how you configure tasks, see Configuring Object Workflows: Worked Example topic.

Creating Tasks Using Child Objects

When you configure an object workflow using a child object, the fields that you select are specific only to that child object.

When a child-object based task is triggered, the task is assigned to the parent object of that child. You can't configure a task for a child object of another child object.

Creating Tasks Using Objects with No Associated Activity

You can create a task for a standard object or an object you created even if it doesn't have a relationship with an Activity. If you try to create a task on an object with no relationship to an Activity, you see a message letting you know that a standalone task will be created unless you first create such a relationship. After they're created, standalone activities will show in the task owner's Activity work area in the desktop UI, and in the top-level Activities card in the application UI.

Enable Task Creation for Object Workflows

You can configure object workflows to trigger the automatic creation and assignment of tasks. For example, you might want to remind a sales representative to call a customer one month before their contract ends. Most objects support the creation of tasks. However, for any object (for example, Asset) that doesn't have a standard relationship to Activity as delivered, the Task event action is disabled. To enable the Task event action, you create a relationship between the target object and Activity objects.

Create a relationship between the desired object and the Activity object in one of two ways:

  • Create your own dynamic choice list field for the Activity object that points to the desired object's records.

  • Create a one-to-many reference relationship with desired object as the source, and the Activity object as the target.

    Tip: This type of relationship is similar to a dynamic choice list relationship. The difference is that when you want to create your own relationship between the objects but you don't need to show it in the UI as a choice list, then you might prefer to simply create the one-to-many relationship rather than the dynamic choice list relationship. With the one-to-many relationship, you don't get a choice list field for the object to add to any Activity user interface.

Once a dynamic choice list or reference relationship exists, you can create tasks for object workflows associated with the desired object.

Creating a Dynamic Choice List Field

In this example, let's create a dynamic choice list field for the Activity object that is populated by records from the Asset object.

  1. In Application Composer, select the Activity object.

  2. Select Fields.

  3. Create a field of type Choice List (Dynamic).

  4. Complete the general steps to configure a new dynamic choice list field. For example, set the display label for the field.

  5. In the Related Object list, select the Asset object.

  6. Complete the rest of the steps to create this dynamic choice list field. For example, in the List Selection Display Value field, select the field that displays as the first column in the dynamic choice list at run time.

  7. Click Submit.

Creating a Relationship

In this example, let's create a relationship between the Activity and Asset objects.

  1. Navigate to Application Composer.

  2. Click the Relationships link under Common Setup.

  3. Click the Create icon.

  4. In the Source Object field, select the Asset object.

  5. In the Target Object field, select Activity.

  6. In the Cardinality field, select 1:M.

  7. Click Save and Close.

Object Workflows and Outbound Messages

You can configure an object workflow to send an outbound message to a Web service at a specified endpoint URL. The endpoint URL is an external Web service that shares data with your applications, and must conform to your Oracle service WSDL.

For example, you can define an object workflow that automatically sends, based on a trigger, an outbound message containing an object like opportunity, lead, or account details from one system to another.

This figure illustrates how outbound messages are configured as part of object workflows.

Outbound Messages

You can configure outbound-messages event for a parent or a child object. When you define a workflow using a parent object, the outbound message is sent using service data objects (SDO) of that parent object as well as its child objects. When you define a workflow using a child object, the outbound message is sent using the SDO of only the child object.

To define an outbound message action:

  1. From the Application Composer main page, select Object Workflows.

  2. Click Create.

  3. Select an Object and provide a meaningful Name and Description for the workflow you are creating.

  4. Define the trigger condition using When a record is created or When a record is updated event point.

  5. Select the Outbound Message event action.

    This opens the Create Action: Outbound Message page.

  6. Specify the Name and Description for the outbound message action and set the Execution Schedule for triggering the action. See: Execution Schedule in this topic.

  7. Provide the endpoint URL of the external Web service.

    To build the external Web service, use the OutboundMessageService.wsdl and .xsd files. Then, when defining the outbound message event action for the object workflow, you provide the endpoint URL of the external Web service.

    For example, an endpoint URL can be http://GlobalFusion:7011/OMTestOpportunity/OutboundMessageServiceSoapHttpPort. At run time, a service data object containing details of the object on which the object workflow is defined is sent to the specified endpoint URL.

  8. Save the event action.

Execution Schedule

While defining an event action, you can optionally set an execution schedule that governs when an event action should happen. Else, the event actions are run immediately. When multiple event actions are configured, the Field Updates happen first before any other event action is triggered. For event actions other than Field Updates, there is no particular sequence and the event actions are triggered based on whether or how you configure the execution schedule.

If a field update event action is also scheduled along with outbound messages event action, the field updates event action is triggered first, so that the outbound messages contain the updated data.

Security Considerations

The outbound messages can use either an authentication-only client-side security policy or a transport-level security policy that protects the message during transfer. The default authentication-only policy used by object workflow outbound message is oracle/wss10_saml_token_client_policy. This policy includes Security Assertion Markup Language (SAML) tokens in outbound Simple Object Access Protocol (SOAP) request messages. This policy should only be used when the target web service is located within a secure network segment.

The corresponding service can use any compatible service policy, such as oracle/wss10_saml_token_service_policy or oracle/wss_saml_or_username_token_service.

When the service is outside your firewall, you must protect the message by selecting the Protect Message option on the Create Action: Outbound Message page. When protected, the outbound message uses oracle/wss_username_token_over_ssl_client_policy with one-way secure socket layer (SSL) enabled by default. The corresponding service must use a compatible service policy, such as oracle/wss_username_token_over_ssl_service_policy.

Outbound Messages Protection

You must perform the following setup activities when you are using the Protect Message option:

  1. Your applications require credentials to access the remote system to which the outbound message is being sent. Log a service request (SR) to provide these credentials to access the remote system.

  2. If the remote system is using a self-signed SSL certificate, log an SR for the Oracle administrator to import the SSL certificate.

You can configure an object workflow to send an outbound message to a third-party Web service at a specified endpoint URL. An endpoint URL is an external Web service that receives data from your applications. The third-party Web service must conform to the service WSDL defined by Oracle.

To build the external Web service, use the OutboundMessageService.wsdl and .xsd files. Then, when defining the outbound message event action for the object workflow, you provide the endpoint URL of the external Web service.

This topic provides the following:

  • How to configure a Web service

  • An example of the OutboundMessageService.wsdl

  • An example of the OutboundMessageService.xsd

  • The security policies available

Configuring a Web Service

To configure a Web service, you must replace the parameters in the OutboundMessageService.xsd file using the Web service instructions.

For more information about Web services, see the SOAP Web Services guide.

  1. For a standard object, search the guide by object name.

    For custom objects, search for the generic Web service for all custom objects in the corresponding application, for example, Sales Custom Business Object.

  2. Extract the .xsd files from the live environment URL using the information provided under the service.

  3. Replace the parameters in OutboundMessageService.xsd with the names for the object of your interest.

    The parameters are marked in the .xsd file as parameters, $OBJECT_TARGET_NAMESPACE$ and $OBJECT_NAME$.

Examples of OutboundMessageService.wsdl and OutboundMessageService.xsd are provided here for reference.

WSDL File Example

This section contains an example of the OutboundMessageService.wsdl, for your reference.


//Sample OutboundMessageService.wsdl 
<wsdl:definitions
     name="OutboundMessageService"
     targetNamespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/"
     xmlns:errors="http://xmlns.oracle.com/adf/svc/errors/"
     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns:types="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
    >
    <wsdl:import namespace="http://xmlns.oracle.com/adf/svc/errors/" location="ServiceException.wsdl"/>
    <wsdl:types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
                 schemaLocation="OutboundMessageService.xsd"/>
        </schema>
    </wsdl:types>
    <wsdl:message name="OutboundMessageService_processOutboundMessage">
        <wsdl:part name="parameters" element="types:processOutboundMessage"/>
    </wsdl:message>
    <wsdl:message name="OutboundMessageService_processOutboundMessageResponse">
        <wsdl:part name="parameters" element="types:processOutboundMessageResponse"/>
    </wsdl:message>
    <wsdl:portType name="OutboundMessageService">
        <wsdl:documentation/>
        <wsdl:operation name="processOutboundMessage">
            <wsdl:input message="tns:OutboundMessageService_processOutboundMessage"/>
            <wsdl:output message="tns:OutboundMessageService_processOutboundMessageResponse"/>
            <wsdl:fault name="ServiceException" message="errors:ServiceException"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="OutboundMessageServiceSoapHttp" type="tns:OutboundMessageService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="processOutboundMessage">
            <soap:operation soapAction="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/processOutboundMessage"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ServiceException">
                <soap:fault name="ServiceException" use="literal" encodingStyle=""/>
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="OutboundMessageService">
        <wsdl:port name="OutboundMessageServiceSoapHttpPort" binding="tns:OutboundMessageServiceSoapHttp">
            <soap:address location="http://adc2111013:7101/OMInterface/OutboundMessageService"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

XSD File Example

This section contains an example of the OutboundMessageService.xsd, for your reference. The parameters are marked in the .xsd file as parameters, $OBJECT_TARGET_NAMESPACE$ and $OBJECT_NAME$.


//Sample: OutboundMessageService.xsd

<schema elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
     xmlns:ns0="http://xmlns.oracle.com/adf/svc/errors/" xmlns:ns1="$OBJECT_TARGET_NAMESPACE$"
     xmlns:ns2="http://xmlns.oracle.com/adf/svc/types/" xmlns:tns="http://xmlns.oracle.com/apps/crmCommon/content/outboundMessage/types/"
     xmlns="http://www.w3.org/2001/XMLSchema">
    <import namespace="http://xmlns.oracle.com/adf/svc/types/" schemaLocation="BC4JService.xsd"/>
    <import namespace="$OBJECT_TARGET_NAMESPACE$" schemaLocation="$OBJECT_NAME$.xsd"/>
    <import namespace="http://xmlns.oracle.com/adf/svc/errors/" schemaLocation="ServiceException.xsd"/>
    <element name="processOutboundMessage">
        <complexType>
            <sequence>
                <element name="object" type="ns1:$OBJECT_NAME$"/>
            </sequence>
        </complexType>
    </element>
    <element name="processOutboundMessageResponse">
        <complexType>
            <sequence/>
        </complexType>
    </element>
</schema>

Security Policy

The outbound messages can use either an authentication-only client-side security policy or a transport-level security policy that protects the message during transfer. The default authentication-only policy used by object workflow outbound message is oracle/wss10_saml_token_client_policy. This policy includes Security Assertion Markup Language (SAML) tokens in outbound Simple Object Access Protocol (SOAP) request messages. This policy should only be used when the target web service is located within a secure network segment.

The corresponding service can use any compatible service policy, such as oracle/wss10_saml_token_service_policy or oracle/wss_saml_or_username_token_service.

When the service is outside your firewall, you must protect the message by selecting the Protect Message option on the Create Action: Outbound Message page. When protected, the outbound message uses oracle/wss_username_token_over_ssl_client_policy with one-way secure socket layer (SSL) enabled by default. The corresponding service must use a compatible service policy, such as oracle/wss_username_token_over_ssl_service_policy.

Object Workflows and Business Processes

This topic explains how you use object workflows to trigger business process flows. When you configure object workflows, you also specify the actions that the workflow must perform when triggered. One of the actions you configure is the Business Process Flow action.

Before you begin, you might want to read Object Workflows: Explained and its related topics to familiarize yourself with what object workflows are, how you set trigger conditions, and the event actions that the object workflows support.

Overview

A business process flow in object workflows is essentially an approval flow. You use these approval flows to send approval requests, for example, when the following events occur:

  • When the win probability of an opportunity is changed above a threshold level.

  • When an object you created has been updated.

  • When a new order is created.

You configure a business process flow action in object workflows using Application Composer; however, the underlying process of creating an object workflow, creating an approval flow, associating the object workflow with the approval flow, triggering them both to send approval requests, and then taking an action on the requests involves multiple applications.

This figure illustrates how object workflows and business processes work together, and the various applications involved in the end-to-end flow.

This figure illustrates how object workflows and
business processes work together
  • Application Composer. You use this application to configure object workflows.

    For examples of how you configure various event actions in object workflows, see Configuring Object Workflows: Worked Example and Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example topics.

  • Oracle Business Process Composer. You use this application to create business processes (or approval flows) using existing or user-defined templates.

    For an example of how you create and deploy a business process flow, see Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example topic.

    For more information on Oracle Business Process Composer, refer Oracle Fusion Middleware Business Process Composer User's Guide for Oracle Business Process Management on Oracle Technology Network, at http://www.oracle.com/technetwork/indexes/documentation/index.html.

  • Oracle Business Process Management (BPM) Worklist application. You use this application to take appropriate action on the approval requests.

    The Worklist application displays tasks or approvals that are assigned to a user. Your worklist tasks appear on the Home page.

Configuring a Business Process Flow Action in Object Workflows

Object workflows contain a set of actions that are run when the workflow is triggered. One of these actions is the Business Process Flow action.

To configure business process flow action:

  1. Navigate to Application Composer.

  2. On the Overview page, click Object Workflows.

  3. Select Actions > Create.

    Create Object Workflow page opens.

  4. Specify a Name for your workflow.

  5. Specify the trigger condition in the Event Point and Condition region.

  6. Under Actions region, click Create for Business Process Flow.

    Create Action: Business Process Flow page opens. You use this page to configure the business process flow action.

This figure shows the Create Action: Business Process Flow page:

This figure shows the Create Action: Business Process
Flow page

The key configurations that you perform using the Create Action: Business Process Flow page are as follows:

  • Provide a meaningful Name for your business process flow action.

  • Click the Search icon in the Project Name field to open Search and Select: Business Process Flow dialog.

    This figure shows the search and select dialog.

    This figure shows the search and select dialog.

    You use the search and select dialog to do the following:

    • Search and specify the project (or approval flow) to trigger when the object workflow is triggered.

    • Launch the Oracle Business Process Composer to create a project based on the chosen template.

      To launch the composer, you click the Create icon to open Create Business Process Flow dialog. You then specify the Name for your project, and then click OK.

  • Specify the input parameters that you want to supply to the approval process. See "Creating an Approval Flow Using Business Process Composer" section in this topic.

Creating an Approval Flow Using Business Process Composer

You access Oracle Business Process Composer using either of the following ways:

  • Using the Business Processes link on the Overview page of the Application Composer.

  • Using the Search icon on the Create Action: Business Process Flow page.

Oracle provides a set of business process you can use without modification, or you can use these business processes as a template to create your own version of the processes. You typically create approval flows using ExtnBusinessProcessComposite template, which is the standard or default template delivered with the product. If there are other templates available, create your approval flow based on the relevant template.

Note: The ExtnBusinessProcessComposite template supports only Business Process Management Notation (BPMN), which is an industry standard notation for defining business processes. For more information on BPMN, see http://www.bpmn.org.

You can only use the existing templates (either as provided or by copying and editing them) to create projects using the services, tasks, and business rules as provided in the template. For more information on the considerations involved when using templates, see Object Workflows and Business Processes: Critical Choices.

For an example of how you create an approval flow using ExtnBusinessProcessComposite template, see Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example.

Associating the Object Workflow with the Relevant Approval Flow

While configuring the business process flow action, you use the input parameters to specify the field-values to pass from the object workflow to the chosen approval flow when the object workflow is triggered.

The input parameters that you pass from object workflows to the approval flow depends on the template that you have chosen for creating the approval flow. When you use the default ExtnBusinessProcessComposite template to create an approval flow, here's how you typically configure the input parameters:

Parameter Description

approvers

Specify the people who should receive the approval request. You can specify one or more of the following:

  • Resources associated with the record (such as its owner or creator, the manager of the owner, or the last person to update the record).

  • Resource groups (such as the direct reports or subordinates of the owner).

  • Specific users.

  • Fields on record: If the selected object contains user-defined text fields that store the approver's GUID, you can select those fields to send approval notifications to a single user or comma-separated GUIDs of multiple users.

heldEntityStatusField

Specify the field that displays the status of the approval request.

emailAddress

Optionally specify the e-mail address of one or more individuals who must receive e-mails on the outcome of the approver action.

title1

Optionally append more information to the title of the notification.

title2

Optionally append more information to the title of the notification.

For more information on the considerations involved when using these input parameters, see Object Workflows and Business Processes: Critical Choices topic.

Triggering the Object Workflow and the Associated Approval Flow

When you trigger the object workflow which has an associated approval flow, the approval flow is also triggered. For example, when you trigger the approval flow that you created using ExtnBusinessProcessComposite template, a task appears in the BPM Worklist application for the person who you have specified in the approver field under input parameters.

You can also configure these input parameters to modify some of the notifications, but with some limitations on what you can modify and how.

Note: Along with the modified notification, the approver of the BPM may also receive the standard email notification. There is no configurable way to stop receiving the standard notification.

For more information on the types of notifications available and how you can modify them, see Object Workflows and Business Processes: Critical Choices.

This topic covers the key points to consider when you work with object workflows to trigger a business process. When you configure object workflows, you also specify the actions that the workflow must perform when triggered. One of the actions you configure is the Business Process Flow action. This business process flow action in object workflows is essentially an approval flow.

Before you begin, you might want to read Object Workflows: Explained topic to familiarize yourself with what object workflows are, how you set trigger conditions, and the event actions that the object workflows support. Additionally, to know how object workflows and business processes interact with each other, read Object Workflows and Business Processes: How they Work Together topic.

Overview

You use templates in Oracle Business Process Composer to create and deploy a project, which you then call from object workflows. A project that you create and deploy is called an approval flow. You must create and deploy at least one project (or approval flow) before you configure the Business Process Flow action in object workflows.

Note: You must work directly in the mainline metadata to create an approval flow. You can't configure the business process flow task while you're in an active sandbox.

You configure a business process flow action in object workflows using Application Composer; however, the underlying process of creating an object workflow, creating an approval flow, associating the object workflow with the approval flow, triggering them both to send approval requests, and then taking an action on the requests involves multiple applications.

  • Application Composer. You use this application to configure object workflows.

    For examples of how you configure various event actions in object workflows, see Configuring Object Workflows: Worked Example and Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example topics.

  • Oracle Business Process Composer. You use this application to create business processes (or approval flows) using existing or user-defined templates.

    For an example of how you create and deploy a business process flow, see Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example topic.

    For more information on Oracle Business Process Composer, refer Oracle Fusion Middleware Business Process Composer User's Guide for Oracle Business Process Management on Oracle Technology Network, at http://www.oracle.com/technetwork/indexes/documentation/index.html.

  • Oracle Business Process Management (BPM) Worklist application. You use this application to take appropriate action on the approval requests.

    The Worklist application displays tasks or approvals that are assigned to a user. Your worklist tasks appear on the Home page.

Using the Default Template to Create Approval Process

The template delivered with the product is the ExtnBusinessProcessComposite template, which uses a basic CrmCommonSerialApprovalProcess process flow. This template contains an approval process covering a typical sales use case. Any project that you create with the seeded template uses CrmCommonSerialApprovalProcess process.

Note: The ExtnBusinessProcessComposite template supports only Business Process Management Notation (BPMN), which is an industry standard notation for defining business processes. For more information on BPMN, see http://www.bpmn.org.

This figure shows the standard ExtnBusinessProcessComposite template:

This figure shows the standard ExtnBusinessProcessComposite
template

For an example of how you create and deploy a project, see Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example.

The default ExtnBusinessProcessComposite template contains services, business rules, and tasks which you can use for configuring approval flows. You can change or add nodes or business rules for human task implementation process.

For example, you can change SerialGivenUserNameApproval with SerialApprovalGroupApproval. However, when creating or modifying a project, do not attempt the following unless you are sure:

  • Deleting or modifying the services, rules, tasks, or system fields in an existing business process. It may fail validations.

  • Removing or changing reserved parameters such as owner, heldEntity, heldEntityId, heldEntityStatusField, and objectProperties.

  • Removing nodes such as CreateHold, UpdateHold, UpdateEntity, and so on.

Note: You can edit only those projects, which have been created by launching BPM Composer from within the Application Composer.

To see the services, tasks, and rules available, select the Project Home tab in Oracle Business Process Composer.

This figure shows the services, tasks, and rules available in the template.

Services, tasks, and rules available in the template

For information on working with business rules, services, and tasks and how to model process flows, refer Oracle Fusion Middleware Modeling and Implementation Guide for Oracle Business Process Management at Oracle Technology Network, at http://www.oracle.com/technetwork/indexes/documentation/index.html.

Supplying Inputs to the Business Process from Object Workflows

Using input parameters you can pass specific values to the associated approval process when the trigger condition is met. These input parameters are specific to the template that you are using to create your approval flow. By default, you use the ExtnBusinessProcessComposite template, which is shipped with the product and covered in the documentation related to object workflows. If you are using some other template, refer to the documentation for that product for the parameters that you can use.

To see where these input parameters reside in Oracle Business Process Composer, right click on the Start node of the approval flow and select Properties.

This figure illustrates where you can see the input parameters in business process composer.

This figure illustrates the input parameters in
business process composer

Notice the heldEntityStatusField and approvers parameters in the figure. These are some of the parameters you are mapping to from object workflows when using the ExtnBusinessProcessComposite template.

When using the standard ExtnBusinessProcessComposite template, these are the inputs you can supply to the associated approval process:

  • approvers

  • heldEntityStatusField

  • emailAddress

  • title1

  • title2

While the approvers and heldEntityStatusField parameters are mandatory, the emailAddress, title1, and title2 are optional parameters.

For more information on these inputs and how you can configure notifications using these inputs, see "Configuring Input Parameters for Modifying Notifications" section in this topic.

Using input parameters, you can pass either static or runtime values to the approval process as follows:

  • To pass actual or static values to the approval flow, select either Literal check box in the Select Default Value dialog or manually enter parameters in single quotes, for example, 'user1'.

    This figure illustrates how you select and mark the input parameters as Literal. This dialog appears when you click on the function icon in the Inputs region.

    This figure illustrates how you select and mark
the input parameters as literal
  • To pass runtime values, do not select Literal in the Select Default Value dialog or just enter the parameters manually without quotes.

    For example, to pass a runtime field (token) for Opportunity Region, enter Region (without quotes). When the workflow is triggered, this field is replaced with runtime value of Region.

You can also obtain approvals serially or in parallel from multiple approvers. For example, to obtain serial approvals first from user1 and then from user2 using Literal values, enter 'user1,user2'. Similarly, for runtime fields, enter user1,user2.

Note: To supply multiple, literal values use single quotes for the entire string without any space in between those values.

Configuring Input Parameters for Modifying Notifications

The field values or the input parameters that you pass from object workflows to the approval flow depends on the template that you have chosen for creating the approval flow. This section contains examples assuming you are using the default ExtnBusinessProcessComposite template.

Before we go into configuring input parameters, it is essential to understand what types of notifications occur when the approval flow is triggered, and when the approval flow is approved or rejected.

  • When the approval flow is triggered, the BPM worklist notification shows, for example, "Opportunity has been submitted for your approval", which is in format "<Object name> has been submitted for your approval".

  • When the approval or rejection happens, the e-mail notification (based on the emailAddress parameter) contains the outcome of the action taken by the approver. The subject of the e-mail can be, for example, "Opportunity has been approved".

You can only minimally change the way the BPM Worklist and e-mail notifications appear by appending information using some of the input parameters.

To change BPM notification, for example, let's assume you are creating a workflow using the Opportunity object and have specified only the approvers and heldEntityStatusField parameters. When such an approval flow is triggered, the notification in BPM Worklist application shows "Opportunity has been submitted for your approval", which is a standard notification.

Now, let's assume that you also want the opportunity name and region to appear in the notification. Assuming that the opportunity is Pinnacle Deal and the region is West, you can change the BPM notification to a more meaningful one by configuring the parameters as follows:

Parameter Values Description Field Type

approvers

'Matt Hooper, Manager of Created By, Resource Group: Direct Reports of Created By'

Specifies one or more people who receive the approval request.

Run Time

heldEntityStatusField

'Approvalstatus_c'

Specifies the field that displays the status of the approval request.

Literal

emailAddress

[Optional]

'jsmith@pinnacle.com,blopez@pinnacle.com'

Specifies e-mail addresses of one or more individuals who receive the approval or rejection notification.

Literal

title1

[Optional]

Name

Appends the name of the opportunity to the title.

Run time

title2

[Optional]

Region

Appends the name of the region (of the opportunity) to the title.

Run time

Now trigger the approval flow again. This time the notification in the BPM Worklist application shows "Opportunity Pinnacle Deal West has been submitted for your approval," which follows the format "<Object name> <title1> <title2> has been submitted for your approval".

Similarly, when an approver takes an action on the request, the title1 and title2 parameters are also appended to the e-mail notification. For example, when the request is approved, the subject of the e-mail shows "Opportunity Pinnacle Deal West has been approved".

To display the notifications in a different format, you can specify only some of the optional parameters.

Note: Along with the modified notification, the approver of the BPM may also receive the standard email notification. There is no configurable way to stop receiving the standard notification.

Specifying the Trigger Condition in Object Workflows

You must ensure that the trigger condition for the object workflow contains the field that you update to trigger the workflow. For example, if you have defined your own field Submit_c of type check box, the trigger condition looks like: isAttributeChanged('Submit_c') && Submit_c=='Y'.

Defining an expression prevents the triggering of the object workflow each time an update or create event point occurs.

For more information on how to set trigger conditions, see Configuring Object Workflows: Example topic.

If you are specifying a drop down, fixed-choice list field for capturing approval status, use the lookup type ZCX_HOLD_STATUS to configure the status values as per your business requirement. The default values provided in this lookup type are: APPROVALPENDING, APPROVED, and REJECTED. Ensure that ZCX_HOLD_STATUS contains the default values or the values that you have specified in this lookup type for tracking the approval status.

Note: To capture the approval status, you can use only fields of type text or fixed choice list.

Set Up Serial Group Approval

You can create an approval workflow that requires approval from a group of people, in sequential order. This is called serial group approval. In serial approval, a list of approvers must approve a process in order (the second person on the list can't approve until the first person has done so). You manage this using Oracle Business Process Manager (BPM) and object workflows.

This topic describes the following:

  • Creating the group of approvers.

  • Creating the approval flow.

  • Deploying the project.

  • Including the approval flow in an object workflow.

  • Allowing the approval flow to complete early.

For more information about human tasks, refer to the "Designing Human Tasks" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Creating the Group of Approvers

To set up serial group approval, you must first create the group for your approvers.

  1. Sign in to the BPM worklist application.

  2. Navigate to Administration, Approval groups.

  3. Create a group named CrmCommonApprovalGroup. Note that you must give the group this name.

  4. Add the members of the group (the people you want to designate as approvers).

    The group can be static or dynamic.

  5. Save the group.

Creating the Approval Flow

Next, you create the approval flow, which is based on the standard approval flow template ExtnBusinessProcessComposite.

  1. Click New on the Business Processes page.

  2. Select ExtnBusinessProcessComposite as the base template.

  3. Remove the standard human task step named SerialApproval.

  4. From the component palette on the right side of BPM Composer, drag an interactive task step into the approval flow in the same place where you removed the existing SerialApproval step.

  5. Rename the new task step (for example, GroupApproval).

    Rename the new task step
  6. Right-click the human task step and click Implement Task.

  7. Search for all patterns and select the SerialApprovalGroupApproval task.

    Select the SerialApprovalGroupApproval task
  8. Click Apply changes.

  9. Right-click the human task step again and click Data Association.

  10. Map the inputs and outputs as shown in the table below.

    Inputs GroupApproval Outputs

    taskTitle

    title

    taskOwner

    taskOwner

    taskOwner

    errorAssignee

    outcome

    taskOutcome

    Inputs and outputs
  11. Click Apply changes.

  12. Save the process.

Deploying the Project

Finally, you deploy the project.

  1. From the main menu, select Deployment, Deploy Project.

  2. In the Deploy Project dialog box, enter the following:

    Field Value

    Revision ID

    Provide an identifiable ID.

    Deployer User Name

    Your sign-in name.

    Password

    Your password.

    Mark composite revision as default

    Select this option.

  3. Click Deploy.

    A confirmation message appears after the project has been deployed successfully.

Including the Approval Flow in an Object Workflow

Now you can create an approval workflow that includes a serial list of approvers. To do this, create an object workflow that uses the GroupApproval flow that you created above.

  1. Make sure you're in an active sandbox.

  2. In Application Composer, click Object Workflows.

  3. Enter a name for the object workflow, and select an object (for example, Opportunity).

  4. Click Create.

  5. Click the Create icon next to Business Process Flow.

  6. Enter a name for the flow.

  7. Click Search next to Project Name.

  8. Select GroupApproval from the list and click OK.

  9. Click Save.

When the object workflow is invoked, the first member of the group receives the approval notification. After the first person approves the flow, it's routed to the second person in the group and so on.

The flow is considered complete when all the members of the approval group approve the request.

Allowing the Approval Flow to Complete Early

In most cases, if the first approver rejects the request, then you will want the flow to immediately complete and not move on to the next approver. You can set up your approval flow to do this by configuring the Early completion settings in BPM Worklist.

  1. Click the Notifications icon on the global header.

  2. Click More Details.

  3. In BPM Worklist, click your user name and select Administration.

  4. Click Task Configuration at the top of the page.

  5. In the Search box, search for task you're using for the object workflow, such as SerialApprovalGroupApproval.

  6. Click the Edit task pencil icon, then click the Configuration tab.

  7. Select the Complete task immediately when participant chooses check box, and select Reject.

  8. Click the Save icon and optionally enter comments.

  9. Click the Commit task icon and optionally enter comments.

Set Up Parallel Approval

You can create an approval workflow that requires approval from a group of people, in any order. This is called parallel group approval. In parallel approval, all members of a list of approvers must approve a process in any order (the order of approvers in the list isn't relevant, but all approvers must approve it). You manage this using Oracle Business Process Manager (BPM) and object workflows.

This topic describes the following:

  • Creating the group of approvers.

  • Creating the approval flow.

  • Deploying the project.

  • Including the approval flow in an object workflow.

For more information about human tasks, refer to the "Designing Human Tasks" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Creating the Group of Approvers

To set up parallel group approval, you must first create the group for your approvers.

  1. Sign in to the BPM worklist application.

  2. Navigate to Administration, Approval groups.

  3. Create a group named CRMCommonApprovalGroup. Note that you must give the group this name.

  4. Add the members of the group (the people you want to designate as approvers).

  5. Save the group.

Creating the Approval Flow

Next, you create the approval flow, which is based on the standard approval flow template ExtnBusinessProcessComposite.

  1. Click New on the Business Processes page.

  2. Select ExtnBusinessProcessComposite as the base template.

  3. Remove the standard human task step named SerialApproval.

  4. From the component palette on the right side of BPM Composer, drag an interactive task step into the approval flow in the same place where you removed the existing SerialApproval step.

  5. Rename the new task step (for example, ParallelApproval).

  6. Right-click the human task step and click Implement Task.

  7. At the bottom of the screen, search for all patterns and select the ParallelApprovalGroupApproval task.

    Select the ParallelApprovalGroupApproval task
  8. Click Apply changes.

  9. Right-click the human task step again and click Data Association.

  10. Map the inputs and outputs as shown in the table below.

    Inputs GroupApproval Outputs

    taskTitle

    title

    taskOwner

    taskOwner

    taskOwner

    errorAssignee

    "REJECT"

    defaultOutcome

    100

    VotingPercentage

    outcome

    taskOutcome

    Inputs and outputs

    In parallel approval, you must pay attention to the parameter votingPercentage. This parameter determines how many group members need to approve the request for the record to be considered approved. By setting the parameter to be 100, you specify that every approver in the list must approve the request.

  11. Click Apply changes.

  12. Save the process.

Deploying the Project

Finally, you deploy the project.

  1. From the main menu, select Deployment, Deploy Project.

  2. In the Deploy Project dialog box, enter the following:

    Field Value

    Revision ID

    Provide an identifiable ID.

    Deployer User Name

    Your sign-in name.

    Password

    Your password.

    Mark composite revision as default

    Select this option.

  3. Click Deploy.

    A confirmation message appears after the project has been deployed successfully.

Including the Approval Flow in an Object Workflow

Now you can create an approval workflow that includes a parallel list of approvers. To do this, create an object workflow that uses the ParallelApproval flow that you created above.

  1. Make sure you're in an active sandbox.

  2. In Application Composer, click Object Workflows.

  3. Enter a name for the object workflow, and select an object (for example, Opportunity).

  4. Click Create.

  5. Click the Create icon next to Business Process Flow.

  6. Enter a name for the flow.

  7. Click Search next to Project Name.

  8. Select GroupApproval from the list and click OK.

  9. Click Save.

When the object workflow is triggered, all the users that are part of CrmCommonApprovalGroup will see the approval request. Based on the voting percentage, the outcome of the approval task is determined. In this example, because we mapped votingPercentage to 100, all the members of the group must approve the task before the record is finally approved.

The flow is considered complete when the specified percentage of members of the approval group (in this case, 100%) approve the request. If any member of the group rejects the request, then the record's status is changed to Rejected.

Set Up Supervisor Hierarchy Approval

You can create an approval workflow that requires approval from a hierarchical group of approvers. This is called supervisory hierarchy approval. You manage this using Oracle Business Process Manager (BPM) and object workflows.

This topic describes the following:

  • Creating the approval flow.

  • Deploying the project.

  • Including the approval flow in an object workflow.

For more information about human tasks, refer to the "Designing Human Tasks" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Creating the Approval Flow

Next, you will create the approval flow, which is based on the standard approval flow template ExtnBusinessProcessComposite.

  1. Click New on the Business Processes page.

  2. Select ExtnBusinessProcessComposite as the base template.

  3. Remove the standard human task step named SerialApproval.

  4. From the component palette on the right side of BPM Composer, drag an interactive task step into the approval flow in the same place where you removed the existing SerialApproval step.

  5. Rename the new task step (for example, SupervisorHierarchyApproval).

  6. Right-click the human task step and click Implement Task.

  7. At the bottom of the screen, search for all patterns and select the SerialSupervisorHierarchyApproval task.

  8. Click Apply changes.

  9. Right-click the human task step again and click Data Association.

  10. Map the inputs and outputs as shown in the table below.

    Inputs GroupApproval Outputs

    taskTitle

    title

    taskOwner

    taskOwner

    taskErrorAssignee

    errorAssignee

    Integer representing the number of levels in the hierarchy (for example, 4)

    noOfLevels

    User name of user at top of hierarchy (for example, 'lisa.jones')

    startingParticipant

    outcome

    taskOutcome

    Inputs and outputs

    In the inputs to the SerialSupervisorHierarchyApproval human task, you can provide the starting approver, up-to approver, or number of levels.

  11. Click Apply changes.

  12. Save the process.

Deploying the Project

Finally, you will deploy the project.

  1. From the main menu, select Deployment, Deploy Project.

  2. In the Deploy Project dialog box, enter the following:

    Field Value

    Revision ID

    Provide an identifiable ID.

    Deployer User Name

    Your sign-in name.

    Password

    Your password.

    Mark composite revision as default

    Select this option.

  3. Click Deploy.

    A confirmation message appears after the project has been deployed successfully.

Including the Approval Flow in an Object Workflow

Now you can create an approval workflow that includes a parallel list of approvers. To do this, create an object workflow that uses the ParallelApproval flow that you created above.

  1. Make sure you're in an active sandbox.

  2. In Application Composer, click Object Workflows.

  3. Enter a name for the object workflow, and select an object (for example, Opportunity).

  4. Click Create.

  5. Click the Create icon next to Business Process Flow.

  6. Enter a name for the flow.

  7. Click Search next to Project Name.

  8. Select SerialSupervisorHierarchyApproval from the list and click OK.

  9. Click Save.

When the object workflow is triggered, the starting approver (in our example, lisa.jones) receives the approval notification. When lisa.jones approves, the request is routed to her manager, and so on until the specified number of levels (in our example, 4) are reached. When approvers at all specified levels approve the request, the record is considered to be approved.

Multiple Approvals on a Single Record

You can set up a record to request a single approval or multiple approvals. If you request multiple approvals, you can do it in one of two ways:

  • Single approval status field

  • Multiple approval status fields (one for each approval)

Single Approval Status Field for Multiple Approvals

If you use a single approval status field (for example, one named "Approval Status"), then each stage of the approval process is requested individually, one after the other. After each approval is requested and obtained, the field is set to Approved. When the record is resubmitted for the next approval, the field is set to Pending Approval and the process is repeated until all required approvals are obtained.

Using Multiple Approval Status Fields for Multiple Approvals

The best practice is to use multiple approval status fields, which makes it easier to differentiate each approval on the record. This is especially true if some business logic depends on each approval.

Multiple approvals are processed in serial fashion; you can submit a new approval only after the previous approval process on the record has been completed.

Here's an example of how you might set up multiple approval status fields.

  1. Start by creating a fixed choice list (for example, Stage Status) including each record that will need approval. In this example, these are:

    • Technical Proposal

    • Financial Proposal

    • Contract

  2. Next, create a fixed-choice list including each approval status (you can use the standard list values from ZCX_HOLD_STATUS):

    • Technical Approval Status

    • Financial Approval Status

    • Contract Approval Status

  3. Create a new BPM process using Default Serial Approval Process.

  4. Create three workflows with the following criteria:

    • heldEntityStatusField = 'TechnicalApprovalStatus_c'OWF criteria: isAttributeChanged('StageStatus') && StageStatus = 'Technical Proposal'

    • heldEntityStatusField = 'TechnicalApprovalStatus_c' OWF criteria: isAttributeChanged('StageStatus') && StageStatus = 'Technical Proposal'

    • heldEntityStatusField = 'ContractApprovalStatus_c' OWF criteria: isAttributeChanged('StageStatus') && and StageStatus = 'Contract'

For the first approval, the Sales officer prepares the Technical Proposal document with revenue lines and sends it for manager approval. After it is approved, the Technical Approval Status field is changed to Approved. The same document is submitted to the customer for signature.

For the second approval, the sales officer prepares the Financial Proposal document (which lists payment terms) and submits it for approval by the Regional Manager and the CEO. After it is approved, the Financial Approval Status field is changed to Approved. The same document is submitted to the customer for signature.

For the third approval, after several stages in Opportunity, the Contract document is prepared and sent for approval by the CEO and Regional Manager. After it is approved, the Contract Approval Status field is changed to Approved. The document is submitted to customer for contract activation. If the customer rejects the terms, revise the contract and repeat the third approval process.

Error Behavior

If multiple approvals are submitted in parallel, then error notifications should be sent to the opportunity owner, who can manually ensure that the approval is resubmitted after the current approval is completed.

Example of Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads

This topic contains an end-to-end example showing how you configure an object workflow to trigger approval requests for creating sales leads.

You're a sales administrator and your management has asked you to create a workflow to automate the business process as follows:

  1. An approval process should be triggered when a sales representative creates a sales lead with a deal amount greater than USD 100000.

  2. When the approval process is triggered, the sales manager of that representative should automatically receive a request for approving the deal.

You use three applications and two roles to configure and test the automated flows; therefore, for ease of understanding, the end-to-end procedure has been logically organized under the following steps:

  1. Creating a field to track the approval status.

    You use Application Composer to create a custom field to track the status of approvals.

  2. Publishing the sandbox and verifying the addition of the field.

    You publish the sandbox to bring the custom field into the mainline metadata.

  3. Creating and deploying an approval flow.

    You use the Oracle Business Process Composer to create and deploy an approval flow.

  4. Creating object workflow to trigger the approval flow.

    You create an object workflow using the Sales Lead object and set the trigger condition on the Deal Amount field.

  5. Triggering and testing the object workflow and approval flow.

    You trigger the object workflow, test the triggering of the associated approval flow, approve the request using Worklist, and then verify the approval.

Step 1: Creating a Field to Track the Status of Approvals

In this step, you create a field to track the status of the approval and add this field to the desired pages.

  1. Sign in using Administrator role.

  2. Create a sandbox and activate it.

    For more information on sandboxes, see Sandboxes: Explained topic.

  3. Navigate to Application Composer.

  4. In the left pane, expand Standard Objects.

  5. Expand Sales Lead.

  6. Click Fields.

    Fields page opens.

  7. Under the Custom tab, select Action > Create.

    Select Field Type dialog box appears.

  8. Select Text.

  9. Click OK.

    Create Text Field page opens.

  10. In the Appearance region, enter Large Deal Approval in the Display Label field.

  11. Click Save and Close.

  12. In the left pane, select Pages under Sales Lead.

    Sales Lead: Pages page opens.

  13. Under Desktop Pages tab, click Create Lead.

    Create Lead page opens.

  14. In the Configure Detail Form region, move the Large Deal Approval field from the Available Fields box to the Selected Fields box.

  15. Click Save and Close.

    You have now added a custom approval field to the Create Lead page. You're back to Sales Lead: Pages page.

  16. Under Desktop Pages tab, click Show Details.

    Show Details page opens.

  17. In the Configure Detail Form region, move the Large Deal Approval field from the Available Fields box to the Selected Fields box.

  18. Click Save and Close.

    You have now added a custom approval field to the Show Details page.

    Note: You're currently working within your sandbox. You have created a custom field and have added that field to two pages. Configurations done within a sandbox for object workflows aren't available to the mainline metadata unless published.

Next, publish your sandbox to make your changes available for use in the mainline metadata.

Step 2: Publishing the Sandbox and Verifying the Addition of the Field

In this step, you publish your sandbox and verify that the Large Deal Approval field has been added to Create Lead and Show Details pages.

For more information on creating and managing sandboxes, and the considerations involved when working with sandboxes, see Sandboxes: Explained topic and its related topics.

To publish the sandbox and verify the addition of the fields:

  1. On the Sandboxes page, select your sandbox and click Publish.

  2. Click the Navigator menu at the top.

  3. Click Lead Qualification under Sales.

  4. Click Create Lead.

    Create Lead page opens.

  5. Verify that Large Deal Approval field has been added to the Create Lead page.

  6. Click Cancel. You create a deal later in this example.

Step 3: Creating and Deploying an Approval Flow

In this step, you create and deploy a business process (also called project) for approval flow using Oracle Business Process Composer.

For more information on working with business process flows, see related topics Object Workflows and Business Processes: Critical Choices and Object Workflows and Business Processes: How They Work Together.

To create and deploy a process using Oracle Business Process Composer:

  1. Navigate to Application Composer.

  2. Select Business Processes.

    Business Processes page opens.

  3. Select Actions > Create.

    The Create Business Process Flow dialog box appears.

  4. Enter Sales Lead Approval in the Name field.

  5. Click OK.

    Oracle Business Process Composer opens in a separate Window.

    Note: If a blocker is enabled on your browser, the business process composer may not open after you click OK, and your browser may get locked. If that happens, use the browser back button to go back to the Business Processes option in Application Composer, and click Edit for the business process (approval flow) that you were creating.

    For this example, you're using a seeded template called ExtnBusinessProcess on an as is basis. You can edit this template to suit your business case. For more information on this template, see the Object Workflows and Business Processes: Critical Choices topic.

    This figure shows the seeded template.

    Shows the seeded template ExtnBusinessProcess with
the basic CrmCommonSerialApprovalProcess flow.
  6. Click Deploy Project using the main menu.

    This figure shows the main menu.

    Main menu in business process composer

    The Deploy Project dialog box appears.

  7. In the Deploy Project dialog box, enter the following information:

    Field Value

    Revision ID

    Provide an identifiable ID.

    Deployer Name

    Your sign in name.

    Password

    Your password.

    Mark composite revision as default

    Select this option.

  8. Click Deploy.

    A confirmation message appears after your project has been deployed successfully.

  9. Close Oracle Business Process Composer.

  10. Confirm as follows whether the project has been deployed successfully:

    1. On the Overview page of Application Composer, click Business Processes.

      The Business Processes page opens.

    2. A green check-mark appears under the Deployed column for the project you created.

You have now successfully deployed a project with the name Sales Lead Approval.

Next, configure an object workflow to call the Sales Lead Approval project.

Step 4: Creating Object Workflow to Trigger Approval Flow

In this step, you configure an object workflow with the required trigger condition and specify the inputs to pass from object workflow to the Sales Lead Approval process.

To configure an object workflow:

  1. Navigate to Application Composer.

  2. On the Overview page, click Object Workflows.

    The Object Workflow page opens.

  3. Select Actions > Create.

    The Create Object Workflow page opens.

  4. Select Sales Lead from the Object list.

  5. Enter Deal amount more than USD 100000 in the Name field.

  6. In the Event Point and Condition region:

    1. Select When a record is created option.

    2. Click the Expression Builder icon.

      Expression Builder opens.

      Enter if(DealAmount>100000 && CurrencyCode=='USD') return true;

    3. Click OK.

  7. In the Actions region, select Business Process Flow. Create Action: Business Process Flow page opens.

  8. Configure the event action as follows:

    1. Enter Sales Lead Approval in the Name field.

    2. In the Project Name field, search and select Sales Lead Approval project that you had created and deployed.

      This figure shows how you search and select a deployed business process (approval flow).

      Search and Select Business Process Flow
    3. Click OK.

    4. In the Inputs region, specify the input parameters that you want to pass to the deployed approval flow using the Select Default Value button. You can also type-in these parameters.

      For more information on input parameters, see Object Workflows and Business Processes: Critical Choices topic. You must mark these values as Literal to pass the values as is. Literal values appear enclosed in single quotes.

      Note: In this example, we are mapping only the mandatory parameters. For more information on the available input parameters in the default template, see Object Workflows and Business Processes: Critical Choices topic.
      Name Default Value Description of the Parameter

      approvers

      'SALES_MANAGER'

      One or more recipients of the approval request.

      heldEntityStatusField

      'LargeDealApproval_c'

      The field that holds the status of the approval.

  9. Click Save to save the event action.

  10. Click Save to save the object workflow.

You have now configured the object workflow.

Next, test whether the object workflow calls the approval flow when the trigger condition is satisfied

Step 5: Triggering and Testing the Object Workflow and Approval Flow

In this step, first trigger the object workflow and then test whether the approval flow runs fine.

  1. Sign in using Sales Representative role.

  2. Click the Navigator menu at the top.

  3. Click Lead Qualification under Sales.

  4. Click Create Lead.

    Create Lead page opens.

  5. Enter New Deal in the Name field.

  6. In the Deal Size field, select USD and enter 120000.

  7. Click Save and Close.

    Creating a lead with deal size (or amount) of more than USD 100000 triggers the object workflow, because you had set the trigger condition for object workflow as: if(DealAmount>100000 && CurrencyCode=='USD') return true;

    To verify whether the workflow has been triggered, check the status in the approval field as follows:

    1. Edit New Deal lead.

    2. Note the status in the Large Deal Approval field, which is set to APPROVALPENDING by default.

    You're currently signed in using Sales Representative role. You must first sign out and then sign in using Sales Manager role to approve the request.

  8. Sign out, and then sign in using Sales Manager role.

    A new task or request appears on the Home page under the Worklist region.

  9. Approve the request.

    You're currently signed in as a Sales Manager. You must first sign out and then sign in as a Sales Representative to verify whether the status in the Large Deal Approval field has changed.

  10. Sign out, and then sign in using Sales Representative role.

  11. Click the Navigator menu at the top.

  12. Click Lead Qualification under Sales.

    Overview page opens.

  13. Under Leads tab, click New Deal.

    Edit Lead: New Deal page opens.

  14. Verify that the status in the Large Deal Approval field has been set to APPROVED.

You have now successfully triggered the object workflow to run the associated approval flow.

Configure an Approval Process for Opportunities

In this example, you learn how to set up approvals for opportunities using a business process flow provided by Oracle.

The approval process outlined in the diagram is triggered when a condition you enter as a Groovy script is true. In this example, the process is triggered when a salesperson enters an opportunity revenue amount greater than USD 100,000. Here's what happens when the process is triggered:

  1. The approval process sends approval requests to one or more users.

    In this example, the notification is sent to one user. If you specify multiple users, then all users must approve before the opportunity is considered approved.

    You can enter identifying information into the subject line of the approval notification to help approvers understand what they're approving. In this example, you enter the opportunity name and the account. The body of the notification includes the name of the person who updated the opportunity.

  2. The approval process updates the approval status to PENDING APPROVAL to indicate that an approval request was sent.

    In this example, you create a custom field to display the status on the Edit Opportunity page.

  3. After the approver views the notification and clicks the Approve or the Reject button, the process updates the status to APPROVED or REJECTED and sends a confirmation back to the user who updated the opportunity.

  4. Optionally, the process can send an informational e-mail about the process outcome to the recipients of your choice.

Approval process described in the text

You create the approval process using Application Composer while working in a sandbox, so you can test the process before publishing it. To create the approval process, you:

  1. Create a custom text field to display the approval status.

  2. Add the custom field to the Edit Opportunity page.

  3. Create an object workflow that triggers the approvals business process provided by Oracle and supplies the required inputs, including the name of the user who receives the approval notification.

  4. Test the approval process before publishing it.

Create a Custom Field to Display the Approval Status

  1. Sign in as a sales administrator or a setup user.

  2. Activate an existing sandbox with Application Composer as one of the available tools, or create a new one.

    The sandbox name appears at the top of the page.

  3. Navigate to Application Composer.

  4. In the left pane, expand Standard Objects.

  5. Expand Opportunity.

  6. Click Fields.

  7. On the Fields page, Custom tab, select Create from the Action menu.

  8. In the Select Field Type window, select Text.

  9. Click OK.

  10. On the Create Text Field page, in the Display Label field in the Appearance region, enter Large Deal Approval.

    The applications creates the technical name and API Name based on your entry. The API name is the name followed by an underscore and the letter c (_c). You enter the API name as one of the parameters of the workflow to indicate this is the field that displays the approval status.

  11. Click Save and Close.

You're now ready to display the custom field on the Edit Opportunity page.

Display the Custom Field on the Edit Opportunity Page

  1. In the Application Composer left pane, select Pages under Opportunity.

  2. On the Opportunity: Pages page, Application Pages tab, scroll down to Details Page Layouts section and edit any custom layout. If none exists, then duplicate the standard layout and edit the resulting custom layout.

  3. In the Subtabs region, click Edit for the Summary.

  4. In the Edit Summary page, move the Large Deal Approval field from the Available Fields box to the Selected Fields box.

  5. Click Save and Close.

  6. Click Done.

  7. Click the Application Composer link at the top left corner of the screen to return to the Application Composer Overview page.

Create an Object Workflow to Trigger the Approval Flow

With the sandbox still active, configure an object workflow with the trigger condition and the inputs to pass to the approvals process.

  1. On the Application Composer page, make sure that Sales is still selected as the Application.

  2. Click Object Workflows.

  3. On the Object Workflow page, select Create from the Actions menu.

  4. On the Create Object Workflows page, select Opportunity from the Object list.

  5. Enter Deal amount more than USD 100000 in the Name field.

  6. In the Event Point and Condition region:

    1. Select the When a record is updated option.

    2. Click the Groovy Builder icon, highlighted with callout 1 in the screenshot

      Create Object Workflow page

      In the Expression Builder window, enter the Groovy script: if (nvl(Revenue,0)>100000 && isAttributeChanged('Revenue')) return true;

      You can ignore the warning.

    3. Click OK.

  7. In the Actions region, click Create (the plus icon on the right side of the page) for Business Process Flow.

  8. In the Create Action: Business Process Flow page, enter Opportunity Approval in the Name field.

  9. In the Project Name field, search and select ExtBusinessProcessComposite. This is the name of the approval business process provided by Oracle.

  10. The Inputs region lists the parameters you can pass to the business process. In the Inputs region, make the following entries:

    1. In the approvers field, enter the user name of the user who's to receive the approval notifications in single quotation marks. For example:'lisa.jones'.

    2. In the heldEntityStatusField, enter the API name of the custom field you created in single quotation marks. For example: 'LargeDealApproval_c'.

    3. In the emailAddress field, enter the e-mail addresses in single quotations of people you want to be notified of the process outcome. Separate multiple e-mails with commas. For example: 'JoanneWong@nomail.com', 'tanakas@nomail.com'

    4. In the title1 and title2 fields, enter the two fields that you want to display in the subject line of the notification:

      The notification subject line appears as: Opportunity <title1><title2> Is Submitted for Your Approval

      In this example, we are adding the opportunity name and the account fields, so make the following entries in the Default Value field:

      • For title1, enter Name.

      • For title2, enter AccountName.

      You can view all of the fields available for insertion, by clicking Select Default Value, the function icon to the right of the field, highlighted by callout 1 in the screenshot.

      Create Action: Business Process Flow page

      Here's how to insert a field:

      1. Select the field.

      2. Click Insert to move the field to the Value region.

      3. Click OK.

  11. Click Save and Close.

Test the Approval Flow

To test the approval flow, create an opportunity and enter a revenue amount greater than USD 100,000. Then sign in as the approver to view the notification and approve.

  1. While signed in as the same user who performed the setup, click the Home icon to return to the springboard.

  2. Double-click on the Sales icon and on the Opportunities icon to open the Opportunities work area.

  3. Click Create Opportunity.

  4. In the Create Opportunity page, enter a name.

  5. Click Save and Continue.

  6. On the Edit Opportunity page, click Add in the Products region to add a revenue line to the opportunity.

    Notice that the Large Deal Approval field you added to the page doesn't display a status. This is because the approval flow is not triggered yet.

  7. Enter a product group or a product and an amount greater than 100000 to trigger the approval workflow.

  8. Click Save and Close.

    Saving triggers the approvals process.

  9. Wait a few minutes to let the approval process run and view the opportunity again. The Large Deal Approval field now displays PENDING APPROVAL.

  10. Sign out by clicking the user name and the Sign Out link.

  11. Sign in as the approver.

  12. Click Notifications (the bell icon) at the top of the screen.

    The Recent Notifications window displays the new approval notification.

  13. Click the notification subject line to display the notification body and click Approve .

  14. Sign out and sign in again as the administrator.

  15. Click Notifications (the bell icon) at the top of the screen.

    The Recent Notifications window displays the approval confirmation.

  16. Navigate back to the Opportunities work area and view the opportunity you created.

  17. The Large Deal Approval field displays APPROVED.

  18. You must publish the Sandbox if you want to make the opportunity approval available for use.

Object Workflows and Groovy Scripts

This topic explains how you use object workflows to trigger Groovy scripts. When you configure object workflows, you also specify the actions that the workflow must perform when triggered. One of the actions you configure is the Groovy Script action.

Before you begin, you might want to read Object Workflows: Explained and its related topics to familiarize yourself with what object workflows are, how you set trigger conditions, and the event actions that object workflows support.

Overview

A Groovy script action in an object workflow lets you call an external Groovy object function that has been previously defined. For example, you might trigger a Groovy action to perform cross-object updates, perform post-processing of large object hierarchies, or asynchronously call Web services.

As a simple example, let's assume that when you close an opportunity, you also want to close all the associated activities for that opportunity.

Using a trigger could cause a delay if the opportunity includes many associated activities, so instead you define an object workflow to trigger when the opportunity's status is updated to Lost. The object workflow calls a Groovy object function that queries the activities related the opportunity and sets their status to "Canceled."

Note: Typically, real-world processing logic used in Groovy script actions is much more complex than the simple example described here.

You configure a Groovy Script action in object workflows by defining an object function, then creating an object workflow that, when launched at run time, executes the object function. For examples of how you configure various event actions in object workflows, see Configuring Object Workflows: Worked Example and Configuring Object Workflows to Trigger Approval Requests for Creating Sales Leads: Worked Example.

Configuring a Groovy Script Action in Object Workflows

Object workflows contain a set of actions that can be run when the workflow is triggered. One of these actions is the Groovy Script action.

To configure a Groovy Script action:

  1. Navigate to Application Composer.

  2. On the Overview page, click Object Workflows.

  3. Select Create from the Actions menu.

    The Create Object Workflow page opens.

  4. Specify a name for your workflow.

  5. Specify the trigger condition in the Event Point and Condition region.

  6. Under the Actions region, click Create for Groovy Script.

    Create Object Workflow page showing Groovy Script
option under Actions

    The Create Action: Groovy Script page opens. You use this page to specify the Groovy object function you want to call.

    This figure shows the Create Action: Groovy Script page.

    Create Action: Groovy Script page
  7. Provide a meaningful name for your Groovy Script action.

  8. Specify an Execution Schedule.

  9. Select a Method Name from the drop-down list. This list displays all Groovy object functions that are visible to the action. You can also click the plus sign next to the Method Name field to display the Create Object Function page and define a new function. See Defining an Object Function for Use in Object Workflows.

    The script appears in read-only form in the Script field.

  10. Click Save.

Defining an Object Function for Use in Object Workflows

If you haven't previously defined an object function to select from the Method list on the Create Action - Groovy Script page when creating your object workflow, you can define one directly from that page. To define an object function for use with the Groovy Script action:

  1. On the Create Action - Groovy Script page, click the plus sign next to the Method Name field.

    The Create Object Function page displays.

  2. Enter a name for the function.

  3. Select void in the Returns field.

    Create Object Function page showing required elements
for a Groovy function usable with Object Workflows
  4. Select Callable by External Systems in the Visibility field.

  5. Do not specify any input parameters.

  6. Enter the script in the Edit Script field.

  7. Click the Validate button to validate the script, and fix any errors.

  8. Click Save and Close.

Your object function is now ready to be called by a Groovy Script action in your object workflow. You can select it from the Method list when configuring an object workflow's Groovy Script action.

Configure Object Workflows

This example demonstrates how to create an object workflow and set a trigger condition for invoking (or launching) the workflow. The trigger condition that will launch the workflow will be when the budget availability date for an opportunity is updated.

As part of the example, you configure these three event actions:

  • Field Updates: Set the opportunity Close Date to 7 days from the new budget availability date. Additionally, lower the Level of Risk for the opportunity and set the Strategic Value to Medium.

  • Task Creation: Create a task for the opportunity owner to follow up with the customer.

  • E-mail notification: First, create an e-mail template for sending e-mail notifications. Then, notify the entire opportunity team about the change in the budget availability date using e-mail.

This example has been split into the following steps:

  1. Creating a workflow and setting its trigger condition.

  2. Configuring a Field Updates event action.

  3. Configuring a Task Creation event action.

  4. Creating an E-Mail Template and then creating an E-Mail Notification event action.

  5. Creating an Opportunity record.

  6. Editing the Opportunity Record to Trigger the Workflow and Verifying the Invoked Event Actions.

1. Creating an Object Workflow and Setting its Trigger Condition

In this example, you create an object workflow using an Opportunity object and create a trigger condition for the workflow using Groovy script. When the budget availability date is changed, the workflow will be triggered.

  1. Click the Navigator menu.

  2. Click the Application Composer link.

    Note: You might need to click the more >> link if you don't see Application Composer.

    The Overview page of Application Composer appears. This page shows the various tasks available to modify and extend your application. In this activity, you are configuring a workflow for the Opportunity object.

  3. In the Overview region, click the Object Workflows link.

    The Object Workflows page appears. You can use this page to search for an existing workflow or create a workflow. In this activity, you create a workflow.

  4. Click the Actions menu below the Search region.

  5. Click the Create menu item.

    The Create Object Workflow page appears.

  6. You must first select an object for which you are creating a workflow. Click the Object list.

  7. Click the Opportunity list item.

  8. Enter "Budget Date Revised" in the Name field.

  9. In the Event Point and Condition region, click the When a record is updated option.

  10. You set the trigger condition using Groovy script. Launch the expression builder to create the condition. In the Event Point and Condition region, click the expression builder button to open the expression builder.

    The Expression Builder dialog appears.

  11. Before you proceed, ensure that the Fields tab is selected.

  12. Identify the correct application programming interface (API) name for the field you want to use for defining your trigger condition. Under the Display Label column in the Opportunity: Fields table, locate and click the Date Budget Available cell.

  13. Insert Date Budget Available into the expression builder. Click the Insert button.

  14. Enter your script in the Expression area using the BudgetDateAvailable field you just inserted. Write a script that meets all of these conditions:

    1. Only the BudgetAvailableDate is updated.

    2. The BudgetAvailableDate is not null.

    3. The opportunity record that you create is updated.

    The following script has been written for you using the BudgetDateAvailable field:

    if(isAttributeChanged('BudgetAvailableDate') && 'BudgetAvailableDate' != null && contains(Name, ' 50 Solar Green Servers')) { return true; } else { return false; }

  15. Validate your script. Click the Validate button.

  16. Click the OK button.

  17. You have set the event point and trigger condition for your object workflow. You now create a Field Updates event action. In this event action, you specify the values with which the Close Date, Level of Risk, and Strategic Value values will be replaced when the field updates action is triggered.

2. Configure a Field Update Event Action

Continuing from the previous step, you are on the Create Object Workflow page. In this step, you configure Field Updates event action for the object workflow and set new values for fields when the workflow is triggered.

  • Set the Close Date to 7 days from the new budget availability date.

  • Lower the Level of Risk from High to Low.

  • Set the Strategic Value to Medium.

  1. In the Actions region, click the Create button on the right of the Field Updates action.

    The Create Action: Field Updates page appears.

  2. Enter "Update Close Date" in the Name field.

  3. In the Execution Schedule region, keep the default setting, which is to update fields right away when the workflow is triggered.

  4. In the Field Update Details region, click the Field to Update list.

  5. Click the Close Date list item.

  6. Click the Value list.

  7. Click the Date Budget Available list item.

  8. Make sure the '+' operator is selected, and enter "7" in the Days field.

  9. Click the Update More Fields link.

  10. Click the Field to Update list.

  11. Click the Level of Risk list item.

    You will lower the Level of Risk for an opportunity when the workflow is triggered. The values in the Level of Risk field are in a descending order of High, Low, and None; therefore, when you select the Populate with next value in list option for Level of Risk, the risk level will be lowered by one step. For example, if the initial value is High, it will change to Low when the workflow is invoked, because Low is the next value in the list.

  12. Click the Populate with next value in list option.

  13. Click the Update More Fields link.

  14. Click the Field to Update list.

  15. Click the Strategic Value list item.

  16. Click the list on the right of the Value group of options.

  17. Click the Medium list item.

  18. Save the Field Update event action. In the upper-right region of the page, click the Save button.

    You're back to the Create Object Workflow page. Now you create a Task Creation event action for the sales team to follow up with the customer.

3. Configuring a Task Creation Event Action

Continuing from the previous step, you are on the Create Object Workflow page. In this example, you configure a Task Creation event action for an object workflow. A task will be created for the opportunity owner to follow up with the customer.

  1. In the Actions region, click the Create button on the right of the Task Creation event action.

  2. Enter "Follow Up Call" in the Name field.

  3. In the Task Details region, enter "Follow up with customer on budget available date" in the Subject field.

  4. You now insert a field token in the Subject field. Place your cursor where you want the token to appear. In the Subject field, click after "customer".

  5. Click the field-token list on the right of the Subject field.

  6. Click the Customer list item.

  7. Click the << Insert button.

    Notice that the [$TargetPartyName$] token is inserted in the Subject where you placed your cursor. You need to adjust trailing or leading text-spaces as required.

  8. Enter "Opportunity Budget Available Date is changed. Follow up with within three days of the new available date. Primary Contact Email ID: " in the Description field.

  9. Use the field-token list on the right of the Description field to insert the following tokens one by one into the description text:

    • Opportunity Name ([$Name$])

    • Primary Contact ([$PrimaryContactPartyName$])

    • Primary Contact E-Mail ([$PrimaryContactEmailAddress$])

  10. Click after "Opportunity" in the Description text.

  11. Click the field-token list on the right of the Description field.

  12. Click the Opportunity Name list item.

  13. Click the <<Insert button.

  14. Click after "Follow up with" in the Description text.

  15. Click the field-token list on the right of the Description field.

  16. Click the Primary Contact list item.

  17. Click the <<Insert button.

  18. Click after "Email ID:" in the Description text.

  19. Click the Primary Contact E-Mail list item.

  20. Click the <<Insert button.

  21. You will now set the task's Due Date to be 3 days after the new Budget Available Date. Click the Due Date list.

  22. Click the Date Budget Available list item.

  23. Make sure the plus sign +operator is selected, and use the increment button (up arrow) to set the value in the Days field to 3.

  24. Click the Start Date list.

  25. Click the Date Budget Available list item. Accept the default 0 (zero) in the Days field.

  26. Click the Owner list.

  27. Click the OwnerResourcePartyid list item.

  28. Click the Assignees list.

  29. Click the OpportunityResourceTeam list item.

  30. Click the Category list, then click the Call, outbound list item..

  31. Click the Priority list, then click the 1 - Very high list item.

  32. Save the Task Creation event action. In the upper-right region of the page, click the Save button.

  33. You are back to the Create Object Workflow page. In the upper-right region of the page, click the Save button. This saves the object workflow.

    You now create the E-Mail Notification event action. Before you create this event action, you must first create an E-Mail Template that you use for sending e-mail notifications.

4. Creating an E-Mail Template and Configuring an E-Mail Notification Event Action

Continuing from the previous step, you are now on the Object Workflows page. In this step, you create an e-mail template, which you use for sending e-mail notifications.

  1. In the Common Setup pane on the left, click the E-Mail Templates link.

    You are on the E-Mail Templates page. You can use this page either to search and edit an existing template or to create a fresh template. In this activity, you create a template.

  2. In the Search Results region, click the Actions menu.

  3. Click the Create menu item.

    The Create E-Mail Template page appears.

  4. Click the Object list.

  5. Click the Opportunity list item.

  6. Enter Budget Available Date Update" in the Name field.

  7. Enter "Opportunity customer budget available date has changed" in the E-Mail Subject field.

  8. You now insert a field token in the E-Mail Subject field. Place your cursor where you want the token to appear. Click after "Opportunity" in the E-Mail Subject field.

  9. Click the field-token list on the right of the E-Mail Subject field.

  10. Click the Opportunity Name list item.

  11. Click the <<Insert button

  12. In the E-Mail Body region, enter "- budget available date regarding opportunity has moved to . The new opportunity close date is ." in the E-Mail Body field.

  13. In the E-Mail Body region, use the Fields list item of the Select list to insert the following field tokens:

    Field Token

    Customer

    [$PartyUniqueName$]

    Opportunity Name

    [$Name$]

    Date Budget Available

    [$BudgetAvailableDate$]

    Close Date

    [$EffectiveDate$]

    Note: Rich text formatting is available only if your e-mail account supports HTML format e-mail.

  14. Click after "- " in the e-mail body.

  15. In the E-Mail Body region, click the field-token list on the left of the Insert button.

  16. Click the Customer list item.

  17. Click the Insert button.

  18. Click after "regarding opportunity" in the e-mail body.

  19. Click the field-token list.

  20. Click the Opportunity Name list item.

  21. Click the Insert button.

  22. Click after "has moved to" in the e-mail body.

  23. Click the field-token list.

  24. Click the Date Budget Available list item.

  25. Click the Insert button.

  26. Click after "close date is" in the e-mail body.

  27. Click the field-token list.

  28. Click the Close Date list item.

  29. Click the Insert button.

  30. Save the E-Mail Template. In the upper-right region of the page, click the Save button.

    You're returned to the E-Mail Templates page.

  31. In the Common Setup pane on the left, click the Object Workflows link.

    You now create an E-mail Notification event action using the e-mail template you just created.

  32. In the Search region, click the Object list.

  33. Click the Opportunity list item.

  34. Click the Search button.

    The Name column in the search results lists the object workflows created for the opportunity object. From this list, you identify and select the object workflow that you are creating.

  35. Click the Budget_Date_Revised cell.

  36. Click the Edit button.

    The Edit Object Workflow page appears. You are editing an existing object workflow to configure and add an E-Mail Notification event action.

  37. In the Actions region, click the Create button on the right of the E-Mail Notification event action.

    The Create Action: E-Mail Notification page appears.

  38. Enter "Notify sales team about budget available date change" in the Name field.

  39. Select the e-mail template that you created. In the E-Mail Details region, click the E-Mail Template list.

  40. From the list of e-mail templates, identify and select the template that you created. Click the Budget Available Date Update template.

  41. Click the Recipient Type list.

  42. Click the Specific e-mail addresses list item.

  43. Enter the desired information into the E-Mail Addresses field.

  44. Save the E-Mail Notification event action. In the upper-right region of the page, click the Save button.

    You are returned to the Edit Object Workflow page.

  45. Save the object workflow. In the upper-right region of the page, click the Save button.

    You have now configured an object workflow with three event actions. This object workflow is invoked (launched) when you update the budget available date for the opportunity that you create.

5. Creating an Opportunity Record

In this section, you trigger the object workflow that you created in the previous steps by entering the budget availability date for an opportunity. You note down the details where the changes will occur after the workflow is triggered.

  1. Click the Navigator menu.

  2. Click the Opportunities link under Sales.

    The Overview page of Opportunities appears. You use this page to create an opportunity record.

  3. In the Opportunities region, click the Create button.

    The Create Opportunity page appears.

  4. Verify that Close Date is the current date, Sales Stage is 01-Qualification, and Win Probability (%) is 0 (zero).

  5. In the Name field, enter "50 Solar Green Servers".

  6. In the Sales Account field, enter "Solar Inc (KIRKLAND, US)".

  7. Click the Sales Account search button adjacent to the Sales Account field.

    The Search and Select: Sales Account dialog appears.

  8. In the dialog, the Solar Inc (Kirkland, US) search parameter appears in the Name field. Click the Search button.

  9. In the Search Results region, click the Solar Inc (Kirkland, US) cell.

    Note: Ensure that the All Sales Accounts tab is selected.

  10. Click the OK button.

  11. In the Revenue Items region, click the Add Row button.

  12. Enter "DG 150 Green Servers" in the Name field.

  13. Enter "50" in the Quantity field.

  14. Enter "2000" in the Estimated Price field.

  15. In the upper-right region of the page, click the Save and Edit button.

    The Edit Opportunity page appears.

  16. Expand the following if not already expanded:

    • Show More area in the Summary region.

    • Revenue Items region.

    • Activity Center region.

  17. Locate the following fields and note their current values:

    • Close Date (in the Summary region).

    • Strategic Value (under Show Less area in the Summary region).

    • Level of Risk (under Show Less area in the Summary region).

    • Date Budget Available (under Show Less area in the Summary region).

    When you update the Date Budget Available field to trigger the workflow, the values in the Close Date, Strategic Value, and Level of Risk fields should change.

  18. Under the Show Less area in the Summary region, click the Level of Risk list.

  19. Click the High list item.

  20. In the upper-right region of the page, click the Save button.

  21. You are still on the Edit Opportunity page. In the Activity Center region, click the Tasks tab.

    Currently there are no Tasks with your sign-in initials.

  22. In the Additional Details region, click the Opportunity Team tab.

  23. In the Team Members table, locate your sign-in username. You will now add another team member: Mateo Lopez.

  24. In the Opportunity Team tab, click the Add Team Members button.

    The Select and Add: Team Members dialog appears.

  25. Find a team member and click the Done button.

  26. Search and add a contact to the opportunity. This will be the primary contact for the opportunity.

  27. In the Additional Details region, click the Contacts tab.

  28. In the Contacts tab, click the Add Row button.

  29. Enter the desired information into the Name field. As you type in the contact name, the contact name and e-mail ID appear.

  30. Click the desired contact.

  31. In the upper-right region of the page, click the Save and Close button.

  32. You're back to the Overview page of Opportunities. You will now edit the opportunity record you just created and update the budget availability date to trigger the event actions.

6. Editing the Opportunity Record to Trigger the Workflow and Verifying the Invoked Event Actions

Continuing from the previous step, you are on the Overview page of Opportunities. You will trigger (launch) the object workflow that you created in the previous steps by entering the budget availability date for an opportunity.

You will also verify the following after the workflow is invoked:

  • Field Updates: Verify that the opportunity Close Date is set to 7 days from the new Budget Available Date. Verify that the Level of Risk is lowered for the opportunity and the Strategic Value is set to Medium

  • Task Creation: Verify that a task is created for the opportunity owner to follow up with the customer.

  • E-mail notification: Verify that an e-mail notification is sent to the entire opportunity team about the change in the opportunity's Budget Available Date.

  1. From the table in the Opportunities region, identify and select the opportunity record that you created. Click the 50 Solar Green Servers link.

  2. You are on the Edit Opportunity page. Before you proceed, expand the Show More area in the Summary region if not already expanded.

  3. Under the Show Less area in the Summary region, click the Date Budget Available (calendar) button.

  4. Click 9 as the date, or click any future date.

  5. In the upper-right region of the page, click the Save and Close button.

    Note: You have just changed the budget availability date and saved the record, saving the changes to the database. The object workflow will be evaluated and triggered at this time, and all the event actions will be executed. The Field Updates event action always happens first followed by other event actions in no particular order. It might take a few seconds for the updates to occur.

  6. In the table under the Opportunities region, identify and select the opportunity record that you created. Click the 50 Solar Green Servers link.

    You are on the Edit Opportunity page. The workflow is now triggered and the configured event actions have been invoked. You will now verify the invocation of Field Updates event action.

  7. In the Summary region, Close Date is now set to 7 days after the Date Budget Available value.

  8. Under the Show Less area in the Summary region, Strategic Value is now set to Medium.

  9. Under the Show Less area in the Summary region, Level of Risk has now been populated with the next value in the list, from High to Low.

    You have verified the invocation of the Field Updates event action. Now, you verify the invocation of the Task Creation event action

    In the Activity Center region, the Due Date filter under the Tasks tab may prevent your task from appearing in the invoked tasks list even after it is invoked. For example, a task having a due date after 10 days will not appear if the Due Date filter is set to Next 7 Days. In this activity, you use the All Tasks filter option to search for your invoked task.

  10. In the Activity Center region, click the Due Date list under the Tasks tab.

  11. Click the All Tasks list item.

  12. In the Tasks tab, click the arrow button adjacent to the Category list.

  13. In the Search results, locate the Subject that has your sign-in initials. Click the Follow up with customer Solar Inc on budget available date link.

    You are on the Edit Task page. Note these details:

    • The Owner of the opportunity is the owner of this task.

    • The task Assignees are persons in the opportunity sales team.

    • In the Description field, the field tokens that you had inserted when creating the Task Creation event action have been replaced with values at runtime.

  14. Click the Done button.

  15. In the upper-right region of the page, click the Save and Close button.

    You have verified the invocation of the Task Creation event action. Next, verify the invocation of the E-Mail Notification event action.

  16. In your e-mail client, locate the Subject of your e-mail. Click the Subject link.

  17. Notice that the field tokens that you inserted while configuring the e-mail notification event action have been replaced with values at runtime. You have now verified the invocation of the E-Mail Notification event action.

    You have now verified the invocation of all three event actions.

Delete Unpublished Object Workflows

You can use Application Composer to delete any unpublished object workflows and their associated actions from the current sandbox. Upon deletion, the corresponding create or update events won't be raised and none of the actions will be triggered. However, deleting an unpublished object workflow won't delete the email template or object function referenced in the object workflow actions. Also, if an action has been scheduled before the object workflow is removed, the action will continue to be executed at the scheduled time.

To delete an unpublished object workflow:

  1. In Application Composer, click Object Workflows under Common Setup.

    The Object Workflows page appears.

  2. Click the Object list and select the object whose workflow you want to delete.

  3. Optionally, if you know the name of the workflow, enter it in the Name field and specify if it's active or not using the Active list.

  4. Click Search.

    The page displays the object workflow based on the specified search criteria.

  5. Select the object workflow and click the delete icon.

  6. Click OK on the confirmation dialog.

FAQs for Creating Object Workflows

Email templates can become invalid if the corresponding template cannot be found in the file repository. This can happen if the template file was migrated elsewhere or was accidentally deleted. Contact your application administrator to attempt recovering the template (file) from the file repository. If the file cannot be recovered, delete the invalid email template and create a fresh one.

Can I specify multiple approvers when configuring a business process flow event action?

Yes. You can modify the default template to design either a parallel or serial business process flow and save it as a new project. A parallel approval is where any one approval is sufficient from the approvers specified in the process flow. A serial approval is where all the approvals are required sequentially from the specified approvers.