30 Using Approval Management

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

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)

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)

For more information, see Section 30.3.6.4.1, "How to Create Lists."

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

IF
ExpenseItems.ReceiptAmount < new BigDecimal(4000)
THEN
call Substitute(fromId:"jcooper", toId:"jstein", ruleName:"Substituted", 
substitutionRules: SubstitutionRules)

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 Section 30.3.6.4.2, "How to Make Approver Substitutions."

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

IF
ExpenseItems.ReceiptAmount > new BigDecimal(3000)
THEN
Call Extend(ifFinalApproverLevel:3, extendBy:2,ruleName:"Modified",lists:Lists)

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 Section 30.3.6.4.3, "How to Make List Modifications."

30.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 run time. 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.

Figure 30-5 shows the globalization icon in the Human Task Editor.

Figure 30-5 Title Globalization Icon

The following procedure explains how to add translatable strings. It assumes that a resource bundle has been specified.

1. Click the icon to display the Edit Translatable Strings dialog.

2. Select a key from the dropdown list or click the plus sign (+) to create one.

   Figure 30-6 shows the Create a New Key dialog, which displays when the plus sign (+) on the Edit Translatable Strings dialog is clicked.

   Figure 30-6 Create a New Key Dialog

   
   

3. Enter a name, the translatable text, and click OK.

   Figure 30-7 shows the Edit Translatable Strings dialog after a new key has been added.

   Figure 30-7 New Key Added

   
   

4. Use the Expression Builder to add values.

   Figure 30-8 shows the completed Edit Translatable Strings dialog.

   Figure 30-8 Translatable Text and Values

   
   

   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.

5. Click OK to close the dialog.

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

To create a reference, enter the WSDL URL and select the port type from the available port types, as shown in Figure 30-9.

Figure 30-9 Web Service Reference

For information about creating SDOs, see "Introduction to References" in the section "Introduction to the SOA Composite Editor" in Developer's Guide for Oracle SOA Suite.

30.3.4.2 How to Define Entity Parameters

The following procedure enables you to accept a service data object (SDO).

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

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

3. Choose Entity.

4. Define the collection, its XPATH expression, and its keys, as shown in Figure 30-10.

   Figure 30-10 Add Task Parameter: Define Collection

   
   

5. Set the collection for the stage.

6. Click OK.

The following procedure enables you to accept static XML.

1. Provide the XSD where the schema is defined.

2. Define the task payload parameter as static XML.

3. Define the collection, its XPATH expression, and its keys.

4. Set the collection for the stage.

5. Click OK.

30.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. Once 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. Figure 30-11 shows how collections are defined.

Figure 30-11 Defining Collections

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 run time. For information about how the collection information is used in a stage, see Section 30.3.6.1, "How to Model and Configure Stages."

30.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 ”CustomerName,” ”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.

30.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 Figure 30-12.

Figure 30-12 Mapped Attributes Section

Use the following procedure to define attribute-label mappings:

1. Click the Add icon to display the Add Mapped Attribute dialog, which is shown in Figure 30-13.

   Figure 30-13 Add Mapped Attribute Dialog

   
   

2. Perform one of these options:

   • From the dropdown list, select the application server that contains the protected-attribute labels.

   • Click the Add icon to create a connection.

   • Click the Edit icon to edit an existing connection.

   The Attribute dropdown list populates with the available attribute labels from the specified server.

3. From the dropdown list, select an attribute.

   Note:

   The list does not include any labels for flexfield attributes to which this task component is being mapped.

4. At the Value field, specify a value using one of these options:

   • Enter an XPath expression that determines the value to be stored in the attribute.

   • Click the icon to create a value in the Expression Builder.

   • Leave the field blank to allow the value to be determined at run time.

   Usually, this XPath expression selects a value from the tasks's payload, but you can specify any valid expression that evaluates to a simple type, such as a string, a date, or a number.

   Be aware that specifying an XPath expression is not mandatory. You may prefer to set the value of the underlying flexfield-attribute value yourself. For example, you can add a custom assign activity to the BPEL process that initiates the task, or manipulate the Task object through the workflow service APIs.

5. Enter a description. This is optional.

6. Click OK.

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

1. In the Assignment and Routing section of the Human Task Editor, select a stage.

2. Click the Add icon, and then select either Sequential stage or Parallel stage from the dropdown list, as shown in Figure 30-14.

   Figure 30-14 Create Stage

   
   

   If you chose to create a sequential stage, the Assignment and Routing section looks like Figure 30-15.

   Figure 30-15 Add Sequential Stage

   
   

   If you chose to create a parallel stage, the Assignment and Routing section looks like Figure 30-16.

   Figure 30-16 Add Parallel Stage

   
   

3. Double-click the stage you just created, or select the stage and click the Edit icon.

   The Edit dialog displays, as shown in Figure 30-17.

   Figure 30-17 Edit Stage Dialog

   
   

4. Enter a name for the stage.

5. Choose one of these options:

   • Non Repeating - specifies that there is only one stage in parallel for each element in a collection

   • Repeat Stage in parallel for each item in a collection - specifies that the stage to repeat in parallel for each element in a collection. For example, if a purchase order contain 10 lines, the stage is repeated 10 times in parallel.

6. From the dropdown list, select a collection.

7. According to your selection, use one of these options:

   • If you selected Non Repeating, click OK to close the Edit dialog.

   • If you selected Repeat Stage in parallel for each item in a collection, additional options display, as shown in Figure 30-18.

     Figure 30-18 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.

     • Click OK to close the Edit dialog.

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

For information on participant types and assigning task participants to a stage, see "How to Assign Task Participants" in the "Creating Human Task Definitions with the Human Task Editor" section in the "Designing Human Tasks" chapter in Developer's Guide for Oracle SOA Suite.

