16 Oracle BPEL Process Manager Workflow Services

16.3.3.1 Task Attributes

The following task attributes are shown in Figure 16-10 and Figure 16-11.

• Task Title (required)

  The task title is used to display the task in Oracle BPEL Worklist Application. The title can include static strings and data from other business process variables.

• Payload (required)

  The task payload is the data in the task. The payload is restricted to BPEL variables and its substructures.

• Payload Display (required)

  The payload display identifies the display mechanism for the payload in the Worklist Application. Auto generated JSP form is the default option in which a JSP is generated by inferring the schema of the selected payload.

  Use the XSL file option to specify an XSL file for the payload display. If you select to use an XSL style sheet generated by an external utility, you must make the following modifications:

  • Add namespaces relating to the task and its requirements to the generated XSL.

  • Ensure that all XPath queries start with the task payload in place of the root of the XML.

  Use the JSP URL option to specify your own JSP that can be used to display the payload. See "Payload Display" for more information.

• Task Creator (optional)

  The creator of the task is the user who initiates the task. The creator can be defined using the XPath Expression Builder. The creator can view the tasks they created from the Worklist Application if they have access to the application. The creator can perform some actions specific to the creator from the Worklist Application, such as withdraw the task. If the creator is not specified, it defaults to the task owner.

• Expiration Duration

  The expiration duration is the maximum duration that the task can be open. This is optional for some workflow patterns and is required for other workflow patterns (such as auto-escalate).

• Task Priority

  If you select the advanced options in the Workflow wizard, you can specify the priority of the tasks. Priority can be 1 through 5, with 1 being the highest. By default, the priority of a task is 3.

• Task Owner (optional)

  The task owner can view the tasks belonging to business processes they own and perform operations on behalf of any of the task assignees. Additionally, the owner can also reassign, withdraw, or escalate tasks. This optional attribute defaults to the system user bpeladmin if not specified. The task owner can be specified in the advanced screens.

• Identification Key (optional)

  The identification key can be used as a user-defined identification for the task. For example, if the task is meant for approving a purchase order, the purchase order id can be set as the identification key of the task. Tasks can be searched from the Worklist Application by the identification key. This attribute has no default value.

Figure 16-10 Workflow Wizard: Task Details

Description of "Figure 16-10 Workflow Wizard: Task Details"

Figure 16-11 Workflow Wizard: Optional Task Details

Description of "Figure 16-11 Workflow Wizard: Optional Task Details"

16.3.3.2 Task Outcomes

The task outcomes capture the possible outcomes of a task such as Accept, Reject, and Approve. The outcomes of the task are specified during the creation of the workflow. The Worklist Application displays these outcomes as the possible actions that a user can perform. You can select one of the seeded outcomes as the possible actions that a user can perform. The task outcomes can also have display values that are different from the actual outcome value. This permits outcomes to be internationalized. See "Resource Bundles" for more information about internationalization.

Figure 16-12 shows where the conclusions are added. By default, JDeveloper BPEL Designer displays common outcomes from the following file, which can be changed to modify the default list of outcomes:

Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\TaskConclusion.xml

Figure 16-12 Task Outcomes

Description of "Figure 16-12 Task Outcomes"

After the workflow is created, you can change the custom actions in the conclusions element of the task configuration XML file, as shown in bold in the following code example.

<taskType ....>
  <task ...>
    <conclusions>
      <conclusion name="ACCEPT">
        <displayValue>Accept</displayValue>
      </conclusion>
      <conclusion name="REJECT">
        <displayValue>Reject</displayValue>
      </conclusion>
    </conclusions>
        ...
  </task>
  <notifications>
      ...
  </notifications>
</taskType>

16.3.3.3 Advanced Task Configurations

The task also has the following optional configurations. All these configurations are captured in the task configuration file. The following configurations are available through the advanced options in the workflow.

• Flex Fields

• Restricted Actions

• Version-Tracking Attributes

• Task Notifications and Reminders

• Resource Bundles

16.3.3.3.1 Flex Fields

The task object contains flex fields for extending the task to capture any data in addition to the payload. These flex fields are treated like other header attributes in the worklist. Tasks can be searched based on data in any of the flex fields. Flex fields are available for each of the following data types: string, double, long, and date. When modeling the business process, you can specify which flex fields are used and a display string for the flex fields. The display value is used by the Worklist Application for the data (instead of using the name of the flex field itself). This also permits display values to be internationalized. See "Resource Bundles" for more information on internationalization. Figure 16-13 shows how you configure flex fields. Only the flex fields that are configured in this window are displayed in the Worklist Application.

Figure 16-13 Task Flex Fields

Description of "Figure 16-13 Task Flex Fields"

You can change flex field information in the flexFields element of the task configuration XML file, as shown in bold in the following code example.

<taskType ....>
  <task ...>
    ...
    <flexFields>
      <flexField name="flexString2">
        <displayValue>displayfor flex string</displayValue>
      </flexField>
    </flexFields>
   ...
  </task>
  <notifications>
      ...
  </notifications>
</taskType>

The following flex fields are available:

• flexString1

• flexString2

• flexString3

• flexString4

• flexLong1

• flexLong2

• flexDouble1

• flexDouble2

• flexDate1

• flexDate2

• flexDate3

The Workflow wizard in JDeveloper BPEL Designer does not capture the assignment to the flex fields. The assignments to the flex fields can be manually added in the workflow BPEL scope. In every workflow that is generated, an assign named setUserDefinedAttributes in the scope is generated for the workflow. The assignments to the flex fields can be added in this assign, as shown in the following BPEL code example.

<sequence>
  <assign name="setUserDefinedAttributes">
       ...
    <copy>
      <from expression="string('value of flex string 1')"/>
      <to variable="WorkflowVar1" query="/task:task/task:flexString1"/>
    </copy>
  </assign>
     ...
<sequence>

16.3.3.3.2 Restricted Actions

The actions that are performed from the Worklist Application are common to all business processes. However, you can restrict some actions in a particular business process. For example, assume that in a loan approval process, the business requirement is never to suspend a loan application. To model this scenario, at design time, you can mark Suspend as a restricted action. When an action is marked as restricted, the Worklist Application does not display the action for this task. Figure 16-14 shows how restricted actions are configured.

Figure 16-14 Restricted Actions

Description of "Figure 16-14 Restricted Actions"

The following actions can be restricted:

• Auto Release

• Reassigned

• Escalated

• Renewed

• Info Requested

After the workflow is created, you can configure restricted actions in the restrictedActions element of the task configuration XML file, as shown in the following code example.

<taskType ...>
  <task ...>
    ...
    <restrictedActions>
      <restrictedAction>AUTO RELEASE</restrictedAction>
      <restrictedAction>ESCALATED</restrictedAction>
      <restrictedAction>REASSIGNED</restrictedAction>
      <restrictedAction>RENEWED</restrictedAction>
      <restrictedAction>INFO REQUESTED</restrictedAction>
      <restrictedAction>SUSPENDED</restrictedAction>
    </restrictedActions>
  </task>
  <notifications>
     ...
  </notifications>
</taskType>

16.3.3.3.3 Version-Tracking Attributes

When a task is modified, Oracle BPEL Process Manager creates a new version of the task as part of the task history. Changes to some of the task attributes, such as status, assignees, payload, and attachments, are always tracked with a new version. In addition, you can mark other attributes of the task as version tracked, including the title of the task, any flex attributes, and comments. Figure 16-15 shows where the version tracking attributes are specified.

Figure 16-15 Version Tracking Attributes

Description of "Figure 16-15 Version Tracking Attributes"

The following attributes can be version tracked:

• flexString1

• flexString2

• flexString3

• flexString4

• flexLong1

• flexLong2

• flexDouble1

• flexDouble2

• flexDate1

• flexDate2

• flexDate3

• title

• payload

• identificationKey

• comments

• attachments

After the workflow is created, you can change version tracked attributes in the versionTracking element of the task configuration XML file, as shown in the following code example.

<taskType ....>
  <task ...>
    ...
    <versionTracking>
      <attribute>attachments</attribute>
      <attribute>payload</attribute>
      <attribute>flexString2</attribute>
      <attribute>comments</attribute>
    </versionTracking>
      ...
  </task>
  <notifications>
   ...
  </notifications>
</taskType>

<taskType ...
        resourceBundleName="VacationRequestResource"
        resourceBundleLocation=" VacationRequestResourceLocation"
        ...
 ...
</taskType>

16.3.4.1 Task Assignment Evaluation

