22 Managing Human Workflow Service Components and Engines

This chapter describes how to manage human task service components and the human workflow service engine, including managing policies, recovering from workflow faults, managing the task details application URI, managing outgoing and incoming email notifications, and moving workflow data from test to production environments.

22.1 Managing Human Task Service Component Policies

You can attach and detach security policies to and from human task service components of currently deployed SOA composite applications. Policies apply security to the delivery of messages. Oracle Fusion Middleware uses a policy-based model to manage web services.

Human tasks have a port that is protected by default using the SAML policy oracle/wss10_saml_token_service_policy. Oracle recommends that you not use this policy in a production environment.

To manage human task service component policies:

Access this page through one of the following options:

From the SOA Infrastructure Menu...

From the SOA Folder in the Navigator...

Select Home.

Select the Deployed Composites tab.

In the Composite section, select a specific SOA composite application.

Under soa-infra, select a specific SOA composite application.

Select the human task service component in the Component Metrics table.

Click Policies.

The Policies page enables you to attach and detach security policies to and from a human task service component. The policies table displays the attached policy name, the policy reference status (enabled or disabled) that you can toggle, the category (Management, Reliable Messaging, MTOM Attachment, Security, or WS Addressing), the total violations, and the authentication, authorization, confidentiality, and integrity failures since the SOA Infrastructure was last restarted.

22.2 Recovering from Human Workflow Service Engine Faults

You can view and recover from faults in the human workflow service engine. All human task service component faults, regardless of the SOA composite application instance of which they are a part, can be viewed in the human workflow service engine.

Human workflow invocations from the BPEL service engine use different transactions than BPEL processes. Therefore, if a BPEL transaction is rolled back for any reason, the workflow task instances are still created.

To view and recover from human workflow service engine faults:

Access this page through one of the following options:

From the SOA Infrastructure Menu...

From the SOA Folder in the Navigator...

Select Service Engines > Human Workflow.

Right-click soa-infra.

Select Service Engines > Human Workflow.

Click Faults.

The Faults page displays the following details:

A utility for searching for a specific fault by specifying criteria and clicking Search. Click the Help icon for details.

Faults that occurred in the human workflow service engine, including the fault ID, error message, whether you can recover from the fault, the time at which the fault occurred, the SOA composite application and human task service component in which the fault occurred, the instance ID of the human task service component, and a link to a log file describing the fault.

Human task service engine faults identified as recoverable can be recovered from Oracle BPM Worklist.

Perform fault recovery through either of the following methods:

In the Error Message column, click a specific message to display complete fault details, including the fault ID, fault time, fault location, fault type, and error message text. If the fault is recoverable, a Recover Now button is displayed that you can click to recover from the fault. Clicking this button invokes the human workflow audit trail page for the instance. The audit trail page has a link to Oracle BPM Worklist called Go to Worklist Application, where you can go to recover from the fault. The Oracle BPM Worklist link does not take you directly to the fault; you must manually locate the fault.

In the Recovery column, click a fault that is marked as recoverable to invoke the human workflow audit trail page for the instance. The audit trail page provides the same link to Oracle BPM Worklist called Go to Worklist Application.

Perform the following additional monitoring tasks from within the faults table:

Click the Show only recoverable faults checkbox to display only faults from which you can recover.

From the Fault Type list, select to display all faults, system faults, business faults, or Oracle Web Services Manager (OWSM) faults in the faults table. Click the Help icon for a description of these fault types.

From the View list, select Columns > Fault ID to display the fault IDs for each error message. The fault ID is automatically generated and uniquely identifies a fault. The fault ID is also displayed when you click an error message.

In the Composite column, click a specific SOA composite application to access its home page.

In the Component column, click a specific service component to access its home page.

In the Component Instance ID column, click a specific service component ID to access task details about the instance (for example, the current state of a task). Rejected messages do not have a component instance ID.

In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

22.3 Managing the URI of the Human Task Service Component Task Details Application

You can add or remove the URI of the task details application used in human workflow.

To manage the URI of the human task service component task details application:

Access this page through one of the following options:

From the SOA Infrastructure Menu...

From the SOA Folder in the Navigator...

Select Home.

Select the Deployed Composites tab.

In the Composite section, select a specific SOA composite application.

Under soa-infra, select a specific SOA composite application.

Select the human task service component in the Component Metrics table.

Click Administration.

