Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.6.3)

Part Number E10224-15
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

34 Introduction to Human Workflow Services

This chapter describes for developers how the human workflow services in Oracle SOA Suite are used. These services perform a variety of operations in the life cycle of a task.

This chapter includes the following sections:

Note:

In previous releases, Oracle BPM Worklist included a feature known as flex fields. Starting with Release 11g R1 (11.1.1.4), flex fields are now known as mapped attributes.

34.1 Introduction to Human Workflow Services

This section describes the responsibilities of the following human workflow services.

34.1.1 SOAP, Enterprise JavaBeans, and Java Support for the Human Workflow Services

Table 34-1 lists the type of Simple Object Access Protocol (SOAP), Enterprise JavaBeans, and Java support provided for the task services. Most human workflow services are accessible through SOAP and remote Enterprise JavaBeans APIs. You can use these services directly by using appropriate client proxies. Additionally, the client libraries are provided to abstract out the protocol details and provide a common interface for all transports.

Table 34-1 Enterprise JavaBeans, SOAP, and Java Support

Service Name Supports SOAP Web Services Supports Remote Enterprise JavaBeans

Task Service: Provides task state management and persistence of tasks. In addition to these services, the task service exposes operations to update a task, complete a task, escalate and reassign tasks, and so on.

Yes

Yes

Task Query Service: Queries tasks for a user based on a variety of search criterion such as keyword, category, status, business process, attribute values, history information of a task, and so on.

Yes

Yes

Identity Service: Enables authentication of users and the lookup of user properties, roles, group memberships, and privileges.

Yes

No

Task Metadata Service: Exposes operations to retrieve metadata information related to a task.

Yes

Yes

User Metadata Service: Manages metadata related to workflow users, such as user work queues, preferences, vacation, and delegation rules.

Yes

Yes

Task Reports Service: Provides workflow report details.

Yes

Yes

Runtime Config Service: Provides methods for managing metadata used in the task service runtime environment.

Yes

Yes

Evidence Store Service: Supports storage and nonrepudiation of digitally-signed workflow tasks.

Yes

Yes


Table 34-2 lists the location for the SOAP Web Services Description Language (WSDL) file for each task service.

Table 34-2 SOAP WSDL Location for the Task Services

Service name SOAP WSDL location

Task Service

http://host:port/integration/services/TaskService/TaskServicePort?WSDL

Task Query Service

http://host:port/integration/services/TaskQueryService/TaskQueryService?WSDL

Identity Service

http://host:port/integration/services/IdentityService/configuration?WSDL

http://host:port/integration/services/IdentityService/identity?WSDL

Task Metadata Service

http://host:port/integration/services/TaskMetadataService/TaskMetadataServicePort?WSDL

User Metadata Service

http://host:port/integration/services/UserMetadataService/UserMetadataService?WSDL

Task Report Service

http://host:port/integration/services/TaskReportService/TaskReportServicePort?WSDL

Runtime Config Service

http://host:port/integration/services/RuntimeConfigService/RuntimeConfigService?WSDL

Evidence Store Service

http://host:port/integration/services/EvidenceService/EvidenceService?WSDL


Table 34-3 lists the JDNI names for the different Enterprise JavaBeans.

Table 34-3 JNDI Names for the Different Enterprise JavaBeans

Service name JNDI Names for the Different Enterprise JavaBeans

Task Service

ejb/bpel/services/workflow/TaskServiceBean

Task Service Enterprise JavaBeans participating in client transaction

ejb/bpel/services/workflow/TaskServiceGlobalTransactionBean

Task Metadata Service

ejb/bpel/services/workflow/TaskMetadataServiceBean

Task Query Service

ejb/bpel/services/workflow/TaskQueryService

User Metadata Service

ejb/bpel/services/workflow/UserMetadataService

Runtime Config Service

ejb/bpel/services/workflow/RuntimeConfigService

Task Report Service

ejb/bpel/services/workflow/TaskReportServiceBean

Task Evidence Service

ejb/bpel/services/workflow/TaskEvidenceServiceBean


For more information about the client library for worklist services, see Chapter 33, "Building a Custom Worklist Client" for details.

34.1.1.1 Support for Foreign JNDI Names

Human workflow services can be integrated with J2EE applications through web services and remote method invocation (RMI). To simplify the remote lookup of Enterprise JavaBeans in other managed servers and clusters or even other Oracle WebLogic Server domains, Oracle WebLogic Server includes foreign JNDI providers that are configured with the remote server's host and port to link Enterprise JavaBeans from that remote server into the local server's JNDI trees.

Workflow services expose the Enterprise JavaBeans listed in Table 34-3 that must all be linked through the foreign JNDI providers to provide full support for the task query service, ADF task flow for human task registration, and embedded worklist region use cases.

To provide support for foreign JNDI names:

  1. Log in to Oracle WebLogic Server Administration Console.

    http://host:port/console
    
  2. In the Domain Structure, select Services > JDBC > Foreign JNDI Providers.

    There is one caveat when linking remote Enterprise JavaBeans names to the local JNDI namespace through a foreign JNDI provider from a SOA server to a managed server or cluster in the same Oracle WebLogic Server domain. The local JNDI names are exposed to all of the managed servers within that domain. This causes namespace collisions on the SOA server within that domain, which already has those Enterprise JavaBeans registered from the Oracle BPM Worklist. An alternative, which avoids collisions while keeping configuration to a minimum, is to use JNDI suffixing. This is done by appending a consistent suffix to the end of all the local JNDI links of the remote workflow Enterprise JavaBeans and creating a simple wf_client_config.xml file that contains the suffix key.

    You can define client properties in either of three ways. For more information, see Section 34.6.1.2, "Configuration Option."

  3. Append the JNDI suffix to each Enterprise JavaBeans name shown in Table 34-3 to register the foreign JNDI names.

    • ejb/bpel/services/workflow/TaskServiceGlobalTransactionean_server1

    • ejb/bpel/services/workflow/TaskServiceBean_server1

    • ejb/bpel/services/workflow/TaskMetadataServiceBean_server1

    • TaskQueryService_server1

    • UserMetadataService_server1

    • RuntimeConfigService_server1

    • TaskReportServiceBean_server1

    • TaskEvidenceServiceBean_server1

  4. Define the remote name by specifying only the ejbJndiSuffix element value in the wf_client_config.xml file, as shown in Example 34-1. You can also use the JAXB WorkflowServicesClientConfigurationType object or the CONNECTION_PROPERTY.EJB_JNDI_SUFFIX in the Map<CONNECTION_PROPERTY, String> properties.

    Example 34-1 ejbJndiSuffix Element Value

    <remoteClient>
          <ejbJndiSuffix>_server1</ejbJndiSuffix>
    </remoteClient>
    

34.1.2 Security Model for Services

With the exception of the identity service, all services that use the above-mentioned APIs (SOAP and remote Enterprise JavaBeans) require authentication to be invoked. All the above channels support passing the user identity using the human workflow context. The human workflow context contains either of the following:

  • Login and password

  • Token

The task query service exposes the authenticate operation that takes the login and password and returns the human workflow context used for all services. Optionally, with each request, you can pass the human workflow context with the login and password.

The authenticate operation also supports the concept of creating the context on behalf of a user with the admin ID and admin password. This operation enables you to create the context for a logged-in user to the Oracle BPM Worklist if the password for that user is not available.

Oracle recommends that you get the workflow context one time and use it everywhere. There are performance implications for getting the workflow context for every request.

A realm is an identity service context from the identity configuration. The realm name can be null if the default configuration is used.

34.1.2.1 Limitation on Propagating Identity to Workflow Services when Using SOAP Web Services

Identity propagation is the replication of authenticated identities across multiple SOAP web services used to complete a single transaction. SOAP web services also support web service security. When web service security is used, the human workflow context does not need to be present in the SOAP input. Web service security can be configured from Oracle Enterprise Manager Fusion Middleware Control.

Note:

Human workflow SOAP clients have been enhanced to work with Security Assertion Markup Language (SAML) token-based identity propagation when the web service is secured.

34.1.2.2 Creating Human Workflow Context on Behalf of a User

The authenticateOnBehalfOf API method on the task query service can create the human workflow context on behalf of a user by passing the user ID and password of an admin user in the request. An admin user is a user with the workflow.admin privilege. This created context is as if it was created using the password on behalf of the user.

This is useful for environments in which a back-end system acts on workflow tasks while users act in their own system. There is no direct interaction with workflow services; the system can use the on-behalf-of-user login to get a context for the user.

Note:

Oracle recommends that you only use this feature for system operations. This is because you must create an admin user context and then query for the human workflow context created on behalf of the user. If you instead use identity propagation, the user is already authenticated and the client can get IWorkflowContext for the already authenticated user. For more information, see Section 34.1.2.3, "Obtaining the Workflow Context for a User Previously Authenticated by a JAAS Application."

In Example 34-2, the human workflow context is created for user jcooper.

Example 34-2 Human Workflow Context Creation

String adminUser = "...."
String adminPassword = "...."
String realm = "...."

IWorkflowContext adminCtx =
taskQueryService.authenticate(user,password.toCharArray(),realm);

IWorkflowContext behalfOfCtx =
 taskQueryService.authenticateOnBehalfOf(adminCtx,"jcooper");

34.1.2.3 Obtaining the Workflow Context for a User Previously Authenticated by a JAAS Application

If the client wants to obtain the workflow context for a user previously authenticated by a JAAS application, you can use identity propagation as shown in Example 34-3.

Example 34-3 Identity Propagation

public IWorkflowContext getWorkflowContextForAuthenticatedUser() throws WorkflowException;

This API returns a workflow context for the authenticated user if the client configures the identity propagation for the appropriate client type. If the client type is remote, Enterprise JavaBeans identity propagation is used with this method. If the client type is SOAP, SAML token propagation is used with this method.

34.1.3 Task Service

The task service exposes operations to act on tasks. Table 34-4 describes the operations of the task service. Package oracle.bpel.services.workflow.task corresponds to the task service.

Table 34-4 Task Service Methods

Method Description

acquireTask

Acquire a task.

acquireTasks

Acquire a set of tasks.

addAttachment

Add an attachment to a task.

addComment

Add a comment to a task.

createToDoTask

Create a to-do task.

delegateTask

Delegate a task to a different user. Both the current assignee and the user to whom the task is delegated can view and act on the task.

delegateTasks

Delegate a list of tasks to a different user. Both the current assignee and the user to whom the list of tasks is delegated can view and act on the tasks.

deleteTask

Perform a logical deletion of a task. The task still exists in the database.

deleteTasks

Perform a logical deletion of a list of tasks. The tasks still exist in the database.

errorTask

Cause the task to error. This operation is typically used by the error assignee.

escalateTask

Escalate a task. The default escalation is to the manager of the current user. This can be overridden using escalation functions.

escalateTasks

Escalate tasks in bulk. The default escalation is to the manager of the current user. This can be overridden using escalation functions.

getApprovers

Get the previous approvers of a task.

getFutureParticipants

Get the future participants of a task. The future participants are returned in the form of a routing slip that contains simple participants (participant node and parallel nodes that contain routing slips).

getUsersToRequestInfoForTask

Get the users from whom a request for information can be requested.

initiateTask

Initiate a task.

mergeAndUpdateTask

Merge and update a task. Use this operation when a partial task should be updated. A partial task is one in which not all the task attributes are present. In this partial task, only the following task attributes are interpreted:

  • Task payload

  • Comments

  • Task state

  • Task outcome

overrideRoutingSlip

Override the routing slip of a task instance with a new routing slip. The current task assignment is nullified and the new routing slip is interpreted as its task is initiated.

purgeTask

Remove a task from the persistent store.

purgeTasks

Remove a list of tasks from the persistent store.

pushBackTask

Push back a task to the previous approver or original assignees. The original assignees do not need to be the approver, as they may have reassigned the task, escalated the task, and so on. The property PushbackAssignee in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control controls whether the task is pushed back to the original assignees or the approvers.

  1. From the SOA Infrastructure menu, select Administration > System MBean Browser.

  2. Select Application Defined MBeans > oracle.as.soainfra.config > Server: soa_server1 > WorkflowConfig > human-workflow.

  3. Click PushbackAssignee to view or change the value.

reassignTask

Reassign a task.

reassignTasks

Reassign tasks in bulk.

reinitiateTask

Reinitiate a task. Reinitiating a task causes a previously completed task to be carried forward so that the history, comments, and attachments are carried forward in a new task.

releaseTask

Release a previously acquired task.

releaseTasks

Release a set of previously acquired tasks.

removeAttachment

Remove a task attachment.

renewTask

Renew a task to extend the time it takes to expire.

requestInfoForTask

Request information for a task.

requestInfoForTaskWithReapproval

Request information for a task with reapproval. For example, assume jcooper created a task and jstein and wfaulk approved the task in the same order. When the next approver, cdickens, requests information with reapproval from jcooper, and jcooper submits the information, jstein and wfaulk approve the task before it comes to cdickens. If cdickens requests information with reapproval from jstein, and jstein submits the information, wfaulk approves the task before it comes to cdickens.

resumeTask

Resume a task. Operations can only be performed by the task owners (or users with the BPMWorkflowSuspend privilege) to remove the hold on a workflow. After a human workflow is resumed, actions can be performed on the task.

resumeTasks

Resume a set of tasks.

routeTask

Allow a user to route the task in an ad hoc fashion to the next user(s) who must review the task. The user can specify to route the tasks in serial, parallel, or single assignment. Routing a task is permitted only when the human workflow permits ad hoc routing of the task.

skipCurrentAssignment

Skip the current assignment and move to the next assignment or pick the outcome as set by the previous approver if there are no more assignees.

submitInfoForTask

Submit information for a task. This action is typically performed after the user has made the necessary updates to the task or has added comments or attachments containing additional information.

suspendTask

Allow task owners (or users with the BPMWorkflowSuspend privilege) to put a human workflow on hold temporarily. In this case, task expiration and escalation do not apply until the workflow is resumed. No actions are permitted on a task that has been suspended (except resume and withdraw).

suspendTasks

Suspend a set of tasks.

updateOutcomeOfTasks

Update the outcome of a set of tasks.

updatePriority

Update the priority of the task and its subtasks for the given task ID. If UpdatePriorityType is INCREMENT then the task is updated by incrementing the given priority by 1—that is, the priority of the task is raised. If the UpdatePriorityType is DECREMENT, then the task is updated by decrementing the priority by 1—that is, the priority of the task is lowered, otherwise the task is updated with the given priority.

updatePriorityOfTasks

For bulk update of tasks. A list of tasks for which the priority must be updated can be passed as a parameter to this API. The priorities of the list of tasks is updated. It updates the priority of the task and its subtasks.

updateTask

Update the task.

updateTaskOutcome

Update the task outcome.

updateTaskOutcomeAndRoute

Update the task outcome and route the task. Routing a task allows a user to route the task in an ad hoc fashion to the next user(s) who must review the task. The user can specify to route the tasks in serial, parallel, or single assignment. Routing a task is permitted only when the human workflow permits ad hoc routing of the task.

withdrawTask