The assignee is captured as a node set. In the two modes for specifying the assignees, the assignee information is represented as follows:

• Static Assignment

  When the assignment is specified by browsing the user directory, the assignees are visually represented as a comma-separated string. In BPEL, a node set is created with a node created for each user specified.

• Dynamic Assignment

  The XPath expression evaluates to a node set. The value of each node represents a user in the assignee list. There can be only one node in the node set, but the value of each node must be a valid user name. It cannot be a comma-separated string. If the input expression is a comma-separated string, XSLT can be used to create a node set from it.

The assignee list is interpreted in different ways for different types of assignments, as follows:

• Single assignment

  The task is assigned to all the assignees in the node set. Each of the assignees can see and approve the task after acquiring it.

• Sequential task

  The task is assigned sequentially to each of the assignees in the node set. For example, if the assignee is set to a node set, as in

  <user xmlns="ns1-namespace>jstein</user>
  <user xmlns="ns1-namespace>jcooper</user>
  <user xmlns="ns1-namespace>wfaulk</user>
  
  

  then the task is first assigned to jstein. On their approval, it is assigned to jcooper, and on jcooper's approval, it is assigned to wfaulk.

• Parallel task

  In a parallel task, a subtask is created for each node in the node set, and the assignee of each subtask is the value of each node in the node set. For example, if the assignee is set to a node set, then a subtask is created for jstein, jcooper, and wfaulk, as follows:

  <user xmlns="ns1-namespace>jstein</user>
  <user xmlns="ns1-namespace>jcooper</user>
  <user xmlns="ns1-namespace>wfaulk</user>
  
  

One exception is the sequential task with management chain, where all the assignees specified are treated as a single assignment for the first assignment. The management chain is computed from the previous approver of the task.

The DocumentReview demo demonstrates dynamic assignment from a node set. The DocumentReview process is modeled on the parallel task with the final approver pattern.

16.3.4.2 Task Assignment Based on External Services

In a scenario where the task assignment is retrieved from an external service, the Dynamic assignment using XPath expression option can be used. The element being pointed to by the XPath expression must be either a node (if assigning to a single user or group) or a node set (if assigning to multiple users or groups).

Any complex task assignee computation must be done before the workflow is started. For example, if the assignee of the task should be the one with the least load of all the possible assignees, then a service can be implemented to compute the assignee, and the assignee returned from the service can be set as the task assignee using the XPath option.

16.3.4.3 Assigning a Task to a Specific User of a Role and Marking It As Acquired

When the task is assigned to a group or multiple users, the task must be acquired before a user can act on the task. It is also possible to set the task as acquired to a user from the business process. This can be done by adding a copy rule in the assign activity named setUserDefinedAttributes. This copy statement sets the /task:task/task:acquiredBy element of the task, as shown in Figure 16-17. The acquiredBy value can be computed from a service; for example, a service that does some load balancing among users computes the acquiredby value. This return value can be set to the acquiredBy element of the task.

Figure 16-17 Copy Rule

Description of "Figure 16-17 Copy Rule"

16.3.4.4 Setting Task Assignees from a Dynamic Delimited String

In a scenario in which the assignees are represented as a delimited string (for example, a comma-separated string), the delimited string must be converted to a node set to set the task assignees from it. For this purpose, you can use orcl:create-nodeset-from-delimited-string. The arguments for this function are as follows:

• QName in which each node in the node set must be created. The QName can be represented in two forms:

  • task:assignee

  • {http://mytask/task}assignee

• Delimited string

  The delimiter used to delimit the string, which can be , (comma) or ; (semicolon), for example.

For example, the BPEL variable inputVariable, part payload, and query /client:TestExtensionFunctionProcessRequest/client:input represent the assignees in a comma-separated format (example, jcooper,jstein,wfaulk) and this comma-separated list contains the assignees of the task. This string cannot be used as-is to set the task assignees because the task assignees are expected to be a node set. To set the assignees, select the dynamic assignment in the task assignees page, as shown in Figure 16-18, and set it to

orcl:create-nodeset-from-delimited-string('task:assignee',
bpws:getVariableData('inputVariable','payload',
'/client:TestExtensionFunctionProcessRequest/client:input'), ',')

Figure 16-18 Workflow Wizard—Assignees

Description of "Figure 16-18 Workflow Wizard—Assignees "

16.3.4.5 Selecting Users or Groups by Browsing the User Directory

Assignees can be selected by browsing the user directory (Oracle Internet Directory (OID), JAZN/XML, LDAP, and so on) that is configured for use by Oracle BPEL Process Manager. Clicking the flashlight icon to browse OID users (next to the User(s) or Group(s) text boxes) produces the Identity lookup dialog window.

In the identity lookup dialog window, shown in Figure 16-19, you can search by entering a search string such as jcooper, j*, *, and so on. Clicking Lookup fetches all the users that match the search criteria.

Figure 16-19 Identify Lookup Dialog

Description of "Figure 16-19 Identify Lookup Dialog"

One or more users or groups can be highlighted and selected by clicking Select.

You can view the hierarchy of a user by highlighting the user and clicking Hierarchy, as shown in Figure 16-20. Similarly, clicking Reportees displays the reportees of a selected user or group.

Figure 16-20 User Hierarchy

Description of "Figure 16-20 User Hierarchy"

You can view the details of a user or group by highlighting the user or group and clicking Detail, as shown in Figure 16-21.

Figure 16-21 Detail Information for a User

Description of "Figure 16-21 Detail Information for a User"

16.3.8.1 Use Case

An employee, through the employee portal, submits a vacation request. The portal initiates a business process that includes a user task modeled using a simple workflow. The task is assigned to the manager of the employee. When the manager approves or rejects the vacation request, the employee is notified with the manager's decision by e-mail. See the VacationRequest example in the samples directory for an implementation of this use case.

16.3.8.2 Customizations for Simple Workflow

The following customizations are possible:

• Changing the assignee after creating the user task

  The assign named setUserDefinedAttributes in the generated scope captures the setting of the task assignee. Depending on whether the task is assigned to a user or a group, the task attribute assigneeUsers or assigneeGroups is set. This assignment can be changed to modify the task assignee. For example, if you are using an external service that does load balancing or determines task assignee based on contents of the payload, you can call this service and set the assignees to a local variable. This variable can then be used to do a dynamic assignment based on an XPath expression.

• Changing the outcomes after creating the user task

  The outcomes are captured in the XML task configuration file, where they can be changed manually. See "Task Outcomes" for more information.

• Changing the user task to support multiple approvals

  A simple workflow (or any variation of simple workflow) does not support multiple approvals because it is intended for a single approval. If reapproval is required, change the user task to sequential workflow.

16.3.9.1 Use Case

The HelpDeskServiceRequest process gives users the ability to file help desk service request tickets. If the person who receives the ticket does not act on it within a specified time period, the ticket is automatically escalated to their manager. The ticket is automatically escalated three times if no one has acted on it within a predefined time, until it gets to the CEO of the company. If the CEO also does not act on it, it expires.

16.3.9.2 Pattern-Specific Parameters

Two parameters are specific to this pattern.

• The maximum number of times the task can be escalated

  This required parameter specifies how many times the task is escalated. For example, if this parameter to set to 2, then the task is assigned to the user jcooper. If none of the users acts on the task in time, the task is assigned to jcooper (initial assignee), user jstein (jcooper's manager) and user wfaulk (jstein's manager).

• The title of a user to whom the task can be escalated

  This optional parameter specifies the title of the last user to whom the task can be escalated. For example, if this parameter is set to Manager, the task is assigned to user jcooper. If none of the users acts on the task in time, the task is assigned to jcooper (initial assignee) and user jstein (jcooper's manager), whose title is Manager.

  The title can be typed in or selected from a list of prespecified titles. The list of titles that are displayed is configured in defaultUserTitles.xml at

  Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\
  
  

When both these parameters are specified, the task is escalated until one of the conditions causes the escalation to stop. For example, if the maximum number of times is 4 and the title is Manager, then the task is assigned to jcooper. If none of the users acts on the task in time, the task is assigned to jcooper (initial assignee), and user jstein (jcooper's manager), whose title is Manager.

Figure 16-26 shows where these parameters are specified.

Figure 16-26 Escalation

Description of "Figure 16-26 Escalation"

16.3.9.3 Customizations for Simple Workflow with Automatic Escalation

The customizations in "Customizations for Simple Workflow" apply to this pattern, in addition to the following.

• Changing the duration for the task assignment

  When the task is expired and is escalated, the task is renewed for a duration equal to the initial expiration duration of the task. The BPEL assign named setEscalationPolicy in the user task scope sets the renewal duration in the variable oraBPMExpDuration. This copy statement can be changed to change the expiration duration for the subsequent task assignments.

• Changing the number of levels of escalation

  The BPEL assign named setEscalationPolicy in the user task scope captures the number of levels of escalation in the variable oraBPMManagementChain (the query for the copy is /identityservice:managementChain/identityservice:levels). This can be changed to any appropriate value.

• Changing the title of the last user to whom the task is escalated

  The BPEL assign named setEscalationPolicy in the user task scope stores the title of the last user in the variable oraBPMManagementChain (the query for the copy is /identityservice:managementChain/identityservice:uptoTitle). This can be changed to any appropriate value.

• Changing the user to whom the task is escalated on task expiration

  By default, on task expiration, the task is escalated to the user's manager. This can be changed by changing the generated BPEL scope. In the generated BPEL scope, there is another BPEL scope named escalateTask that performs the escalation. In the scope, change the escalateTask invoke to invoke the updateTask operation on the TaskManagerService instead of the escalateTask operation. The TaskManagerService.wsdl file defines the updateTask operation. The task assignees (users or groups) to whom the task is escalated must be set before the operation is invoked. In addition, the state of the task (task:task/task:state) must be set to ASSIGNED before the operation is invoked.

16.3.10.1 Use Case

A business process manages renewal of magazine subscriptions. The rules of the subscription are that if the user cancels the subscription one month before the expiration date of the current subscription, then the subscription is cancelled free of charge. If the user cancels in the last month of the current subscription, then the subscription is cancelled with a charge. If the user does not cancel, it is renewed.

The process is initiated 60 days before the subscription is up for renewal. The process contains a user task modeled with the simple workflow with automatic renewal pattern. When the magazine subscription task is assigned to a user, an e-mail is sent to the user. The user can go to a portal and renew or cancel the subscription. Depending on the user action, the business process determines the cancellation or cancellation with charge or renewal.

16.3.10.2 Pattern-Specific Parameters

One parameter is specific to this pattern.

• The maximum number of times the task can be renewed

  This required parameter specifies how many times the task is renewed.

16.3.10.3 Customizations for Simple Workflow with Automatic Renewal

The customizations in "Customizations for Simple Workflow" apply to this pattern, in addition to the following:

• Changing the duration for the task assignment

  When the task expires, it is renewed. The renewal duration of the task is the same as it was for the first task assignment. The BPEL assign named setRenewalPolicy in the user task scope sets the new expiration duration in the variable oraBPMRenewDuration. This copy statement can be changed to change the expiration duration for the subsequent task assignments.

• Changing the number of levels of renewal

  The BPEL assign named setRenewalPolicy in the user task scope stores the maximum number of levels of renewal in the variable oraBPMMaxTimesRenewed. This can be changed to any appropriate value.

• Adding logic depending on number of times renewed

  The BPEL scope level variable oraBPMNumOfTimesRenewed captures the number of times the task is renewed. This variable can be used to build additional logic in the business process.

16.3.11.1 Use Cases

A loan application processing system receives loan applications. These loan applications are initially assigned a group called LoanAgentGroup. A user in this group evaluates and approves the loan application and provides a loan offer. If the loan application amount is greater than 100,000 US dollars, then the loan application and the initial loan offer are sent to the initial approver's manager. After they approve it, the loan application is routed to their manager. If the loan application amount is less than or equal to 100,000 US dollars, then the initial loan offer is sent back to the caller. This use case is demonstrated in the LoanDemoPlusWithWorkflow sample.

Another use case is when a purchase order approval system processes a purchase order using a business process. An employee belonging to a group named Supervisor initially evaluates the purchase order. After the initial user approves the purchase order, their manager approves it. After the manager approves the purchase order, the purchase order is forwarded to the billing and shipping departments. This use case is demonstrated in the Order Booking tutorial purchase order approval service.

16.3.11.2 Pattern-Specific Parameters

The sequential workflow has the following pattern-specific parameters.

• The approvers assignment policy

• Outcome that results in the task being routed

• Continue routing expression

In simple workflow, the assignees are specified for the only assignment of the task. In sequential workflow, the set of users to whom the task is routed is specified. There are two ways to specify this.

1. A list of users from a business process variable or a static list set at design time.

2. A management chain. This involves selecting the initial assignees (a set of groups or users) and parameters to select the management chain. The parameters to select the management chain include specifying the following attributes:

   1. The number of levels in the management chain

      This required parameter specifies how many levels in the management chain are included in the list. For example, if this parameter to set to 2 and the task is initially assigned to a user jcooper, then both the user jstein (jcooper's manager) and user wfaulk (jstein's manager) are included in the list, apart from jcooper (the initial assignee).

   2. The title of the last user in the management chain

      This optional parameter specifies the title of the last user in the management chain. For example, if this parameter is set to Manager and the task is assigned to a user jcooper, user jstein (jcooper's manager) is included in the list, apart from jcooper (the initial assignee).

      The title can be typed in or selected from a list of prespecified titles. The list of titles is configured in defaultUserTitles.xml at

      Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\
      
      

When both these parameters are specified, then the task routing is determined by both the title and the number of levels. The routing continues until one of the conditions—title or the number of levels—no longer applies. The following examples illustrate this.

Example: If the maximum level in the management chain is four and the title is Manager and the task is assigned to a user jcooper, then the list includes jcooper (initial assignee) and user jstein (jcooper's manager), whose title is Manager. The task is not be routed beyond the Manager, even though the maximum number of levels is set to 4. This is useful in cases where you want the approvals to go up to a certain management level (for example, Director).

Example: If the maximum level in the management chain is 1 and the title is Director and the task is assigned to a user jcooper, then the list includes jcooper (initial assignee) and user jstein (jcooper's manager, whose title is Manager). It does not include wfaulk (jstein's manager, whose title is Director) because the task was already routed to one user beyond the initial assignee.

There are also two parameters that determine if the task must be routed.

1. The list of outcomes that cause the task to be routed can also be specified. For example, if a task has two outcomes, ACCEPT and REJECT, the business logic might require the task to be routed to the next approver only if the current user accepted the task.

2. A continue routing expression can also be specified. If this expression evaluates to true, the task is routed further after a specific user acts on it. This expression can be used to dynamically control how many approvals are required. Examples of this expression are as follows:

   1. The task is routed only if the loan amount is greater than 1000; otherwise it is approved only once.

      bpws:getVariableData('loan', '/auto:loan/auto:loanApplication/auto:loanAmount') > number(10000)
      
      

   2. The task is routed until it is approved by a manager.

      ora:getPreviousApproversTitle('/task:task/task:taskId') = string('Manager')
      
      

   3. The task is approved at most three times.

      ora:getNumberOfTimesApproved('/task:task/task:taskId') < 3
      
      

   4. The task is approved at most three times when the loan amount is greater than 10000; otherwise it should be approved only once.

      ora:getNumberOfTimesApproved('/task:task/task:taskId') < 3 and
      bpws:getVariableData('loan', '/auto:loan/auto:loanApplication/auto:loanAmount') > number(10000)
      
      

The extension function ora:getPreviousApproversTitle() gets the title of the previous task approver. The function getNumberOfTimesApproved() gets the number of times a task was approved. See "Workflow-Related XPath Extension Functions" for a list of the extension functions.

Figure 16-31 shows the routing parameters.

Figure 16-31 Routing Parameters

Description of "Figure 16-31 Routing Parameters"

16.3.11.3 Customizations for Sequential Workflow

• Changing the initial assignee in the management chain after creating the user task

  The assign named setUserDefinedAttributes in the generated scope captures the assignment of the task assignee. Depending on whether the task was assigned to a user or a group, the task attribute assigneeUsers or assigneeGroups is set. This assignment can be changed to modify the task assignee.

• Changing the management chain parameters after creating the user task

  The assign named setRoutingPolicy in the generated scope sets the approver function in the task attribute approvers. The approver function contains the management chain parameters. The parameters can be changed in this function. See "Approver Functions" for more information.

• Changing the assignees in the list after creating the user task

  The assign named setUserDefinedAttributes in the generated scope captures the assignment of the task assignee. The assignment to the oraBPMRouteAssignees variable attributes /taskmngr:assigneeEntities/taskmngr:assignee captures the list of users or groups.

• Changing the outcomes after creation of the user task

  Task outcomes are captured in the XML task configuration file, where outcomes can be changed manually. See "Task Outcomes" for more information.

• Changing routing policy

  The assign named setRoutingPolicy captures the routing policy. The future assignees of a task in a sequential workflow are captured in the approvers attribute of the task object. This assign sets the approvers attribute to an approver function depending on the assignment policy chosen—management chain or list of users. See "Approver Functions" for more information.

• Changing continue routing expression

  In the generated scope, the continue routing expression is evaluated in the assign named evaluateRoutingCriteria. The condition that is set in the wizard is negated with a not() in this expression. This expression can be changed as needed.

• Adding continue routing expression

  The response from each user is received in the receive activity receiveUpdatedTask. The receive activity follows a switch activity in which one of the case statements is:

  Task is COMPLETED and the task outcome is one of the outcomes specified in the routing policy
  
  

  The expression on this case statement can be changed to add any continue routing expression.

• Adding approvers

  In the management chain routing policy, approvers can be added by changing the management chain parameters as described previously. Similarly, by changing the assignees in the list of users as described previously, approvers can be added.

• Changing the user or group to whom the task is routed based on output of an external system

  In the generated BPEL, there is a scope named routeTaskToNextApprover. This scope is responsible for routing the task to the next user or group. By default, this routing is based on the approver function. In a scenario where the next task assignee is determined by an external system, the activities in the routeTaskToNextApprover scope can be modified to achieve that. The TaskRoutingService exposes an operation called routeTask that routes the task to a specified user or group. The input message for this operation includes the task, an id that identifies either a user or a group, and a Boolean flag that identifies the entity as a group or a user. After a message is created, change the routeTaskToNextApprover invoke and its input variable accordingly to use the routeTask operation instead of the routeTaskToNextApprover operation.

16.3.12.1 Use Case

An employee (for example, jcooper) requests a new laptop urgently. The sequential workflow first routes the task to their manager for approval (for example, jstein) and then to a person in the procurement department (for example, jlondon) to acquire the laptop. If the workflow is set up with automatic escalation after two days, then the request first goes to the manager for approval and if it is not approved in two days, then the task can be automatically routed to the next person in the management hierarchy (jstein's manager, wfaulk). Similar escalation can also be done for the procurement representative. This enables the workflow to complete without long delays in the approval process.

16.3.12.2 Pattern-Specific Parameters

All the parameters that apply to the sequential workflow apply to this pattern as well. In addition to those parameters, the following parameters are specific to this pattern.

• The maximum number of times the task can be escalated

  This required parameter specifies how many times the task is escalated for each assignment. For example, if this parameter to set to 2, the task is assigned to user jcooper. If jcooper does not act on the task in time, then the task is escalated to user jstein (jcooper's manager). If jstein does not act on the task, then the task is escalated to user wfaulk (jstein's manager).

• The title of a user up to whom the task can be escalated

  This optional parameter specifies the title of the last user to whom the task can be escalated. For example, if this parameter is set to Manager, then the task is assigned to a user jcooper. If none of the users act on the task in time, then the task is assigned to jcooper (initial assignee) and user jstein (jcooper's manager), whose title is Manager.

  The title can be typed in or selected from a list of prespecified titles. The list of titles is configured in defaultUserTitles.xml at

  Oracle_Home\integration\jdev\jdev\system10.1.2.1.0.1915\
  
  

When both these parameters are specified, the task is escalated until one of the conditions causes the escalation to stop. For example, if the maximum number of times is 4, and the title is Manager, then the task is assigned to user jcooper. If none of the users act on the task in time, then the task is assigned to jcooper (initial assignee), user jstein (jcooper's manager), whose title is Manager.

16.3.12.3 Customizations for Sequential Workflow with Escalation

All the customizations that apply to the sequential workflow apply to this pattern also.

• Changing the escalation policy

  The assign named setRoutingPolicy in the generated scope sets the escalation policy. The title of the last user to escalate up to is set to the attribute /identityservice:managementChain/identityservice:uptoTitle of the variable oraBPMManagementChain. The level of escalation is set to the attribute /identityservice:managementChain/identityservice:levels of the variable oraBPMManagementChain. These assignments can be changed as required.

• Changing the expiration duration of the task when escalated

  By default, the expiration duration of the task when escalated is the initial expiration duration of the task. Changing the assignment to the variable oraBPMExpDuration in the assign setRoutingPolicy changes the expiration duration when the task is escalated.

• Changing the user to whom the task is escalated on task expiration

  By default, on task expiration, the task is escalated to the user's manager. This can be changed by changing the generated BPEL scope. In the generated BPEL scope, another BPEL scope named escalateTask performs the escalation. In the scope, change the escalateTask invoke to invoke the updateTask operation on the TaskManagerService instead of the escalateTask operation. The TaskManagerService.wsdl defines the updateTask operation. The task assignees (users or groups) to whom the task is escalated must be set before the operation is invoked. In addition, the state of the task (task:task/task:state) should be set to ASSIGNED before the operation is invoked.

16.3.13.1 Assigning Parallel Tasks to Each User in a Group

You cannot use a concat function to assign a parallel task to each user in a group. Instead, use the ora:getUsersInGroup(groupName) extension function to perform this task (for example, assign the parallel task to users fkafka, szweig, and mmitch in group LoanAnalyticGroup). This extension function gets the users in a group as a node-set. In this case, specify the XPath expression as follows in the Dynamic assignment using XPath expression field in the Assignees window of the Workflow wizard:

ora:getUsersInGroup('LoanAnalyticGroup')

The use of the ora:getUsersInGroup function is described on Oracle BPEL Console under Manage BPEL Domain > XPath Library and also in Appendix G, "XPath Extension Functions".

Oracle BPEL Process Manager does not provide built-in functionality for explicitly assigning a task to each user in multiple groups. For example, if group LoanAgentRole has users jcooper, jstein, and wfaulk and group Supervisor has users jlondon and cdickens, then creating a parallel task to assign to users jcooper, jstein, wfaulk, jlondon, and cdickens is not directly supported. As a workaround, you can write your own bpelx:exec (Java inside BPEL) to create a node-set that contains all the users from both groups and assign the parallel task to that node-set.

16.3.13.2 Use Case

A hiring process is used to hire new employees. Each interviewer votes to hire or not hire a candidate. If 75% of the votes are to hire, then the candidate is hired; otherwise, the candidate is rejected. The process is modeled using the parallel workflow, where each interviewer can vote independently from the other interviewers.

16.3.13.3 Pattern-Specific Parameters

Parallel workflow has the following pattern-specific parameters.

• The percentage required for an outcome to be chosen as the final outcome

• The default outcome

• Configuration if early completion is enforced

Figure 16-36 shows where these parameters are configured.

Figure 16-36 Outcome Determination

Description of "Figure 16-36 Outcome Determination"

16.3.13.4 Customizations for Parallel Workflow

• Changing the outcomes after creation of the user task

  The outcomes are captured in the XML task configuration file, where they can be changed manually. See "Task Outcomes" for more information.

• Changing the parameters of the outcome determination policy

  The assign named setUserDefinedAttributes in the generated scope captures the outcome determination policy. The percentage required for the final outcome is assigned to the BPEL variable oraBPMConclusionPercentage and the default outcome is set in the BPEL variable oraBPMDefaultConclusion.

16.3.14.1 Use Case

A DocumentReview process is used to review a document. The document creator creates the document and initiates a process by specifying the document and the reviewers of the document. Each reviewer can review the document simultaneously and independently of the other reviewers. After all the reviewers are done reviewing, the creator of the document gets to review the comments of the reviewers. See the DocumentReview example in the samples directory for an implementation of this use case.

16.3.14.2 Pattern-Specific Parameters

Parallel workflow with final reviewer has the same pattern-specific parameters as parallel workflow. In addition to choosing the parallel participants, the final reviewer must also be set. Figure 16-37 shows where the final reviewer is selected.

Figure 16-37 Setting Reviewers

Description of "Figure 16-37 Setting Reviewers"

16.3.14.3 Customizations for Parallel Workflow with Final Reviewer

All the customizations for the parallel workflow apply to this pattern, in addition to the following:

• Changing the final reviewer of the task

  The assign named setUserDefinedAttributes in the generated scope captures the reviewers. The reviewers are set in the /taskmngr:assigneeEntities/taskmngr:assignee attribute of the oraBPMReviewers variable. This assignment can be changed to change the final reviewer.

16.3.15.1 Use Case

This pattern is typically used when a sequence of users or roles that need to act on the task is not determined automatically by the workflow process, but instead by the user who is currently assigned the task. Each user decides whether the task must be routed further or if it is complete. For example, an HR representative writes a new policy document and has it reviewed by their manager. The manager may decide that another person should also review it before it is accepted. This person may in turn forward the task to others before approving it. Hence, the task may be routed to multiple users before coming back to the original reviewer, who then finally approves it based on comments from others.

16.3.15.2 Customizations for Adhoc Workflow

• Changing the initial assignee of the task

  The assign named setUserDefinedAttributes in the generated scope captures the assignment of the task assignee. Depending on whether the task is assigned to a user or a group, the task attribute assigneeUsers or assigneeGroups is set. This assignment can be changed to modify the initial assignee.

16.3.16.1 Use Case

A purchase order approval system processes purchase orders. When the system processes approvals over $100,000, a supervisor must be notified, but without stopping the processing. This information is used by the supervisor to monitor the system.

16.3.16.2 Customization for FYI Tasks

• Changing the assignee after creating the FYI task

  The assign named setUserDefinedAttributes in the generated scope captures the assignment of the task assignee. Depending on whether the task was assigned to a user or a group, the task attribute assigneeUsers or assigneeGroups is set. This assignment can be changed to modify the task assignee.

16.3.18.1 Use Case

A hiring process is used to hire new employees. Each interviewer votes to hire or not hire a candidate. If 75% of the votes are to hire, then the candidate is hired; otherwise, the candidate is rejected. If the candidate is to be hired, then the human resources contact completes the hiring process. The HR contact also needs to see the interviewers and the comments they made about the candidate. This process can be modeled using a parallel workflow for the hiring. If the candidate is hired, then a simple workflow can extend the parallel workflow so that the hiring request, history, and the interviewer comments are carried over. This simple workflow is assigned to the HR contact.

16.3.18.2 Pattern-Specific Parameters

There are no parameters specific to the extended workflow. The parameters are driven by the pattern chosen for the extended workflow.

16.3.18.3 Customization for Task Continuations

The follow customization applies:

• Customization applicable to the workflow pattern also applies to the extended workflow.

• Changing a new workflow to an extended workflow

  Any new workflow can be changed to an extended workflow. For example, if Workflow1 uses the BPEL variable Workflow1Var and Workflow2 uses Workflow2Var, and Workflow2 must be changed to extend Workflow1, then do the following:

  1. Delete the BPEL variable Workflow2Var.

  2. Replace all occurrences of Workflow2Var in the BPEL with Workflow1Var.

  3. In the generated scope, after the BPEL assign activities, there is a scope named initiateTask. In this scope, there is an invoke initiateTask activity that calls the TaskManagerService in the operation initiateTask. Change this operation to reinitiateTask.

  This customization is useful when two workflows that have different payloads must carry the same history information. When modeled as new workflows, the modeler can take advantage of the autogenerated JSP for display purposes and then change the new workflow to an extended workflow.

16.3.19.1 Payload Updates

The task carries a payload in it. If the payload is set from a business process variable, then an assign with the name copyPayloadFromTask is created in each of the case and otherwise branches to copy the payload from the task back to its source. If the payload is expressed as other XPath expressions (such as ora:mergeChildNodes(...), ora:getNodes(...)), then this assign is not created because of the lack of a process variable to copy the payload back. If the payload need not be modified, then this assign can be removed.

16.3.19.2 Case Statements for Other Task Conclusions

By default, the switch activity contains case statements for the outcomes only. The other task conclusions are captured in the otherwise branch. These conclusions are as follows:

• The task is withdrawn

• The task is errored

• The task is expired

If business logic must be added for each of these other conclusions, then case statements can be added for each of the preceding conditions. The case statements can be created as shown in the following BPEL segment. The XPath conditions for the other conclusions in the case activities for each of the preceding cases are shown in bold.

<switch name="taskSwitch">
  <case condition="bpws:getVariableData('SequentialWorkflowVar1',
'/task:task/task:state') = 'COMPLETED' and
bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:conclusion') = 'ACCEPT'">
    <bpelx:annotation>
      <bpelx:pattern>Task outcome is ACCEPT
      </bpelx:pattern>
    </bpelx:annotation>
      ...
  </case>
  <case condition=
"bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'WITHDRAWN'">
    <bpelx:annotation>
      <bpelx:pattern>Task is withdrawn
      </bpelx:pattern>
    </bpelx:annotation>
     ...
  </case>
  <case condition=
"bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'EXPIRED'">
    <bpelx:annotation>
      <bpelx:pattern>Task is expired
      </bpelx:pattern>
    </bpelx:annotation>
     ...
  </case>
  <case condition=
"bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'ERRORED'">
    <bpelx:annotation>
      <bpelx:pattern>Task is errored
      </bpelx:pattern>
    </bpelx:annotation>
     ...
  </case>
  <otherwise>
    <bpelx:annotation>
      <bpelx:pattern>Task is EXPIRED, WITHDRAWN or ERRORED
      </bpelx:pattern>
    </bpelx:annotation>
      ...
  </otherwise>
</switch>

16.5.1.1 Customizing the Autogenerated JSP

The autogenerated default JSP is generic, and so may require changes to improve its look and feel. The JSP works in conjunction with the mapping file to determine which elements in the payload are displayed in the form.

16.5.1.2 Customizing the Mapping File

The mapping file gives you control of the presentation. The mapping file is an XML file that contains a list of showable fields. The root element in the mapping file contains its targetNameSpace, other namespaces, showXmlView, and xmlEditable as its attributes.

The payload, by default, shows only the HTML form view. It also has an XML source view that can be used to set payload XML directly. ShowXmlView identifies if the XML source view is enabled, while xmlEditable identifies if the XML source view in the payload presentation is editable or not. ShowXmlView is set to false by default, while xmlEditable is set to true.

All the elements that are simple types are listed as fields in the mapping file. Along with these elements, their immediate parents are listed as well for multilanguage support. Each field has three properties defined in the mapping file. They are xpath, editable, and resource_key.

The xpath property defines the XPath of this field. It is always prefixed by /ns0:task/ns0:payload. This is the XPath to the root of the payload object. When maxOccurs is greater than 1, it is denoted by [*]. For example, /ns0:task/ns0:payload/company[*]/ceo shows that maxOccurs is greater than 1 for the company field.

The editable property defines if this field is editable. It defaults to true. If the value of this field is changed to false, the default JSP shows a disabled text field that disallows value changes.

The resource_key property is for multilanguage support. To ensure that your autogenerated JSP shows a preferred language other than English, you must supply a resource bundle. To do that, you modify your taskConfigtaskName.xml file. Add two attributes—resourceBundleName and resourceBundleLocation—to the top element, task. The resourceBundleLocation attribute points to a JAR file, and resourceBundleName specifies the resource bundle's file name in the JAR file. The resourceBundleLocation attribute is optional for globalization purposes.

The following code shows an example of taskConfig<taskName>.xml:

<taskType name="taskConfigSimpleWorkflow2.xml" 
     resourceBundleName="MyBundle"
     targetNamespace="http://taskTypes/taskConfigSimpleWorkflow2.xml"
     features="xpathNotification"
     xmlns:tns="http://taskTypes/taskConfigSimpleWorkflow2.xml"
     xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
     xmlns:xp20="http:
//www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.Xpath20"
     xmlns:ldap="http://schemas.oracle.com/xpath/extension/ldap"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:Notification="http:
//xmlns.oracle.com/pcbpel/taskservice/taskNotification"
     xmlns:client="http://xmlns.oracle.com/i18nProcess"
     xmlns:ora="http://schemas.oracle.com/xpath/extension"
     xmlns="http://xmlns.oracle.com/pcbpel/taskservice/tasktype"
     xmlns:ns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"
     xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
     xmlns:task="http://xmlns.oracle.com/pcbpel/taskservice/task"
     xmlns:orcl="http:
//www.oracle.com/XSL/Transform/java/oracle.tip.pc.services.functions.ExtFunc">
  <task actionableNotifications="YES"
     xmlns="http://xmlns.oracle.com/pcbpel/taskservice/tasktype">
    <conclusions>
      <conclusion name="ACCEPT">
        <displayValue>getMessage(ACCEPT_MSG)</displayValue>
      </conclusion>
...
</taskType>

MyBundle points to a properties file that resides at the root of the project. The following code shows an example of MyBundle_en-US.properties:

ACCEPT_MSG = Accept0
REJECT_MSG = Reject0
FLEX_STRING1_MSG = Flex String1
FLEX_LONG1_MSG = Flex Long1
FLEX_DATE1_MSG = Flex Date1
TASK_TITLE = i18n Task

In this case, if a field is defined in your mapping file as follows

   <field>
      <xpath>/ns0:task/ns0:payload/taskTitle</xpath>
      <editable>true</editable>
      <resourceKey>TASK_TITLE</resourceKey>
   </field>

then calling

PayloadUtil.getElementDisplayName("/ns0:task/ns0:payload/taskTitle", ,
form, context.getLocale(), task)

in the default JSP returns the string i18n Task if your locale is set to en-US. Similarly, if your locale is set to French, the proper properties file (MyBundle_fr.properties) is picked up.

16.5.1.3 Customizing the Default JSP

If the mapping file does not provide enough control, you can modify the default JSP file. Only modify the section after the label:

/* Modify the code below when necessary */

Most JSP modifications can be made in the JSP design view of JDeveloper BPEL Designer.

By default, all the fields are set to text field. If you want to change text field to text area, you can do the following. In the Component Palette, select Text Area, as shown in Figure 16-45. Drop it into the position of the text field you want to replace. Note that the name of the text field is set by calling the function PayloadFormGenerator.constructName(String xpath), and the value of the field is set by PayloadFormGenerator.selectNodeValue(Element payload, String xpath, Map namespace). These functions must be used to construct form field names and to retrieve form field values. Set the text area's name and value to the same name and value as text field. Delete the text field.

Figure 16-45 JDeveloper BPEL Designer JSP Design View

Description of "Figure 16-45 JDeveloper BPEL Designer JSP Design View"

In the place you want to insert text or other HTML elements that are not in a table, add text by typing it or add an HTML element by dragging and dropping the HTML component from the Component Pallet.

If the place you want to insert HTML elements that is in an HTML table, to insert text or a horizontal rule, first add a table row by clicking a row, right-clicking, and selecting Insert Row. After a row is inserted, you may need to merge all the cells in the row by selecting all the cells in the row and right-clicking to select Merge Cells. Then you can either type your text or drag and drop your HTML component.

If you want to change the layout of the table or form, highlight the section you want to modify, right-click, and select table or form. If you want to format the text, use the toolbar's color and style buttons.

It is recommended that you modify the default JSP's look and feel only. You should preserve the functions being used in the JSP. You must not alter the hidden parameters being submitted in the HTML form, because the Update button invokes form submission to the UpdateServlet that expects certain values. If your change is complicated and has programming logic in it, you must switch to the source view and modify the JSP code directly. See "The Custom JSP URL" for a lightweight code analysis of the JSP.

By putting the statement <%@ page pageEncoding="UTF-8" %> in the default JSP, UTF-8 is set as the default encoding. If you want to modify this statement to set the JSP to other encoding, for example ISO, then you must also change UpdateServlet. To do this, add one encoding element in the taskConfigtask_name.xml file. The modified file looks as follows:

<taskType>
   <task>
      ...
      <payloadDisplay>
         <jsp>defaultWFPayloadJSP</jsp>
         <xpathFile>taskConfigSimpleWorkflowWithAutomaticEscalation
            1_WF_Fields.xml</xpathFile>
         <encoding>ISO</encoding>
      </payloadDisplay>
    </task>
</taskType>

16.5.1.4 Multibyte Payload in the Task Detail JSP

To ensure that a multibyte payload is correctly displayed on the Task Detail page, modify the TaskConfigtask_name.xml file that is generated during design time by adding the following element as a child element of PayloadDisplay:

<encoding>character_set_used_for_JSP</encoding>

If this element is not specified, UTF-8 is used by default.

16.5.4.1 APIs

As with the autogenerated JSP, the JSP run-time library and the OraBPEL library are automatically added to your BPEL project for compilation of the custom JSP file.

16.5.4.2 Customizing the Complete Task JSP

The previous sections described how you can customize the look and feel of the payload portion of the task using a custom JSP, XSL, or by modifying the autogenerated JSP. You can also override the complete JSP, including the header (task attributes and actions section) and the footer (attachment, comments section) by specifying a custom JSP to display the entire task details. The payload JSP URL is captured in the task configuration XML file in the element payloadDisplay, as follows:

<taskType ...>
  <task ...>
   ...    
    <payloadDisplay>
      <jsp>http://localhost:9700/payloads/vacationrequest/payload.jsp</jsp>
    </payloadDisplay>
      ...
  </notifications>
</taskType>

16.7.1.1 The JAZN Provider

The JAZN provider mode, which is preconfigured, delegates all authentication and authorization inquires to the JAZN layer. Two JAAS providers are supplied as part of the OC4J security infrastructure: the XML-based file and LDAP-based OID.

16.7.1.2 Third-Party LDAP Server

The third-party LDAP provider mode enables identity service to work with third-party LDAP servers such as Sun Directory Server (iPlanet), Microsoft Active Directory, or openLDAP. In this mode, identity service assumes that the directory is the central repository of all user data, including authentication credentials, roles, and profiles. The standard organizationalPerson, inetOrgPerson objects from the LDAP schema are used to retrieve these details.

16.7.1.3 Custom User Repository Plug-ins

This mode enables UPI to define a new custom identity service provider to plug in a specific non-LDAP-based user repository. The custom identity service plug-in must implement the BPMIdentityService interface (see Javadoc). This identityservice class name must be registered in is_config.xml. See "User and Role Properties" for more information.

16.7.4.1 Structure of the Identity Service Configuration File

Identity service configuration is defined in the is_config.xml file. The file must be located in a directory that is included in the CLASSPATH of Oracle BPEL Process Manager. By default, it is stored in

Oracle_Home\integration\orabpel\system\services\config

The XML schema for the is_config.xml file is stored in

Oracle_Home\integration\orabpel\system\xmllib\workflow\xsd

Figure 16-47 shows the structure of the BPMIdentityService configuration.

Figure 16-47 BPMIdentityService Configuration

Description of "Figure 16-47 BPMIdentityService Configuration"

The identity service configuration file (as defined by is_config.xsd) consists of a root element BPMIdentityServiceConfig, which can have only one provider. As discussed previously, identity service supports the following main plug-in types: JAZN provider, third-party LDAP directories, or custom repository plug-ins.

The provider element specifies the providerType, which can be JAZN, LDAP, or CUSTOM, provider name (optional), and any provider-specific properties.

For example, in the case of the JAXN XML provider, you must set the providerType attribute to JAZN and specify the value of the userPropertiesFile attribute. See "Configuration for the XML-Based JAZN Provider" for more information about userPropertiesFile.

Similarly, if you use a custom plug-in to the identity service, you must set the providerType attribute to CUSTOM. You then specify the class name for custom identity service plug-in implementation, as follows:

<BPMIdentityServiceConfig mlns="http://www.oracle.com/pcbpel/identityservice/isconfig" >
  <provider providerType="CUSTOM" 
    name="CustomPlugIn"
    class="package.name.CustomIdentityService"
  </provider>
</BPMIdentityServiceConfig>

In addition, the provider can define the following optional parameters in the configuration file. Most of these parameters apply to JAZN-based or LDAP-based providers, but can be used by custom providers also.

16.7.4.1.1 connection Element

The connection element is used to specify the URL, admin username (binddn- bind as this Distinguished name), the credential (password) for the LDAP or RDBMS connection used by the identity service, and a Boolean flag (encrypted) to specify that the password is either in plain text or is encrypted. Identity service overwrites the is_config.xml file after reading the configuration and encrypts the user password if it finds the password in plain text. Figure 16-48 shows the structure of the connection configuration.

Figure 16-48 connection Configuration

Description of "Figure 16-48 connection Configuration"

The connection can specify connection pool properties by setting the following attributes on the pool element:

• initsize—initial size of the connection pool

• maxsize—maximum size of the connection pool

• prefsize— preferred size of the pool

• timeout—time after which the connection is released if there is no activity (in seconds)

The LDAP plug-in for identity service uses the following default values:

• initsize="2"

• maxsize="25"

• prefsize="10"

• timeout="60"

If you are using a custom identity service plug-in, you can also specify any additional connection-specific properties as name-value pairs.

16.7.4.1.2 userControls and roleControls Elements

The userControls element is used to define user controls and to restrict the LDAP user search. Figure 16-49 shows the structure of the userControls element.

Figure 16-49 userControls Element

Description of "Figure 16-49 userControls Element"

The roleControls element is used to define role controls and restrict the LDAP role search. Figure 16-50 shows the structure of the roleControls element.

Figure 16-50 roleControls Element

Description of "Figure 16-50 roleControls Element"

Both userControls and roleControls can have a search element that has the following optional attributes:

• searchbase—a list of LDAP entries, the distinguished names (DNs) of user or group containers.

• maxSizeLimit—the maximum number of elements that are fetched from LDAP during a search operation

• maxTimeLimit—the maximum time to wait to retrieve elements from an LDAP search

• scope—determines the search level. The value can be onelevel, in which the search descends one level from the supplied DN or subtree, in which the search descends the hierarchy from the DN to the lowest level in the tree.

By default, the LDAP provider for identity service uses the following values: maxSizeLimit ="1000", maxTimeLimit ="120" (sec), and scope="subtree".

<BPMIdentityServiceConfig xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig" > 
  <provider providerType="CUSTOM" name="db2"
      class="package.name.CustomIdentityService"
    <property name="customProperty" value="customValue" /> 
  </provider>
</BPMIdentityServiceConfig>

16.7.4.2 Configuration for the XML-Based JAZN Provider

The JAZN element jazn provider="XML" location="./jazn-data.xml"/ is in

Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\
application-deployments\hw-services\orion-application.xml

and

Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\config\jazn.xml

The identity service configuration file must specify the userPropertiesFile property and provide the value of the file name where all user properties are stored:

<IdentityServiceConfig
          xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig"
          xmlns:isc="http://www.oracle.com/pcbpel/identityservice/isconfig"
          providerType="jazn">
  <provider name="xml"
    <property name="userPropertiesFile" value="users-properties.xml"/> 
  </provider>
</IdentityServiceConfig>

Note that the users-properties.xml file from that example stores all extended user's properties. This is not required for JAZN authorization or authentication. However, the BPEL identity service requires this file to get contact details and the organizational hierarchy for users. If this file is not created, then certain workflow functionality such as notifications, manager views, or task escalation may not work. By default, the identity service looks for users-properties.xml in the Oracle BPEL Process Manager classpath. Oracle Universal Installer stores the default users-properties.xml in

Oracle_Home\integration\orabpel\system\services\config

16.7.4.3 Configuration for the LDAP-Based JAZN Provider (OID)

If you select the Identity Management Access option during BPEL Process Manager for OracleAS Middle Tier installation, the identity service is automatically configured with OID. For all other installation scenarios, you must manually configure the LDAP-based JAZN provider (OID) in two steps:

• OID Configuration

• Middle-Tier Configuration

$ldifmigrator "input_file=system-oid.sbs" "output_file=system-oid.ldif" -lookup
"host=ldap.acme.com" "port=389" "subscriber=acme" "s_UserCommonNamingAttribute=cn"
dn="cn=admin" password=welcome

$ldifmigrator "input_file=demo-oid.sbs" "output_file=demo-oid.ldif" 
-lookup dn="cn=admin" password=welcome "host=ldap.acme.com" "subscriber=acme"
"s_UserCommonNamingAttribute=cn"

$ldapadd -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f system-oid.ldif
$ldapmodify -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f demo-oid.ldif

16.7.4.4 Configuration for a Third-Party LDAP Server

Note the following considerations when using a third-party LDAP server. The configuration for Active Directory is slightly different. These differences are also described.

1. The third-party LDAP servers must be configured to use the following standard objectClasses:

   For Active Directory	For Other Third-Party LDAP Servers
   top	top
   person	person
   organizationalPerson	organizationalPerson
   user	inetOrgPerson
   group	groupOfUniqueNames

   
   

   Usually LDAP servers predefine the list of searchable attributes based on the cn, firstname, lastname, and email attributes. You can customize the attributes that can be searchable. The user manager attribute from inetOrgPerson objectClass should be searchable to allow workflow escalation. See the documentation for the third-party LDAP server you are using for how to set up the searchable attribute.

   The recommended searchable attribute list is cn, sn, givenName, uid, manager, title, mail, and telephoneNumber.

2. When you seed Oracle BPEL Process Manager users and roles into the LDAP server, the process assumes that the users' and groups' container is created in LDAP. To create system and optionally demo ldif files, open the following template files in:

   Oracle_Home\integration\orabpel\system\services\config\ldap
   
   

   For Active Directory	For Other Third-Party LDAP Servers
   system-winServer2003-ActDir.sbs	system-ldap.sbs
   demo-winServer2003-ActDir.sbs	demo-ldap.sbs
   demo-roleGrants-winServer2003-ActDir.sbs

   
   

   Replace the substitution variables with the appropriate values, as shown in the following examples. The actual values to enter depend upon your domain:

   LDAP Server	Substitution Variable	Replace With Value
   Active Directory	%s_UserContainerDN%	cn=Users,dc=us,dc=oracle,dc=com
   	%s_GroupContainerDN%	cn=Users,dc=us,dc=oracle,dc=com
   Other Third-Party LDAP Servers	%s_UserCommonNamingAttribute%	cn
   	%s_UserContainerDN%	ou=People,dc=ldap,dc=acme,dc=com
   	%s_GroupContainerDN%	ou=Groups,dc=ldap,dc=acme,dc=com

   
   

   where:

   • %s_UserContainerDN% with a DN value of the entry under which all users are supposed to be added. The users container with:

     • dn: cn=Users,dc=us,dc=oracle,dc=com is used in this example for Active Directory

     • dn: ou=People,dc=ldap,dc=acme,dc=com is used in this example for other third-party LDAP servers

   • %s_GroupContainerDN% with a DN value of the entry under which all public groups are supposed to be added. The groups' container with:

     • dn: cn=Users,dc=us,dc=oracle,dc=com is used in this example for Active Directory

     • dn: ou=Groups,dc=ldap,dc=acme,dc=com is used in this example for other third-party LDAP servers

   • %s_UserCommonNamingAttribute% with the value used to construct the user's DN. In this example for other third-party LDAP servers, the cn value is used. %s_UserCommonNamingAttribute% and value are not applicable to Active Directory.

   Perform the following steps based on your type of third party LDAP server:

   • For Active Directory:

     Run the following commands at the DOS command prompt on Windows 2003:

     ldifde.exe -i -k -f system-winServer2003-ActDir.ldif
     ldifde.exe -i -k -f demo-winServer2003-ActDir.ldif
     ldifde.exe -i -k -f demo-roleGrants-winServer2003-ActDir.ldif
     
     

     See the following Microsoft Active Directory Documentation for details about all bulk import options for Active Directory's ldifde.exe:

     http://www.microsoft.com/technet/prodtechnol/windowsserver2003/technologies
     /directory/activedirectory/stepbystep/adbulk.mspx#ECAA
     
     

     The Windows system administrator must set passwords for all seeded users; otherwise, worklist application authentication does not work for those users.

   • For other third-party LDAP servers:

     Store changes in the system-ldap.ldif and demo-ldap.ldif files. Then load the system-ldap.ldif file to the LDAP server by using the ldapadd utility. Optionally, load demo-ldap.ldif with the ldapmodify utility.

     For example:

     $ldapadd -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f system-oid.ldif
     $ldapmodify -c -h ldap.acme.com -p 389 -D "cn=admin" -w welcome -f demo-oid.ldif
     
     

     See the documentation for the third-party LDAP server you are using for information about the ldapadd and ldapmodify commands.

3. The identity service third-party LDAP provider must specify connection, userControls, and roleControls elements in the identity service configuration file.

   Identity service third-party LDAP provider implementation defines a set of user search properties that must be configured:

   • nameattribute—the name of the LDAP attribute that uniquely identifies the name of the user. In Sun Directory Server, it is uid; in Active Directory, it is user.

   • objectClass—the LDAP schema object class used to represent a user. In Sun Directory Server, it is inetOrgPerson.

   And set of role search properties:

   • nameattribute—the name of the LDAP attribute that uniquely identifies the name of the role. In Sun Directory Server, it is uniqueMember; in Active Directory, it is member.

   • objectclass—the LDAP schema object class that is used to represent a group. In Sun Directory Server, it is groupOfUniqueNames. In Active Directory, it is group.

   • membershipsearchscope—specifies how deep in the LDAP directory tree to search for role membership. Supported values: onelevel or subtree.

   • memberattribute—The attribute of a static LDAP group object specifying the distinguished names (DNs) of the members of the group. In Sun Directory Server, it is uniqueMember; in Active Directory, it is member.

Both userControls and roleControl must define a search element with the searchbase attribute.

The searchbase attribute of the userControls search element is a space-separated list of DNs in the LDAP directory that contains users; for example, cn=users,dc=us,dc=abc,dc=com.

The searchbase attribute of the roleControls search element is a space-separated list of DNs in the LDAP directory that contains roles; for example, cn=Groups,dc=us,dc=abc,dc=com

An example of the LDAP server Sun Directory Server configuration follows:

<BPMIdentityServiceConfig xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig"> 
  <provider providerType="LDAP" name="iplanet" 
    <property name="realmName" value="iPlanetRealm"/> 
      <connection url="ldap://host:port" 
         binddn="uid=admin,ou=administrators,ou=topologymanagement,o=netscaperoot"
         password="welcome" encrypted="false" >
        <pool initsize="2" maxsize="25" prefsize="10" timeout="60"/>
      </connection>
    <userControls >
      <property name="nameattribute" value="uid"/>
      <property name="objectclass" value="inetOrgPerson"/>
        <search searchbase="ou=People,dc=us,dc=oracle,dc=com" 
maxSizeLimit="1000" maxTimeLimit="120" scope="onelevel" />
    </userControls>

    <roleControls >
      <property name="nameattribute" value="cn"/>
      <property name="objectclass" value="groupOfUniqueNames"/>
      <property name="membershipsearchscope" value="onelevel"/>
      <property name="memberattribute" value="uniquemember"/>
      <search searchbase="ou=Groups,dc=us,dc=oracle,dc=com" 
             maxSizeLimit="1000" maxTimeLimit="120" scope="onelevel" />
    </roleControls>
  </provider>
</BPMIdentityServiceConfig>

An example for Microsoft Active Directory follows:

<BPMIdentityServiceConfig xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig"> 
  <provider providerType="CUSTOM" name="Active Directory"
    <property name="realmName" value="ActiveDirectoryRealm"/>
    <connection url="ldap://host:port"
          binddn="cn=administrator,cn=Users,dc=us,dc=oracle,dc=com"
          password="welcome" encrypted="false" />
    <userControls >
      <property name="nameattribute" value="cn"/>
      <property name="objectclass" value="user"/>
      <search searchbase="cn=Users,dc=us,dc=oracle, dc=com", 
            maxSizeLimit="1000" maxTimeLimit="120 " scope="onelevel" />
    </userControls>

    <roleControls >
      <property name="nameattribute" value="cn"/>
      <property name="objectclass" value="group"/>
      <property name="membershipsearchscope" value="onelevel"/>
      <property name="memberattribute" value="member"/>
      <search searchbase="cn=Users,dc=us,dc=oracle,dc=com"
           maxSizeLimit="1000" maxTimeLimit="120" scope="onelevel" />
    </roleControls>
  </provider>
</BPMIdentityServiceConfig>

16.7.4.5 Configuration for CUSTOM User Repository Plug-ins

The following example shows how to use configuration properties to configure custom plug-ins. In this example, the CustomIdentityService class is used to demonstrate custom repository plug-ins. This class implements the BPMIdentityService interface.

<BPMIdentityServiceConfig mlns="http://www.oracle.com/pcbpel/identityservice/isconfig"> 
  <provider providerType="CUSTOM" name="CustomProvider" 
        class="custompakage.CustomIdentityService">
    <property name="realmName" value="CustomRealm"/> 
    <property name="CustomProviderProperty1" value="CustomProviderValue1"/> 
    <property name="CustomProviderProperty2" value="CustomProviderValue2"/> 
    <connection url="ldap://host:port"
             binddn="uid=admin password="welcome" encrypted="false" > 
      <property name="CustomConnProperty1" value="CustomConnValue1"/> 
      <property name="CustomConnProperty2" value="CustomConnValue2"/> 
    </connection>

    <userControls>
      <property name="CustomControlsProperty1" value="CustomControlsValue1"/> 
      <property name="CustomControlsProperty2" value="CustomControlsValue2"/> 
      <search searchbase="ou=UserContainer,dc=us,dc=oracle,dc=com"> 
        <property name="CustomSearchProperty1" value="CustomSearchValue1"/> 
        <property name="CustomSearchProperty2" value="CustomSearchValue2"/> 
      </search>
    </userControls>

    <roleControls >
      <property name="CustomControlsProperty1" value="CustomControlsValue1"/> 
      <property name="CustomControlsProperty2" value="CustomControlsValue2"/> 
      <search searchbase="ou=GroupContainer,dc=us,dc=oracle,dc=com"> 
        <property name="CustomSearchProperty1" value="CustomSearchValue1"/> 
        <property name="CustomSearchProperty2" value="CustomSearchValue2"/> 
      </search>
    </roleControls>
  </provider>
</BPMIdentityServiceConfig>

In addition to existing provider properties, you can define custom property elements that can be added to provider, connection, userControls, roleControls, and search elements in the configuration file to extend provider definitions.

16.7.5.1 Requirements

The custom identity service plug-in must implement the BPMIdentityService interface. This is the entry point for any identity service provider. See "Implementing the Identity Service Plug-in" for details.

See the sample implementation of a custom database plug-in in the Oracle_Home\integration\orabpel\samples\hw\isplugin\db directory.

16.7.5.2 Description of Oracle BPEL Process Manager Interfaces

Table 16-2 describes the available interfaces.

See the Javadoc for the different interfaces of identity service at ORACLE_HOME\integration\orabpel\docs\workflow.

16.7.5.3 Implementing the Identity Service Plug-in

The identity service plug-in can be implemented in one of two ways:

• Simple Implementations

  For simple implementations, you can use the framework provided in the database plug-in sample to plug in your providers. This implementation is most suitable for the following:

  • For simple repositories, in which you can implement just one interface and have the plug-in up and running.

  • For supporting multiple providers, in which you can use the supplied framework and easily add in the providers.

• Advanced Implementations

  For complex repositories, in which you can build your own framework and implement all of the essential interfaces.

16.7.5.4 Deploying the Identity Service Plug-in

For the workflow services to instantiate and invoke the plug-in, it must be deployed to a location in the library path of Oracle BPEL Process Manager. For example, for the database plug-in:

• The command obant deploy compiles the sample files and then assembles a JAR file that is copied to the Oracle_Home\integration\orabpel\services\lib location. The database plug-in is assembled into a JAR file named IS-DBPlugin.jar and deployed to the Oracle_Home\services\lib location. See the Oracle_Home\integration\orabpel\samples\hw\isplugin\db\build.xml file for more details.

• The plug-in must be deployed and the library path must point to this JAR file. The IS-DBPlugin.jar file is added to the library path by adding the following lines to the application.xml file (found in the Oracle_Home\system\appserver\oc4j\j2ee\home\config directory)

  <library path="D:\OraBPELPM_1\integration\orabpel\system\services/lib/IS-DBPlugin.jar"/>
  
  

The same scheme of deployment can be used for any custom plug-in, with minor changes such as the name of the provider JAR file.

16.7.5.5 Registering and Configuring Identity Service for the Custom Plug-in

Identity service configuration in defined in the is_config.xml file. The file must be located in a directory that is in the classpath of Oracle BPEL Process Manager. By default, it is stored in Oracle_Home\system\services\config.

The identity service configuration file consists of a root element BPMIdentyServiceConfig, which can have only one provider. For any custom service, the providerType attribute is set to CUSTOM (since this is a custom provider).

The following sample configuration file describes the database plug-in implemented as a custom provider (for more details, see the configuration file in ORACLE_HOME\integration\orabpel\samples\hw\isplugin\db).

<BPMIdentityServiceConfig xmlns = 
 "http://www.oracle.com/pcbpel/identityservice/isconfig"><provider providerType="CUSTOM" name="DBProvider" class =
 "IdentityServiceCustomPlugin.CustomIdentityService">
      <connection>
         <property name="dataSource" value="jdbc/BPELSamplesDataSource"/>
      </connection>
   </provider>
</BPMIdentityServiceConfig>

Table 16-3 describes the components of the sample configuration file.

<property name="dataSource"
 value="jdbc/BPELSamplesDataSource"/>

Custom plug-ins can define name-value properties as required for their data source.

16.7.5.6 Creating Users and Groups

The identity service plug-in only provides interfaces for the following:

• User authentication

• User properties lookup

• Group membership

• Workflow

• Actions permitted

The identity service plug-in does not include creation of users and roles or granting of roles to users. You must use tools specific to the user repository to accomplish this task. For OID, the users and roles can be created using the Directory Administration Service (DAS) tool.

16.7.5.7 Using the Plug-in with Installed Samples

Once the plug-in is deployed and configured, you can run the standard workflow service samples over the new provider. This requires seeding the system and demo users and roles (those used by the samples) into the data source of the custom plug-in.