The Administration page shows the URI for the task details application.

If the SOA server is SSL enabled or disabled, then you must manually enable or disable SSL for any already deployed workflow task detail applications. Change the workflow task display URL to use the correct protocol and port number. To enable the use of the SSL (HTTPS) URL, ensure that the HTTP port setting is left blank.

Click the Add icon to specify the following details for the URI:

Application name

Hostname

HTTP port

HTTPS port (optional)

URI

Click Apply.

22.4 Recovering from Human Task Service Component Faults

You can view and recover from human task service component faults. The human task service component is also known as the human workflow service component.

To view and recover from human task service component faults:

Access this page through one of the following options:

From the SOA Infrastructure Menu...

From the SOA Folder in the Navigator...

Select Home.

Select the Deployed Composites tab.

In the Composite section, select a specific SOA composite application.

Under soa-infra, select a specific SOA composite application.

Select the human task service component in the Component Metrics table.

Click Faults.

The Faults page displays the following details:

A utility for searching for a specific human task service component fault by specifying criteria and clicking Search. Click the Help icon for details.

Faults that occurred in the human task service component, including the fault ID, error message, whether you can recover from the fault, the time at which the fault occurred, the instance ID of the human task service component, and a link to a log file describing the fault.

Human workflow service engine faults identified as recoverable can be recovered from Oracle BPM Worklist.

Perform fault recovery through either of the following methods:

In the Error Message column, click a specific message to display complete fault details, including the fault ID, fault time, fault location, fault type, and error message text. If the fault is recoverable, a Recover Now button is displayed that you can click to recover from the fault. Clicking this button invokes the human workflow audit trail page for the instance. The audit trail page has a link to Oracle BPM Worklist called Go to Worklist Application, where you can go to recover from the fault. The Oracle BPM Worklist link does not take you directly to the fault; you must manually locate the fault.

In the Recovery column, click a fault that is marked as recoverable to invoke the human workflow audit trail page for the instance. The audit trail page provides the same link to Oracle BPM Worklist called Go to Worklist Application.

Perform the following additional monitoring tasks from within the faults table:

Click the Show only recoverable faults checkbox to display only faults from which you can recover.

From the Fault Type list, select to display all faults, system faults, business faults, or OWSM faults in the faults table. Click the Help icon for a description of these fault types.

From the View list, select Columns > Fault ID to display the fault IDs for each error message. The fault ID is automatically generated and uniquely identifies a fault. The fault ID is also displayed when you click an error message.

In the Component Instance ID column, click a specific service component ID to access task details about the instance (for example, the current state of a task). Rejected messages do not have a component instance ID.

In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

22.5 Managing Outgoing Notifications and Incoming Email Notifications

You can manage incoming and outgoing notifications through email in human workflow, including testing messages, resending messages, and identifying messages as spam.

Incoming and outgoing notifications are sent to and from human workflow. Incoming notifications are responses to actionable notifications. For example, an outgoing notification is sent to the manager of an employee requesting vacation leave. The manager approves the request by clicking the Approve link in the actionable notification email. This action sends an incoming notification to human workflow for possible additional processing.

To manage outgoing notifications and incoming email notifications:

Access this page through one of the following options:

From the SOA Infrastructure Menu...

From the SOA Folder in the Navigator...

Select Service Engines > Human Workflow.

Right-click soa-infra.

Select Service Engines > Human Workflow.

Click Notification Management.

The upper part of the Notification Management page displays the following details:

A utility for searching for a specific message by specifying criteria and clicking Search. You must expand the Search icon to display this utility.

Outgoing notifications, including the source ID, the source type (for example, if a notification is sent by a BPEL service component, the type is BPEL), the channel used (for example, email, SMS, instant messenger, or voice), the address of the message recipient, the message status (for example, error, send, retry, sent), and the time at which the message was sent.

The lower part of the Notification Management page displays the following details:

A utility for searching for a specific message by specifying criteria and clicking Search. You must expand the Search icon to display this utility.

Incoming notifications, including the message ID, the channel used (same types as for outgoing notifications), the address of the message sender, the address of the message recipient, the message status (replied email notification, unsolicited email, unknown email content, response not processed, and response processed), a link to the content of the message, and the time at which the message was received.

Test that outgoing messages are arriving at the correct destination. This ensures that the destination is reachable and messages are arriving. Selecting this option invokes a dialog for specifying the following destination details:

Destination address

Delivery channel (for example, email)

Message subject and content

Note: You cannot send test notification messages with the messaging extension driver because it requires the following:

Specific data to be manually entered into the test page (such as the URI of the task details)

URI-specific headers (such as time, user, and so on)

Resend

Select specific outgoing notification messages in the table and click Resend to resend. Use this option if you believe that messages are not arriving at their correct destination. For example, you may have incorrectly configured a recipient address. After correcting the address, click Resend to test the delivery.

Resend All Similar Notifications

Resend all error notification messages having the same recipient address as the selected one.

View Bad Addresses

Click to display a list of bad or invalid addresses. The addresses are automatically removed from the bad address list after one hour. If you do not want to wait an hour, you can explicitly select and delete them.

Delete icon

Click to delete a selected message.

If outgoing notifications are sent to an incorrect address of a message recipient, they are displayed as errors in the Recipient column. You can correct the recipient's address and resend the notification.

In the Recipient column, click the email address and correct the address.

Perform the following actions on incoming notifications.

Action

Description

Mark as Spam

Mark the message sender's address of the selected notification as spam. This action prevents incoming notifications from the same sender address from being delivered again.

No Spam

Mark incoming messages as not being spam. This action enables new messages from the sender's address to be delivered again.

22.6 Moving Human Workflow Data from a Test to a Production Environment

You can migrate Human Workflow user metadata, such as views, mapped attribute (previously known as flex field) mappings, and vacation rules, from a test environment to a production environment using the Human Workflow User Config Data Migrator. The Data Migrator is available as an ant target that can be executed at the command line. You specify the input parameters for the migration of data in a properties file, migration.properties.

A production server to which you want to move the data on SOAServer_A.

Since you have a significant amount of data on SOAServer_A, it can be time consuming to manually migrate all of the data to SOAServer_B.You can use the Data Migrator to move the data from the test server to the production server. You run the ant target at the command line of SOAServer_A to migrate data to SOAServer_B.Migration is always performed through an XML file. The Data Migrator supports the following operations:

Export operation: Stores all the human workflow user-configurable data from the source SOA server to the XML file.

Import operation: Creates all the human workflow user-configurable data in the target SOA server by reading from the XML file.

22.6.1 Moving Human Workflow Data from Test to Production Environments

Perform the following steps to move data from a test to a production environment.

To move human workflow data from test to production environments:

Ensure that the PATH environment variable contains the JAVA_HOME and ANT_HOME environment variables and that they point to the locations within the Oracle SOA Suite installation.

Create a migration.properties file in any location to export user metadata for the worklist application (for example, group rules, views, mapped attribute mappings, and vacation rules) from the test environment. See Section 22.6.2.1, "Migration Property File Examples" for instructions on how to specify properties.

Note the following:

You can export mapped attribute mappings.

You can export attribute labels.

You can only export one type of data at a time.

When you export data for a particular user or group, you must export each in separate operations.

You must export attribute labels before you export mapped attribute mappings.

To export attribute labels, use the following values in the migration.properties file:

Human workflow artifacts such as task mapped attribute mappings, rules, views, and approval groups are defined based on namespace. The Data Migrator migrates human workflow artifacts based on namespace. Therefore, it is not possible to migrate human workflow artifacts based on a partition.

Create the migration.properties file to import user metadata for the worklist application to the production environment.

Note the following:

You can only import one type of data at a time.

When you import data for a particular user or group, you must import it in separate operations.

You must import attribute labels before you import mapped attribute mappings.

To import attribute labels, use the following values in the migration.properties file:

Import the data to the production environment from the file export_all_userRules.xml, which you created with the map.file property in Step 3. The following example shows how to invoke the command and specify the properties:

The following example imports task payload mapped attribute mappings for all task definition IDs. Task payload mapped attribute mappings use attribute labels. As a prerequisite, find out the attribute labels involved in the task payload mapped attribute mappings to import. These attribute labels must be available in the target SOA server before the import of task payload mapped attribute mappings into the target SOA server.

The following example imports task payload mapped attribute mappings for a specific task definition ID. Task payload mapped attribute mappings make use of attribute labels. As a prerequisite, find out the attribute labels that are involved in the task payload mapped attribute mappings to import. These attribute labels must be available in the target SOA server before the import of task payload mapped attribute mappings into the target SOA server.