The creator of the task can withdraw any pending task if they are no longer interested in sending it further through the human workflow. A task owner can also withdraw a task on behalf of the creator. When a task is withdrawn, the business process is called back with the state attribute of the task set to Withdrawn.

withdrawTasks

Withdraw a set of tasks.


For more information, see the following:

34.1.4 Task Query Service

The task query service queries tasks based on a variety of search criterion such as keyword, category, status, business process, attribute values, historical information of a task, and so on. Table 34-5 describes the operations of the task query service, including how to use the service over SOAP. Package oracle.bpel.services.workflow.query corresponds to the task query service.

Table 34-5 Task Query Service Methods

Method Description

authenticate

Authenticates a user with the identity authentication service and passes back a valid IWorkflowContext object.

authenticateOnBehalfOf

Optionally makes authentication on behalf of another user.

countTasks

Counts the number of tasks that match the specified query criteria.

countViewTasks

Counts the number of tasks that match the query criteria of the specified view.

createContext

Creates a valid IWorkflowContext object from a preauthenticated HTTP request.

doesTaskExist

Checks to see if any existing tasks match the specified query criteria.

doesViewTaskExist

Checks to see if any tasks exist match the query criteria of the specified view.

getWorkflowContext

Gets a human workflow context with the specified context token.

destroyWorkflowContext

Cleans up a human workflow context that is no longer needed. This method is typically used when a user logs out.

getTaskDetailsById

Gets the details of a specific task from the task's taskId property.

getTaskDetailsByNumber

Gets the details of a specific task from the task's task number property.

getTaskHistory

Gets a list of the task versions for the specified task ID.

getTaskSequence

Gets the task sequence tree of a task whose ID is a task ID, for those type of sequences.

getTaskVersionDetails

Gets the specific task version details for the specified task ID and version number.

getWorkflowContextForAuthenticatedUser

Gets the IWorkflowContext object for a user authenticated by a JAAS application. Use this either with Enterprise JavaBeans or SAML token identity propagation.

queryAggregatedTasks

Executes the specified query, and aggregates a count of the tasks returned by the query, grouped by the specified column.

queryTaskErrors

Returns a list of task error objects matching the specified predicate.

queryTasks

Returns a list of tasks that match the specified filter conditions. Tasks are listed according to the ordering condition specified (if any). The entire list of tasks matching the criteria can be returned or clients can execute paging queries in which only a specified number of tasks in the list are retrieved. The filter conditions are as follows:

  • assignmentFilter: Filters tasks according to whom the task is assigned, or who created the task. Possible values for the assignment filter are as follows:

    ADMIN: No filtering; returns all tasks regardless of assignment or creator.

    ALL: No filtering; returns all tasks regardless of assignment or creator.

    CREATOR: Returns tasks in which the context user is the creator.

    GROUP: Returns tasks that are assigned to a group, application role, or list of users of which the context user is a member.

    MY: Returns tasks that are assigned exclusively to the context user.

    MY_AND_GROUP: Returns tasks that are assigned exclusively to the context user, or to a group, application role, or list of users of which the context user is a member.

    OWNER: Returns tasks in which the context user is the task owner.

    PREVIOUS: Returns tasks the context user previously updated.

    REPORTEES: Returns tasks that are assigned to reportees of the context user.

    REVIEWER: Returns tasks for which the context user is a reviewer.

  • keywords: An optional search string. This only returns tasks in which the string is contained in the task title, task identification key, or one of the task text mapped attributes (formerly referred to as flex fields).

  • predicate: An optional oracle.bpel.services.workflow.repos.Predicate object that allows clients to specify complex, SQL-like query predicates.

queryViewAggregatedTasks

Executes the query as defined in the specified view, and aggregates the selected tasks according to the chart property defined in the view.

queryViewTasks

Returns a list of tasks according to the criteria in the specified view. The entire list or paged list of tasks can be returned. Clients can specify additional filter and ordering criteria to those in the view.


For more information, see the following:

34.1.5 Identity Service

The identity service is a thin web service layer on top of the Oracle WebLogic Server security infrastructure, namely Oracle Identity Management and Oracle Platform Security Services (OPSS), or any custom user repository. The identity service enables authentication of users and the lookup of user properties, roles, group memberships, and privileges. Oracle Identity Management is the sole identity service provider for Oracle WebLogic Server. Oracle Identity Management handles all storage and retrieval of users and roles for various repositories, including XML, LDAP, and so on. More specifically, Oracle Identity Management provides the following features:

  • All providers are supported through Oracle Identity Management. The OracleAS JAAS Provider (JAZN) and LDAP providers are no longer supported. The custom provider is deprecated and supported only for backward compatibility. All customization of providers is performed through the custom provider to Oracle Identity Management, through configuring Oracle Virtual Directory (OVD) as an LDAP provider to Oracle Identity Management, or through both. OVD aggregates data across various repositories.

  • The OPSS layer is used, which includes the following:

    • Identity store

    • Policy store

    • Credential store

    • Framework

    For more information, see Oracle Fusion Middleware Security Guide. All security configuration is done through the jps-config.xml file.

  • All privileges are validated against permissions, as compared to actions in previous releases.

  • The following set of application roles are defined. These roles are automatically defined in the SOA Infrastructure application of the OPSS policy store.

    • SOAAdmin: Grant this role to users who must perform administrative actions on any SOA module. This role is also granted the BPMWorkflowAdmin and B2BAdmin roles.

    • BPMWorkflowAdmin: Grant this role to users who must perform any workflow administrative action. This includes actions such as searching and acting on any task in the system, creating and modifying user and group rules, performing application customization, and so on. This role is granted the BPMWorkflowCustomize role and the following permissions:

      • workflow.mapping.protectedFlexField

      • workflow.admin.evidenceStore

      • workflow.admin

    • BPMWorkflowCustomize: Grant this role to business users who must perform mapped attributes (formally flex field) mapping to public mapped attributes. This role is also granted the workflow.mapping.publicFlexField permission.

  • The following workflow permissions are defined:

    • workflow.admin: Controls who can perform administrative actions related to tasks, user and group rules, and customizations.

    • workflow.admin.evidenceStore: Controls who can view and search evidence records related to digitally-signed tasks (tasks that require a signature with the use of digital certificates).

    • workflow.mapping.publicFlexField: Controls who can perform mapping of task payload attributes to public mapped attributes.

    • workflow.mapping.protectedFlexField: Controls who can perform mapping of task payload attributes to protected mapped attributes.

Note:

You cannot specify multiple authentication providers for Oracle SOA Suite. This is because OPSS does not support multiple providers. The provider to use for human workflow authentication must be the first one listed in the order of authentication providers for Oracle SOA Suite.

For more information, see the following:

34.1.5.1 Identity Service Providers

Oracle Identity Management is the only supported provider for release 11g, as shown in Figure 34-1.

Figure 34-1 Identity Service Providers

Description of Figure 34-1 follows
Description of "Figure 34-1 Identity Service Providers"

34.1.5.1.1 Custom User Repository Plug-ins

Starting with release 11g, custom provider plug-ins in the identity service are not supported. All identity customizations are now done in the identity store. Oracle Fusion Middleware supports providers that enable the User and Role API to interact with custom identity stores. For more information, visit the following URL:

http://www.oracle.com/technetwork/middleware/id-mgmt/overview/index.html

34.1.6 Task Metadata Service

The task metadata service exposes operations to retrieve metadata information related to a task. Table 34-6 describes these methods. Package oracle.bpel.services.workflow.metadata corresponds to the task metadata service.

Table 34-6 Task Metadata Service Methods

Method Description

getTaskMetadataByNamespace

Gets the TaskMetadata object that describes the human task service component with the specified task definition namespace and composite version.

getOutcomes

Gets the permitted outcomes of a task. The outcomes are returned with their display values.

getResourceBundleInfo

Gets the resource bundle information of the task. The resource bundle information contains the location and the name of the bundle.

getRestrictedActions

Gets the actions that are restricted for a particular task.

getTaskAttributesForTaskDefinitions

Gets a list of TaskAttribute objects that describe standard task attributes and mapped attribute columns that are common for the specified task definitions.

getTaskAttributesForTaskNamespaces

Gets a list of TaskAttribute objects that describe standard task attributes and mapped attribute columns that are common for task definitions identified by the specified namespaces.

getTaskAttributes

Gets the task message attributes.

getTaskAttributesForTaskDefinition

Gets the message attributes for a particular task definition.

getTaskDefinition

Gets the task definition associated with the task.

getTaskDefinitionById

Gets the task definition by the task definition ID.

getTaskDefinitionOutcome

Gets the outcomes given the task definition ID.

getTaskDisplay

Gets the task display for a task.

getTaskVisibilityRules

Gets the task visibility rules.

getTaskDisplayRegion

Gets the task display region for a task.

getVersionTrackedAttrs

Gets the task attributes that when changed cause a task version creation.

listTaskMetadata

Lists the task definitions in the system.


For more information, see Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager.

34.1.7 User Metadata Service

The user metadata service provides methods for managing metadata specific to individual users and groups. It is used for getting and setting user worklist preferences, managing user custom views, and managing human workflow rules for users and groups.

For most methods in the user metadata service, the authenticated user can query and update their own user metadata. However, they cannot update metadata belonging to other users.

In the case of group metadata (for example, human workflow rules for groups), only a user designated as an owner of a group (or a user with the workflow.admin privilege) can query and update the metadata for that group. However, a user with the workflow.admin privilege can query and update metadata for any user or group.

Table 34-7 describes the methods in the user metadata service. Package oracle.bpel.services.workflow.user corresponds to the user metadata service.

Table 34-7 User Metadata Service Methods

Method Description

createRule

Creates a new rule.

decreaseRulePriority

Decreases the priority of a rule by one. This method does nothing if this rule has the lowest priority.

deleteRule

Deletes a rule.

getVacationInfo

Retrieves the date range (if any) during which a user is unavailable for the assignment of tasks.

getRuleDetail

Gets the details for a particular human workflow rule.

getRuleList

Retrieves a list of rules for a particular user or group.

updateRule

Updates an existing rule.

increaseRulePriority

Increases the priority of a rule by one. Rules for a user or group are maintained in an ordered list of priority. Higher priority rules (those closer to the head of the list) are executed before rules with lower priority. This method does nothing if this rule has the highest priority.

getUserTaskViewList

Gets a list of the user task views that the user owns.

getGrantedTaskViewList

Gets a list of user task views that have been granted to the user by other users. Users can use granted views for querying lists of tasks, but they cannot update the view definition.

getStandardTaskViewList

Gets a list of standard task views that ship with the human workflow service, and are available to all users.

getUserTaskViewDetails

Gets the details for a single view.

createUserTaskView

Creates a new user task view.

updateUserTaskView

Updates an existing user task view.

deleteUserTaskView

Deletes a user task view.

updateGrantedTaskView

Updates details of a view grant made to this user by another user. Updates are limited to hiding or unhiding the view grant (hiding a view means that the view is not listed in the main inbox page of Oracle BPM Worklist), and changing the name and description that the granted user sees for the view.

getUserPreferences

Gets a list of user preferences for the user. User preferences are simple name-value pairs of strings. User preferences are private to each user (but can still be queried and updated by a user with the workflow.admin privilege).

setUserPreferences

Sets the user preference values for the user. Any preferences that were previously stored and are not in the new list of user preferences are deleted.

getPublicPreferences

Gets a list of public preferences for the user. Public preferences are similar to user preferences, except that any user can query them. However, only the user that owns the preferences, or a user with the workflow.admin privilege, can update them. Public preferences are useful for storing application-wide preferences (preferences can be stored under a dummy user name, such as MyAppPrefs).

setPublicPreferences

Sets the public preferences for the user.

setVacationInfo

Sets a date range over which the user is unavailable for the assignment of tasks. (Dynamic assignment functions do not assign tasks to a user that is on vacation.)

getStandardTaskViewDetails

Gets the full details for a particular standard view, identified by its viewId.


For more information, see the following:

34.1.8 Task Report Service

The task report service executes a report and receives the results. Table 34-8 describes the method. Package oracle.bpel.services.workflow.report corresponds to the task report service. The standard reports shown in Table 34-8 are available as part of installation.

Table 34-8 Task Report Service

Report Description

Unattended tasks report

Provides an analysis of tasks assigned to users' groups or reportees' groups that require attention because they have not yet been acquired.

Tasks priority report

Provides an analysis of the number of tasks by priorities assigned to a user, reportees, or their groups.

Tasks cycle time report

Provides an analysis of time taken to complete tasks from assignment to completion based on users' groups or reportees' groups.

Tasks productivity report

Provides an analysis of tasks assigned and tasks completed in a given time period for a user, reportees, or their groups.

Tasks time distribution report

Provides an analysis of time taken to complete their part of the tasks for a given user, user's groups, or reportees in the given time period.


34.1.9 Runtime Config Service

The runtime config service provides methods for managing metadata used in the task service runtime environment. It principally supports the management of task payload mapped attribute mappings and the URIs used for displaying task details.

The task object used by the task service contains many mapped attributes, which can be populated with information from the task payload. This allows the task payload information to be queried, displayed in task listings, and used in human workflow rules.

The runtime config service provides methods for querying and updating the URI used for displaying the task details of instances of a particular task definition in a client application. For any given task definition, multiple display URIs can be supported, with different URIs being used for different applications. The method getTaskDisplayInfo can query the URIs for a particular task definition. The method setTaskDisplayInfo can define new URIs or update existing ones. Only users with the workflow.admin privilege can call setTaskDisplayInfo, but any authenticated user can call getTaskDisplayInfo.

The runtime config service allows administrators to create mappings between simple task payload attributes and these mapped attributes.

Only a user with the workflow.mapping.publicFlexField or workflow.mapping.protectedFlexField privilege can make updates to payload mappings for public mapped attributes. Only a user with the workflow.mapping.protectedFlexField privilege can make updates to payload mappings for protected mapped attributes. Any authenticated user can use the query methods in this service.

An administrator can create attribute labels for the various mapped attributes. These attribute labels provide a meaningful label for the attribute (for example, a label Location may be created for the mapped attribute TextAttribute1). A given mapped attribute may have multiple labels associated with it. This attribute label is what is displayed to users when displaying lists of attributes for a specific task in Oracle BPM Worklist. The attribute labels for a specific task type can be determined by calling the getTaskAttributesForTaskDefinition method on the task metadata service.

When defining attribute labels, the following fields are automatically populated by the service. You do not need to specify values for these attributes when creating or updating attribute labels:

  • Id

  • CreatedDate

  • WorkflowType

  • Active

Valid values for the task attribute field for public mapped attributes are as follows:

  • TextAttribute1 through TextAttribute20

  • FormAttribute1 through FormAttribute10

  • UrlAttribute1 through UrlAttribute10

  • DateAttribute1 through DateAttribute10

  • NumberAttribute1 through NumberAttribute10

Mappings can then be created between task payload fields and the attribute labels. For example, the payload field customerLocation can be mapped to the attribute label Location. Different task types can share the same attribute label. This allows payload attributes from different task types that have the same semantic meaning to be mapped to the same attribute label.

Note:

