32 Using Approval Management
Get an overview of the approval management extensions that are available for the human workflow services of Oracle SOA Suite. The human workflow service handles all interactions with users or groups who participate in the business process by creating and tracking tasks for the appropriate users in the organization.
Users typically access tasks through a variety of clients, including Oracle BPM Worklist, email, portals, or custom applications. Approval management extensions enable you to define complex task routing slips for human workflow by taking into account business documents and associated rules to determine the approval hierarchy for a work item. Additionally, approval management extensions let you define multi-stage approvals with associated list builders based on supervisor or position hierarchies. You define the approval task in the Human Task Editor of Oracle JDeveloper, and associate the task with a BPEL process.
For more information about human tasks, see the chapters in part in the Using the Human Workflow Service Component Developing SOA Applications with Oracle SOA Suite guide.
This chapter includes the following sections:
32.1 Introduction to Approval Management
Approval Management extensions extend human workflow services with complex approval patterns. It serves as a sophisticated “Assignment Manager" for human workflow.
Some of the key workflow features include:
-
Declarative modeling of approval management processes
-
The ability to define complex multi-stage approval with static and dynamic approval list
-
A Workflow Editor to define task parameters, assignment and routing policies, escalation and expiration settings, and notification settings
-
Policy-based task assignment, which allows users to define approval rules based on business documents
-
The ability to design a task form to render contents of the approval task and associated task operations
-
The ability to define email, voice, and Instant Messaging notifications for various participants in the workflow
-
A web-based worklist application for task assignees, process owners, and administrators
-
The ability to look up users and roles in various user directories, including Oracle Internet Directory, LDAP, and third-party directories
AMX provides the following additional features:
-
Attributes derived from ADF view object in transactional applications
-
The ability to retrieve various job, position, and supervisory hierarchies from HR systems using hierarchy provider plug-ins.
-
The ability to define rules for controlling approval lists and hierarchy configurations
32.1.1 AMX Components
The following figure shows the key AMX and human task integration components. These components are described in subsequent sections of this chapter.
The human workflow service enables users to model human interactions as part of a business process. The human workflow service handles requests based on task and rules metadata. It consists of the following set of core services:
-
Task service
-
Task query service
-
User metadata service
-
Task metadata service
-
Identity service
-
Notification service
-
Assignment manager
These services are described in detail in the chapter “Designing Task Display Forms for Human Tasks" in Developing SOA Applications with Oracle SOA Suite. AMX serves as a sophisticated assignment manager within human workflow allowing you to model complex approval patterns based on business rules.
The core components required for approval management include the following:
-
Human Task Editor in JDeveloper
This task editor is used to define the metadata for a human task and the routing slip. The task editor lets you define such things as task parameters, outcomes, expiration and escalation, and notification settings. Some of the components added by AMX include the ability to do the following:
-
Define multi-stage approvals and associated approval list builders in JDeveloper.
-
Determine the approval hierarchy based on business documents (ADF objects) and business rules. This is done through Rules Designer in JDeveloper
-
-
Human workflow services
Some of the key services that are required for handling complex approvals include the following:
-
Task Service - Responsible for creating and managing tasks in the dehydration store
-
Identity Service - Responsible for authentication and authorization of users and groups. The service can look up various user directories for authorization and contact information for users.
-
Task Query Service - Responsible for retrieving tasks for the web-based worklist application
-
Decision Service - Responsible for executing business rules related to approvals
-
-
Oracle BPM Worklist
Oracle BPM Worklist is a web-based application that lets users access tasks assigned to them and perform actions based on their roles in the approval process. Oracle BPM Worklist supports the following profiles:
-
Work assignee - An end user who is assigned a task. These users can view tasks assigned to them and perform actions, and also can define custom views and define routing rules for their tasks.
-
Process owner - Typically a business analyst responsible for managing certain types of approvals. These users can manage tasks for the processes they own, define approval groups, and change approval policies
-
Workflow administrator - Typically a system administrator responsible for managing errored tasks, and administering and monitoring work queues. This user also may use Oracle Enterprise Manager to monitor the health of the workflow services.
-
32.2 Understanding Approval Management Concepts
AMX extends human workflow services with additional functionality to handle complex approval patterns.
Some human workflow concepts with which you must be familiar are the following:
-
Human Task Editor in JDeveloper
-
Task metadata (task parameters, allowed operations, and patterns) and routing slip
-
ADF task flow based on task forms
-
Oracle BPM Worklist
These concepts are described in “Using the Human Workflow Service Component” part in theDeveloping SOA Applications with Oracle SOA Suite guide.
The sections that follow describe new concepts introduced to handle complex approvals.
32.2.1 Task
A task handles approvals. A different task is created for each approval requirement based on the business served by it. For example, an approve new expense report task or an approve new purchase order task.
Some of the standard metadata for a task include the following:
-
Task attributes such as title, outcomes (approve, reject, and so on) priority, expiration and others
-
Task parameters that may be based on simple primitive types, XML elements, or external entities such as ADF view objects
-
A complex approval task that may include one or more stages to identify the key milestones within the approval sequence. For more information see Stages.
-
Expiration and escalation policy
-
Notification settings for notifying various participants
-
List builders within stages, which are based on names and expression, management chain, supervisory, position, job-level hierarchy, or approval groups. For more information, see List Builders.
-
Approval task configurations, including policies for substitution and modification of approvers, configuration of self-approval, and repeated approvers. For more information, see Task.
The following figure shows the various stages in a sample approval pattern.
The approval pattern consists of four stages:
-
Header approval
-
Line approval
-
Receipt verification
-
Payment
Header approval runs in parallel with line approval and receipt verification. After these stages run, the payment stage runs.
Each of the four stages has list builders. Multiple list builders in a stage can run in serial or parallel to one another. One or more approvers can exist within each list builder. The following figure illustrates these concepts.
Figure 32-3 Stages and Their List Builders
Description of "Figure 32-3 Stages and Their List Builders"
These concepts are described in the sections that follow.
32.2.2 Service Data Objects
ADF Business Components objects can be exposed easily as Service Data Objects (SDOs) through the service interface. This provides a flexible way to accept business entities. Subsequently, supporting SDOs natively, enables us to accept multiple business entities. This also lays the foundation for future Flexfield SDO support. Since an SDO is a structured XML, you can pass it in as static XML through the task payload.
A collection is defined in an entity parameter for the task. It enables access to a portion of the business entity as an XML fragment retrieved by an XPATH expression. Keys allow us to identify the primary keys in this fragment.
An entity parameter is the definition that tells us how to access an SDO or a static XML. An entity parameter captures the following information for an SDO:
-
Identity of a reference in the overall SCA process, including the Web service definition language (WSDL) for the SDO web service
-
Method to invoke
-
Input message to the web service
-
Output message to the web service
-
Collections
An entity parameter captures the following information for a static XML:
-
XSD for the static XML
-
Collections
For example, an expense voucher can have hierarchical groupings of header, lines, and cost centers. For approval policy purposes, you may only define a collection on header and lines if these are the only components required for determining the set approvers. It is not necessary to map as collections those parts of the business document that are not necessary to define rules.
For more information, see “Implementing Business Services with Application Modules" and "Integrating Service-Enabled Application Modules" in Developing Fusion Web Applications with Oracle Application Development Framework guide.
32.2.3 Stages
A stage is a set of approvals related to a collection. The same collection can be associated with multiple approval stages.
The following figure illustrates the mapping of stages and collections.
Figure 32-4 Mapping of Stages and Collections
Description of "Figure 32-4 Mapping of Stages and Collections"
Each approval stage is associated with a collection. In the figure, there are four stages in the approval.
-
Header Approval is associated with the Expense Header collection.
-
Receipt Verification is associated with the Expense Header collection.
-
Payment is associated with the Expense Header collection.
-
Line Approval is associated with the Expense Lines collection.
A compound approval may consist of multiple stages and then can be modeled in serial or parallel with each other. Each stage consists of list builders to determine the list of approvers.
Optionally, each list builder can be associated with an approval policy, that is, a set of rules. At runtime, the appropriate set of approvals are returned based on the list builders used within the stage and on the associated policies.
32.2.4 List Builders
As described in Stages, each approval stage consists of list builders to determine the actual list of approvers. The following list builders are supported.
-
Names and Expressions
Enables you to construct a list using static names, or names coming from XPath expressions.
-
Approval Groups
Includes predefined approver groups in the approver list. Approval groups can be static or dynamic.
-
Job Level
Ascends the supervisory hierarchy, starting at a given approver and continuing until an approver with a sufficient job level is found.
-
Position
Ascends the position hierarchy, starting at a given approver's position and continuing until a position with a sufficient job level is found.
-
Supervisory
Ascends the primary supervisory hierarchy, starting at the requester or at a given approver, and generates a chain that has a fixed number of approvers in it.
-
Management Chain
Enables you to construct a list based on management relationships in the corresponding user directory.
The management chain participant type only supports parallel routing when the first assignee in the management chain is a single user. You cannot specify parallel participants such as a set of users or a group, as the initial assignees in the management chain.
-
Rule-based
Enables you to model rules that return different list-builder types based on different conditions. For example, if you model a supervisory list builder with rules, the rule can return only the supervisory list builder. If you model a rule-based list builder, the rule can return different list-builder types.
Note:
The Approval Groups, Job Level, Position, and Supervisory list builders are specific to AMX, and are described in detail in How to Model and Configure List Builders.
For information about the Names and Expressions, Management Chain, and Rule-based list builders, see Creating a Single Task Participant List in the How to Assign Task Participants sections in the Developing SOA Applications with Oracle SOA Suite guide.
32.2.5 Task Operations
Most of the standard human task operations also are available on AMX-based tasks. Some of the common operations include the following:
-
User-defined outcomes - Business outcomes, such as "Approve" and Reject," that are associated with a task. When a user performs these types of actions, the task is removed from the user's "Inbox" and is marked as completed or moved to the next approver.
-
Delegate - Allows a user to assign a task to another person or role to act on his or her behalf.
-
Escalate - Allows a user or an administrator to escalate a task to the user's supervisor.
-
Reassign - Allows users to transfer a task to another user. From that point on, the new user's hierarchy is used for supervisor or other organization-based approvals.
-
Withdraw - Allows the task initiator or administrator to cancel or withdraw the task after the approval has started.
-
Request for Information - Allows a task approver to request information from any prior participant or the task initiator.
-
Pushback - Allows the task approver to push back the task to the previous approver to review it again.
-
Adhoc Insertions - Allows any task assignee to insert approvers in the generated approval list.
Note:
The position list builder does not allow the approver to reassign, delegate, escalate or perform adhoc insertions.
See the section "Acting on Tasks: The Task Details Page," in the chapter "Using Oracle BPM Worklist Application" in Developing SOA Applications with Oracle SOA Suite for a complete list of actions.
32.2.6 Business Rules for Approval
Approvers of a task can be defined either inline in a task definition or by using business rules to specify the list builders that identify the actual approvers of a task. In addition, you can use business rules to specify approver substitution and list modifications. These rules are defined with the help of Oracle Business Rules and can vary between organizations. Typically, however, they are defined by the customer.
Business rules are a combination of conditions and actions. Optionally, priority and validity periods can be defined for these rules. In Human Workflow rules, rule conditions are defined using fact types that correspond to the task, and to the task message and entity attributes (which are XML representations of SDO objects). Rule actions consist of approver list builders and their parameters. Approver list builders move up a particular hierarchy and construct or modify the approver list according to the parameters defined. Approver list builders are implemented as XML (JAXB) fact types.
For more information about these concepts, see the Using the Business Rules Service Component part in the Developing SOA Applications with Oracle SOA Suite guide.
32.2.6.1 List Creation
A list creation policy includes rule conditions and actions that create the list builders.
The following example rules illustrate the configuration of the Supervisory list-builder parameters that create an approver list based on an SDO-based fact type.
For more information, see How to Create Lists.
Example 32-1 Rule 1
IF
ExpenseItems.ReceiptAmount < 200
THEN
call CreateSupervisoryList( levels:1,
startingPoint:HierarchyBuilder.getPrinicipal("jstein",-1,"",""),
uptoApprover:HierarchyBuilder.getPrinicipal("wfaulk",-1,"",""),
autoActionEnabled:false,autoAction:null,
responseType:ResponseType.REQUIRED,ruleName:"Rule_1",lists:Lists)Example 32-2 Rule 2
IF
xpenseItems.ReceiptAmount >= 200
THEN
call CreateSupervisoryList( levels:1,
startingPoint:HierarchyBuilder.getPrinicipal("wfaulk",-1,"",""),
uptoApprover:HierarchyBuilder.getPrinicipal("cdickens",-1,"",""),
autoActionEnabled:false,autoAction:null,
responseType:ResponseType.REQUIRED,ruleName:"Rule_2",lists:Lists)
32.2.6.2 Approver Substitution
Users, groups, and application roles appearing in a list can be substituted using list substitution. List substitution is available from Rules Designer and does not require any configuration in JDeveloper.
The following example rule illustrates approver-substitution usage.
This rule implies that if the expense item amount is less than 4000, then substitute approver "jcooper," if present in the approver list, with approver "jstein."
For more information, see How to Make Approver Substitutions.
Example 32-3 Approver-Substitution Usage
IF ExpenseItems.ReceiptAmount < new BigDecimal(4000) THEN call Substitute(fromId:"jcooper", toId:"jstein", ruleName:"Substituted", substitutionRules: SubstitutionRules)
32.2.6.3 List Modification
Job Level and Position lists can be extended or truncated from rules. List modification is applied after list creation.
The following example rule illustrates list-modification usage.
This rule implies that if the expense item amount is greater than 3000, and if the final approver in the approver list is of Job Level 3, then extend the approver list by at least two relative levels.
For more information, see How to Make List Modifications.
Example 32-4 List-Modification Usage
IF ExpenseItems.ReceiptAmount > new BigDecimal(3000) THEN Call Extend(ifFinalApproverLevel:3, extendBy:2,ruleName:"Modified",lists:Lists)
32.3 Designing Approval Management Tasks in Oracle JDeveloper
You design approval management tasks by defining a human task that provides the ability to model multi-stage approvals and determine the appropriate approvers based on approval policies for a business object and the associated HR hierarchy provider.
This section describes the overall modeling process and the specifics of the process you use to model approval management tasks in JDeveloper.
32.3.1 Introduction to the Modeling Process
The modeling process for designing approval management tasks includes the following:
-
Creating a human task definition
-
Creating a task display form using the Human Task Editor
Creating a human task definition includes the following tasks:
-
Specifying general information, such as task title and task-title globalization, outcomes, priority, owner, and category
-
Defining task parameters, including those with service data object (SDO) references
-
Specifying mapped attributes
-
Modeling task routing by specifying stages and list builders, and modeling any business rules that define the list builders
-
Defining escalation and renewal policies
-
Specifying notification settings
-
Modeling any advanced settings like callbacks, security access rules, and restricted assignment
Some of these procedures are discussed in the sections that follow. For information about those that are not discussed, see the chapters in “Using the Human Workflow Service Component” part in theDeveloping SOA Applications with Oracle SOA Suite guide.
32.3.2 Before You Begin
Before designing approval management tasks, you must satisfy the following prerequisites:
-
You must have deployed SDO services.
-
You must have created a human task service component in which to design the approval task.
32.3.3 Specifying General Information
Some general information, including task title, outcomes, priority, owner, and category, is not specific to AMX.
For more information about these, see How to Define the Human Task Activity Title, Initiator, Priority, and Parameter Variables Developing SOA Applications with Oracle SOA Suite.
32.3.3.1 Task-Title Globalization
The title attribute of the task object contains a user-friendly value that mainly is descriptive in nature. In AMX, the task title can be globalized so that it renders in the user's preferred language.
Title is defined in the *.task file for design time and in the WorkflowTask.xsd file for runtime. Currently, the definition of these elements in both of these files are simple xsd:string types. For globalization, the structure and usage of these elements change to accommodate a mechanism that provides translatable, formatted strings.
The design-time metadata for these elements is enhanced to contain a value element and an optional set of parameters. Messages defined as an XPath expression or static have their information stored in the value element and require no parameters. Messages defined that rely on information in a resource bundle have a key stored in the value element with some parameters also defined.
The Human Task Editor provides a mechanism in the Expression Builder to enable the user to specify the resource key and parameters and, at the same time, generate the appropriate design time XML in the taskDefinition.
The following figure shows the globalization icon in the Human Task Editor.
The following procedure explains how to add translatable strings. It assumes that a resource bundle has been specified.
-
Select Translation from the drop-down list.
The Global icon displays.
-
Click the icon to display the Edit Translatable Strings dialog box.
-
Select a key from the drop-down list or click the plus sign (+) to create one.
The following Create a New Key dialog box, displays when you click the plus sign (+) on the Edit Translatable Strings dialog box.
-
Enter a name, the translatable text, and click OK.
The New Key added dialog box shows the Edit Translatable Strings dialog box after a new key has been added.
-
Use the Expression Builder to add values.
The Translatable Text and Values dialog box shows the completed Edit Translatable Strings dialog box.
Note:
The title value, or a definition of the title value can be set in two places: in the TaskDefinition XML (
.task) file, or in the bpel file. When set in the bpel file, this value takes precedence over the definition in the TaskDefinition. However, the value in the bpel file is not translatable. -
Click OK to close the dialog box.
32.3.4 Specifying Task Parameters
Specifying task parameters includes the following tasks:
-
Creating SDO references
-
Defining entity parameters
-
Defining collections
32.3.4.1 How to Create Service Data Object (SDO) References
An SDO service can be invoked from workflow services to retrieve the SDO as XML. This invocation is in the form of a SOA web service call. When the SDO service WSDL URL is available, a web service reference should be added using the Create Web Service dialog box.
To create a reference, enter the WSDL URL and select the port type from the available port types, as shown in the following figure.
For information about creating SDOs, see "Introduction to References" in the section "Introduction to the SOA Composite Editor" in Developing SOA Applications with Oracle SOA Suite.
32.3.4.2 How to Define Entity Parameters
The following procedure enables you to accept a service data object (SDO).
-
Create a Service reference in the composite.
This allows Fabric to create all the necessary wiring to a specific URL that points to a WSDL.
-
Define the task payload as external and specify which workflow retrieves the SDO object.
This creates task parameters representing the input and output to the SDO web service.
-
Choose Entity.
-
Select a reference.
-
Set the collection for the stage.
-
Click OK.
The following procedure enables you to accept static XML.
- Provide the XSD where the schema is defined.
- Define the task payload parameter as static XML.
- Define the collection, its XPATH expression, and its keys.
- Set the collection for the stage.
- Click OK.
32.3.4.3 How to Define Collections
Collections are references to specific parts of a task message attribute, both static-XML based and entity attributes. After defined, collections can then be associated with stages to identify a stage as acting on a collection.
Defining a collection involves defining the name of the collection and the XPath to the collection element. If the collection is defined for an entity attribute, the keys for the collection element have to be specified as well. Each key has to be a direct child of the collection element. The following figure shows how collections are defined.
When you define a collection, JDeveloper automatically determines if it should be repeating element or not. This information is used when collections are associated with a stage. A non-repeating collection can be associated with a singular stage. A repeating collection, when associated with a stage, repeats the stage in parallel for each element in the collection at runtime. For information about how the collection information is used in a stage, see How to Model and Configure Stages.
32.3.5 Specifying Mapped Attributes
Human workflow provides task-message attributes that you can use for storing use-case-specific data, such as data extracted from a task's payload. These attributes are also known as flexfield attributes or mapped flexfield attributes.
Mapped flexfield attributes allow payload values to be displayed as columns in the task listing, rather than being hidden in the task details. These values are stored in the human workflow database schema, and you can use them in queries, view definitions, and assignment rule definitions.
There are two types of message attributes:
-
public - Attributes mapped to specific task components at runtime. These mappings can be changed at any time, and must be re-created when a task component is redeployed. For more information see in Using Mapped Attributes (Flex Fields) in the Developing SOA Applications with Oracle SOA Suite guide.
-
protected - AMX-specific mappings between a task component and protected flexfield attributes defined at design time. They cannot be changed at runtime, and are deployed along with the task component.
Table 32-1 summarizes the 60 available protected flexfield attributes.
Table 32-1 Protected Flexfield Attributes
Name Description ProtectedTextAttribute1 - ProtectedTextAttribute20
Stores text data, up to 2000 characters. The content in these fields is checked during keyword searches in the Oracle BPM Worklist and through the task-query service.
ProtectedFormAttribute1 - ProtectedFormAttribute10
Stores text data, up to 2000 characters. The content in these fields is not checked during keyword searches in the Oracle BPM Worklist.
ProtectedURLAttribute1 - ProtectedURLAttribute10
Stores text data, up to 200 characters. The content in these fields is not checked during keyword searches in the Oracle BPM Worklist.
ProtectedDateAttribute1 - ProtectedDateAttribute10
Stores date information.
ProtectedNumberAttribute1 - ProtectedNumberAttribute10
Stores number information.
32.3.5.1 About Attribute Labels and Attribute-Label Mappings
Attribute labels are user-defined properties that allow a meaningful string to be applied to a particular flexfield attribute. The label should reflect the data to store in the attribute. For example, “CustomerName" for “ProtectedTextAttribute1," “OrderNumber" for “ProtectedNumberAttribute2," or “OrderDate" for “ProtectedDateAttribute1."
A flexfield attribute can have multiple attribute labels defined for it. For example, the attribute “ProtectedTextAttribute1" could have the labels “CusomerName," “PartId" and “EmployeeDepartment".
Attribute-label mappings for protected attributes are defined at design time in the Human Task Editor. They define a mapping between a particular task component and an attribute label, and also specify how the value of the attribute should be populated. The same attribute label can be re-used in multiple mappings. This allows task components to map data having the same semantic meaning into a common attribute identified by a common label.
For example, PurchaseOrder, LoanRequest and ServiceRequest tasks all could define mappings to the “CustomerName" label. By sharing the same attribute labels across multiple task components, it is possible to construct worklist queries that query multiple task types and display or filter values from the common attribute labels. For example, it would be possible to construct a query that selected PurchaseOrder, LoanRequest, and ServiceRequest tasks, and then displayed the “CustomerName" as a column in the worklist task listing.
32.3.5.2 How to Define Attribute-Label Mappings
You define attribute-label mappings in the Mapped Attributes section of the Human Task Editor, as shown in the following figure.
Use the following procedure to define attribute-label mappings:
- Click the Add icon to display the Add Mapped Attribute dialog box.
32.3.6 Specifying Routing and Approval Policies
Specifying routing and approval policies includes the following tasks:
-
Modeling and configuring stages
-
Modeling task participants
-
Modeling and configuring list builders
-
Defining business rules
-
Using business rules to specify list builders
-
Using assignment-context information
-
Aggregating task approvals
32.3.6.1 How to Model and Configure Stages
Based on functional needs, you can add and arrange multiple stages in a structure that can be a combination of sequential and parallel stages. This section describes how to create sequential and parallel stages.
Use the following procedure to create a stage:
- Drag the stage from the palette on the right side to a specific location on the canvass.
If you chose to create a sequential stage, the Assignment and Routing section looks like the following figure.
If you chose to create a parallel stage, the Assignment and Routing section looks like the following figure.
- Double-click the stage you just created.
The Edit dialog box displays, as shown in the following figure.
- According to your selection, use one of these options:
-
If you selected Non Repeating, click OK to close the Edit dialog box.
-
If you selected Repeat Stage in parallel for each item in a collection, additional options display, as shown in the following figure.
Figure 32-17 Edit Stage Dialog: Repeat Stage
Description of "Figure 32-17 Edit Stage Dialog: Repeat Stage"Do the following:
-
Select a default outcome.
-
Select a consensus percentage.
-
Choose either to trigger the outcome immediately or wait until all the votes are in before triggering the outcome.
-
Check the Share attachments and comments check box.
-
Click OK to close the Edit dialog box.
-
-
32.3.6.2 How to Model Task Participants
Inside each stage you either can edit the default task participant or add new task participants. Task participants are assigned based on routing patterns, which can be any of the following:
-
Single
-
Parallel
-
Serial
-
FYI
After selecting a routing pattern, you also must select and model a list builder. This process is discussed in more detail in How to Model and Configure List Builders.
32.3.6.3 How to Model and Configure List Builders
Stage uses a combination of list builders to generate the approver list. For more information, see Stages and List Builders. You can only use each type of list builder only one time per stage. You can arrange these approver list builders in either sequential or parallel order. The order you select governs the order in which those approvers included in approver lists that are generated by list builders are assigned an approval task.
The following list builders are specific to AMX:
-
Approval Groups
-
Job Level
-
Position
-
Supervisory
Table 32-2 describes the AMX-specific list builders and the options available to them.
Table 32-2 List-Builder Options
| Option Name | Description | List Builder |
|---|---|---|
|
Value-based |
Specifies constraints to build the list of participants based on provided values. |
All Except Position |
|
Rule-based |
Specifies constraints to build the list of participants based on rules that are defined in the Rule Editor. |
All |
|
Name |
The name of the approval group to use. |
Approval Groups |
|
Allow Empty Groups |
Allows the use of approval groups with no members. |
Approval Groups |
|
List Ruleset |
Name of the ruleset specifying constraints for building participant list. |
All |
|
Starting Participant |
The first participant in a list, usually a manager. |
Job Level Position Supervisory |
|
Top Participant |
The last participant in the approval. Approval does not go beyond this participant in a hierarchy. |
Job Level Position Supervisory |
|
Number of Levels |
A positive number specifying the number of levels to traverse for Supervisory, or the number of job level for Job Level and Position. This number can be an absolute value, or a value relative to starting point or creator. |
Job Level Position Supervisory |
|
Relative to |
A positive number specifying the number of levels to traverse for Supervisory, or the number of job level for Job Level and Position. Possible values are: starting point, creator and absolute. |
Job Level Position |
|
Include all managers at last level |
If the job level equals that of the previously calculated last participant in the list then it includes the next manager in the list. |
Job Level |
|
Utilized Participants |
Utilizes only the participants specified in this option from the calculated list of participants. Available options are: Everyone, First and Last manager, Last manager. |
Job Level Position |
|
Auto Action Enabled |
Specifies if the list builder automatically acts on task based on the next option. |
Supervisory Job Level Position |
|
Auto Action |
Specifies the outcome to be set. It can be null if auto action is not enabled. |
Supervisory Job Level Position |
If you do not configure the hierarchy provider plug-in, then the position list builder does not work.
When you define a hierarchy extension, if you do not define the property mustUseSpecifiedProvider then its default value is true.
You can configure the Supervisory and Job Level list builders not to throw an exception when there is a problem with the hierarchy plug in. To configure the list builders, you must add the mustUseSpecifiedProvider property to the workflow-identity-config.xml configuration file, and set the value attribute to false.
By default, the workflow-identity-config.xml file does not include the mustUseSpecifiedProvider property. If this property is present and its value is false, then, then the Supervisory and Job Level list builders use the LDAP management chain when there is a problem with the hierarchy plugin.
Example 32-5 shows a workflow-identity-config.xml file that specifies the mustUseSpecifiedProvider property. The value of this property is set to true so that the Supervisory and Job Level builders fail when the hierarchy plug in is not available.
Example 32-5 workflow-identity-config.xml Configuration File
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<configurations>
<configuration realmName="jazn.com">
<provider providerType="JPS" name="JpsProvider" service="Identity">
<property name="jpsContextName" value="default"/>
<property name="IdentityServiceExtension"
value="HCMIdentityServiceExtension"/>
</provider>
</configuration>
</configurations>
<property name="caseSensitive" value="false"/>
<property name="mustUseSpecifiedProvider" value="true"/> <!-- Fail when the hierarchy plug ins are not available-->
<serviceExtensions>
...
</ISConfiguration> 32.3.6.3.1 How to Model an Approval Groups List Builder
Approval groups are a statically defined or a dynamically generated list of approvers. Approval groups usually are configured by the process owner using the worklist application. Typically, they are used to model subject matter experts outside the transaction's managerial chain of authority, such as human resources or legal counsel, that must act on a task before or after management approval.
Static approval groups are predetermined lists of approvers, while dynamic approval groups generate approver lists at runtime. Dynamic approval groups require:
-
Delivery of an implementation according to the dynamic approver list interface by the developer
-
Registration of the above implementation as a dynamic approval group using the Oracle BPM Worklist's UI by the IT department
-
Availability of the class file in a globally well-known directory that is part of the SOA class path
Use dynamic approval groups when you need to calculate the approval group dynamically based on the task payload. Specially in line level approval where each line may require different approval group. For example, each cost center may require the approval of a different cost center owner. Each line may have different cost centers that require the approval of different cost center owners. When the number of cost centers is greater than one hundred, this may become difficult to manage with business rules.
Two views of the Approval Groups list builder are shown in the following figures.
Figure 32-18 Value-Based Approval Groups List Builder Dialog
Description of "Figure 32-18 Value-Based Approval Groups List Builder Dialog"
Figure 32-19 Rule-Based Approval Groups List Builder Dialog
Description of "Figure 32-19 Rule-Based Approval Groups List Builder Dialog"
To model an Approval Groups list builder, first specify if the list builder's attributes are to be value-based or rule-based, and then select the options on the corresponding dialog box. For information about the options, see Table 32-2.
Note:
If you configure the resource list with a group, then it behaves as a single type participant regardless of the serial or parallel type configuration.
32.3.6.3.2 How to Model a Job Level List Builder
The Job Level list builder ascends the supervisory hierarchy, starting at a given approver and continuing until an approver with a sufficient job level is found.
Two views of the Job Level list builder are shown in the following figures.
Figure 32-20 Value-Based Job Level List Builder Dialog
Description of "Figure 32-20 Value-Based Job Level List Builder Dialog"
Figure 32-21 Rule-Based Job Level List Builder Dialog
Description of "Figure 32-21 Rule-Based Job Level List Builder Dialog"
To model a Job Level list builder, first specify if the list builder's attributes are to be value-based or rule-based, and then select the options on the corresponding dialog box. For information about the options, see Table 32-2.
32.3.6.3.3 How to Model a Position List Builder
The Position list builder ascends the position hierarchy, starting at the requester's or at a given approver's position, and goes up a specified number of levels or to a specific position.
The following figure shows a view of the Position list builder.
Figure 32-22 Rule-Based Position List Builder Dialog
Description of "Figure 32-22 Rule-Based Position List Builder Dialog"
To model a Position list builder, first specify if the list builder's attributes are to be value-based or rule-based, and then select the options on the corresponding dialog box. For information about the options, see Table 32-2.
32.3.6.3.4 How to Model a Supervisory List Builder
The Supervisory list builder ascends the primary supervisory hierarchy, starting at the requester or at a given approver, and generates a chain that has a fixed number of approvers in it.
Two views of the Position list builder are shown in the following figures.
Figure 32-23 Value-Based Supervisory List Builder Dialog
Description of "Figure 32-23 Value-Based Supervisory List Builder Dialog"
Figure 32-24 Rule-Based Supervisory List Builder Dialog
Description of "Figure 32-24 Rule-Based Supervisory List Builder Dialog"
To model a Supervisory list builder, first specify if the list builder's attributes are to be value-based or rule-based, and then select the options on the corresponding dialog box. For information about the options, see Table 32-2.
32.3.6.4 How to Use Business Rules to Specify List Builders
Approvers of a task can be defined either inline in a task definition or by using business rules to specify the list builders that identify the actual approvers of a task. In addition, you can use business rules to specify approver substitution and list modifications. These rules are defined with the help of Oracle Business Rules and can vary between organizations. Typically, however, they are defined by the customer.
Business rules are a combination of conditions and actions. Optionally, priority and validity periods can be defined for these rules. In Human Workflow rules, rule conditions are defined using fact types that correspond to the task, and to the task message and entity attributes (which are XML representation of SDO objects). Rule actions consist of approver list builders and their parameters. Approver list builders move up a particular hierarchy and construct or modify the approver list according to the parameters defined. Approver list builders are implemented as XML (JAXB) fact types.
For more information about these concepts, see the Using the Business Rules Service Component part in the Developing SOA Applications with Oracle SOA Suite guide.
The sections that follow explain list creation, approver substitution, list modification, and repeating node attributes using Oracle Business Rules.
32.3.6.4.1 How to Create Lists
You can use business rules to define the list builders you want to use. There are two types of business rules:
-
Rules that define the parameters of a specific list builder. In this case, the task routing pattern dialog box is modeled to use a specific list builder. The parameters in the list builder come from rules. With this option, rules should return a list builder of the same type as the one modeled in JDeveloper. The following figure shows a sample configuration.
Figure 32-25 Specific List-Builder Configuration
Description of "Figure 32-25 Specific List-Builder Configuration" -
Rules that define the list builder and the list-builder parameters. In this case, the list itself is built using rules. The following figure shows a sample configuration.
Figure 32-26 List Builder and Parameters Configuration
Description of "Figure 32-26 List Builder and Parameters Configuration"
In the rule dictionary, rule functions are seeded to facilitate the creation of list builders. These functions are the following:
-
CreateResourceList
-
CreateSupervisoryList
-
CreateManagementChainList
-
CreateApprovalGroupList
-
CreateJobLevelList
-
CreatePositionList
In Rules Designer, model your conditions and, in the action part, "call" one of the functions above to complete building your lists, as shown in the following figure.
Figure 32-27 Modeling Conditions in Rules Designer
Description of "Figure 32-27 Modeling Conditions in Rules Designer"
The parameters for the rule functions are similar to the ones in JDeveloper modeling. In addition to the configurations in JDeveloper, some additional options are available in Rules Designer for the following attributes:
-
startingPoint and topApprover - In JDeveloper, starting point and top approver are specified as users. In Rules Designer, you can build a HierarchyPrincipal as the starting point and top approver. To build a Hierarchy Principal, use the HierarchyBuilder function, as shown in the following figure.
Note:
If you want to leave the job level attribute undefined when using the HierarchyBuilder function, then you must set its value to a negative integer.
HierarchyBuilder has a number of functions including getManager, getPrincipal, and getManagerOfHierarchyPrincipal.
HierarchyBuilder.getManager builds an approval list and takes the following parameters:
ListbuilderType - String - can be "supervisory"," joblevel" or "position"
ReferenceUser - String - for example "Task.creator"
AssignmentID - long - the default value is -1, otherwise it is set to the user
EffectiveDate - String - for example, "2015–07–31"
HierarchyType - String - specifies the type of manager to look for when the list is built. Example values are "LINE_MANAGER", "RESOURCE_MANAGER", "CORPORATE_MANAGER", "PROJECT_MANAGER"
An example HierarchyBuild.getManager call is
HierarchyBuilder.getManager("supervisory",Task.creator,-1,"2015-07-31","LINE_MANAGER")HierarchyBuilder.getPrincipal locates an approval list member and can be used, for example, to identify the top approver in an approval list. It takes the following parameters:
PrincipalName - String - can be "supervisory"," joblevel" or "position"
AssignmentID - long - the default value is -1, otherwise it is set to the user
EffectiveDate - String - for example, "2015–07–31"
HierarchyType - String - specifies the type of manager to look for when the list is built. default is "LINE_MANAGER". Other possible values are "RESOURCE_MANAGER", "CORPORATE_MANAGER", "PROJECT_MANAGER"
-
autoActionEnabled and autoAction - From Rules Designer, you can configure that the users resulting from a particular list builder can act automatically on the task.
-
responseType - If the response type is REQUIRED, the assignee has to act on the task; otherwise, the assignment would be converted to an FYI assignment.
-
ruleName - Rule name is used to create an assignment reason. Rule set name + "_" + rule name is used as a key to look up the resource bundle for a translatable reason for assignment. This resource is looked up first in the project resource bundle, then in the custom resource bundle, and last in the system resource bundle.
-
lists - This is an object that is a holder for all the lists that are built. Clicking this option shows a pre-asserted fact 'Lists' object to be used as the parameter.
The following figures show examples of rules.
Note:
If multiple rules fire, the list builder created by the rule with the highest priority is selected.
If the rules have the same priority, they are fired in random order, the first one fired is selected.
WARNING:
An improper or incomplete rules definition in a list-creation rule set can cause runtime errors. Errors can be caused by the following:
-
No rule was defined in the rule set.
-
None of the conditions defined in the rule was met.
Ensure that rules are properly defined to handle all conditions.
32.3.6.4.2 How to Make Approver Substitutions
List substitution enables you to substitute users, groups, and application roles that appear in a list. List substitution is available from Rules Designer and does not require any configuration in JDeveloper. In each rule dictionary there is a pre-seeded rule set named "SubstitutionRules." Also in the rule dictionary, a "Substitute" rule function is seeded to configure list substitutions. Table 32-3 lists the "Substitute" functions and their parameters.
Table 32-3 "Substitute" Function Parameters
| Parameter | Description |
|---|---|
|
fromId |
The ID of the user/group/application role from which to substitute. |
|
toId |
The ID of the user/group/application role which to substitute to. |
|
ruleName |
Used to create an assignment reason. Rule set name + "_" + rule name is used as a key to look up the resource bundle for a translatable reason for assignment. This resource is looked up first in the project resource bundle, then in the custom resource bundle, and last in the system resource bundle. |
|
substitutionRules |
An object that is a holder for all the substitutions. Clicking this option shows a pre-asserted fact 'SubstitutionRules' object to be used as the parameter. |
Note:
In a Human Task with a substitution rule, the resulting approval list might have a duplicate participant. It is not possible to edit the duplicate approvers in the Future Participants list.
The following figure shows a sample approver-substitution action.
Figure 32-31 Sample Approver-Substitution Action
Description of "Figure 32-31 Sample Approver-Substitution Action"
32.3.6.4.3 How to Make List Modifications
List modification enables you to extend or truncate the Job Level and Position list builders from rules. List modification is applied after the list is created. This feature does not require any configuration from JDeveloper. In each rule dictionary there is a pre-seeded rule set named "ModificationRules." This rule set is called only when the Job Level and Position list builders are asserted in the list that created the rule sets. Only the highest priority applicable rule is applied.
In Rules Designer, rule functions are seeded to facilitate list modifications. These functions are the following:
-
Extend
-
Truncate
These rule functions are shown in the following figure.
Extend and truncate parameters are listed in Table 32-4 and Table 32-5.
Table 32-4 "Extend" Function Parameters
| Parameter | Description |
|---|---|
|
ifFinalApproverLevel |
The level at which final approver is at or below. |
|
extendBy |
The number of levels to add to the final job level. |
|
ruleName |
Used to create an assignment reason. Rule set name + "_" + rule name is used as a key to look up the resource bundle for a translatable reason for assignment. This resource is looked up first in the project resource bundle, then in the custom resource bundle, and last in the system resource bundle. |
|
lists |
An object that is a holder for all the lists that are built. Clicking this option shows a pre-asserted fact 'Lists' object to be used as the parameter. |
Table 32-5 "Truncate" Function Parameters
| Parameter | Description |
|---|---|
|
afterLevel |
The level after which to truncate. |
|
ruleName |
Used to create an assignment reason. Rule set name + "_" + rule name is used as a key to look up the resource bundle for a translatable reason for assignment. This resource is looked up first in the project resource bundle, then in the custom resource bundle, and last in the system resource bundle. |
|
lists |
An object that is a holder for all the lists that are built. Clicking this option shows a pre-asserted fact 'Lists' object to be used as the parameter. |
The following figure shows a sample list-modification action.
Figure 32-33 Sample List-Modification Action
Description of "Figure 32-33 Sample List-Modification Action"
32.3.6.4.4 How to Define Repeating-Node Attributes of a Business Rule Condition
When defining a business rule, you can base a rule condition on an attribute that comes from a repeating node. For example, there can be multiple line items for each purchase-order header in a purchase-order scenario. In this case, PurchaseOrderHeader is a non-repeating node, and PurchaseOrderLines is a repeating node.
When defining a rule like the following:
IF line item's amount is <50000, THEN create supervisory list containing jcooper up to two levels
the amount is an attribute of line, that is, it is an attribute of a repeating node.
Use the following procedure to define repeating-node attributes:
- In Base Dictionary, select Facts.
In the Humantask1RulesBase rules tab, a list of facts displays as follows.
- Edit each appropriate fact to ensure that it is visible, as shown in the following figure.
- Decide whether you want to add a generic rule, a decision table, or a verbal rule. Once you decide, click the Add (+) button. In Rules Designer, select a rule and click Add icon (+).
The following rule-definition section displays.
- Click the double down arrows to the left of the rule name to show advanced settings, as shown in the following figure.
- Select Tree Mode, then click <fact type> to display a list of options from which to choose a ROOT, as shown in the following figure.
32.3.6.5 How to Use Assignment Context
Assignment context is information that is present in the task. During a task's life cycle, it progresses through various assignees. As the context of the task assignees changes, the assignment-context value also changes.
When browsing through the history of a task, you can see the various assignment contexts that the task contained during its life cycle. The Oracle BPM Worklist uses assignment context when it displays task history.
32.3.6.5.1 Configuring Assignment Context
You configure assignment context in the Add (or Edit) Participant Type dialog box in JDeveloper in the following ways:
-
Select the Rule-based option in the Participant Type section.
In this case, the assignment context is configured implicitly, behind the scenes. The Rules layer resolves the list of assignees based on the rule. As the task progresses through the various assignees, the assignment context value is computed based on the rule.
Assignment context can also be assigned in value-based context. See Assigning Task Participants for more information.
-
Select the Advanced finger tab to configure any number of assignment contexts.
In this case, you can customize assignment contexts by entering your own information into the Assignment Context fields. the following figure shows the fields.
Table 32-6 contains field descriptions.
Table 32-6 Assignment-Context Field Descriptions
Field Description Name
Assignment-context name, which can be whatever you choose. This is a string field.
Value
Assignment-context value, which can be whatever you choose. This is a string field.
Type
Associated with the Value field.
Possible values are:
-
By name - A user-provided Value parameter.
-
By Expression - A Value parameter created by the Expression Builder.
-
32.3.6.6 How to Aggregate Task Approvals
A task can be assigned multiple times to one user during the task life cycle. The Human Task Editor enables you to configure how often a user sees the task.
The following procedure explains how to configure task-approval aggregation.
- Click Configure in the top.
The Task Properties window displays as follows.
When the task is aggregated and assigned to a user, the task has a collection table in the Oracle BPM Worklist that displays all the collections in the task the user is approving. After the user performs an action, the action is recorded and then replayed to all the user's assignments, either in the stage or task.
An aggregated task is a proxy task for all the regular assignments.
Aggregated tasks are business tasks and show the actions approve and reject. If you can aggregate FYI tasks, then they show the approve and reject actions. In this case the approve and reject actions are treated as an acknowledgement.
Note:
Aggregation is available only when the assignees are from the same set. For example, if you assign a task to user A and another to both user A and user B; then user A sees two separate tasks. The two assignments are not aggregated because the assignees are not exactly the same.
32.3.7 Defining Escalation and Renewal Policies
This feature is not specific to AMX. For more information, see in Escalating, Renewing, or Ending the Task in Developing SOA Applications with Oracle SOA Suite
Note:
Escalation is only applicable to management chain.
32.3.8 Specifying Notification Settings
This feature is not specific to AMX. For more information, see in Specifying Participant Notification Preferences in Developing SOA Applications with Oracle SOA Suite.
32.3.9 Using Advanced Settings
Using advanced settings includes the following tasks:
-
Specifying callbacks for notes, attachments, and validation
-
Defining security access rules
32.3.9.1 How to Add Callbacks for Notes, Attachments, and Validation
Callbacks are mechanisms that allow you to do the following:
-
Access notes and attachments associated with business objects from external content-management systems or custom schemas
-
Perform custom validation of workflow tasks at various points in a task life cycle by defining validation logic for each task action
Use the following procedure to add callbacks:
- From the Task Editor, select the 4 finger tab to configure the callbacks.
The Callback Details dialog box opens as follows.
32.3.9.2 How to Define Security Access Rules
Access rules restrict the actions that a user can perform by overriding default actions and permissions. At runtime, the system checks every operation in a task against any defined access rules to see if a user is permitted to make changes, such as approve, add, delete, and so on If the user is not permitted to make changes, the operation errors out with an appropriate error message.
In AMX, access rules can be defined for Groups and Application Roles. For example, if an access rule is defined to restrict the "Withdraw" action for a group called Operators, then any user belonging to that group is not allowed to withdraw the task. Similarly, if an access rule is defined to restrict the "Withdraw" action for an application role called SOAAuditViewer, then any user who has been granted the SOAAuditViewer application role is not allowed to withdraw the task.
To define a security access rule:
- Click Configure Visibility....
The Configure Task Content Access dialog box displays, as shown in the following figure.
Figure 32-42 Configure Task Content Access Dialog (1)
Description of "Figure 32-42 Configure Task Content Access Dialog (1)"
Use the same procedure to define access rules for Application Groups, with the following exceptions:
-
Click the Task Actions tab to select it.
-
Select Application from the drop-down list.
-
Select application roles to include in the access rule from the Select an Application Role dialog box, as shown in the following figure.
See Figure 29-62 in Specifying Access Policies and Task Actions on Task Content for more information.
For more information, see in Specifying Access Policies and Task Actions on Task Content in Developing SOA Applications with Oracle SOA Suite.
32.4 Using the End-to-End Approval Management Samples
You can use samples of end-to-end approval management.
Table 32-7 shows the end-to-end workflow examples included in the ORACLE_HOME\samples\soa-infra\workflow\amx directory.
In addition to the demonstration features listed in the table, all samples show the use of worklist applications and workflow notifications.
Table 32-7 End-to-End Samples
| Sample | Description | Location |
|---|---|---|
|
Expense Line Approval |
Illustrates line-level approval with approval policy defined. |
|
|
Employee Hiring |
Illustrates ad-hoc insertion capabilities for an approval having two stages - Approval Group List Builder in "Order" voting regime and a Supervisory list builder. |
|
|
Purchase Order Approval |
Illustrates the Purchase Order approval scenario with header and line-level approvals. |
|
|
Employee Transfer |
Illustrates the Employee Transfer scenario from one team to another through parallel job level participants. |
|
|
Self Approval |
Illustrates how to implement self-approval through auto-action rules. |
|
|
Position List Builder |
Illustrates the use of the Position list builder. |
|
32.5 Using the User Metadata Migration Utility
The user metadata migration utility, hwfMigrator, automates the process of migrating Workflow user-configurable data from one SOA server to another by executing a shell script.
For more information about the user metadata migration utility, see Moving Human Workflow Data from a Test to a Production Environment in Administering Oracle SOA Suite and Oracle Business Process Management Suite.