19Approval Workflows

This chapter contains the following:

With approval management in BPM Worklist, you configure workflow tasks that users act on for approvals, including the notifications involved. For example, specify levels of approval needed, control approval routing, and configure email notifications. After all assignees approve a workflow task, whatever got approved takes effect. Some tasks are just FYI, and assignees don't need to do anything. Either way, here are some examples of what you can do to configure workflow tasks, including notifications:

  • Set how many levels of approval are needed for transactions over a particular amount

  • Define whom the assignees would be, based on the supervisory hierarchy in Oracle Fusion Cloud HCM

  • Create approval groups so that the workflow task can be assigned to the set of users in the group instead of an individual user

  • Control when to send notifications to users involved with the task

  • Disable or enable in-app or email notifications, or both

Get Started

In the Offerings work area, enable the Approval Routing Administration feature at the offering level so that these setup tasks are available in the Application Extensions functional area:

  • Manage Task Configurations

  • Manage Approval Groups

These setup tasks take you to BPM Worklist, where you do most of the setup and configuration related to workflow. But, depending on your offering, you might use a different functional area or even another approval setup task. Some product families have pages or tools that you can use instead of, or in addition to, BPM Worklist, depending on what you want to configure.

Manage Workflow Tasks

After users create a task, for example by submitting something for approval, you can use the Transaction Manager: Transactions page in the Transaction Console work area to keep track of the workflow task. And also to jump in when you need to, especially if something goes wrong.

For workflow data, you can use the tables that start with FND_BPM in the Oracle Applications Cloud Tables and Views for Common Features guide, and the Manage Tasks API in the REST API for Common Features in Oracle Applications Cloud guide. Don't query other tables or use other APIs that aren't documented.

Create Approval Groups

An approval group is a set of users that can act on workflow tasks. You can set up tasks so that at some point in the approval flow they get routed to an approval group instead of an individual user. An approval group can contain other approval groups.

  • When a task is assigned to an approval group in a parallel participant, someone in the group can claim the task and act on it. When the task is claimed, no one else in the group can act on it. But if the person who claimed the task releases it, then someone else from the group can claim it.

  • If it's a serial participant instead, the task is routed to each member of the approval group in sequence, so everyone must act on it.

  • There are two types of groups in workflow. One is the approval groups we are talking about here that you can use in task configurations to define routing. The other is LDAP groups that are available for users to select when they delegate or reassign tasks, but it's not recommended for them to use LDAP groups.

There aren't any predefined approval groups, so it's up to you if you want to create any. Here's how you go about it:

  1. In the Setup and Maintenance work area, go to the Manage Approval Groups task in the Application Extensions functional area.

  2. In BPM Worklist, on the Approval Groups tab, click the Create Approval Group icon in the Groups toolbar.

  3. On the Details page, enter the group name.

  4. In the Members section, click the Add Member icon.

  5. In the Add to Group dialog box, select User or Approval Group, depending on what you want to add to your group.

  6. Find and select the specific user or group, and click OK.

  7. Add more members, and edit or delete any if you need to.

    Note: For approval groups that you plan to use in serial participants, add members in the order that you want tasks to get assigned. If you add User 1, User 2, and then User 3, the task is first assigned to User 1, then User 2, and finally User 3.
  8. Click Save.

Caution: Don't delete your approval group if it's used in at least one approval rule. You can still edit the group.

Configure Approval Rule Sets and Rules

Rule sets and rules control how a workflow task is routed, assigned, and completed, based on specific conditions. For example, a rule can say that for a transaction that costs more than a certain amount, approvals must go up three levels in the management chain. A workflow task has one or more rule sets, and a rule set has one or more rules. At run time, if a rule set has multiple rules, all the rules are evaluated at the same time. A rule has two parts, an If section that has the conditions, or tests, and a Then section that has the actions to take when the conditions are met.

Configure Rule Sets