Only payload fields that are simple XML types can be mapped.

The runtime config service also provides the following:

  • Methods for querying the dynamic assignment functions supported by the server

  • Methods for maintaining the task display URLs used for displaying the task details in Oracle BPM Worklist and other applications

  • Methods for getting the server HTTP and JNDI URLs

Table 34-9 describes the methods in the runtime config service. Package oracle.bpel.services.workflow.runtimeconfig corresponds to the runtime config service.

Table 34-9 Runtime Config Service

Method Description

CreateAttributeLabel

Creates a new attribute label for a particular task mapped attribute.

createPayloadMapping

Creates a new mapping between an attribute label and a task payload field.

DeleteAttributeLabel

Deletes an existing attribute label.

deletePayloadMapping

Deletes an existing payload mapping.

getAttributeLabelUsages

Gets a list of attribute labels (either all attribute labels or labels for a specific type of attribute) for which mapping (if any) the labels are currently used.

getGroupDynamicAssignmentFunctions

Returns a list of the dynamic assignment functions that can select a group that are implemented on this server.

getTaskDisplayInfo

Retrieves information relating to the URIs used for displaying task instances of a specific task definition.

getTaskStatus

Gets the status of a task instance corresponding to a particular task definition and composite instance.

getUserDynamicAssignmentFunctions

Returns a list of the dynamic assignment functions that can select a user that are implemented on this server.

GetWorkflowPayloadMappings

Gets a list of all the mapped attribute mappings for a particular human workflow definition.

setTaskDisplayInfo

Sets information relating to the URIs to be used for displaying task instances of a specific task definition.

updateAttributeLabel

Updates an existing attribute label.


For more information, see the following:

34.1.9.1 Internationalization of Attribute Labels

Attribute labels provide a method of attaching a meaningful label to a task mapped attribute. It can be desirable to present attribute labels that are translated into the appropriate language for the locale of the user.

To use a custom resource bundle, place it at the location identified by the workflow configuration parameter workflowCustomClasspathURL (which can be a file or HTTP path).

This can be set in either of two places in Oracle Enterprise Manager Fusion Middleware Control:

  • System MBean Browser page

  • Workflow Task Service Properties page

For more information, see the workflow-110-workflowCustomizations sample, which describes how to use this parameter. Visit the Oracle SOA Suite samples for details:

Entries for mapped attribute labels must be of the form:

FLEX_LABEL.[label name]=Label Display Name

For instance, the entry for a label named Location is:

FLEX_LABEL.Location=Location

Adding entries to these files for attribute labels is optional. If no entry is present in the file, the name of the attribute label as specified using the API is used instead.

34.1.10 Evidence Store Service and Digital Signatures

The evidence store service is used for digital signature storage and nonrepudiation of digitally-signed human workflows. A digital signature is an electronic signature that authenticates the identity of a message sender or document signer. This ensures that the original content of the message or document sent is unchanged. Digital signatures are transportable, cannot be imitated by others, and are automatically time-stamped. The ability to ensure that the original signed message arrived means that the sender cannot repudiate it later. Digital signatures ensure that a human workflow document:

  • Is authentic

  • Has not been forged by another entity

  • Has not been altered

  • Cannot be repudiated by the sender

A cryptographically-based digital signature is created when a public key algorithm signs a sender's message with a sender's private key.

During design time, signatures are enabled for the task. During runtime in Oracle BPM Worklist, when a user approves or rejects the task, the web browser:

  • Asks the user to choose the private key to use for signing.

  • Generates a digital signature using the private key and task content provided by Oracle BPM Worklist.

Figure 34-2 provides an example.

Figure 34-2 Digital Signature and Certificate

Description of Figure 34-2 follows
Description of "Figure 34-2 Digital Signature and Certificate"

Notes:

  • The certificate refers to a Personal Information Exchange Syntax Standard (PFX) file that includes a certificate and a private key, and is protected by a simple text password. PFX specifies a portable format for storing or transporting a user's private keys, certificates, miscellaneous secrets, and so on.

  • The possession of a private key that corresponds to the public key of a certificate is sufficient to sign the data, because the signature is verifiable through the public key in the certificate. However, no attempt is made to correlate the name of a user of a certificate with the person updating it. For example, user jstein can sign using the private key of user cdickens if jstein has that private key.

The following digital signature features are supported:

  • PKCS7 signatures based on X.509 certificates

  • Browser-based, digitally-signed content without attachments

34.1.10.1 Prerequisites

Prerequisites for using digital signatures and certificates are as follows:

  • Users of the Oracle BPM Worklist must have certificates

  • The administrator must specify the CAs and corresponding CRL URL whose certificates must be trusted. Users are expected to upload only certificates issued by these CAs. This is done by editing the System MBean Browser in Oracle Enterprise Manager Fusion Middleware Control.

    1. Log in to Oracle Enterprise Manager Fusion Middleware Control.

    2. In the navigator, expand the SOA folder.

    3. Right-click soa-infra, and select Administration > System Mbean Browser.

      The System Mbean Browser displays on the right side of the page.

    4. Expand Application Defined MBeans > oracle.as.soainfra.config > Server: server_name > WorkflowConfig > human-workflow.

    5. Click the Operations tab on the right side of the page.

    6. Click addTrustedCA.

    7. Provide values for caName and caURL. You must do this for each certificate in the trust chain. For example, values provided for each invocation may look as shown in Table 34-10.

      Table 34-10 caName and caURL Values

      caName caURL

      CN = Intg, OU =AppServ, O =Oracle, C = US

      http://www.oracle.com/Integration%20CRL%20Data.crl

      CN = Intg1, OU =AppServ, O =Oracle, C = US

      http://www.oracleindia.in.com/Integration%20In.crl

      CN = Intg2, OU =AppServ, O =Oracle, C = US

      http://www.oracle.us.com/integration.crl


    8. Click Invoke.

34.1.10.2 Interfaces and Methods

Table 34-11 through Table 34-14 describe the methods in the evidence store service. Package oracle.bpel.services.security.evidence corresponds to the evidence service.

Table 34-11 ITaskEvidenceService Interface

Method Description

createEvidence

Creates evidence and stores it in the repository for nonrepudiation.

getEvidence

Gets a list of evidence matching the given criteria. The result also depends on the privileges associated with the user querying the service. If the user has been granted the workflow.admin.evidenceStore permission (points to a location detailing how to grant the permission), all matching evidence is visible. Otherwise, only that evidence created by the user is visible.

uploadCertificate

Uploads certificates to be used later for signature verification. This is a prerequisite for creating evidence using a given certificate. A user can only upload their certificates.

updateEvidence

Updates the CRL verification part of the status. This includes verified time, status, and error messages, if any.

validateEvidenceSignature

Validates the evidence signature. This essentially performs a nonrepudiation check on the evidence. A value of true is returned if the signature is verified. Otherwise, false is returned.


Table 34-12 Evidence Interface

Method Description

getCertificate

Gets the certificate used to sign this evidence.

getCreateDate

Gets the creation date of the evidence.

getErrorMessage

Gets the error message associated with the CRL validation.

getEvidenceId

Gets the unique identifier associated with the evidence.

getPlainText

Gets the content that was signed as part of this evidence.

getPolicy

Gets the signature policy of the evidence. This is either PASSWORD or CERTIFICATE.

getSignature

Gets the signature of this evidence.

getSignedDate

Gets the date on which the signature was created.

getStatus

Gets the CRL validation status. This can be one of the following:

  • AVAILABLE: The evidence is available for CRL validation.

  • FAILURE: CRL validation failed.

  • SUCCESS: CRL validation succeeded.

  • UNAVAILABLE: The CRL data could not be fetched.

  • WAIT: CRL validation is in progress.

getTaskId

Gets the unique identifier of the task with which this evidence is associated.

getTaskNumber

Gets the task number of the task with which this evidence is associated.

getTaskPriority

Gets the task priority of the task with which this evidence is associated.

getTaskStatus

Gets the task status of the task with which this evidence is associated.

getTaskSubStatus

Gets the task substatus of the task with which this evidence is associated.

getTaskTitle

Gets the title of the task with which this evidence is associated.

getTaskVersion

Gets the version of the task with which this evidence is associated.

getVerifiedDate

Gets the date on which the CRL validation of the certificate used was performed.

getWorkflowType

Gets the workflow type of the task with which this evidence is associated. This is typically BPELWF.


Table 34-13 Certificate Interface

Method Description

getCA

Gets the certificate issuer's distinguished name (DN).

getCertificate

Gets the certificate object that is abstracted by the interface.

getID

Gets the certificate's serial number.

getIdentityContext

Gets the identity context with which the uploader of this certificate is associated.

getUserName

Gets the user name with whom this certificate is associated.

isValid

Returns true if the certificate is still valid.


Table 34-14 Policy Type and Workflow Type Interface

Method Description

fromValue

Constructs an object from the string representation.

value

Returns the string representation of this object.


For more information, see the following:

34.1.11 Task Instance Attributes

A task is work that must be done by a user. When you create a task, you assign humans to participate in and act upon the task. Table 34-15 describes the task attributes that are commonly used and interpreted by applications.

Table 34-15 Task Attributes

Task Attribute Name Description

task/applicationContext

The application with which any application roles associated with this task (assignees, owners, and so on) belong.

task/category

An optional category of the task.

task/creator

The name of the creator of this task.

task/dueDate

The due date for the task. This is used on to-do tasks.

task/identificationKey

An optional, custom, unique identifier for the task. This can be set as an additional unique identifier to the standard task ID and task number. This key can retrieve a task based on business object identifiers for which the task is created.

task/identityContext

The identity realm under which the users and groups are seeded. In a single realm environment, this defaults to the default realm.

task/ownerGroup

The group (if any) that owns this task instance. Task owners can be application roles, users, or groups. If the owner of the task is a group, this field is set.

task/ownerRole

The application role (if any) that owns this task instance. Task owners can be application roles, users, or groups. If the owner of the task is an application role, this field is set.

task/ownerUser

The user (if any) that owns this task instance. Task owners can be application roles, users, or groups. If the owner of the task is a user, this field is set.

task/payload

The task payload that is captured as XML.

task/percentageComplete

The percentage of the task completed. This is used on to-do tasks.

task/priority

An integer number that defines the priority of this task. A lower number indicates a higher priority. The numbers 1 to 5 are typically used.

task/startDate

The start date for the task. This is used on to-do tasks.

task/subCategory

An optional subcategory of the task.

task/taskDefinitionId

The task definition ID that binds the task to the task metadata. At task initiation time, this can be either the compositeDN/componentName string or the targetNamespace in the .task file. If the later is used, the active version matching the targetNamespace is used.

task/taskDisplayUrl

The URL to use to display the details for this task.

task/title

The title of the task.


Table 34-16 lists the attributes that capture process metadata information.

Table 34-16 Attributes Capturing Process Metadata Information

Attribute Description

task/processInfo/domain

The domain to which the composite that contains the task component that defines this task instance belongs.

task/sca/applicationName

The application that is deployed.

task/sca/componentName

The name of the task component that defines this task instance.

task/sca/compositeDN

A unique name for the particular deployment of the composite that contains the task component that defines this task instance.

task/sca/compositeInstanceId

The composite instance ID.

task/sca/compositeName

The name of the composite that contains the task component that defines this task instance.

task/sca/compositeVersion

The version of the composite that contains the task component that defines this task instance.


Table 34-17 lists the attachment-related attributes.

Table 34-17 Attachment-related attributes

Attribute Description

task/attachment/content

The attachment content.

task/attachment/mimeType

The Multipurpose Internet Mail Extension (MIME) type of the attachment.

task/attachment/name

The name of the attachment.

task/attachment/updatedBy

The user who updated the attachment.

task/attachment/updatedDate

The date on which the attachment was updated.

task/attachment/URI

The URI if the attachment is URI-based.


Table 34-18 lists the comment-related attributes.

Table 34-18 Comment-related Attributes

Attribute Description

task/userComment/comment

The user comment.

task/userComment/updatedBy

The user who added the comment.

task/userComment/updatedDate

The date on which the comment was added.


Table 34-19 lists the attributes manipulated by the workflow services system.

Table 34-19 Attributes Manipulated by the Workflow Services System

Attribute Description

task/systemAttributes/acquiredBy

If a task is assigned to a group, application role, or to multiple users, and then claimed by a user, this field is set to the name of the user who claimed the task.

task/systemAttributes/approvers

The IDs of users who performed custom actions on the task.

task/systemAttributes/assignedDate

The date that this task was assigned.

task/systemAttributes/assignees

The current task assignees (can be users, groups, or application roles).

task/systemAttributes/createdDate

The date the task instance was created.

task/systemAttributes/customActions

The custom actions that can be performed on the task.

task/systemAttributes/endDate

The end date for the task. This is used on to-do tasks.

task/systemAttributes/expirationDate

The date on which the task instance expires.

task/systemAttributes/fromUser

The user who previously acted on the task.

task/systemAttributes/hasSubTasks

If true, there are subtasks.

task/systemAttributes/isGroup

If true, the task is assigned to a group.

task/systemAttributes/originalAssigneeUser

If a user delegates a task to another user, this field is populated with the name of the user who delegated the task.

task/systemAttributes/outcome

The outcome of the task (for example, approved or rejected). This is only set on completed task instances.

task/systemAttributes/parentTaskId

This is only set on reinitiated tasks (the task ID of the previous task that is being reinitiated).

task/systemAttributes/parentTaskVersion

This only set on a subtask. This refers to the version of the parent task.

task/systemAttributes/participantName

The logical name of the participant as modeled from Oracle JDeveloper.

task/systemAttributes/reviewers

The reviewers of the task. This can be a user, group, or application role.

task/systemAttributes/rootTaskId

The ID of the root task. This is the same as the task ID for the root task.

task/systemAttributes/stage

The stage name that is being executed.

task/systemAttributes/state

The current state of the task instance.

task/systemAttributes/substate

The current substate of the task.

task/systemAttributes/subTaskGroupInstanceId

A unique ID that is set on a subtask. This same ID is set on the parent task's taskGroupInstanceId. This is required to identify which subtasks were created at which time.

task/systemAttributes/systemActions

The system actions (such as reassign, escalate, and so on) that can be performed on a task.

task/systemAttributes/taskDefinitionName

The name of the task component that defines this task instance.

task/systemAttributes/taskGroupId

The ID of the immediate parent task. This only sets a subtask.

task/systemAttributes/taskGroupInstanceId

A unique ID that is set on the parent task. This same ID is set on the subtask's subTaskGroupInstanceId. This is required to identify which subtasks were created at which time.

task/systemAttributes/taskId

The unique ID of the task.

task/systemAttributes/taskNamespace

A namespace that uniquely defines all versions of the task component that defines this task instance. Different versions of the same task component can have the same namespace, but no two task components can have the same namespace.

task/systemAttributes/taskNumber

An integer number that uniquely identifies this task instance.

task/systemAttributes/updatedBy

The user who last updated the task.

task/systemAttributes/updatedDate

The date this instance was last updated.

task/systemAttributes/version

The version of the task.

task/systemAttributes/versionReason

The reason the version was created.