After selecting a routing pattern, you also must select and model a list builder. This process is discussed in more detail in Section 30.3.6.3, "How to Model and Configure List Builders."

30.3.6.3 How to Model and Configure List Builders

A stage uses a combination of list builders to generate the approver list. For more information, see Section 30.2.3, "Stages" and Section 30.2.4, "List Builders." You can use each list builder type only once 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 30-2 describes the AMX-specific list builders and the options available to them.

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

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

30.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 run time. 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 amount of cost centers is greater than a hundred, this may become difficult to manage with business rules.

Note:

In Drop 8, an approval group is a flat list. Serial and parallel patterns no longer are defined.

Two views of the Approval Groups list builder are shown in Figure 30-19 and Figure 30-20.

Figure 30-19 Value-Based Approval Groups List Builder Dialog

Figure 30-20 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. For information about the options, see Table 30-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.

30.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 Figure 30-21 and Figure 30-22.

Figure 30-21 Value-Based Job Level List Builder Dialog

Figure 30-22 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. For information about the options, see Table 30-2.

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

Figure 30-23 shows a view of the Position list builder.

Figure 30-23 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. For information about the options, see Table 30-2.

30.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 Figure 30-24 and Figure 30-25.

Figure 30-24 Value-Based Supervisory List Builder Dialog

Figure 30-25 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. For information about the options, see Table 30-2.

30.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 chapter "Overview of Oracle Business Rules" in Developer's Guide for Oracle SOA Suite.

The sections that follow explain list creation, approver substitution, list modification, and repeating node attributes using Oracle Business Rules.

30.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 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. Figure 30-26 shows a sample configuration.

  Figure 30-26 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. Figure 30-27 shows a sample configuration.

  Figure 30-27 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 Figure 30-28.

Figure 30-28 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 Figure 30-29.

  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.

  Figure 30-29 HierarchyBuilder Function

  
  

  The HierarchyBuilder function 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.

Figure 30-30 and Figure 30-31 show examples of rules.

Figure 30-30 Example Rules (1)

Figure 30-31 Example Rules (2)

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

30.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 30-3 lists the "Substitute" functions and their parameters.

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

Figure 30-32 shows a sample approver-substitution action.

Figure 30-32 Sample Approver-Substitution Action

30.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 Figure 30-33.

Figure 30-33 Rule Functions

Extend and truncate parameters are listed in Table 30-4 and Table 30-5.

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

Figure 30-34 shows a sample list-modification action.

Figure 30-34 Sample List-Modification Action

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

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

1. In the Assignment and Routing Policy section of the Human Task Editor, select a stage and click the pencil icon to the right of "Task goes from starting to final participant."

2. In the Configure Restricted Assignment dialog, select the Assignment tab.

   Figure 30-41 shows the tab selected in the dialog.

   Figure 30-41 Configure Restricted Assignment Dialog

   
   

3. Select a task-aggregation option from the dropdown list:

   • None - Indicates there is no approval aggregation, which means the user sees the task as many times as it is assigned to him or her.

   • Stage - A user sees the task only one time in a stage.

   • Task - A user sees the task only one time in the task life cycle.

4. Click OK.

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. Only the following actions are permitted on an aggregated task:

• Custom actions like approve/reject

• Reassign

• Acquire

The user can perform additional actions on the individual tasks, such as escalate, but those actions are not be recorded and played back for other tasks. Those actions are treated as actions on an individual task and not on an aggregated task.

Aggregated tasks are business tasks therefore they 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.

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

1. From the Task Editor, expand the Advanced Settings section.

2. Click Configure Callbacks....

   The Callback Details dialog opens, as shown in Figure 30-42.

   Figure 30-42 Callback Details Dialog

   
   

3. Click the Other Callbacks tab.

   Additional entry fields display, as shown in Figure 30-43.

   Figure 30-43 Other Callbacks Tab

   
   

4. Use one of these options:

   • In the Comments Callback field, enter the appropriate Java class for the notes callback.

   • In the Attachments Callback field, enter the appropriate Java class for the attachments callback.

   • In the Validation Callback field, enter the appropriate Java classes, separated by commas, for the validation callback.

5. Click OK.

30.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 run time, 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:

1. Expand the Advanced Settings section of the Human Task Editor, and locate the Override default access to task content and actions option, as shown in Figure 30-44.

   Figure 30-44 Access Rules Option

   
   

2. Click Configure Visibility....

   The Configure Task Content Access dialog displays, as shown in Figure 30-45.

   Figure 30-45 Configure Task Content Access Dialog (1)

   
   

3. Click the Task Content or Task Actions tab to select it. (This procedure assumes the Task Content tab has been selected.)

4. Select a task to edit and click the Edit icon.

   A second Configure Task Content Access dialog displays.

5. From the dropdown list, select Group, as shown in Figure 30-46.

   Figure 30-46 Configure Task Content Access Dialog (2)

   
   

   The Identity Lookup dialog displays.

6. Select an application server, realm, and appropriate groups, as shown in Figure 30-47.

   Figure 30-47 Identity Lookup Dialog

   
   

7. Click OK.

   The selected groups are added to the access rule, as shown in Figure 30-48.

   Figure 30-48 Groups Added to Access Rule

   
   

8. Click OK to close the dialog.

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

• Select application roles to include in the access rule from the Select an Application Role dialog, as shown in Figure 30-49.

  Figure 30-49 Select an Application Role Dialog

  
  

For more information, see the section ”Specifying Access Rules on Task Content" in the chapter "Designing Human Tasks" in Developer's Guide for Oracle SOA Suite.