First, create or find the rule set you want to work on:

  1. In the Setup and Maintenance work area, go to the Manage Task Configurations task in the Application Extensions functional area. Or, depending on your offering, you might use a different functional area or another approval setup task.

  2. In BPM Worklist, on the Task Configuration tab, search for the workflow task in the Tasks to be configured pane.

  3. Select the task from the search results and click the Edit task icon in the toolbar.

    Note: You may see a message saying that flexfields have been modified. This means someone used Application Composer to create new fields, which creates flexfields on the back end. Click the Start Synchronization button to get the latest set of flexfields that you can use for the rules in this task.
  4. Click the Assignees subtab.

  5. If the diagram mapping out the workflow task is big, click the Switch to Vertical Layout link.

  6. In the diagram, find the participant you want to work on. Click the Go to rule icon and select Go to rule. Or, select the participant and, in the pane after the diagram, click the link in the Business rule field.

  7. Go on to work on the rule set that's displayed. Or, in the Rule Sets section, select another rule set to edit (or delete, if possible), or click the Add Rule Set icon.

  8. Click the Show Advanced Settings icon before the rule set name to see the Effective Date list and Active check box. The rule set needs to be effective and active to apply when people create workflow tasks. It's a good idea to leave the effective date set to Always.

  9. Now you're ready to add, edit, or delete rules in the rule set. Expand the rule if it's not already. As with the rule set, you can click the Show Advanced Settings icon for a rule to make sure that the rule is effective and active.

Here's a screenshot to help us understand what we see in the Assignees tab:

The Assignees tab where you configure rule sets
and rules
Callout Number What It Is

1

The Rule Sets section, where you can select a rule set to work on or create a new rule set.

2

The rule set name, with the Show Advanced Settings icon.

3

The toolbar for working on rules within the rule set.

4

The names of the rules in the rule set, each with the Expand icon and the Show Advanced Settings icon.

Configure the If Section in Rules

In the If section of the rule, define conditions for the rule. Each line in this section is called a test.

  1. Click the Left Value icon to select an attribute in the Condition Browser dialog box.

    Note: Even though you can find attributes starting at the Tasks folder, payload subfolder, and then going from there, it's better to select the same attribute from another folder other than Task, if available.
  2. Select an operator.

  3. Click the Right Value icon to select something from the Condition Browser dialog box, or enter a value in the corresponding field.

  4. Click the icon at the end of the line, after the Right Value icon, for more options. For example, select (...) to get an and or or toggle and add another line. You can also select Delete Test to remove a line.

    Caution: If the attribute you're evaluating in the condition is optional, users might not have entered something for that attribute in the UI. For your rule to work properly, it's highly recommended that you first have a line in the condition that checks if the attribute isn't blank. So that means you select the attribute, select isn't as the operator, enter null, click the icon at the end of the line, and select (...) to get an and. Then the next line would be the condition that you're evaluating the attribute for.

Configure the Then Section in Rules

In the Then section of the rule, define what happens when the conditions in the If section are met.

  1. Edit any existing actions. Or, click the Add Action icon, and you usually select Add Approver and then a list builder, which controls how to route the task.

  2. Fill in the rest of the section. The fields you get depends on the list builder, but here are some that you might use.

    Field What This Is

    Response Type

    Required: The assignee needs to take action, for example to approve or reject.

    FYI: The assignee doesn't need to take action.

    Number of Levels

    Number of levels required for the task to be completely approved, from the starting participant to the top participant.

    Starting Participant

    The first assignee in the approval chain.

    Top Participant

    The last assignee in the approval chain if the chain goes up that high. Approvals don't go beyond this participant, for example in the supervisory hierarchy.

    Auto Action Enabled

    If set to True, there's an automatic action that is taken on the task when the rule conditions are met.

    Auto Action

    "APPROVE": The task is automatically approved.

    "REJECT": The task is automatically rejected.

    Rule Name

    The name of the rule with the Then section that you want to use.

    • Leave the field with the name of the rule you're working on, to indicate that this rule will use the Then section defined here for this rule.

    • Or, you can enter the name of an existing rule from any task, enclosed with quotation marks, and leave all the other fields in this Then section blank. The Then section in the rule you entered would apply to this rule you're working on. So basically, you're reusing the Then section from another rule.

    To select the starting or top participant:

    1. Click the Starting Participant or Top Participant icon.

    2. In the Add Hierarchy Participant dialog box, select the Get User option for a particular user, or Get Manager for an attribute, such as the task creator.

    3. For the Get Manager option only, select the list builder that's used for the rule.

    4. For the Get User option, enter in the Reference User field the user ID that the user signs in with, enclosed in quotation marks, for example "KLEE".

      For the Get Manager option, here's what you do for the Reference User field:

      1. Click the Expression Builder icon.

      1. In the Variables tab of the Expression Builder, select the attribute you want in the hierarchy. For example, expand Task > payload and find your attribute there.

      2. Click the Insert Into Expression button.

      3. Click OK.

    5. Leave the Effective Date field blank to use the latest hierarchy, for example supervisory hierarchy.

    6. Click OK.

    What shows up in the Starting Participant or Top Participant field reflects what you have in the Add Hierarchy Participant dialog box. Here are a couple of examples.

    • HierarchyBuilder.getManager("supervisory",Task.payload.Owner User Name,-1,"","")

      Part of the Participant Value What This Means

      getManager

      You selected the Get Manager option.

      "supervisory"

      You selected the Supervisory list builder.

      Task.payload.Owner User Name

      For the Reference User field, you went to Task > payload > Owner User Name in the Variables tab to select the Owner User Name attribute.

      -1

      This is the default value, which corresponds to the primary employment assignment. That supervisory hierarchy will be used to find assignees for the task.

      "",""

      You left the Hierarchy Type and Effective Date fields blank, so there's nothing between the quotation marks.

    • HierarchyBuilder.getPrincipal("KLEE","","")

      Part of the Participant Value What This Means

      getPrincipal

      You selected the Get User option.

      "KLEE"

      For the Reference User field, you entered "KLEE".

      "",""

      You left the Hierarchy Type and Effective Date fields blank, so there's nothing between the quotation marks.

  3. In the Tasks to be configured toolbar, click the Commit task icon when you're ready to roll out your changes.