task/systemAttributes/workflowPattern

The pattern that is being executed (for example, parallel, serial, FYI, or single).


Table 34-20 lists the mapped attributes.

Table 34-20 Mapped Attributes

Attribute Description

task/systemMessageAttributes/*

The mapped attributes.


34.2 Notifications from Human Workflow

Notifications are sent to alert users of changes to the state of a task. Notifications can be sent through any of the following channels: email, telephone voice message, instant messaging (IM), or short message service (SMS). Notifications can be sent from a human task in a BPEL process or directly from a BPEL process.

In releases before 11g, email notifications were sent through the human workflow email notification layer. Voice and SMS notifications were sent through Oracle's hosted notification service. IM notifications were not supported.

Starting with release 11g, the human workflow email notification layer works with Oracle User Messaging Service to alert users to changes in the state of a task. The Oracle User Messaging Service exposes operations that can be invoked from the BPEL process or human task to send notifications through email, voice, IM, or SMS channels.

The Oracle User Messaging Service supports features such as:

On application servers other than Oracle Fusion Middleware, the human workflow email notification layer can be used for email notifications.

For more information about configuring the Oracle User Messaging Service, see the following:

34.2.1 Contents of Notification

Each email notification can contain the following parts:

  • The notification message

  • The HTML content from Oracle BPM Worklist:

    This is a read-only view of Oracle BPM Worklist on the task. For information on how you can configure email notifications to include the content from Oracle BPM Worklist, see Section 30.7, "Creating an Email Notification."

  • Task attachments:

    For notifications that include task attachments.

  • Actionable links

Notifications through SMS, IM, and voice contain only the notification message.

The notification message is an XPath expression that can contain static text and dynamic values. In creating the messages, only the task BPEL variable is available for dynamic values. This restriction is because the messages are evaluated outside the context of the BPEL process. The payload in the task variable is also strongly typed to contain the type of the payload for XPath tree browsing. The XPath extension function hwf:getNotificationProperty(propertyName) is available to get properties for a particular notification. The function evaluates to corresponding values for each notification. The propertyName can be one of the following values:

  • recipient

    The recipient of the notification

  • recipientDisplay

    The display name of the recipient

  • taskAssignees

    The task assignees

  • taskAssigneesDisplay

    The display names of the task assignees

  • locale

    The locale of the recipient

  • taskId

    The ID of the task for which the notification is meant

  • taskNumber

    The number of the task for which the notification is meant

  • appLink

    The HTML link to the Oracle BPM Worklist task details page

Example 34-4 demonstrates the use of hwf:getNotificationProperty and hwf:getTaskResourceBundle:

Example 34-4 Use of hwf:getNotificationProperty and hwf:getTaskResourceBundle

concat('Dear ', hwf:getNotificationProperty('recipientDisplay'), ' Task ',
/task:task/task:systemAttributes/task:taskNumber, ' is assigned to you. ',
hwf:getTaskResourceBundleString(/task:task/task:systemAttributes/task:taskId,
'CONGRATULATIONS', hwf:getNotificationProperty('locale')))

This results in a message similar to the following:

Dear Cooper, James Task 1111 is assigned to you. Congratulations

34.2.2 Error Message Support

The human workflow email notification layer is automatically configured to warn an administrator about error occurrences in which intervention is required. Error notifications and error response messages are persisted.

You can view messages in Oracle Enterprise Manager Fusion Middleware Control.

For more information about viewing messages, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

34.2.3 Reliability Support

The human workflow email notification layer works with Oracle User Messaging Service to provide the following reliability support:

  • Messages are not lost:

    • If the human workflow email notification layer fails after acknowledging receipt of a message from the human workflow.

    • If the human workflow email notification layer and Oracle User Messaging Service both fail before the Oracle User Messaging Service acknowledges receipt of a message from the human workflow.

    • If the Oracle User Messaging Service is down. Message delivery is retried until successful.

    • If a notification channel is down.

  • Notifications that cannot be delivered are retried three times and the address is marked as invalid. The address is also added to the bad address list. If needed, you can manually remove these addresses from the bad address list in Oracle Enterprise Manager Fusion Middleware Control. Outgoing notifications are not resent until the address is corrected. To guard against any incorrect identification, the address is marked as invalid only for about an hour. No new notifications are sent in this time.

  • Incoming notification responses from an address that has been identified as a spam source are ignored.

  • Incoming notification messages are persisted.

  • Incoming notification responses that indicate notification delivery failure (for example, an unknown host mail) are not ignored. Instead, corrective actions are automatically taken (for example, the bad address list is updated).

  • Incoming notification responses can be configured to send acknowledgements indicating notification status to the sender.

  • Validation of incoming notification responses is performed by correlating the incoming notification message with the outgoing notification message.

For more information about notifications, see the following:

34.2.4 Management of Oracle Human Workflow Notification Service

An administrator can perform the following management tasks from Oracle Enterprise Manager Fusion Middleware Control:

  • View failed notifications and erroneous incoming notification responses and take corrective actions.

  • Perform corrective actions such as delete, resend, and edit on outgoing notifications and addresses.

  • View bad emails and block email addresses for incoming notification responses.

  • Manage the bad email address list.

  • Access runtime data of failed notifications. You can purge this data when it is no longer needed.

For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

34.2.5 How to Configure the Notification Channel Preferences

To configure the notification channel preferences:

  1. In Oracle JDeveloper, configure the notification service for email and other channels. See Chapter 17, "Using the Notification Service" for details.

  2. Open the Human Task Editor in Oracle JDeveloper.

    The notifications for a task can be configured during the creation of a task in the Human Task Editor. Notifications can be sent to different types of participants for different actions.

    The actions for which a task notification can be sent are described in Section 29.8.1, "How to Notify Recipients of Changes to Task Status."

    Notifications can be sent to users involved in the task in various capacities. These users are described in Section 29.8.1, "How to Notify Recipients of Changes to Task Status."

    When the task is assigned to a group, each user in the group is sent a notification if no notification endpoint is available for the group.

    For more information, see the following:

  3. From the messaging server pages of Oracle Enterprise Manager Fusion Middleware Control, configure the appropriate channel (for example, email). See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for details.

  4. From the Workflow Notification Properties pages of Oracle Enterprise Manager Fusion Middleware Control, configure the notification mode parameter for the notification service to either all channels or email.

    By default, this value is set to NONE, meaning that no notifications are sent. The possible values are:

    • ALL

      The email, IM, SMS, and voice channels are configured and notification is sent through any channel.

    • EMAIL

      Only the email channel is configured for sending notification messages.

    • NONE

      No channel is configured for sending notification messages. This is the default setting.

34.2.6 How to Configure Notification Messages in Different Languages

A notification consists of four types of data generated from multiples sources and internationalized differently. However, for all internationalized notifications, the locale is obtained from the BPMUser object of the identity service.

  • Prepackaged strings (action links, comments, Oracle BPM Worklist, and so on)

    These strings are internationalized in the product as part of the following package:

    oracle.bpel.services.workflow.resource
    

    The user's locale is used to get the appropriate message.

  • Task details attachment

    The user's locale is used to retrieve the task detail HTML content.

  • Task outcome strings (approve, reject, and so on)

    The resource bundle for outcomes is specified when the task definition is modeled in the Advanced Settings section of the Human Task Editor. The key to each of the outcomes in the resource bundle is the outcome name itself.

  • Notification message

To configure notification messages in different languages:

  1. Use one of the following methods to internationalize messages in the notification content:

    1. To use values from the resource bundle specified during the task definition, use the following XPath extension function:

      hwf:getTaskResourceBundleString(taskId, key, locale?)
      

      This function returns the internationalized string from the resource bundle specified in the task definition.

      The locale of the notification recipient can be retrieved with the following function:

      hwf:getNotificationProperty('locale')
      

      The task ID corresponding to a notification can be retrieved with the following function:

      hwf:getNotificationProperty('taskId')
      
    2. If a different resource bundle is used, then use the following XPath extension to retrieve localized messages:

      orcl:get-localized-string()
      

For more information, see Section 29.6.2, "How to Specify Multilingual Settings."

34.2.7 How to Send Actionable Messages

There are several methods for sending actionable messages. This section provides an overview of procedures.

Note:

If digital signatures are enabled for a task, actionable emails are not sent during runtime. This is the case even if actionable emails are enabled during design time.

34.2.7.1 How to Send Actionable Emails for Human Tasks

Task actions can be performed through email if the task is set up to enable actionable email (the same actions can also be performed from Oracle BPM Worklist). An actionable email account is the account in which task action-related emails are received and processed.

To send actionable emails for human tasks:

  1. In the Advanced tab of the Notification section of the Human Task Editor, select Make notification actionable to make email notifications actionable. This action enables you to perform task actions through email.

    If a notification is actionable, the email contains links for each of the custom outcomes.

  2. To send task attachments with the notification message, select Send task attachments with email notifications.

    When an actionable email arrives, perform the following tasks.

  3. Click the Approve link to invoke a new email window with approval data. Figure 34-3 provides details.

    Figure 34-3 Actionable Notifications

    Description of Figure 34-3 follows
    Description of "Figure 34-3 Actionable Notifications"

  4. Add comments in the comments section of the approval mail. For example:

    This contract has been approved based on the attached information.
    
  5. Add attachments as needed, as shown in Figure 34-4.

    Figure 34-4 Attachment to an Actionable Email

    Description of Figure 34-4 follows
    Description of "Figure 34-4 Attachment to an Actionable Email"

  6. Do not change anything in the subject or the body in this email. If you change the content with the NID substrings, the email is not processed.

  7. Click Send.

  8. Set properties such as incoming server, outgoing mail server, outgoing user name and password, and others from the Oracle User Messaging Service section of Oracle Enterprise Manager Fusion Middleware Control.

  9. In the Workflow Notification Properties page of Oracle Enterprise Manager Fusion Middleware Control, set the notification mode to ALL or EMAIL.

  10. In the Workflow Task Service Properties page of Oracle Enterprise Manager Fusion Middleware Control, set the actionable email account name.

For more information about the Oracle User Messaging Service section, Workflow Notification Properties page, and Workflow Task Service Properties page of Oracle Enterprise Manager Fusion Middleware Control, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

34.2.8 How to Send Inbound and Outbound Attachments

If the include attachments flag is checked; only email is sent. The emails include all the task attachments as email attachments.

To send inbound and outbound attachments:

  1. Select Send task attachments with email notifications in the Advanced tab of the Notification section of the Human Task Editor.

    In the actionable email reply, the user can add attachments in the email. These attachments are added as task attachments.

For more information, see Section 29.8.7, "How to Make Email Messages Actionable."

34.2.9 How to Send Inbound Comments

To send inbound comments:

  1. Add comments in the actionable email reply between Comments[[' and ']], as shown in Figure 34-3. Those contents are added as task comments. For example, Comments[[looks good]].

34.2.10 How to Send Secure Notifications

To send secure notifications:

  1. Select Make notifications secure (exclude details) in the Advanced tab of the Notification section of the Human Task Editor. This action enables a default notification message to be used. In this case, the notification message does not include the content of the task. Also, this notification is not actionable. The default notification message includes a link to the task in Oracle BPM Worklist. You must log in to see task details.

    For more information, see Section 29.8.5, "How to Secure Notifications to Exclude Details."

34.2.11 How to Set Channels Used for Notifications

To set channels used for notifications:

  1. Set up preferred notification channels by using the preferences user interface in Oracle BPM Worklist. The channel is dynamically determined by querying the user preference store before sending the notification. If the user preference is not specified, then the email channel is used.

    For more information about the Oracle Delegated Administration Service, see Oracle Fusion Middleware Guide to Delegated Administration for Oracle Identity Management.

34.2.12 How to Send Reminders

Tasks can be configured to send reminders, which can be based on the time the task was assigned to a user or the expiration time of a task. The number of reminders and the interval between the reminders can also be configured. The message used for reminders is the message that is meant for ASSIGNEES when the task is marked as ASSIGNED.

To send reminders:

  1. Set reminders in the Advanced tab of the Notification section of the Human Task Editor. Reminder configuration involves the following parameters:

    • Recurrence:

      Specifies the number of times reminders are sent. The possible values for recurrence are EVERY, NEVER, 0, 1, 2 …, 10.

    • RelativeDate:

      Specifies if the reminder duration is computed relative to the assigned date or to the expiration date of the task. The possible values for the relativeDate are ASSIGNED, EXPIRATION, and BEFORE DUE DATE. The final value appears in Oracle JDeveloper if you modify the escalation and expiration policy of the task to use the option Action Requested Before (known as Use Due Date in previous releases).

    • Duration:

      Specifies the duration from the relativeDate and the first reminder and each reminder since then. The data type of duration is xsd:duration, whose format is defined by ISO 8601 under the form PnYnMnDTnHnMnS. The capital letters are delimiters and can be omitted when the corresponding member is not used. Examples include PT1004199059S, PT130S, PT2M10S, P1DT2S, -P1Y, or P1Y2M3DT5H20M30.123S.

    The following examples illustrate when reminders are sent:

    • If the relativeDate is ASSIGNED, the recurrence is EVERY, the reminder duration is PT1D, and the task is assigned at 3/24/2005 10:00 AM, then reminders are sent at 3/25/2005 10:00 AM, 3/26/2005 10:00 AM, 3/27/2005 10:00 AM, and so on until the user acts on the task.

    • If the relativeDate is EXPIRATION, the recurrence is 2, the reminder duration is PT1D, and the task expires at 3/26/2005 10:00 AM, then reminders are sent at 3/24/2005 10:00 AM and 3/25/2005 10:00 AM if the task was assigned before 3/24/2005 10:00 AM.

    • If the relativeDate is EXPIRATION, the recurrence is 2, the reminder duration is PT1D, the task expires at 3/26/2005 10:00 AM, and the task was assigned at 3/24/2005 3:00 PM, then only one reminder is sent at 3/25/2005 10:00 AM.

    For more information, see Section 29.8.3, "How to Set Up Reminders."

34.2.13 How to Set Automatic Replies to Unprocessed Messages

The human workflow notification service sends you an automatic reply message when it cannot process an incoming message (due to system error, exception error, user error, and so on). You can modify the text for these messages in the global resource bundle. Example 34-5 shows the WorkflowLabels.properties file. For more information, see Section 34.5.2, "Global Resource Bundle – WorkflowLabels.properties."

Example 34-5 WorkflowLabels.properties

# String to be prefixed to all auto reply messages
AUTO_REPLY_PREFIX_MESSAGE=Oracle Human Workflow Service 
# String to be sufixed to all auto reply mesages
AUTO_REPLY_SUFFIX_MESSAGE=This message was automatically generated by Human \
                Workflow Mailer. Do not reply to this mail.

# Message indicating closed status of a notified task
TaskClosed=You earlier received the notification shown below. That notification \
                is now closed, and no longer requires your response. You may \
                simply delete it along with this message.

# Message indicating that notification was "replied" to instead of "responded" by
# using the response link.
EMailRepliedNotification=The message you sent appeared to be a reply to a \
                notification. To respond to a notification, use the \
                response link that was included with your notification.

#
EMailUnSolicited= The message you sent did not appear to be in response to a \
                notification. If you are responding to a notification        \
                Use the response link that was included with your notification.

EMailUnknownContent= The message you sent did not appear to be in response to a \
                notification. If you are responding to a notification,      \
                Use the response link that was included with your notification.

ResponseNotProcessed=Your response to notification could not be processed. \
                Log in to worklist application for more details.

ResponseProcessed=Your response to notification was successfully processed.

34.2.14 How to Create Custom Notification Headers

Some task participants may have access to multiple notification channels. You can use custom notification headers to enable this type of participant to specify a single channel as the preferred channel on which to receive notifications.

To create custom notification headers:

  1. In the Notification header attributes section of the Advanced tab of the Notification section of the Human Task Editor, create custom notification headers that specify the preferred notification channel to use (such as voice, SMS, and so on). The human workflow email notification layer provides these header values to the rule-based notification service of the Oracle User Messaging Service for use.

    For example, set the Name field to deliveryType and the Value field to SMS.

    The rule-based notification service is only used to identify the preferred notification channel to use. The address for the preferred channel is obtained from Oracle Identity Management. The notification message is created from the information provided by both services.

    For more information, see the following:

34.3 Assignment Service Configuration

This section describes how to configure the assignment service with dynamic assignment functions. It contains these topics:

34.3.1 Dynamic Assignment and Task Escalation Patterns

When tasks are assigned to a group, application role, or list of users a single user must claim a task to act on it. However, you can also automatically send work to users by using various dispatching mechanisms.

Automatic task dispatching is done through dynamic assignment patterns. Dynamic assignment patterns select a particular user or group from either a group or a list of users or groups. Similarly, when a task is escalated, a task escalation pattern can be used to determine the user to whom the task should be escalated to. Several patterns are provided out of the box. However, you can also create your own patterns for dynamic assignment and task escalation and register them with the workflow service. Table 34-21 describes the three dynamic assignment patterns and one task escalation pattern that are provided out-of-the-box.

Table 34-21 Dynamic Assignment Patterns

Assignment Pattern Type Description

LEAST_BUSY

Dynamic assignment

Picks the user or group with the least number of tasks currently assigned to it.

MOST_PRODUCTIVE

Dynamic assignment

Picks the user or group that has completed the most tasks over a certain time period (by default, the last seven days).

ROUND_ROBIN

Dynamic assignment

Picks each user or group in turn.

MANAGERS_MANAGER

Task escalation

Picks the manager's manager.


These patterns all check a user's vacation status. A user that is currently unavailable is not automatically assigned tasks.

Dynamic assignment patterns can be used when defining a task participant, as described in Section 29.4.3, "How to Configure the Single Participant Type". They can also be used with task-assignment rules allowing end-users to specify dynamic assignment of tasks to the members of groups that they manage, as described in Section 32.7.2, "How To Create Group Rules."

The dynamic assignment patterns can also be called by using an xpath function in any xpath expression in the task definition.

The signature of the function is:

hwf:dynamicTaskAssign(patternName, participants, inputParticipantType, targetAssigneeType, isGlobal, invocationContext, parameter1, parameter2, ..., parameterN)

The parameters are:

  • patternName: Mandatory. Name of the pattern to use

  • participants: Mandatory. The participant or participants to select the assignee from. Can be a string or element containing a participant name or a comma-separated list of participant names, or a set of elements containing participant names or comma-separated lists of participant names. Participants must all be of the same type.

  • inputParticipantType: Mandatory. The type of the input participants (user, group, or application_role)

  • targetAssigneeType: Mandatory. The type of assignee to select (user, group, or application_role). Value must match the context in which the function is being used (for example, must be user if dynamically selecting an owner user. If the inputParticipantType is user, the only valid value here is user.

  • isGlobal: Boolean value that indicates if the pattern should be assessed using tasks of all types, or just tasks of the same type as the current task. Optional - defaults to false.

  • invocationContext: String to uniquely identify where this function is being used. If not specified, a default context is assigned.

  • parameterN: Some dynamic assignment patterns allow parameters to be specified. The parameter values can be specified as name-value pairs, using an “=” character as a delimiter - for example, “TIME_PERIOD=7”

Example usages:

hwf:dynamicTaskAssign(“LEAST_BUSY”,”jcooper,jstein,mtwain”,”user”,”user”,”true”,”ErrorAssignee”)

hwf:dynamicTaskAssign(“MOST_PRODUCTIVE”,task:task/task:payload/task:users,”user”,”user”,”false”,”OwnerUser”,”TIME_PERIOD=7”)

hwf:dynamicTaskAssign(“LEAST_BUSY”,”DeveloperRole”,”application_role”,”group”):

Before 11g Release 1 (11.1.1.6.1), dynamic assignment could be achieved by using the XPath functions wfDynamicUserAssign and wfDynamicGroupAssign. These XPath functions have been deprecated in 11g Release 1 (11.1.1.6.1). They can still be used, but Oracle recommends that you migrate any existing usage of these XPath functions to the new dynamicTaskAssign function.

34.3.1.1 How to Implement a Dynamic Assignment Pattern

Follow these procedures to implement your own dynamic assignment pattern.

To implement dynamic assignment patterns:

Write a Java class that implements the following interface:

oracle.bpel.services.workflow.assignment.dynamic.IDynamicAssignmentPattern

Implementations must provide support for selecting a single assignee from a list of participants (all of the same type) by implementing the method getAssigneeFromParticipantList.

An implementation does not have to support all assignee types. The interface provides the method getSupportedAssigneeType to enable the implementation to specify which types of assignee it supports.

Implementations can accept input parameters to specify selection criteria, the Dynamic Assignment Framework validates these input parameters, and the implementation can define its parameters (if any) in the method getPatternParameters().

An implementation can also accept initialization parameters, which are set when the implementation is initialized by the framework. The parameter values are defined in the human workflow configuration (either via configMBean, or by Human Workflow Service Engine configuration in Oracle Enterprise Manager Fusion Middleware Control), where the dynamic assignment pattern is registered.

For convenience, the framework provides the class AbstractDynamicAssignmentPattern which implements some common functionality. Assignment pattern implementations can extend this abstract class, to save implementing some parameter and localization support.

Before 11g Release 1 (11.1.1.6.1), custom dynamic assignment patterns were implemented using one or both of the following interfaces:

oracle.bpel.services.workflow.assignment.dynamic.IDynamicGroupAssignmentFunction
oracle.bpel.services.workflow.assignment.dynamic.IDynamicUserAssignmentFunction

These interfaces do not offer all the features available in the new IDynamicAssingmentPattern interface, and have been deprecated. The Dynamic Assignment Framework remains backward compatible with implementations that use the old interface, but Oracle recommends that you migrate any implementations you have to use the new interface.

For information about the Javadoc for dynamic assignment interfaces and utilities, see Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager.

34.3.1.2 How to Configure Dynamic Assignment Patterns

Dynamic assignment patterns are configured along with other human workflow configuration parameters in Oracle Enterprise Manager Fusion Middleware Control.

Each dynamic assignment has two mandatory parameters:

  • name:

    The name of the pattern

  • classpath:

    The fully qualified class name of the class that implements the pattern.

In addition, each pattern can optionally have any number of properties. These properties are simple name-value pairs that are passed as initialization parameters to the pattern.

The property values specified in these tags are passed as a map (indexed by the value of the name attributes) to the setInitParameters method of the dynamic assignment patterns.

Two of the out-of-the-box patterns have initialization parameters. These are:

  • ROUND_ROBIN

    The parameter MAX_MAP_SIZE specifies the maximum number of sets of users or groups for which the pattern can maintain ROUND_ROBIN counts. The dynamic assignment pattern holds a list of users and groups in memory for each group (or list of users and groups) on which it is asked to execute the ROUND_ROBIN pattern.

  • MOST_PRODUCTIVE

    The parameter DEAFULT_TIME_PERIOD specifies the length of time (in days) over which to calculate the user's productivity. This value can be overridden when calling the MOST_PRODUCTIVE dynamic assignment pattern.

For more information about configuring the dynamic assignment functions from Oracle Enterprise Manager Fusion Middleware Control, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

34.3.1.3 How to Configure Display Names for Dynamic Assignment Patterns

The runtime config service provides methods for returning a list of available user and group dynamic assignment patterns. These patterns return both the name of the pattern, and a user-displayable label and description for the pattern and its parameters. The patterns support localization of the display name, so that it displays in the appropriate language for the context user. These patterns are used by Oracle BPM Worklist and the JDeveloper Human Task Editor to show a list of available dynamic assignment patterns.

The dynamic assignment framework provides methods allowing pattern implementations to provide human-readable display names and descriptions for patterns and their parameters.

The out-of-the-box pattern implementations, and custom implementations that extend the AbstractDynamicPattern class use the WorkflowLabels.properties resource bundle file to configure these display strings.

To configure display names for dynamic assignment patterns:

Specify display names and descriptions (and appropriate translations) for your dynamic assignment patterns and their parameters by adding entries to the resource property file WorkflowLabels.properties, and associated resource property files in other languages. This file should be placed in the class path identified in the workflow configuration parameter workflowCustomizationsClasspathURL, at the path

oracle/bpel/services/workflow/resource/WorkflowLabels.properties

Entries for dynamic assignment patterns must be of the following form:

DYN_ASSIGN_FN.[pattern name]=Pattern Display Name

DYN_ASSIGN_DESCR.[pattern name]=Function Description

DYN_ASSIGN_PARAM_LABEL.[pattern name].[parameter name]=Parameter Display Name

DYN_ASSIGN_PARAM_LABEL.[pattern name].[parameter name]=Parameter Description

For instance, the entries for the MOST_PRODUCTIVE pattern are:

DYN_ASSIGN_FN.MOST_PRODUCTIVE = Most Productive

DYN_ASSIGN_DESCR.MOST_PRODUCTIVE = Picks the user, group or application role that has completed the highest number of tasks within a certain time period. For group and application roles the total number of tasks completed by all the users who are direct members of that group or role are counted. The time period to use can be specified using the Time Period parameter. If no time period is specified, then the default value specified in the dynamic assignment configuration for the instance is used.

DYN_ASSIGN_PARAM_LABEL.MOST_PRODUCTIVE.TIME_PERIOD = Time Period

DYN_ASSIGN_PARAM_DESCR.MOST_PRODUCTIVE.TIME_PERIOD = The previous number of days over which to count the number of completed tasks. If not specified, the default value defined in the human workflow dynamic assignment configuration is used.

Adding entries to these files for dynamic assignment patterns is optional. If no entry is present in the file, then the name of the function (for example, ROUND_ROBIN') is used instead.

For more information about the WorkflowLabels.properties file, see the workflow-110-workflowCustomizations sample available with the Oracle SOA Suite samples.

34.3.1.4 How to Implement a Task Escalation Pattern

Task escalation functions are very similar to dynamic assignment patterns, but perform a different function (determining to whom a task is assigned when it is escalated). Custom implementations must implement a different interface (IDynamicTaskEscaltionPattern).

34.3.2 Dynamically Assigning Task Participants with the Assignment Service

Human workflow participants are specified declaratively in a routing slip. The routing slip guides the human workflow by specifying the participants and how they participate in the human workflow (for example, management chain hierarchy, serial list of approvers, and so on).

The Human Task Editor enables you to declaratively create the routing slip using various built-in patterns. In addition, you can use advanced routing based on business rules to do more complex routing. However, to do more sophisticated routing using custom logic, you implement a custom assignment service to do routing.

To support a dynamic assignment, an assignment service is used. The assignment service is responsible for determining the task assignees. You can also implement your own assignment service and plug in that implementation for use with a particular human workflow.

The assignment service determines the following task assignment details in a human workflow:

  • The assignment when the task is initiated.

  • The assignment when the task is reinitiated.

  • The assignment when a user updates the task outcome. When the task outcome is updated, the task can either be routed to other users or completed.

  • The assignees from whom information for the task can be requested.

  • If the task supports reapproval from Oracle BPM Worklist, a user can request information for reapproval.

  • The users who reapprove the task if reapproval is supported.

The human workflow service identifies and invokes the assignment service for a particular task to determine the task assignment.

For example, a simple assignment service iteration is as follows:

  1. A client initiates an expense approval task whose routing is determined by the assignment service.

  2. The assignment service determines that the task assignee is jcooper.

  3. When jcooper approves the task, the assignment service assigns the task to jstein. The assignment service also specifies that a notification must be sent to the creator of the task, jlondon.

  4. jstein approves the task and the assignment service indicates that there are no more users to whom to assign the task.

34.3.2.1 How to Implement an Assignment Service

To implement an assignment service:

  1. Implement the assignment service with the IAssignmentService interface. The human workflow service passes the following information to the assignment service to determine the task assignment:

    • Task document

      The task document that is executed by the human workflow. The task document contains the payload and other task information like current state, and so on.

    • Map of properties

      When an assignment service is specified, a list of properties can also be specified to correlate callbacks with back-end services that determine the task assignees.

    • Task history

      The task history is a list of chronologically-ordered task documents to trace the history of the task. The task documents in this list contain a subset of attributes in the actual task (such as state, updatedBy, outcome, updatedDate, and so on).

34.3.2.2 Example of Assignment Service Implementation

Notes:

  • The assignment service class cannot be stateful. This is because every time human workflow services must call the assignment service, it creates a new instance.

  • The getAssigneesToRequestForInformation method can be called multiple times because one of the criteria to show the request-for-information action is that there are users to request information. Therefore, this method is called every time the human workflow service tries to determine the permitted actions for a task.

You can implement your own assignment service plug-in that the human workflow service invokes during human workflow execution.

Example 34-6 provides a sample IAssignmentService implementation named TestAssignmentService.java.

Example 34-6 Sample IAssignmentService Implementation

/* $Header: TestAssignmentService.java 24-may-2006.18:26:16 Exp $ */
/* Copyright (c) 2004, 2006, Oracle. All rights reserved.  */
/*
   DESCRIPTION
    Interface IAssignmentService defines the callbacks an assignment 
    service implements. The implementation of the IAssignmentService 
    is called by the workflow service
   PRIVATE CLASSES
    <list of private classes defined - with one-line descriptions>
   NOTES
    <other useful comments, qualifications, etc.>
   MODIFIED    (MM/DD/YY)
        
 */
