29 Introduction to Human Workflow Services

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

This appendix includes the following sections:

29.1 Introduction to Human Workflow Services

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

  • Task service

  • Task query service

  • Identity service

  • Task metadata service

  • User metadata service

  • Task report service

  • Runtime config service

  • Evidence store service

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

Table 29-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 local 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 29-1 Enterprise JavaBeans, SOAP, and Java Support

Service Name Supports SOAP Web Services Supports Remote Enterprise JavaBeans Supports Local 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

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

Yes

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

Yes

Yes

Yes

Task Reports Service: Provides workflow report details.

Yes

Yes

Yes

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

Yes

Yes

Yes

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

Yes

Yes

Yes

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

Yes

Yes

Yes

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

Yes

No

No


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

Table 29-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 29-3 lists the JDNI names for the different Enterprise JavaBeans.

Table 29-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 28, "Building a Custom Worklist Client"

29.1.2 Security Model for Services

With the exception of the identity service, all services that use the above-mentioned APIs (SOAP, remote Enterprise JavaBeans, local Enterprise JavaBeans, and Java WSIF) 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.

29.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. The web service security can be configured from the Oracle Enterprise Manager Fusion Middleware Control Console.

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.

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

In Example 29-1, the human workflow context is created for user jcooper.

Example 29-1 Human Workflow Context Creation

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

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

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

29.1.3 Task Service

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

Table 29-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 in them).

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 workflow-config.xml controls whether the task is pushed back to the original assignees or the approvers.

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 sequential, parallel, or simple 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.

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:

29.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, history information of a task, and so on. Table 29-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 29-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 make 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 tasks exist that 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 sequence.

getTaskVersionDetails

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

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

29.1.5 Identity Service

The identity service is a thin web service layer on top of the Oracle Application Server 11g 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 Application Server 11g. 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-infra 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 flex field mapping to public flex fields. 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 flex fields.

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

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:

29.1.5.1 Identity Service Providers

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

Figure 29-1 Identity Service Providers

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

29.1.5.1.1 Custom User Repository Plug-ins

This mode enables you to plug in a non-LDAP-based user repository by registering a custom identity service provider. This mode is provided only for backward compatibility. The custom identity service plug-in must implement the BPMIdentityService interface (see the Javadoc). This identityservice class name must be registered in workflow-identity-config.xml.

29.1.6 Task Metadata Service

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

Table 29-6 Task Metadata Service Methods

Method Description

getTaskMetadataByNamespace

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

getOutcomes

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

getResourceBundleInfo

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

getRestrictedActions

Get the actions that are restricted for a particular task.

getTaskAttributesForTaskDefinitions

Get a list of TaskAttribute objects that describe standard task attributes and mapped flex-field columns that are common for the specified task definitions.

getTaskAttributesForTaskNamespaces

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

getTaskAttributes

Get the task message attributes.

getTaskAttributesForTaskDefinition

Get the message attributes for a particular task definition.

getTaskDefinition

Get the task definition associated with the task.

getTaskDefinitionById

Get the task definition by the task definition ID.

getTaskDefinitionOutcome

Get the outcomes given the task definition ID.

getTaskDisplay

Get the task display for a task.

getTaskVisibilityRules

Get the task visibility rules.

getTaskDisplayRegion

Get the task display region for a task.

getVersionTrackedAttrs

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

listTaskMetadata

List the task definitions in the system.


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

29.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 29-7 describes the methods in the user metadata service. Package oracle.bpel.services.workflow.user corresponds to the user metadata service.

Table 29-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 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:

29.1.8 Task Report Service

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

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


29.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 flex field mappings and the URIs used for displaying task details.

The task object used by the task service contains many flex field 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 flex field attributes.

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

An administrator can create attribute labels for the various flex field attributes. These attribute labels provide a meaningful label for the attribute (for example, a label Location may be created for the flex field attribute TextAttribute1). A given flex field 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 flex fields 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 the Oracle BPM Worklist and other applications

  • Methods for getting the server HTTP and JNDI URLs

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

Table 29-9 Runtime Config Service

Method Description

CreateAttributeLabel

Creates a new attribute label for a particular task flex field 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 flex field 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:

29.1.9.1 Internationalization of Attribute Labels

Attribute labels provide a method of attaching a meaningful label to a task flex field 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 Console:

  • 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 following URL for details:

http://www.oracle.com/technology/sample_code/products/hwf

Entries for flex field 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

Note that 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.

29.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, and 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 the 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 the Oracle BPM Worklist.

Figure 29-2 provides an example.

