| Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite 11g Release 1 (11.1.1) E10224-03 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite 11g Release 1 (11.1.1) E10224-03 |
|
Previous |
Next |
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 chapter includes the following sections:
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
Table 30-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 30-1 Enterprise JavaBeans, SOAP, and Java Support
Table 30-2 lists the location for the SOAP Web Services Description Language (WSDL) file for each task service.
Table 30-2 SOAP WSDL Location for the Task Services
| Service name | SOAP WSDL location |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 30-3 lists the JDNI names for the different Enterprise JavaBeans.
Table 30-3 JNDI Names for the Different Enterprise JavaBeans
| Service name | JNDI Names for the Different Enterprise JavaBeans |
|---|---|
|
Task Service |
|
|
Task Service Enterprise JavaBeans participating in client transaction |
|
|
Task Metadata Service |
|
|
Task Query Service |
|
|
User Metadata Service |
|
|
Runtime Config Service |
|
|
Task Report Service |
|
|
Task Evidence Service |
|
For more information about the client library for worklist services, see Chapter 29, "Building a Custom Worklist Client"
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.
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. |
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 30-1, the human workflow context is created for user jcooper.
Example 30-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");
The task service exposes operations to act on tasks. Table 30-4 describes the operations of the task service. Package oracle.bpel.services.workflow.task corresponds to the task service.
Table 30-4 Task Service Methods
| Method | Description |
|---|---|
|
|
Acquire a task. |
|
|
Acquire a set of tasks. |
|
|
Add an attachment to a task. |
|
|
Add a comment to a task. |
|
|
Create a to-do task. |
|
|
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. |
|
|
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. |
|
|
Perform a logical deletion of a task. The task still exists in the database. |
|
|
Perform a logical deletion of a list of tasks. The tasks still exist in the database. |
|
|
Cause the task to error. This operation is typically used by the error assignee. |
|
|
Escalate a task. The default escalation is to the manager of the current user. This can be overridden using escalation functions. |
|
|
Escalate tasks in bulk. The default escalation is to the manager of the current user. This can be overridden using escalation functions. |
|
|
Get the previous approvers of a task. |
|
|
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). |
|
|
Get the users from whom a request for information can be requested. |
|
|
Initiate a task. |
|
|
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:
|
|
|
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. |
|
|
Remove a task from the persistent store. |
|
|
Remove a list of tasks from the persistent store. |
|
|
Push back a task to the previous approver or original assignees. The original assignees do not need to be the approver as they may have reassigned the task, escalated the task, and so on. The property PushbackAssignee in the System MBean Browser of Oracle Enterprise Manager Fusion Middleware Control Console controls whether the task is pushed back to the original assignees or the approvers.
|
|
|
Reassign a task. |
|
|
Reassign tasks in bulk. |
|
|
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. |
|
|
Release a previously acquired task. |
|
|
Release a set of previously acquired tasks. |
|
|
Remove a task attachment. |
|
|
Renew a task to extend the time it takes to expire. |
|
|
Request information for a task. |
|
|
Request information for a task with reapproval. For example, assume |
|
|
Resume a task. Operations can only be performed by the task owners (or users with the |
|
|
Resume a set of tasks. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
Allow task owners (or users with the |
|
|
Suspend a set of tasks. |
|
|
Update the outcome of a set of tasks. |
|
|
Update the task. |
|
|
Update the task outcome. |
|
|
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. |
|
|
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 |
|
|
Withdraw a set of tasks. |
For more information, see the following:
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager
Sample workflow-118-JavaSamples, which demonstrates some APIs
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 30-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 30-5 Task Query Service Methods
| Method | Description |
|---|---|
|
|
Authenticates a user with the identity authentication service and passes back a valid |
|
|
Optionally make authentication on behalf of another user. |
|
|
Counts the number of tasks that match the specified query criteria. |
|
|
Counts the number of tasks that match the query criteria of the specified view. |
|
|
Creates a valid |
|
|
Checks to see if any tasks exist that match the specified query criteria. |
|
|
Checks to see if any tasks exist match the query criteria of the specified view. |
|
|
Gets a human workflow context with the specified context token. |
|
|
Cleans up a human workflow context that is no longer needed. This method is typically used when a user logs out. |
|
|
Gets the details of a specific task from the task's |
|
|
Gets the details of a specific task from the task's |
|
|
Gets a list of the task versions for the specified task ID. |
|
|
Gets the task sequence tree of a task whose ID is a task ID, for those type of sequence. |
|
|
Gets the specific task version details for the specified task ID and version number. |
|
|
Executes the specified query, and aggregates a count of the tasks returned by the query, grouped by the specified column. |
|
|
Returns a list of task error objects matching the specified predicate. |
|
|
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:
|
|
|
Executes the query as defined in the specified view, and aggregates the selected tasks according to the chart property defined in the view. |
|
|
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:
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager in the documentation library
Sample workflow-118-JavaSamples, which demonstrates some APIs
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:
Oracle Fusion Middleware Security Guide for details about OPSS
Oracle Fusion Middleware Application Developer's Guide for Oracle Identity Management for details about Oracle Identity Management
Oracle Fusion Middleware Administrator's Guide for Oracle Virtual Directory for details about OVD
Oracle Identity Management is the only supported provider for release 11g, as shown in Figure 30-1.
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.
The task metadata service exposes operations to retrieve metadata information related to a task. Table 30-6 describes these methods. Package oracle.bpel.services.workflow.metadata corresponds to the task metadata service.
Table 30-6 Task Metadata Service Methods
| Method | Description |
|---|---|
|
|
Get the |
|
|
Get the permitted outcomes of a task. The outcomes are returned with their display values. |
|
|
Get the resource bundle information of the task. The resource bundle information contains the location and the name of the bundle. |
|
|
Get the actions that are restricted for a particular task. |
|
|
Get a list of |
|
|
Get a list of |
|
|
Get the task message attributes. |
|
|
Get the message attributes for a particular task definition. |
|
|
Get the task definition associated with the task. |
|
|
Get the task definition by the task definition ID. |
|
|
Get the outcomes given the task definition ID. |
|
|
Get the task display for a task. |
|
|
Get the task visibility rules. |
|
|
Get the task display region for a task. |
|
|
Get the task attributes that when changed cause a task version creation. |
|
|
List the task definitions in the system. |
For more information, see Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager.
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 30-7 describes the methods in the user metadata service. Package oracle.bpel.services.workflow.user corresponds to the user metadata service.
Table 30-7 User Metadata Service Methods
| Method | Description |
|---|---|
|
|
Creates a new rule. |
|
|
Decreases the priority of a rule by one. This method does nothing if this rule has the lowest priority. |
|
|
Deletes a rule. |
|
|
Retrieves the date range (if any) during which a user is unavailable for the assignment of tasks. |
|
|
Gets the details for a particular human workflow rule. |
|
|
Retrieves a list of rules for a particular user or group. |
|
|
Updates an existing rule. |
|
|
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. |
|
|
Gets a list of the user task views that the user owns. |
|
|
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. |
|
|
Gets a list of standard task views that ship with the human workflow service, and are available to all users. |
|
|
Gets the details for a single view. |
|
|
Creates a new user task view. |
|
|
Updates an existing user task view. |
|
|
Deletes a user task view. |
|
|
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. |
|
|
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 |
|
|
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. |
|
|
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 w |
|
|
Sets the public preferences for the user. |
|
|
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.) |
|
|
Gets the full details for a particular standard view, identified by its |
For more information, see the following:
Chapter 28, "Using Oracle BPM Worklist" for details about the rule configuration and user preference pages
Sample workflow-118-JavaSamples, which demonstrates some APIs
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager
The task report service executes a report and receives the results. Table 30-8 describes the method. Package oracle.bpel.services.workflow.report corresponds to the task report service. The standard reports shown in Table 30-8 are available as part of installation.
Table 30-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. |
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 30-9 describes the methods in the runtime config service. Package oracle.bpel.services.workflow.runtimeconfig corresponds to the runtime config service.
Table 30-9 Runtime Config Service
| Method | Description |
|---|---|
|
|
Creates a new attribute label for a particular task flex field attribute. |
|
|
Creates a new mapping between an attribute label and a task payload field. |
|
|
Deletes an existing attribute label. |
|
|
Deletes an existing payload mapping. |
|
|
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. |
|
|
Returns a list of the dynamic assignment functions that can select a group that are implemented on this server. |
|
|
Retrieves information relating to the URIs used for displaying task instances of a specific task definition. |
|
|
Gets the status of a task instance corresponding to a particular task definition and composite instance. |
|
|
Returns a list of the dynamic assignment functions that can select a user that are implemented on this server. |
|
|
Gets a list of all the flex field mappings for a particular human workflow definition. |
|
|
Sets information relating to the URIs to be used for displaying task instances of a specific task definition. |
|
|
Updates an existing attribute label. |
For more information, see the following:
Section 30.3.1, "Dynamic Assignment and Task Escalation Functions" for additional details
Chapter 28, "Using Oracle BPM Worklist" for details about flex field mapping
Sample workflow-118-JavaSamples, which demonstrates some APIs.
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager
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.
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 30-2 provides an example.
Figure 30-2 Digital Signature and Certificate
|
Notes:
|
The following digital signature features are supported:
PKCS7 signatures based on X.509 certificates
Browser-based, digitally-signed content without attachments
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.
Log in to Oracle Enterprise Manager Fusion Middleware Control Console.
In the navigator, expand the SOA folder.
Right-click soa-infra, and select Administration > System Mbean Browser.
The System Mbean Browser displays on the right side of the page.
Expand Application Defined MBeans > oracle.as.soainfra.config > Server: server_name > WorkflowConfig > human-workflow.
Click the Operations tab on the right side of the page.
Click addTrustedCA.
Provide values for caName and caURL. You must do this for each certificate in the trust chain. For example, values provided for each invocation may look as shown in Table 30-10.
Table 30-10 caName and caURL Values
| caName | caURL |
|---|---|
|
|
|
|
|
|
|
|
|
Click Invoke.
Table 30-11 through Table 30-14 describe the methods in the evidence store service. Package oracle.bpel.services.security.evidence corresponds to the evidence service.
Table 30-11 ITaskEvidenceService Interface
| Method | Description |
|---|---|
|
|
Creates evidence and stores it in the repository for nonrepudiation. |
|
|
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 |
|
|
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. |
|
|
Updates the CRL verification part of the status. This includes verified time, status, and error messages, if any. |
|
|
Validates the evidence signature. This essentially performs a nonrepudiation check on the evidence. A value of |
Table 30-12 Evidence Interface
| Method | Description |
|---|---|
|
|
Gets the certificate used to sign this evidence. |
|
|
Gets the creation date of the evidence. |
|
|
Gets the error message associated with the CRL validation. |
|
|
Gets the unique identifier associated with the evidence. |
|
|
Gets the content that was signed as part of this evidence. |
|
|
Gets the signature policy of the evidence. This is either |
|
|
Gets the signature of this evidence. |
|
|
Gets the date on which the signature was created. |
|
|
Gets the CRL validation status. This can be one of the following:
|
|
|
Gets the unique identifier of the task with which this evidence is associated. |
|
|
Gets the task number of the task with which this evidence is associated. |
|
|
Gets the task priority of the task with which this evidence is associated. |
|
|
Gets the task status of the task with which this evidence is associated. |
|
|
Gets the task substatus of the task with which this evidence is associated. |
|
|
Gets the title of the task with which this evidence is associated. |
|
|
Gets the version of the task with which this evidence is associated. |
|
|
Gets the date on which the CRL validation of the certificate used was performed. |
|
|
Gets the workflow type of the task with which this evidence is associated. This is typically |
Table 30-13 Certificate Interface
| Method | Description |
|---|---|
|
|
Gets the certificate issuer's distinguished name (DN). |
|
|
Gets the certificate object that is abstracted by the interface. |
|
|
Gets the certificate's serial number. |
|
|
Gets the identity context with which the uploader of this certificate is associated. |
|
|
Gets the user name with whom this certificate is associated. |
|
|
Returns |
Table 30-14 Policy Type and Workflow Type Interface
| Method | Description |
|---|---|
|
|
Constructs an object from the string representation. |
|
|
Returns the string representation of this object. |
For more information, see the following:
Section 26.3.12, "How to Specify a Workflow Digital Signature Policy" for details about specifying digital signatures and digital certificates in the Human Task Editor
Chapter 27, "Designing Task Forms for Human Tasks" for details about digitally signing a task action in the Oracle BPM Worklist
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 30-15 describes the task attributes that are commonly used and interpreted by applications.
Table 30-15 Task Attributes
| Task Attribute Name | Description |
|---|---|
|
|
The application with which any application roles associated with this task (assignees, owners, and so on) belong. |
|
|
An optional category of the task. |
|
|
The name of the creator of this task. |
|
|
The due date for the task. This is used on to-do tasks. |
|
|
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. |
|
|
The identity realm under which the users and groups are seeded. In a single realm environment, this defaults to the default realm. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
The task payload that is captured as XML. |
|
|
The percentage of the task completed. This is used on to-do tasks. |
|
|
An integer number that defines the priority of this task. A lower number indicates a higher priority. The numbers |
|
|
The start date for the task. This is used on to-do tasks. |
|
|
An optional subcategory of the task. |
|
|
The task definition ID that binds the task to the task metadata. At task initiation time, this can be either the |
|
|
The URL to use to display the details for this task. |
|
|
The title of the task. |
Table 30-16 lists the attributes that capture process metadata information.
Table 30-16 Attributes Capturing Process Metadata Information
| Attribute | Description |
|---|---|
|
|
The domain to which the composite that contains the task component that defines this task instance belongs. |
|
|
The application that is deployed. |
|
|
The name of the task component that defines this task instance. |
|
|
A unique name for the particular deployment of the composite that contains the task component that defines this task instance. |
|
|
The composite instance ID. |
|
|
The name of the composite that contains the task component that defines this task instance. |
|
|
The version of the composite that contains the task component that defines this task instance. |
Table 30-17 lists the attachment-related attributes.
Table 30-17 Attachment-related attributes
| Attribute | Description |
|---|---|
|
|
The attachment content. |
|
|
The Multipurpose Internet Mail Extension (MIME) type of the attachment. |
|
|
The name of the attachment. |
|
|
The user who updated the attachment. |
|
|
The date on which the attachment was updated. |
|
|
The URI if the attachment is URI-based. |
Table 30-18 lists the comment-related attributes.
Table 30-18 Comment-related Attributes
| Attribute | Description |
|---|---|
|
|
The user comment. |
|
|
The user who added the comment. |
|
|
The date on which the comment was added. |
Table 30-19 lists the attributes manipulated by the workflow services system.
Table 30-19 Attributes Manipulated by the Workflow Services System
| Attribute | Description |
|---|---|
|
|
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. |
|
|
The IDs of users who performed custom actions on the task. |
|
|
The date that this task was assigned. |
|
|
The current task assignees (maybe users, groups, or application roles). |
|
|
The date the task instance was created. |
|
|
The custom actions that can be performed on the task. |
|
|
The end date for the task. This is used on to-do tasks. |
|
|
The date on which the task instance expires. |
|
|
The user who previously acted on the task. |
|
|
If |
|
|
If |
|
|
If a user delegates a task to another user, this field is populated with the name of the user who delegated the task. |
|
|
The outcome of the task (for example, approved or rejected). This is only set on completed task instances. |
|
|
This is only set on reinitiated tasks (the task ID of the previous task that is being reinitiated). |
|
|
This only set on a subtask. This refers to the version of the parent task. |
|
|
The logical name of the participant as modeled from Oracle JDeveloper. |
|
|
The reviewers of the task. This can be a user, group, or application role. |
|
|
The ID of the root task. This is the same as the task ID for the root task. |
|
|
The stage name that is being executed. |
|
|
The current state of the task instance. |
|
|
The current substate of the task. |
|
|
A unique ID that is set on a subtask. This same ID is set on the parent task's |
|
|
The system actions (such as reassign, escalate, and so on) that can be performed on a task. |
|
|
The name of the task component that defines this task instance. |
|
|
This only sets a subtask. This is the ID of the immediate parent task. |
|
|
A unique ID that is set on the parent task. This same ID is set on the subtask's |
|
|
The unique ID of the task. |
|
|
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. |
|
|
An integer number that uniquely identifies this task instance. |
|
|
The user who last updated the task. |
|
|
The date this instance was last updated. |
|
|
The version of the task. |
|
|
The reason the version was created. |
|
|
The pattern that is being executed (for example, parallel, serial, FYI, or single). |
Table 30-20 lists the flex field attributes.
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:
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for instructions on configuring notification service delivery channels in Oracle Enterprise Manager Fusion Middleware Control Console
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 27.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 30-2 demonstrates the use of hwf:getNotificationProperty and hwf:getTaskResourceBundle together:
Example 30-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
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.
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:
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite
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.
To configure the notification channel preferences:
In Oracle JDeveloper, configure the notification service for email and other channels. See Chapter 17, "Using the Notification Service" for details.
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 26.3.10.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 26.3.10.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:
Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for details about configuring the notification channel
Section 26.3.10, "How to Specify Participant Notification Preferences" to configure task notifications in the Human Task Editor
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.
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.
Only the email channel is configured for sending notification messages.
NONE
No channel is configured for sending notification messages. This is the default setting.
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:
Use one of the following methods to internationalize messages in the notification content:
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')
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 26.3.8.2, "Specifying Multilingual Settings."
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. |
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:
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.
To send task attachments with the notification message, select Send task attachments with email notifications.
When an actionable email arrives, perform the following tasks.
Click the Approve link to invoke a new email window with approval data. Figure 30-3 provides details.
Add comments in the comments section of the approval mail. For example:
This contract has been approved based on the attached information.
Add attachments as needed, as shown in Figure 30-4.
Figure 30-4 Attachment to an Actionable Email
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.
Click Send.
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.
In the Workflow Notification Properties page of Oracle Enterprise Manager Fusion Middleware Control Console, set the notification mode to ALL or EMAIL.
In the Workflow Task Service Properties page of Oracle Enterprise Manager Fusion Middleware Control Console, set the actionable email account name.
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:
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 26.3.10.6, "Making Email Messages Actionable."
To send inbound comments:
Add comments in the actionable email reply between Comments[[' and ']]. Those contents are added as task comments. For example, Comments[[looks good]].
To send secure notifications:
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 26.3.10.5, "Securing Notifications to Exclude Details."
To set channels used for notifications:
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.
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:
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 26.3.10.3, "Setting Up Reminders."
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 30.5.2, "Global Resource Bundle – WorkflowLabels.properties."
Example 30-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.
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:
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:
This section describes how to configure the assignment service with dynamic assignment 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 30-21 describes the three dynamic assignment functions.
Table 30-21 Dynamic Assignment Functions
| Function | Type | Description |
|---|---|---|
|
|
Dynamic assignment |
Picks the user or group with the least number of tasks currently assigned to it. |
|
|
Task escalation |
Picks the manager's manager. |
|
|
Dynamic assignment |
Picks the user or group that has completed the most tasks over a certain time period (by default, the last seven days). |
|
|
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.
Follow these procedures to implement your own dynamic assignment function.
To implement dynamic assignment functions:
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
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.
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.
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:
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 class path 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
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).
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, 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:
A client initiates an expense approval task whose routing is determined by the assignment service.
The assignment service determines that the task assignee is jcooper.
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.
jstein approves the task and the assignment service indicates that there are no more users to which to assign the task.
To implement an assignment service:
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).
|
Notes:
|
You can implement your own assignment service plug-in that the human workflow service invokes during human workflow execution.
Example 30-4 provides a sample IAssignmentService implementation named TestAssignmentService.java.
Example 30-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 implements. The implementation of the IAssignmentService
is called by the workflow service
PRIVATE CLASSES
<list of private classes defined - with one-line descriptions>
NOTES
<other useful comments, qualifications, etc.>
MODIFIED (MM/DD/YY)
*/
/**
* @version $Header: IAssignmentService.java 29-jun-2004.21:10:35 Exp
$
*
*
*/
package oracle.bpel.services.workflow.test.workflow;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import oracle.bpel.services.workflow.metadata.routingslip.model.*;
import oracle.bpel.services.workflow.metadata.routingslip.model.Participants;
import oracle.bpel.services.workflow.metadata.routingslip.model.ParticipantsType.*;
import oracle.bpel.services.workflow.task.IAssignmentService;
import oracle.bpel.services.workflow.task.ITaskAssignee;
import oracle.bpel.services.workflow.task.model.Task;
public class TestAssignmentService implements
oracle.bpel.services.workflow.task.IAssignmentService {
static int numberOfApprovals = 0;
static String[] users = new String[]{"jstein", "wfaulk", "cdickens"};
public Participants onInitiation(Task task,
Map propertyBag) {
return createParticipant();
}
public Participants onReinitiation(Task task,
Map propertyBag) {
return null;
}
public Participants onOutcomeUpdated(Task task,
Map propertyBag,
String updatedBy,
String outcome) {
return createParticipant();
}
public Participants onAssignmentSkipped(Task task,
Map propertyBag) {
return null;
}
public List getAssigneesToRequestForInformation(Task task,
Map propertyBag) {
List rfiUsers = new ArrayList();
rfiUsers.add("jcooper");
rfiUsers.add("jstein");
rfiUsers.add("wfaulk");
rfiUsers.add("cdickens");
return rfiUsers;
}
public List getReapprovalAssignees(Task task,
Map propertyBag,
ITaskAssignee infoRequestedAssignee) {
List reapprovalUsers = new ArrayList();
reapprovalUsers.add("jstein");
reapprovalUsers.add("wfaulk");
reapprovalUsers.add("cdickens");
return reapprovalUsers;
}
private Participants createParticipant() {
if (numberOfApprovals > 2) {
numberOfApprovals = 0;
return null;
}
String user = users[numberOfApprovals++];
ObjectFactory objFactory = new ObjectFactory();
Participants participants = objFactory.createParticipants();
Participant participant = objFactory.createParticipantsTypeParticipant();
participant.setName("Loan Agent");
ResourceType resource2 = objFactory.createResourceType(user);
resource2.setIsGroup(false);
resource2.setType("STATIC");
participant.getResource().add(resource2);
participants.getParticipantOrSequentialParticipantOrAdhoc().
add(participant);
return participants;
}
}
To deploy a custom assignment service:
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:
|
The custom escalation function enables you to integrate a custom rule in a human workflow.
To implement a custom escalation function:
Create a custom task escalation function and register this with the human workflow service that uses that function in task definitions.
Use the Advanced Settings section of the Human Task Editor to integrate the rule in a human workflow.
For more information, see Section 26.3.9.6, "Specifying Escalation Rules."
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.
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.
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 30.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.
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
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.
The ADF task flow applications and associated data controls that get created to display the details of a particular task type use the resource bundle oracle.bpel.services.workflow.worklist.resource.worklist to store their resource strings.
You can provide your own custom resource strings for a task detail ADF task flow by adding a customized resource bundle in the task flow application.
You can localize the XML element name displayed in the task flow form through this resource bundle. You can add keys, and use them in the task flow form contents section. The input text label looks as follows:
#{resources.mykeyword}
A copy of the WorkflowLabels.properties resource bundle is available in the sample workflow-110-workflowCustomizations. This sample illustrates in detail how to provide your own customized resource strings for the task detail ADF task flow application.
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:
Log in to Oracle Enterprise Manager Fusion Middleware Control Console.
In the navigator, expand the SOA folder.
Right-click soa-infra, and select Administration > System Mbean Browser.
The System MBean Browser displays on the right side of the page.
Expand Application Defined MBeans > oracle.as.soainfra.config > Server: server_name > WorkflowIdentityConfig > human-workflow > WorkflowIdentityConfig.PropertyType.
Click caseSensitive.
Click the Operations tab.
Click setValue.
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.
This section describes how human workflow clients integrate with Oracle WebLogic Server services.
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 30-5 provides details.
Example 30-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>
Example 30-6 provides an example of the task query service client code.
Example 30-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);
}
}
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 class path, then the property map is the main source of configuration.
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 30-7. The configuration defines a server named default. The XML file must go into the client application's EAR file.
Example 30-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>
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 30-8:
Example 30-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 starts a new transaction)
};
|
Note: If you use the properties map, you do not need to specifyIWorkflowServiceClientConstants.CONNECTION_PROPERTY.MODE. This property has been deprecated in this release. |
Example 30-9 provides an example for remote Enterprise JavaBeans clients.
Example 30-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 30-10 provides an example for a SOAP client.
Example 30-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);
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 30-11 shows how to pass a logger to the workflow service clients:
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.
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.
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.
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 30.6.1.2.2, "Workflow Client Configuration in the Property Map."
IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_PRINCIPAL
IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_SECURITY_CREDENTIALS
Identity propagation only works if the application is deployed under the Oracle WebLogic Server container and secured with container security or the client is secured with a custom JAAS login module.
End users log in to the client application with the correct user name and password. The users using the client application must be available in the identity store used by the SOA application. As a best practice, configure the client to use the same identity store as the workflow services and Oracle SOA Suite are using. This guarantees that if the user exists on the client side, they also exist on the server side.
For information about configuring the identity store, see Oracle Fusion Middleware Security Guide.
For information about interacting with custom identity stores, visit the following URL:
http://www.oracle.com/technology/products/id_mgmt/opss/index.html
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.
To enable identity propagation, the client configuration must specify a special propagation mode.
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 30-12 shows the SAML token dynamic client.
Example 30-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.
In the configuration file, you can define the propagation mode by using the <identityPropagation> element in the <soapClient>, as shown in Example 30-13.
Example 30-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.
A client application without identity propagation must have the bpm-services.jar file in its class path. For 11g Release 1, the client class path requires the 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.
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
This section describes database views that enable queries against the Oracle workflow services schema to receive reports. Table 30-22 lists the reports exposed in Oracle BPM Worklist and the database views corresponding to these reports.
Table 30-22 Report Views
| Existing Worklist Report | Corresponding Database View |
|---|---|
|
Unattended Tasks report |
|
|
Task Cycle Time report |
|
|
Task Productivity report |
|
|
Task Priority Report |
|
Table 30-23 describes the WFUNATTENDEDTASKS_VIEW report view.
Table 30-23 Unattended Tasks Report View
| Name | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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;
Table 30-24 describes the WFTASKCYCLETIME_VIEW report view.
Table 30-24 Task Cycle Time Report View
| Name | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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;
Table 30-25 describes the WFPRODUCTIVITY_VIEW report view.
Table 30-25 Task Productivity Report View
| Name | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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;
Table 30-26 describes the WFTASKPRIORITY_VIEW report view.
Table 30-26 Task Priority Report View
| Name | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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;
|
 Copyright © 2005, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|