/**
 *  @version $Header: IAssignmentService.java 29-jun-2004.21:10:35 Exp
 $
 *  
 *  
 */
package oracle.bpel.services.workflow.test.workflow;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import oracle.bpel.services.workflow.metadata.routingslip.model.*; 
import oracle.bpel.services.workflow.metadata.routingslip.model.Participants;
import oracle.bpel.services.workflow.metadata.routingslip.model.ParticipantsType.*;
import oracle.bpel.services.workflow.task.IAssignmentService;
import oracle.bpel.services.workflow.task.ITaskAssignee;
import oracle.bpel.services.workflow.task.model.Task;
public class TestAssignmentService implements
 oracle.bpel.services.workflow.task.IAssignmentService {
    static int numberOfApprovals = 0;
    static String[] users = new String[]{"jstein", "wfaulk", "cdickens"};
    public Participants onInitiation(Task task, 
                                     Map propertyBag) {
        return createParticipant();
    }
    public Participants onReinitiation(Task task, 
                                       Map propertyBag) {
        return null;
    }
    public Participants onOutcomeUpdated(Task task, 
                                         Map propertyBag,
                                         String updatedBy,
                                         String outcome) {
        return createParticipant();
    }
    public Participants onAssignmentSkipped(Task task, 
                                            Map propertyBag) {
        return null;
    }
    public List getAssigneesToRequestForInformation(Task task, 
                                                    Map propertyBag) {
        List rfiUsers = new ArrayList();
        rfiUsers.add("jcooper");
        rfiUsers.add("jstein");
        rfiUsers.add("wfaulk");
        rfiUsers.add("cdickens");
        return rfiUsers;
    }
    public List getReapprovalAssignees(Task task, 
                                       Map propertyBag,
                                       ITaskAssignee infoRequestedAssignee) {
        List reapprovalUsers = new ArrayList();
        reapprovalUsers.add("jstein");
        reapprovalUsers.add("wfaulk");
        reapprovalUsers.add("cdickens");
        return reapprovalUsers;
    }
    private Participants createParticipant() {
        if (numberOfApprovals > 2) {
            numberOfApprovals = 0;
            return null;
        }
        String user = users[numberOfApprovals++];

        ObjectFactory objFactory = new ObjectFactory();
        Participants participants = objFactory.createParticipants();
        Participant participant = objFactory.createParticipantsTypeParticipant();
        participant.setName("Loan Agent");
        ResourceType resource2 = objFactory.createResourceType(user);
        resource2.setIsGroup(false);
        resource2.setType("STATIC");
        participant.getResource().add(resource2);

        participants.getParticipantOrSequentialParticipantOrAdhoc().
          add(participant);
        return participants;
    }

}