Example of a Rule

Let's take a look at an example of a rule. In the If section, we have two tests, the first checking if an attribute is a specific value, the second checking if an attribute is more than a certain amount. The attribute names reflect where the attribute is in the hierarchy you get in the Condition Browser dialog box. The and connecting the two tests means that both conditions must be met.

Example of the If section in a rule

In the Then section, there's the action that applies if the conditions are met, and it's defined based on a Supervisory list builder. Assignees must take action, and only one approval is needed.

Example of the Then section in a rule

When workflow tasks are assigned to users, they get notifications through email. They also get in-app notifications in the Things to Finish section on the home page and the notifications list in the global header. From these two places, users can open the Notifications page to see all their in-app notifications. If you have BPM Workflow System Admin Role (BPMWorkflowAdmin), you can disable or enable these email and in-app notifications for all users. For example, you can disable notifications when you're testing changes to approval rules. That way you don't send test notifications to users. And then when you're ready, enable notifications again.

Here are things to know about disabling workflow notifications:

  • You disable only email notifications that are sent as part of workflow tasks, not all emails in general.

  • Users can still find their workflow tasks in the Worklist: Notifications and Approvals work area.

Set the Notification Mode

Here's how you disable or enable workflow notifications:

  1. Click the Notifications icon in the global header.

  2. Click Show All.

  3. On the Notifications page, click the Worklist button.

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

  5. On the Administration tab, open the Application Preferences page and go to the Notification section.

  6. Select a value from the Notification Mode list:

    • All: This is the default value.

      • Email notifications are enabled.

      • Workflow notifications are included in the global header, home page, and Notifications page.

    • None:

      • Email notifications are disabled.

      • Workflow notifications aren't included in the global header, home page, and Notifications page.

    • Email:

      • Email notifications are enabled.

      • New workflow notifications won't appear in the global header, home page, and Notifications page.

    • In-app:

      • Email notifications are no longer sent.

      • Workflow notifications in the global header, home page, and Notifications page are enabled.

  7. Click Save.

Define When to Automatically Dismiss or Withdraw Workflow Tasks

For a workflow task to be purged and removed from users' worklists, it must have a final status, like Completed or Withdrawn. Tasks go from the Assigned status to the Completed status when the final assignee approves or rejects the tasks. For your information (FYI) tasks get a final status when assignees explicitly dismiss the tasks. If assignees don't do anything within a certain period of time that result in a final task status, the tasks are automatically dismissed (FYI tasks) or withdrawn (all other tasks).

When FYI Tasks Are Eligible to Be Automatically Dismissed