Figure 29-2 Digital Signature and Certificate

Description of Figure 29-2 follows
Description of "Figure 29-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

29.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 Console.

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

    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. For example, values provided for each invocation may look as shown in Table 29-10.

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

29.1.10.2 Interfaces and Methods

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

Table 29-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 29-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 29-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 29-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:

29.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 29-15 describes the task attributes that are commonly used and interpreted by applications.

Table 29-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 29-16 lists the attributes that capture process metadata information.

Table 29-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 29-17 lists the attachment-related attributes.

Table 29-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 29-18 lists the comment-related attributes.

Table 29-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 29-19 lists the attributes manipulated by the workflow services system.

Table 29-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 (maybe 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 equal to 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

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

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 29-20 lists the flex field attributes.

Table 29-20 Flex Field Attributes

Attribute Description

task/systemMessageAttributes/*

The flex fields.


29.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 from a BPEL process directly.

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 business process or human task to send notifications through email, voice, IM, or SMS channels.

The Oracle User Messaging Service supports features such as:

  • Sending and receiving messages and statuses

  • Sending notifications to a specific address on a particular channel

  • Sending notifications to a set of failover addresses

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:

29.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 26.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 29-2 demonstrates the use of hwf:getNotificationProperty and hwf:getTaskResourceBundle together:

Example 29-2 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

29.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 Console.

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

29.2.3 Reliability Support

The human workflow email notification layer works with the 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 Console. 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:

29.2.4 Management of Oracle Human Workflow Notification Service

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

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

29.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 16, "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 25.3.9.1, "Notifying 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 25.3.9.1, "Notifying 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 Console, configure the appropriate channel (for example, email). See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for details.

  4. From the Workflow Notification Properties pages of Oracle Enterprise Manager Fusion Middleware Control Console, 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.

29.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 details 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. If you want to use values from the resource bundle specified during the task definition, then 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 25.3.10.4, "Specifying Multilingual Settings."

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

29.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 Notification Settings section of the Human Task Editor, select Make notifications 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. If you want 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 29-3 provides details.

    Figure 29-3 Actionable Notifications

    Description of Figure 29-3 follows
    Description of "Figure 29-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 29-4.

    Figure 29-4 Attachment to an Actionable Email

    Description of Figure 29-4 follows
    Description of "Figure 29-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 username and password, and others from the Oracle User Messaging Service section of Oracle Enterprise Manager Fusion Middleware Control Console.

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

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

29.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 Notification Settings 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 25.3.9.6, "Making Email Messages Actionable."

29.2.9 How to Send Inbound Comments

To send inbound comments:

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

29.2.10 How to Send Secure Notifications

To send secure notifications:

  1. Mark a notification as secure in the Notification Settings 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 25.3.9.5, "Securing Notifications to Exclude Details."

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

29.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 Notification Settings section of the Human Task Editor. Reminder configuration involves the following parameters:

    • Recurrence:

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

    • RelativeDate:

      The 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 DUE DATE.

    • Duration:

      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 25.3.9.3, "Setting Up Reminders."

29.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. For more information see Section 29.5.2, "Global Resource Bundle – WorkflowLabels.properties."

Example 29-3 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.

29.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 Custom Notification Headers field of the Notification Settings 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.

    Note that 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:

29.3 Assignment Service Configuration

This section describes how to configure the assignment service with dynamic assignment functions.

29.3.1 Dynamic Assignment and Task Escalation Functions

When tasks are assigned to a group, users in the group must typically claim a task to act on it. However, you can also automatically send work to users in the group by using various dispatching mechanisms. Automatic task dispatching is done through dynamic assignment functions. Dynamic assignment functions select a particular user or group from either a group, or from a list of users or groups. Several functions are automatically provided. However, you can also create your own functions and register them with the workflow service. Table 29-21 describes the three dynamic assignment functions.

Table 29-21 Dynamic Assignment Functions

Function Type Description

LEAST_BUSY

Dynamic assignment

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

MANAGERS_MANAGER

Task escalation

Picks the manager's manager.

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.


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

These dynamic assignment functions can be called using the custom XPath functions in a BPEL process or task definition:

  • wfDynamicUserAssign

  • wfDynamicGroupAssign

These XPath functions must be called with at least two, and optionally more parameters:

  • The name of the dynamic assignment function being called.

  • The name of the group on which to execute the function (or a list of users or groups).(Optional) The identity realm to which the user or group belongs (the default value is the default identity realm).

  • Additional optional parameters specific to the dynamic assignment function. In the case of the MOST_PRODUCTIVE assignment function, this is the length of time (in days) to calculate a user's productivity. The two other functions do not use additional parameters.

In addition, human workflow rules created for a group can use dynamic assignment functions to select a member of that group for reassignment of a task.

In addition to these functions, a dynamic assignment framework is provided that enables you to implement and configure your own dynamic assignment functions.

29.3.1.1 How to Implement a Dynamic Assignment Function

Follow these procedures to implement your own dynamic assignment function.

To implement dynamic assignment functions:

  1. Write a Java class that implements one or both of the following interfaces:

    oracle.bpel.services.workflow.assignment.dynamic. IDynamicUserAssignmentFunction
    oracle.bpel.services.workflow.assignment.dynamic. IDynamicGroupAssignmentFunction
    
  2. If your dynamic assignment function selects users, implement the first interface. If it selects groups, implement the second interface. If it allows the selection of both users and groups, implement both interfaces.

    The two interfaces above both extend the interface oracle.bpel.services.workflow.assignment.dynamic.IDynamicAssignmentFunction.

    Your Java class should also implement the methods in that interface. These interfaces as shown in the Javadoc.

    The dynamic assignment framework also provides the utility class oracle.bpel.services.workflow.assignment.dynamic.DynamicAssignmentUtils.

    This class provides many methods that are useful when implementing dynamic assignment functions.

    For information about the Javadoc for dynamic assignment interfaces and utilities, see SOA_ORACLE_HOME\javadoc\soa-infra.

29.3.1.2 How to Configure Dynamic Assignment Functions

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

Each dynamic assignment has two mandatory parameters in this file, in the form of a <function> tag.

The function tag must contain two attributes:

  • name: The name of the function

  • classpath: The fully qualified class name of the class that implements the function.

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

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

Two of the functions 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 function can maintain ROUND_ROBIN counts. The dynamic assignment function 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 function.

  • MOST_PRODUCTIVE

    The parameter DEAFULT_TIME_PERIOD specified 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 function. Use an XPath function by specifying an alternative value as the third parameter in the XPath function call.

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

29.3.1.3 How to Configure Display Names for Dynamic Assignment Functions

The runtime config service provides methods for returning a list of available user and group dynamic assignment functions. These functions return both the name of the function, and a user-displayable label for the function. The functions support localization of the display name, so that it displays in the appropriate language for the context user. These functions are used by Oracle BPM Worklist to show a list of available dynamic assignment functions. This applies exclusively to dynamic assignment functions. Display names for task escalation functions are not supported.

To configure display names for dynamic assignment functions:

  1. Specify display names (and appropriate translations) for your dynamic assignment functions by adding entries to the resource property file WorkflowLabels.properties, and associated resource property files in other languages. This file exists in the classpath identified in the workflow configuration parameter workflowCustomizationsClasspathURL.

    Entries for dynamic assignment functions must be of the form:

    DYN_ASSIGN_FN.[function name]=Function Display Name
    

    For instance, the entry for the ROUND_ROBIN function is:

    DYN_ASSIGN_FN.ROUND_ROBIN = Round Robin
    

    Note that adding entries to these files for dynamic assignment functions 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 at the following URL:

    http://www.oracle.com/technology/sample_code/products/hwf
    

29.3.1.4 How to Implement a Task Escalation Function

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

29.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, sequential 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, if you want to do more sophisticated routing using custom logic, then 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 which to assign the task.

29.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).

29.3.2.2 Example of Assignment Service Implementation

Notes:

  • The assignment service class cannot be stateful 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 29-4 provides a sample IAssignmentService implementation named TestAssignmentService.java.

Example 29-4 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 will implement. The implementation of the IAssignmentService 
    will be 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;
    }

}

29.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 SCA-INF/lib as a JAR.

    • Change the Oracle BPEL Process Manager shared library to include your JAR files.

    Note:

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

29.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 Advanced Settings section of the Human Task Editor to integrate the rule in a human workflow.

    For more information, see Section 25.3.10.1, "Specifying Escalation Rules."

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

  • IAssignmentService

  • IRestrictedAssignmentService

  • IRoutingSlipCallback

  • IPercentageCompletionCallback

  • INotificationCallback

  • Project level resource bundles

The callback classes can be in the following locations:

  • JARs in the SCA-INF/lib directory of the project

  • Classes in the SCA-INF/classes directory of the project

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

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

29.5.1 Task Resource Bundles

Each human workflow component can be associated with a resource bundle. The bundle defines the resource strings to be used 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 used as 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 Advanced Settings section of the Human Task Editor in Oracle JDeveloper. Note that 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 29.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.

29.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.worklfow.resource.WorkflowLabels.properties

You can customize this bundle to provide alternatives for existing display strings or to add additional strings (for example, for flex field 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

  • Flex field attribute labels:

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

    • getTaskAttributesForTaskDefinition

    • getTaskAttributesForTaskDefinitions

    If translated resource strings are required for flex field 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 following URL:

    http://www.oracle.com/technology/sample_code/products/hwf
    

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

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

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.

29.5.5 Case Sensitivity

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

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

  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.

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

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

There are three supported service types:

  • Local

  • Remote

  • SOAP

Local and remote clients use Enterprise JavaBeans clients (local Enterprise JavaBeans and remote Enterprise JavaBeans, accordingly). SOAP uses SOAP clients. Each type of service requires you to configure workflow clients. Example 29-5 provides details.

Example 29-5 Client Configuration File

<workflowServicesClientConfiguration>
<server name="default" default="true">
   <localClient>
      <participateInClientTransaction>false</participateInClientTransaction>
   </localClient>
   <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>

29.6.1.1 Task Query Service Client Code

Example 29-6 provides an example of the task query service client code.

Example 29-6 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);
   }  
  
}

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

  • wf_client_config.xml file

  • Property map

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

29.6.1.2.1 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 and local 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 29-7. The configuration defines a server named default. The XML file must go into the client application's EAR file.

Example 29-7 Client Configuration

<workflowServicesClientConfiguration>
server name="default" default="true">
<localClient>
   <participateInClientTransaction>false</participateInClientTransaction>
</localClient>

<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>
29.6.1.2.2 Workflow Client Configuration in the Property Map

If you want 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 if you want 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.

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

The IWorkflowServiceClientConstants.CONNECTION_PROPERTY, which can be used in the properties map, is show in Example 29-8:

Example 29-8 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"
            // LOCAL and REMOTE EJB  option
            TASK_SERVICE_PARTICIPATE_IN_CLIENT_TRANSACTION  // default value is
               false
            //(task service EJB will start a new transaction)
 };

Note:

If you use the properties map, you do not need to specify IWorkflowServiceClientConstants.CONNECTION_PROPERTY.MODE. This property has been deprecated in this release.

Example 29-9 provides an example for remote Enterprise JavaBeans clients.

Example 29-9 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 29-10 provides an example for a SOAP client.

Example 29-10 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);

29.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 29-11 shows how to pass a logger to the workflow service clients:

Example 29-11 java.util.logging.Logger

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

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

29.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 following 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.

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

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

29.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 29.6.1.2.2, "Workflow Client Configuration in the Property Map."

  • IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL

  • IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS

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

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

29.6.2.2.1 Client configuration

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

29.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 following property is optional. If the identity propagation mode is set, you run by default in dynamic mode.

    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 following code:

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

Example 29-12 shows the SAML token dynamic client.

Example 29-12 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.

29.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 29-13.

Example 29-13 <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.

29.6.2.2.4 Identity Propagation Mode Setting Through the JAXB Object

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

29.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 classpath requires the following 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
    

29.7 Database Views for Oracle Workflow

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

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


29.7.1 Unattended Tasks Report View

Table 29-23 describes the WFUNATTENDEDTASKS_VIEW report view.

Table 29-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:

    SELECT tasknumber, taskname, assigneegroups FROM WFUNATTENDEDTASKS_VIEW
     WHERE expirationdate > current_date AND expirationdate < current_date +
     7;
    
  • Query unattended tasks for mygroup:

    SELECT tasknumber, taskname, assigneegroups FROM WFUNATTENDEDTASKS_VIEW
     WHERE 'mygroup' IN assigneegroups;
    
  • Query unattended tasks created in the last 30 days:

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

29.7.2 Task Cycle Time Report View

Table 29-24 describes the WFTASKCYCLETIME_VIEW report view.

Table 29-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:

    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:

    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:

    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:

    SELECT avg(cycletime) FROM  WFTASKCYCLETIME_VIEW  WHERE enddate >
      (current_date - 7);
    
  • Query tasks that took more than seven days to complete:

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

29.7.3 Task Productivity Report View

Table 29-25 describes the WFPRODUCTIVITY_VIEW report view.

Table 29-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:

    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:

    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:

    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:

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

29.7.4 Task Priority Report View

Table 29-26 describes the WFTASKPRIORITY_VIEW report view.

Table 29-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:

    SELECT updatedby, priority, count(taskid) FROM  WFTASKPRIORITY_VIEW GROUP
     BY  updatedby, priority;
    
  • Query 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:

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