34.3.2.3 How to Deploy a Custom Assignment Service

To deploy a custom assignment service:

  1. Use one of the following methods to make an assignment service implementation class and its related classes available in the class path of Oracle BPEL Process Manager:

    • Load your classes in SCA-INF/classes directly or in SCA-INF/lib as a JAR.

    • Place the class files for your custom function in a directory tree or JAR file. Then, update the worklfowCustomClasspathURL configuration parameter to point to the JAR or root directory in which your classes are located. As this is a URL, it is possible to host the class files on a web server, and make them accessible to multiple Oracle WebLogic Servers through HTTP. It is even possible to deploy the files into the metadata repository (MDS), and use an ORAMDS URL to point to the appropriate location. This approach is described in detail in sample workflow-110-workflowCustomizations. To download this sample, visit the Oracle SOA Suite samples.

    Notes:

    • You cannot create different versions of the assignment service for use in different BPEL processes unless you change package names or class names.

    • Java classes and JAR files in the suitcase are not available in the class path and therefore cannot be used as a deployment model for the assignment service.

    • The steps must be repeated for each node in a cluster.

34.3.3 Custom Escalation Function

The custom escalation function enables you to integrate a custom rule in a human workflow.

To implement a custom escalation function:

  1. Create a custom task escalation function and register this with the human workflow service that uses that function in task definitions.

  2. Use the Human Task Editor to integrate the rule in a human workflow.

    For more information, see Section 29.7.6, "How to Specify Escalation Rules."

34.4 Class Loading for Callbacks and Resource Bundles

You can load classes for the following callbacks and resource bundles directly from the SOA project instead of having to load classes in the oracle.soainfra.common shared library and restarting Oracle WebLogic Server:

The callback classes can be in the following locations:

Additionally, to support backward compatibility, the project level resource bundles can also be in the same directory as the .task file.

34.5 Resource Bundles in Workflow Services

This section describes the resource bundles used in human workflow services and how they can be customized to provide alternative resource strings.

The human workflow service APIs and Oracle BPM Worklist use the locale set in the IWorkflowContext object to access the APIs. This is the locale of the user in the user directory configured with the identity service. If no locale is specified for the user, then the default locale for the Java EE server is used instead.

It is possible for API clients to override this locale by setting a new value in the IWorkflowContext object. Oracle BPM Worklist provides a user preference option that allows users to use their browser's locale, rather than the locale set in their user directory.

34.5.1 Task Resource Bundles

Each human workflow component can be associated with a resource bundle. The bundle defines the resource strings to use as display names for the task outcomes. The resource strings are returned by the TaskMetadataService method getTaskDefinitionOutcomes, and are displayed in Oracle BPM Worklist and the task flow task details application.

In addition, you can use the human workflow XPath function getTaskResourceBundle string to look up resource strings for the task's resource bundle. For example, this XPath function can be part of the XPath expression used to construct notification messages for the task.

A human workflow component is associated with a resource bundle by setting the Resource Name and Resource Location fields of the Resource Details dialog in the Presentation section of the Human Task Editor. The value for the Resource Location field is a URL, and the resource bundle can be contained within a JAR file pointed to by the URL. It is possible to share the same resource bundle between multiple human workflow components by using a common location for the resource bundle.

If no resource bundle is specified for the human workflow component, the resource string is looked up in the global resource bundle. (See Section 34.5.2, "Global Resource Bundle – WorkflowLabels.properties.") Commonly-used task outcomes can be defined in the global resource bundle, alleviating the need to define a resource bundle for individual human workflow components.

If no resource string can be located for a particular outcome, then the outcome name is used as the display value in all locales.

34.5.2 Global Resource Bundle – WorkflowLabels.properties

The following global resource bundle is used by human workflow service APIs to look up resource strings:

oracle.bpel.services.workflow.resource.WorkflowLabels.properties

You can customize this bundle to provide alternatives for existing display strings or to add additional strings (for example, for mapped attribute labels, standard views, or custom dynamic assignment functions).

The global resource bundle provides resource strings for the following:

  • Task attributes:

    Labels for the various task attributes displayed in Oracle BPM Worklist (or other clients). Resource string values are returned from the following TaskMetadataService methods:

    • getTaskAttributes

    • getTaskAttributesForTaskDefinition

    • getTaskAttributesForTaskDefinitions

  • Mapped attribute labels:

    Mapped attribute labels created through the runtime config service. These strings are used in Oracle BPM Worklist when displaying mapped attributes. Resource string values are returned from the TaskMetadataService methods:

    • getTaskAttributesForTaskDefinition

    • getTaskAttributesForTaskDefinitions

    If translated resource strings are required for mapped attribute mappings, then customize the WorkflowLabels.properties bundle to include the appropriate strings.

  • Task outcomes:

    Default resource strings for common task outcomes. These can be overridden by the task resource bundle, as described above. The resource strings are returned by the TaskMetadataService method getTaskDefinitionOutcomes, if no task-specific resource bundle has been specified. As shipped, the global resource bundle contains resource strings for the following outcomes:

    • Approve

    • Reject

    • Yes

    • No

    • OK

    • Defer

    • Accept

    • Acknowledge

  • Dynamic assignment function names:

    Labels for dynamic assignment functions. These strings are returned from the runtime config service methods getUserDynamicAssignmentFunctions and getGroupDynamicAssignmentFunctions. The shipped resource bundle contains labels for the standard dynamic assignment functions (ROUND_ROBIN, LEAST_BUSY, and MOST_PRODUCTIVE). If additional custom dynamic assignment functions have been created, then modify the WorkflowLabels.properties resource bundle to provide resource strings for the new functions.

  • Standard view names:

    Labels for standard views. If you want translated resource strings for any standard views you create, then add them here. Standard view resource strings are looked up from the resource bundle, and are returned as the standard view name from the UserMetadataService methods getStandardTaskViewList and getStandardTaskViewDetails. The key for the resource string should be the name given to the standard view when it is created. If no resource string is added for a particular standard view, then the name as entered is used instead.

  • Notification messages:

    Resource strings used when the task service sends automatic notifications. These can be customized to suit user requirements.

  • Task routing error comments:

    When an error is encountered in the routing of a task, the task service automatically appends comments to the task to describe the error. The various strings used for the comments are defined in this resource bundle.

A copy of the WorkflowLabels.properties resource bundle is available in the sample workflow-110-workflowCustomizations.

You can customize the WorkflowLabels.properties resource bundle by editing it and then adding the customized version to the class path for workflow services, ahead of the version that ships with the product.

This can be done in the following ways:

  • Place the customized file in a directory tree:

    directory_path/oracle/bpel/services/workflow/resource/WorkflowLabels.properties
    
  • Update the worklfowCustomClasspathURL configuration parameter to point to directory_path. (As this is a URL, it is possible to host the resource bundles on a web server, and make them accessible to multiple Oracle WebLogic Servers.) This approach is described in detail in sample workflow-110-workflowCustomizations. To download this sample, visit the Oracle SOA Suite samples.

34.5.3 Worklist Client Resource Bundles

The ADF worklist client application uses two resource bundles that contain all the strings displayed in the worklist client web application.

  • oracle.bpel.worklistapp.resource.WorkflowResourceBundle:

    This contains strings used by both the ADF Oracle BPM Worklist, and the JSP-based sample Oracle BPM Worklist that shipped with version 10.1.3 of Oracle SOA Suite.

  • oracle.bpel.worklistapp.resource.WorklistResourceBundle:

    This contains strings used only by the ADF Oracle BPM Worklist.

Copies of the worklist resource bundles are available in the sample workflow-110-workflowCustomizations.

The sample illustrates how to customize Oracle BPM Worklist by recompiling these resource bundles, and adding the updated classes to Oracle BPM Worklist.

34.5.4 Task Detail ADF Task Flow Resource Bundles

The ADF task flow applications and associated data controls that get created to display the details of a particular task type use the resource bundle oracle.bpel.services.workflow.worklist.resource.worklist to store their resource strings.

You can provide your own custom resource strings for a task detail ADF task flow by adding a customized resource bundle in the task flow application.

You can localize the XML element name displayed in the task flow form through this resource bundle. You can add keys, and use them in the task flow form contents section. The input text label looks as follows:

#{resources.mykeyword}

A copy of the WorkflowLabels.properties resource bundle is available in the sample workflow-110-workflowCustomizations. This sample illustrates in detail how to provide your own customized resource strings for the task detail ADF task flow application.

34.5.5 Specifying Stage and Participant Names in Resource Bundles

You can provide translated values for stage names and participant names in the composite resource bundle. The resource bundle should contain entries such as the following:

  • stage_name=translated_value

  • participant_name=translated_value

34.5.6 Case Sensitivity in Group and Application Role Names

By default, the human workflow system is case insensitive to user names. All user names are stored in lowercase. However, group names and application role names are always case sensitive. User name case insensitivity can be changed in Oracle Enterprise Manager Fusion Middleware Control.

Caution:

Only change this setting after performing a new installation. Changing this value on an installation that is actively processing instances, or has many instances in the database, causes serious issues.

To change case sensitivity:

  1. Log in to Oracle Enterprise Manager Fusion Middleware Control.

  2. In the navigator, expand the SOA folder.

  3. Right-click soa-infra, and select Administration > System Mbean Browser.

    The System MBean Browser displays on the right side of the page.

  4. Expand Application Defined MBeans > oracle.as.soainfra.config > Server: server_name > WorkflowIdentityConfig > human-workflow > WorkflowIdentityConfig.PropertyType.

  5. Click caseSensitive.

  6. Click the Operations tab.

  7. Click setValue.

  8. In the Value field, enter true, and click Invoke.

If you are upgrading from 10.1.3, which by default was case sensitive, set caseSensitive to true for the system to be the same as with 10.1.3.

34.6 Introduction to Human Workflow Client Integration with Oracle WebLogic Server Services

This section describes how human workflow clients integrate with Oracle WebLogic Server services.

34.6.1 Human Workflow Services Clients

Human workflow services expose the following workflow services:

  • Task service

  • Task query service

  • User metadata service

  • Task evidence service

  • Task metadata service

  • Runtime config service

  • Task report service

To use any of these services, you must use the abstract factory pattern for workflow services. The abstract factory pattern provides a way to encapsulate a group of individual factories that have a common theme.

Perform the following tasks:

  • Get the IWorkflowServiceClient instance for the specific service type. The WorkflowServiceClientFactory provides a static factory method to get IWorkflowServiceClient according to the service type.

  • Use the IWorkflowServiceClient instance to get the service instance to use.

The supported service types are Remote and Soap.

Remote clients use Enterprise JavaBeans clients (remote Enterprise JavaBeans, accordingly). SOAP uses SOAP clients. Each type of service requires you to configure workflow clients. Example 34-7 provides details.

Example 34-7 Client Configuration File

<workflowServicesClientConfiguration>
<server name="default" default="true">
   <remoteClient>
      <serverURL>t3://myhost.us.oracle.com:7001</serverURL>
      <userName>weblogic</userName>
      <password>weblogic</password>
      <initialContextFactory>weblogic.jndi.WLInitialContextFactory
         </initialContextFactory>
      <participateInClientTransaction>false</participateInClientTransaction>
   </remoteClient>
   <soapClient>
      <rootEndPointURL>http://myhost.us.oracle.com:7001</rootEndPointURL>
      <identityPropagation mode="dynamic" type="saml">
      <policy-references>
      <policy-reference enabled="true" category="security" 
        uri="oracle/wss10_saml_token_client_policy"/>
      </policy-references>
      </identityPropagation>
   </soapClient>
</server>
</workflowServicesClientConfiguration>

The client configuration file can contain definitions for several configurations. Each server must have its own unique name. If the configuration file defines multiple servers, one server must be set with the default attribute equal to true. The workflowServicesClientConfiguration has an optional attribute named serverType that can be set to one of the following: LOCAL, REMOTE, or SOAP. Each server can override the client type by using the optional attribute clientType.

Example 34-8 provides details.

Example 34-8 Client Configuration File with Multiple Configuration Definitions

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workflowServicesClientConfiguration
 xmlns="http://xmlns.oracle.com/bpel/services/client" clientType="REMOTE"
   <server name="server1" default="true"  clientType="SOAP">
      <remoteClient>
         <serverURL>t3://myhost1.us.oracle.com:7001</serverURL>
         <initialContextFactory>weblogic.jndi.WLInitialContextFactory</initialContextFactory>
         <participateInClientTransaction>false</participateInClientTransaction>
      </remoteClient> -->
      <soapClient>
         <rootEndPointURL>http://myhost1.us.oracle.com:7001</rootEndPointURL>
         <identityPropagation mode="dynamic" type="saml">
            <policy-references>
               <policy-reference enabled="true" category="security"
                                 uri="oracle/wss10_saml_token_client_policy"/>
            </policy-references>
         </identityPropagation>
      </soapClient>
   </server>
   <server name="server2">
      <remoteClient>
         <serverURL>t3://myhost2.us.oracle.com:7001</serverURL>
         <initialContextFactory>weblogic.jndi.WLInitialContextFactory</initialContextFactory>
         <participateInClientTransaction>false</participateInClientTransaction>
      </remoteClient> -->
      <soapClient>
         <rootEndPointURL>http://myhost2us.oracle.com:7001</rootEndPointURL>
         <identityPropagation mode="dynamic" type="saml">
            <policy-references>
               <policy-reference enabled="true" category="security"
                                 uri="oracle/wss10_saml_token_client_policy"/>
            </policy-references>
         </identityPropagation>
      </soapClient>
   </server>