The FYI Notifications Expiration Period (FND_NOTIFICATION_EXP_PERIOD) profile option controls when FYI tasks are eligible to be automatically dismissed.

  1. In the Setup and Maintenance work area, go to the Manage Applications Core Administrator Profile Values task in the Application Extensions functional area.

  2. On the Manage Applications Core Administrator Profile Values page, leave the profile option with the default value of 7 at the Site level, or replace it with a different number.

The profile value represents the number of days after the FYI task is created. When assignees don't read or dismiss an FYI task within this many days after the task was created, the task is then eligible to get automatically dismissed.

When All Other Tasks Are Eligible to Be Automatically Withdrawn

All other tasks (the ones that aren't FYI) are eligible to be automatically withdrawn if both of these things happen:

  • The expiration settings for the particular task is set to Do Nothing on the Deadlines subtab, within the Task Configuration tab in BPM Worklist.

  • Assignees don't take action to send the task to a final status within 180 days after the task was created. This number is reflected in the Open Tasks Withdrawn After Number of Days field on the Application Preferences page, which you can open by clicking the Administration tab in BPM Worklist.

When Eligible Tasks Are Automatically Dismissed or Withdrawn

Now we know when tasks are eligible, but when are they actually dismissed or withdrawn automatically?

  • FYI tasks: A process runs every three days, starting the first day of each month. For example, it runs on May 1, 4, 7, and so on, and again on June 1 and every three days after. So, if you leave the FYI Notifications Expiration Period profile value at 7, depending on when the process runs, an FYI task can be automatically dismissed within seven to ten days after it's created. The process changes the task status from Assigned to Completed.

  • All other tasks: A process runs every three days, starting the second day of each month. For example, it runs on May 2, 5, 8, and so on, and again on June 2 and every three days after. The process changes the task status to Withdrawn.

Synchronize Notifications in the Global Header and Home Page with Workflow Tasks

When workflow tasks are assigned to users, they can get an email as well as a notification in the global header and in the Things to Finish section on the home page. Updates they make to tasks from the global header, for example approving them, are automatically reflected in the Things to Finish section. Same goes the other way around, too.

But, the notifications don't immediately reflect changes to the task status if users take action through email, the Worklist: Notifications and Approvals work area, or BPM Worklist. For example, after you approve a task from email, you can still see the notification in the global header and home page asking for approval. Another case like that's when a task is assigned to an approval group, and everyone in the group gets a notification. Say you approve that task from the Things to Finish section. Your notification is removed from that section and the notifications list in the global header, but the same notification is still there for everyone else in the approval group.

So, use the Synchronize Notifications in Global Header scheduled process to synchronize notifications with the latest task status for all users:

  • This affects the notifications list in the global header, the Things to Finish section, and the Notifications page that shows all notifications, not just what's pending for the user.

  • The process includes notifications not just for tasks that require action, but also ones that are just FYI.

  • The process doesn't update the title of notifications in the global header, home page, or Notifications page. Like email subjects, the notification titles are static.

Note: No matter what the task status is, the scheduled process also removes notifications that are older than 30 days from the notifications list, Things to Finish section, and Notifications page.

Even when notifications aren't in sync with the latest workflow task status, users can still find the latest task status in the Worklist: Notifications and Approvals work area.

Schedule the Process

In the Scheduled Processes work area, submit the Synchronize Notifications in Global Header process to run on a schedule. It's recommended that you schedule the process to run every two hours. But if you need to run it more frequently, don't schedule it to run more often than every 30 minutes.

You need to have the Manage Scheduled Job Definition (FND_MANAGE_SCHEDULED_JOB_DEFINITION_PRIV) privilege to run this process. Predefined administrator job roles for product families have this privilege.

What Happens After Synchronization

One key thing that affects what users see in the notifications list, Things to Finish section, or Notifications page is whether the workflow task is pending for the user. Here's an example of what happens before and after the scheduled process runs:

  1. A notification is pending a user's approval.

  2. The user approves the task from email. The task status changes, but the notification requesting approval is still in the global header and Things to Finish section.

  3. After synchronization, because the task status is Completed and the task is no longer pending for the user, here's what happens to the notification:

    • It's removed from the list in the global header.

    • It's no longer a card in the Things to Finish section.

    • On the Notifications page, it moves from the Assigned to Me tab to the All tab.

How Workflow Tasks Are Archived and Purged

Workflow tasks with a final status of Completed, Errored, Expired, or Withdrawn can be archived and purged. In progress tasks with statuses like Assigned, Information Requested, or Suspended aren't eligible.

  • Archiving keeps a copy of the task data for audit, data retention or analysis, and other purposes.

  • Purging removes the completed tasks from users' worklists and permanently deletes the original data.

Archive

Tasks are automatically archived once a day without you having to set anything up. You can't change or stop this automatic archive, which includes all eligible tasks that aren't archived yet. These scheduled processes run in this order to get the daily archive done:

  • Extract Workflow Tasks for Archive

  • Process Translations for Workflow Tasks Archive

  • Upload Workflow Task Attachments for Archive

Here are some things to know about these processes:

  • All three scheduled processes must complete for tasks to get archived. But, as soon as the Extract Workflow Tasks for Archive is done, the tasks are available for purge.

  • Though unlikely, if you ever need to archive more frequently, you can use the Scheduled Processes work area to manually run these processes in the same order. Make sure one process finishes before you submit another.

    You have the option to set parameters for the Extract Workflow Tasks for Archive process. But let's say you leave the default with 50000 as the number of tasks in a batch and a maximum runtime of 120 minutes. That means the process will archive in batches of 50000 workflow tasks. If it's still running after two hours, the process finishes archiving the current batch and then stops. You can check the log file of the process to see how many tasks are included in the archive.

Archived data includes task details, approval history, comments, and attachments. How you view or use the archived data depends on the products you're using. For example, the data might be displayed in a table on a page, or available through a business intelligence subject area that you can select to create an analysis.

These are the database tables that store the archived data:

  • FND_BPM_TASK_B

  • FND_BPM_TASK_TL

  • FND_BPM_TASK_HISTORY_B

  • FND_BPM_TASK_HISTORY_TL

  • FND_BPM_TASK_ASSIGNEE

  • FND_BPM_TASK_COMMENT

  • FND_BPM_TASK_ATTACHMENT

Purge

Archived tasks that were last updated over 30 days ago are purged without you doing any setup. The purge runs daily at midnight. You can't change or stop this automatic purge.

After a task is purged, users can no longer find it in BPM Worklist or the Worklist: Notifications and Approvals work area. The task's approval history won't be available either. But, the tasks are still in the archive tables and available in analytics or anything else that reflects the archived data

Roles for Workflow Administration Access

Predefined roles provide access to workflow administration functionality. Users with the workflow roles can perform tasks such as setting up approval rules and managing submitted approval tasks. This table identifies the predefined Oracle Business Process Management (BPM) role for sales workflow administration access, and the predefined job roles that inherit it. It also shows the BPM role that provides workflow administration access for all product families. You can assign a predefined BPM role to a custom job role, if required.

Product Family Role Name and Code Inherited by Job Role

Sales

BPM Workflow Customer Relationship Management Administrator

BPMWorkflowCRMAdmin

Corporate Marketing Manager

Customer Relationship Management Application Administrator

Marketing Analyst

Marketing Manager

Marketing Operations Manager

Marketing VP

Sales Lead Qualifier

All

BPM Workflow All Domains Administrator Role

BPMWorkflowAllDomainsAdmin

This role isn't assigned to any predefined job role, but you can add it to custom job roles.

Search for Workflow Tasks to Configure

Some workflow setup applies to all tasks, but most of the time you configure specific tasks. To work on a specific workflow task in BPM Worklist, you first run a search and then select the task from the search results.

  1. In the Setup and Maintenance work area, go to the Manage Task Configurations task in the Application Extensions functional area. Or, depending on your offering, you might use a different functional area or another approval setup task.

  2. In BPM Worklist, on the Task Configuration tab, run a search in the Tasks to be configured pane.

  3. If you don't get any results, or the ones you want, change your search term and try again.

Here are some things to know about the search:

  • This searches against various attributes, for example the task title (the one on the General subtab that appears on the Task Configuration tab after you select a task from the search results), application name, and category. But, the search doesn't match against the task name you see in the search results.

  • The search is case-sensitive.

  • Search by * if you want all tasks in the search results.

  • Only default tasks are included in the search results. You can click Show and select the Active Versions check box to get both default and active tasks.