</workflowServicesClientConfiguration>

In Example 34-8, server2 uses the default clientType of REMOTE, while server1 overrides the default clientType value to use the clientType of SOAP. The same rule applies if the JAXB WorkflowServicesClientConfigurationType object is used instead of the wf_client_config.xml file.

If the configuration defines a client type, you can use the factory method from the WorkflowServiceClientFactory class. Example 34-9 provides details.

Example 34-9 Factory Method from WorkflowServiceClientFactory Class

public static IWorkflowServiceClient
 getWorkflowServiceClient(WorkflowServicesClientConfigurationType wscc, Logger
 logger) throws WorkflowException

If the map defines a client type with the property CONNECTION_PROPERTY.CLIENT_TYPE, the factory method in Example 34-10 can be used:

Example 34-10 Factory Method for CONNECTION_PROPERTY.CLIENT_TYPE

public static IWorkflowServiceClient getWorkflowServiceClient(Map<CONNECTION_
PROPERTY, String> properties, String serverName,    Logger logger) throws
 WorkflowException

34.6.1.1 Task Query Service Client Code

Example 34-11 provides an example of the task query service client code.

Example 34-11 Task Query Service Client Code

/**
 * WFClientSample
 */
package oracle.bpel.services.workflow.samples;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import oracle.bpel.services.workflow.IWorkflowConstants;
import oracle.bpel.services.workflow.WorkflowException;
import oracle.bpel.services.workflow.client.IWorkflowServiceClient;
import oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
import oracle.bpel.services.workflow.client.IWorkflowServiceClientConstants
 .CONNECTION_PROPERTY;
import oracle.bpel.services.workflow.query.ITaskQueryService;
import oracle.bpel.services.workflow.query.ITaskQueryService.AssignmentFilter;
import oracle.bpel.services.workflow.query.ITaskQueryService.OptionalInfo;
import oracle.bpel.services.workflow.repos.Ordering;
import oracle.bpel.services.workflow.repos.Predicate;
import oracle.bpel.services.workflow.repos.TableConstants;
import oracle.bpel.services.workflow.verification.IWorkflowContext;

public class WFClientSample {

  public static List  runClient(String clientType) throws WorkflowException {
      try {
      
         IWorkflowServiceClient wfSvcClient = null;
         ITaskQueryService taskQuerySvc = null;
         IWorkflowContext wfCtx = null;

         // 1. this step is optional since configuration can be set in  wf_client_
             config.xml file
         Map<CONNECTION_PROPERTY, String> properties = new HashMap<CONNECTION_
PROPERTY, String>();
         if (WorkflowServiceClientFactory.REMOTE_CLIENT.equals(clientType)) {
           properties.put(CONNECTION_PROPERTY.EJB_INITIAL_CONTEXT_FACTORY,
 "weblogic.jndi.WLInitialContextFactory");
           properties.put(CONNECTION_PROPERTY.EJB_PROVIDER_URL,
 "t3://myhost.us.oracle.com:7001");
           properties.put(CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS,
 "weblogic");
           properties.put(CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL, "weblogic");
         } else if (WorkflowServiceClientFactory.SOAP_CLIENT.equals(clientType)) {
           properties.put(CONNECTION_PROPERTY.SOAP_END_POINT_ROOT,
 "http://myhost:7001");
           properties.put(CONNECTION_PROPERTY.SOAP_IDENTITY_
PROPAGATION,"non-saml"); // optional
         } 
         // 2. gets IWorkflowServiceClient for specified client type
         wfSvcClient =
 WorkflowServiceClientFactory.getWorkflowServiceClient(clientType, properties,
 null);

         // 3. gets ITaskQueryService instance
         taskQuerySvc = wfSvcClient.getTaskQueryService();

         // 4. gets IWorkflowContext instance
         wfCtx = taskQuerySvc.authenticate("jcooper", "welcome1".toCharArray(),
 "jazn.com");

         // 5. creates displayColumns
         List<String> displayColumns = new ArrayList<String>(8);
         displayColumns.add("TASKID");
         displayColumns.add("TASKNUMBER");
         displayColumns.add("TITLE");
         displayColumns.add("CATEGORY");

         // 6. creates optionalInfo
         List<ITaskQueryService.OptionalInfo> optionalInfo = new
 ArrayList<ITaskQueryService.OptionalInfo>();
         optionalInfo.add(ITaskQueryService.OptionalInfo.DISPLAY_INFO);

         // 7. creates assignmentFilter
         AssignmentFilter assignmentFilter = AssignmentFilter.MY_AND_GROUP;

         // 8. creates predicate
         List<String> stateList = new ArrayList<String>();
         stateList.add(IWorkflowConstants.TASK_STATE_ASSIGNED);
         stateList.add(IWorkflowConstants.TASK_STATE_INFO_REQUESTED);
         Predicate predicate = new Predicate(TableConstants.WFTASK_STATE_COLUMN,
 Predicate.OP_IN, stateList);

         // 9. creates ordering
         Ordering ordering = new Ordering(TableConstants.WFTASK_DUEDATE_COLUMN,
 true, false);
         ordering.addClause(TableConstants.WFTASK_CREATEDDATE_COLUMN, true,
 false);

         // 10. calls service - query tasks 
         List taskList = taskQuerySvc.queryTasks(wfCtx, 
                                                (List<String>) displayColumns, 
                                                (List<OptionalInfo>) optionalInfo, 
                                                (AssignmentFilter)
                                                  assignmentFilter, 
                                                (String) null, // keywords is
 optional (see javadoc)
 // optional
                                                 predicate, 
                                                 ordering,
                                                 0,    // starting row 
                                                 100); // ending row for paging, 0
                                                    if no paging
      
         // Enjoy result
         System.out.println("Successfuly get list of tasks for client type: " +
            clientType +
                            ". The list size is " + taskList.size());
         return taskList;
      } catch (WorkflowException e) {
         System.out.println("Error occurred");
         e.printStackTrace();
         throw e;
      }
   }
   
   public static void main(String args[]) throws Exception {
      runClient(WorkflowServiceClientFactory.REMOTE_CLIENT);
      runClient(WorkflowServiceClientFactory.SOAP_CLIENT);
   }  
  
}

34.6.1.2 Configuration Option

Each type of client is required to have a workflow client configuration. You can set the configuration in the following locations:

  • JAXB object

  • wf_client_config.xml file

  • Property map

The property map is always complementary to the wf_client_config.xml file. The JAXB object or property map can overwrite the configuration attribute. The file is optional. If it cannot be found in the application class path, then the property map is the main source of configuration.

34.6.1.2.1 JAXB Object

You can use the JAXB object to define the client configuration. Example 34-12 shows how to use the WorkflowServiceClientFactory method.

Example 34-12 JAXB Object

public static IWorkflowServiceClient getWorkflowServiceClient(String clientType,
                           WorkflowServicesClientConfigurationType wscc,
                           Logger logger) throws WorkflowException
34.6.1.2.2 Workflow Client Configuration File - wf_client_config.xml

The client configuration XSD schema is present in the wf_client_config.xsd file.

The server configuration should contain three types of clients:

  • localClient

  • remoteClient

  • soapClient

Oracle recommends that you specify all clients. This is because some services (for example, the identity service) do not have remote clients. Therefore, when you use remote clients for other services, the identity service uses the SOAP service.

An example of a client configuration XML file is shown in Example 34-13. The configuration defines a server named default. The XML file must go into the client application's EAR file.

Example 34-13 Client Configuration

<workflowServicesClientConfiguration>
server name="default" default="true">

<remoteClient>
   <serverURL>t3://myhost.us.oracle.com:7001</serverURL>
   <userName>weblogic</userName>
   <password>weblogic</password>
   <initialContextFactory>weblogic.jndi.WLInitialContextFactory
      </initialContextFactory>
   <participateInClientTransaction>false</participateInClientTransaction>
</remoteClient>

<soapClient>
   <rootEndPointURL>http://myhost.us.oracle.com:7001</rootEndPointURL>
   <identityPropagation mode="dynamic" type="saml">
   <policy-references>
      <policy-reference enabled="true" category="security" 
         uri="oracle/wss10_saml_token_client_policy"/>
      </policy-references>
   </identityPropagation>
</soapClient>

</server>
</workflowServicesClientConfiguration>

You can define client properties in wf_client_config.xml when WorkflowServicesClientConfigurationType wscc is null.

The WorkflowServiceClientFactory getWorkflowServiceClient() methods always look for wf_client_config.xml in the class path. If this file is found, the client properties are loaded.

All properties defined in either the property map or the JAXB object override values defined in the wf_client_config.xml file.

34.6.1.2.3 Workflow Client Configuration in the Property Map

To specify the connection property dynamically, you can use a java.util.Map to specify the properties. The properties take precedence over definitions in the configuration file. Therefore, the values of the properties overwrite the values defined in wf_client_config.xml. If you do not want to dynamically specify connection details to the server, you can omit the property setting in the map and pass a null value to the factory method. In that case, the configuration wf_client_config.xml is searched for in the client application class path.

The configuration file must be in the class path only to get the configuration from the file. It is optional to have the file if all settings from the specific client type are done through the property map. The JAXB object is also not required to have the file, since all settings are taken from the JAXB object. Example 34-14 provides details.

Example 34-14 Property Map

IWorkflowServiceClient   wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory
.REMOTE_CLIENT,
(Map<IWorkflowServiceClientConstants.CONNECTION_PROPERTY, String> ) null, null);

If you do so, the value from wf_client_config.xml found in the class path is used by the client to access the services. If the file is not found in the class path and you do not provide the setting according to the service type, a workflow exception is thrown. If the properties map is null and the file is not found, an exception is thrown. If the client omits some properties in the map while the file is not found, the service call fails at runtime (the properties are complementary to the file).

You can define client properties by using the WorkflowServiceClientFactory method. Example 34-15 provides details.

Example 34-15 WorkflowServiceClientFactory Method

public static IWorkflowServiceClient getWorkflowServiceClient(String clientType,
                          Map<CONNECTION_PROPERTY, String> properties,
                          Logger logger) hrows WorkflowException 

If the map defines a client type with the property CONNECTION_PROPERTY type, the factory method in Example 34-16 can be used:

Example 34-16 Factory Method for CONNECTION_PROPERTY Type

public static IWorkflowServiceClient getWorkflowServiceClient(Map<CONNECTION_
PROPERTY, String> properties,   Logger logger) throws WorkflowException

The IWorkflowServiceClientConstants.CONNECTION_PROPERTY, which can be used in the properties map for setting client properties, is shown in Example 34-17:

Example 34-17 CONNECTION_PROPERTY

public enum CONNECTION_PROPERTY {
            MODE,  // not supported , deprecated
            EJB_INITIAL_CONTEXT_FACTORY,
            EJB_PROVIDER_URL,
            EJB_SECURITY_PRINCIPAL,
            EJB_SECURITY_CREDENTIALS,
            // SOAP configuration
            SOAP_END_POINT_ROOT,
            SOAP_IDENTITY_PROPAGATION, // if value is 'saml' then SAML-token
              identity propagation is used
            SOAP_IDENTITY_PROPAGATION_MODE,  // "dynamic'
            MANAGEMENT_POLICY_URI, // dafault value is "oracle/log_policy"
            SECURITY_POLICY_URI,   // default value is  "oracle/wss10_
               saml_token_client_policy"
            // REMOTE EJB
            TASK_SERVICE_PARTICIPATE_IN_CLIENT_TRANSACTION  // default value is
               false
            //(task service EJB starts a new transaction)
            CLIENT_TYPE,            DISCOVERY_OF_END_POINT,
            WSS_RECIPIENT_KEY_ALIAS,
            EJB_JNDI_SUFFIX // append to jndi name to used  foreign jndi name
 };

Note:

If you use the properties map, you do not need to specify IWorkflowServiceClientConstants.CONNECTION_PROPERTY.MODE. This property is deprecated in 11g Release 1.

Example 34-18 provides an example for remote Enterprise JavaBeans clients.

Example 34-18 Example for Remote Enterprise JavaBeans Clients

Map<CONNECTION_PROPERTY,String> properties = new HashMap<CONNECTION_
PROPERTY,String>();
properties.put(CONNECTION_PROPERTY.EJB_INITIAL_CONTEXT_
FACTORY,"weblogic.jndi.WLInitialContextFactory");

properties.put(CONNECTION_PROPERTY.EJB_PROVIDER_URL,
 "t3://myhost.us.oracle.com:7001");
properties.put(CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL, "weblogic");
properties.put(CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS, "weblogic");
IWorkflowServiceClient client =
 WorkflowServiceClientFactory.getWorkflowServiceClient(
                                WorkflowServiceClientFactory.REMOTE_CLIENT,
 properties, null);

Example 34-19 provides an example for a SOAP client.

Example 34-19 Example for SOAP Client

Map<CONNECTION_PROPERTY,String> properties = new HashMap<CONNECTION_
PROPERTY,String>();
properties.put(CONNECTION_PROPERTY.SOAP_END_POINT_ROOT, "http://myhost:7001");
IWorkflowServiceClient client =
 WorkflowServiceClientFactory.getWorkflowServiceClient(
                                WorkflowServiceClientFactory.SOAP_CLIENT,
 properties, null);

34.6.1.3 Client Logging

Clients can optionally pass in a java.util.logging.Logger to where the client logs messages. If there is no logger specified, the workflow service client code does not log anything. Example 34-20 shows how to pass a logger to the workflow service clients:

Example 34-20 java.util.logging.Logger

java.util.logging.Logger logger = ....;

IWorkflowServiceClient client =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory
.REMOTE_CLIENT, properties, logger);

34.6.1.4 Configuration Migration Utility

The client configuration schema has changed between release 10.1.3.x and 11g Release 1. To migrate from release 10.1.3.x to 11g Release 1, use the utility shown in Example 34-21.

Example 34-21 Configuration Migration Utility

java -classpath wsclient_extended.jar:bpm-services.jar 
 oracle.bpel.services.workflow.client.config.MigrateClientConfiguration 
original_file [new_file];

where original_file is a wf_client_config.xml file from 10.1.3.x and new_file is the optional name of the new configuration file. If a new name is not specified, the utility backs up the original configuration file and overwrites the wf_client_config.xml file.

34.6.2 Identity Propagation

This section describes how to propagate identities using Enterprise JavaBeans and SAML-tokens for SOAP clients.

There are performance implications for getting the workflow context for every request. This is also true for identity propagation. If you use identity propagation with SAML-token or Enterprise JavaBeans, authenticate the client by passing null for the user and password, get the workflow context instance, and use another service call with workflow context without identity propagation.

34.6.2.1 Enterprise JavaBeans Identity Propagation

The client application can propagate user identity to services by using Enterprise JavaBeans identity propagation. The client code is responsible for securing the user identity.

34.6.2.1.1 Client Configuration

If you use identity propagation, the client code must omit the element's <userName> and <password> under the <remoteClient> element in the wf_client_config.xml configuration file. In addition, do not populate the following properties into Map<IWorkflowServiceClientConstants.CONNECTION_PROPERTY,String> properties as you did in Section 34.6.1.2.3, "Workflow Client Configuration in the Property Map."

  • IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL

  • IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS

34.6.2.1.2 Requirements for Client Applications For Identity Propagation

Identity propagation only works if the application is deployed under the Oracle WebLogic Server container and secured with container security or the client is secured with a custom JAAS login module.

End users log in to the client application with the correct user name and password. The users using the client application must be available in the identity store used by the SOA application. As a best practice, configure the client to use the same identity store as the workflow services and Oracle SOA Suite are using. This guarantees that if the user exists on the client side, they also exist on the server side.

For information about configuring the identity store, see Oracle Fusion Middleware Security Guide.

For information about interacting with custom identity stores, visit the following URL:

http://www.oracle.com/technetwork/middleware/id-mgmt/overview/index.html

34.6.2.2 SAML Token Identity Propagation for SOAP Client

If you use a SOAP client, you can use the SAML-token identity propagation supported by Oracle web services.

This section assumes the application resides in and is secured by the Oracle WebLogic Server container.

34.6.2.2.1 Client configuration

To enable identity propagation, the client configuration must specify a special propagation mode.

34.6.2.2.2 Identity Propagation Mode Setting Through Properties

If properties are used, then populate the property CONNECTION_PROPERTY.SOAP_IDENTITY_PROPAGATION with the value saml.

  • Dynamic SAML token propagation mode

    The SAML token policy is provided dynamically (the default). The property shown in Example 34-22 is optional. If the identity propagation mode is set, you run by default in dynamic mode.

    Example 34-22 Identity Propagation Mode Setting Through Properties

    properties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.SOAP_
    IDENTITY_PROPAGATION_MODE , "dynamic");
    

By default, SAML-token constructs dynamic policy based on the following security policy URI: oracle/wss10_saml_token_client_policy. Logging is not used. To overwrite the default policy URI, the client can add the code shown in Example 34-23.

Example 34-23 Default Policy URI Overwrite

properties.put(CONNECTION_PROPERTY.SECURITY_POLICY_URI     "oracle/wss10_saml_
token_client_policy");
properties.put(CONNECTION_PROPERTY.MANAGEMENT_POLICY_URI , "oracle/log_policy");

Example 34-24 shows the SAML token dynamic client.

Example 34-24 Token Dynamic Client

Map<CONNECTION_PROPERTY,String> properties = new HashMap<ONNECTION_
PROPERTY,String>();
properties.put(CONNECTION_PROPERTY.SOAP_IDENTITY_PROPAGATION , "saml");
properties.put(CONNECTION_PROPERTY.SOAP_END_POINT_ROOT,
 "http://myhost.us.oracle.com:7001");
properties.put(ONNECTION_PROPERTY.SECURITY_POLICY_URI, "oracle/wss10_saml_token_
client_policy"); //optional
properties.put(CONNECTION_PROPERTY.MANAGEMENT_POLICY_URI , "oracle/log_policy");
  //optional
IWorkflowServiceClient client =
                            WorkflowServiceClientFactory.getWorkflowServiceClient(
                            WorkflowServiceClientFactory.SOAP_CLIENT,
properties, null);

The client reference to the policy URI must match the server policy URI. Otherwise, SAML token propagation fails.

34.6.2.2.3 Identity Propagation Mode Setting in Configuration File

In the configuration file, you can define the propagation mode by using the <identityPropagation> element in the <soapClient>, as shown in Example 34-25.

Example 34-25 <identityPropagation> Element

<soapClient>
        <rootEndPointURL>http://myhost.us.oracle.com:7001</rootEndPointURL>
        <identityPropagation mode="dynamic" type="saml">
            <policy-references>
                <policy-reference enabled="true" category="security"
 uri="oracle/wss10_saml_token_client_policy"/>
            </policy-references>
        </identityPropagation> </soapClient>

For more information, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

34.6.2.2.4 Identity Propagation Mode Setting Through the JAXB Object

You can programmatically set the identity propagation mode with the JAXB object.

34.6.2.3 Public Key Alias

You can use the oracle.wsm.security.util.SecurityConstants.ClientConstants.WSS_RECIPIENT_KEY_ALIAS property with the workflow client. This property sets the alias for the recipient's public key that is used to encrypt the type outbound message. Use this property to secure workflow services with the public key alias. This property is only relevant when the SOAP client type uses identity propagation.

The client code must add the WSS_RECIPIENT_KEY_ALIAS value to the map if the public key alias is defined. Example 34-26 provides details.

Example 34-26 WSS_RECIPIENT_KEY_ALIAS Property

Map<CONNECTION_PROPERTY,String> properties = new HashMap<ONNECTION_
PROPERTY,String>();
properties.put(CONNECTION_PROPERTY.SOAP_IDENTITY_PROPAGATION , "saml");
properties.put(CONNECTION_PROPERTY.SOAP_END_POINT_ROOT,
 "http://myhost.us.oracle.com:7001");
properties.put(CONNECTION_PROPERTY.WSS_RECIPIENT_KEY_ALIAS,keyAlias); 
// where keyAlias  is a key alias value
properties.put(ONNECTION_PROPERTY.SECURITY_POLICY_URI, "oracle/wss10_saml_token_
client_policy"); //optional
properties.put(CONNECTION_PROPERTY.MANAGEMENT_POLICY_URI , "oracle/log_policy");
  //optional
IWorkflowServiceClient client =
                            WorkflowServiceClientFactory.getWorkflowServiceClient(
                            WorkflowServiceClientFactory.SOAP_CLIENT,
 properties, null);

If the client uses the JAXB WorkflowServicesClientConfigurationType object or the wf_client_config.xml file, an optional element called wssRecipientKeyAlias is added under the identityPropagation element for a SOAP client. Example 34-27 provides details.

Example 34-27 wssRecipientKeyAlias Element

<xsd:complexType name="identityPropagationType">
    <xsd:sequence>
      <xsd:element name="policy-references"  type="PolicyReferencesType" 
       minOccurs="0" maxOccurs="1"/>
      <xsd:element name="wssRecipientKeyAlias"  type="xsd:string"  minOccurs="0"
       maxOccurs="1"/> </xsd:sequence> 
    <xsd:attribute name="type" type="xsd:string"  default="saml"/>
    <xsd:attribute name="mode" type="xsd:string"  default="dynamic"/>
  </xsd:complexType>

For more information about how to create and use the public key alias in the credential store, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

34.6.3 Client JAR Files

A client application without identity propagation must have the bpm-services.jar file in its class path. For 11g Release 1, the client class path requires the files shown in Example 34-28.

Example 34-28 Client JAR Files

${bea.home}/wlserver_10.3/server/lib/wlfullclient.jar
${bea.home}/AS11gR1SOA/webservices/wsclient_extended.jar
${bea.home}/AS11gR1SOA/soa/modules/oracle.soa.fabric_11.1.1/bpm-infra.jar
${bea.home}/AS11gR1SOA/soa/modules/oracle.soa.workflow_11.1.1/bpm-services.jar

The wlfullclient.jar file must be generated.

  1. Generate the wlfullclient.jar as follows:

    cd ${bea.home}/wlserver_10.3/server/lib
    java -jar ../../../modules/com.bea.core.jarbuilder_1.3.0.0.jar
    

34.7 Task States in a Human Task

The following list identifies all the task states available in a human task. The constants for all states are defined in IWorkflowConstants.java.

For more information about IWorkflowConstants.java, see Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager.

34.8 Database Views for Oracle Workflow

This section describes database views that enable queries against the Oracle workflow services schema to receive reports. Table 34-22 lists the reports exposed in Oracle BPM Worklist and the database views corresponding to these reports.

Table 34-22 Report Views

Existing Worklist Report Corresponding Database View

Unattended Tasks report

WFUNATTENDEDTASKS_VIEW

Task Cycle Time report

WFTASKCYCLETIME_VIEW

Task Productivity report

WFPRODUCTIVITY_VIEW

Task Priority Report

WFTASKPRIORITY_VIEW


34.8.1 Unattended Tasks Report View

Table 34-23 describes the WFUNATTENDEDTASKS_VIEW report view.

Table 34-23 Unattended Tasks Report View

Name Type

TASKIDFoot 1 

VARCHAR2(64)

TASKNAME

VARCHAR2(200)

TASKNUMBER

NUMBER

CREATEDDATE

DATE

EXPIRATIONDATE

DATE

STATE

VARCHAR2(100)

PRIORITY

NUMBER

ASSIGNEEGROUPS

VARCHAR2(2000)


Footnote 1 NOT NULL column

For example:

  • Query unattended tasks that have an expiration date of next week, as shown in Example 34-29.

    Example 34-29 Query of Unattended Tasks with an Expiration Date of Next Week

    SELECT tasknumber, taskname, assigneegroups FROM WFUNATTENDEDTASKS_VIEW
     WHERE expirationdate > current_date AND expirationdate < current_date +
     7;
    
  • Query unattended tasks for mygroup, as shown in Example 34-30.

    Example 34-30 Query of Unattended Tasks for mygroup

    SELECT tasknumber, taskname, assigneegroups FROM WFUNATTENDEDTASKS_VIEW
     WHERE 'mygroup' IN assigneegroups;
    
  • Query unattended tasks created in the last 30 days, as shown in Example 34-31.

    Example 34-31 Query of Unattended Tasks Created in the Last 30 Days

    SELECT tasknumber, taskname, assigneegroups FROM WFUNATTENDEDTASKS_VIEW
     WHERE createddate > current_date -30;
    

34.8.2 Task Cycle Time Report View

Table 34-24 describes the WFTASKCYCLETIME_VIEW report view.

Table 34-24 Task Cycle Time Report View

Name Type

TASKIDFoot 1 

VARCHAR2(64)

TASKNAME

VARCHAR2(200)

TASKNUMBER

NUMBER

CREATEDDATE

DATE

ENDDATE

DATE

CYCLETIME

NUMBER(38)


Footnote 1 NOT NULL column

For example:

  • Compute the average cycle time (task completion time) for completed tasks that were created in the last 30 days, as shown in Example 34-32.

    Example 34-32 Average Cycle Time for Completed Tasks Created in the Last 30 Days

    SELECT avg(cycletime) FROM  WFTASKCYCLETIME_VIEW  WHERE createddate > 
     (current_date - 30);
    
  • Query the average cycle time for all completed tasks created in the last 30 days and group them by task name, as shown in Example 34-33.

    Example 34-33 Average Cycle Time for All Completed Tasks Created in Last 30 days Grouped by Task Name

    SELECT taskname, avg(cycletime) FROM WFTASKCYCLETIME_VIEW WHERE
     createddate > (current_date - 30) GROUP BY taskname;
    
  • Query the least and most time taken by each task, as shown in Example 34-34.

    Example 34-34 least and most time taken by each task

    SELECT taskname, min(cycletime), max(cycletime) FROM WFTASKCYCLETIME_VIEW
     GROUP BY taskname;
    
  • Compute the average cycle time for tasks completed in the last seven days, as shown in Example 34-35.

    Example 34-35 Average Cycle Time for Tasks Completed in the Last Seven Days

    SELECT avg(cycletime) FROM  WFTASKCYCLETIME_VIEW  WHERE enddate >
      (current_date - 7);
    
  • Query tasks that took more than seven days to complete, as shown in Example 34-36.

    Example 34-36 Tasks Taking More than Seven Days to Complete

    SELECT taskname, avg(cycletime) FROM WFTASKCYCLETIME_VIEW WHERE cycletime
     > ((current_date +7) - current_date) GROUP BY taskname;
    

34.8.3 Task Productivity Report View

Table 34-25 describes the WFPRODUCTIVITY_VIEW report view.

Table 34-25 Task Productivity Report View

Name Type

TASKNAME

VARCHAR2(200)

TASKID

VARCHAR2(200)

TASKNUMBER

NUMBER

USERNAME

VARCHAR2(200)

STATEFoot 1 

VARCHAR2(100)

LASTUPDATEDDATE

DATE


Footnote 1 For completed tasks, the state is null. Use decode(outcome, '', 'COMPLETED', outcome) in queries.

For example:

  • Count the number of unique tasks that the user has updated in the last 30 days, as shown in Example 34-37.

    Example 34-37 Number of Unique Tasks Updated in the Last 30 Days

    SELECT username, count(distinct(taskid))  FROM WFPRODUCTIVITY_VIEW WHERE
     lastupdateddate > (current_date -30) GROUP BY username;
    
  • Count the number of tasks that the user has updated (one task may have been updated multiple times) in the last seven days, as shown in Example 34-38.

    Example 34-38 Number of Tasks Updated in the Last 7 Days

    SELECT username, count(taskid)  FROM WFPRODUCTIVITY_VIEW  WHERE
     lastupdateddate > (current_date -7) GROUP BY username;
    
  • Count the number of tasks of each task type on which the user has worked, as shown in Example 34-39.

    Example 34-39 Number of Tasks of Each Task Type on Which the User has Worked

    SELECT username, taskname, count(taskid) FROM WFPRODUCTIVITY_VIEW GROUP
     BY username, taskname;
    
  • Count the number of tasks of each task type that the user has worked on in the last 100 days, as shown in Example 34-40.

    Example 34-40 Number of Tasks of Each Task Type Worked on in the Last 100 Days

    SELECT username, taskname, count(taskid) FROM WFPRODUCTIVITY_VIEW WHERE
     lastupdateddate > (current_date -100) GROUP BY username, taskname;
    

34.8.4 Task Priority Report View

Table 34-26 describes the WFTASKPRIORITY_VIEW report view.

Table 34-26 Task Priority Report View

Name Type

TASKIDFoot 1 

VARCHAR2(64)

TASKNAME

VARCHAR2(200)

TASKNUMBER

NUMBER

PRIORITY

NUMBER

OUTCOME

VARCHAR2(100)

ASSIGNEDDATE

DATE

UPDATEDDATE

DATE

UPDATEDBY

VARCHAR2(64)


Footnote 1 NOT NULL column

For example:

  • Query the number of tasks updated by each user in each task priority, as shown in Example 34-41.

    Example 34-41 Number of Tasks Updated by Each User in Each Task Priority

    SELECT updatedby, priority, count(taskid) FROM  WFTASKPRIORITY_VIEW GROUP
     BY  updatedby, priority;
    
  • Query task-to-outcome distribution, as shown in Example 34-42.

    Example 34-42 Task-to-outcome Distribution

    SELECT taskname, decode(outcome, '', 'COMPLETED', outcome),  count
     (taskid) FROM WFTASKPRIORITY_VIEW GROUP BY taskname, outcome;
    
  • Query the number of tasks updated by the given user in each priority, as shown in Example 34-43.

    Example 34-43 Number of Tasks Updated by the Given User in Each Priority

    SELECT priority, count(taskid) FROM WFTASKPRIORITY_VIEW WHERE
     updatedby='jstein' GROUP BY priority;