20 Managing Worklists

This chapter describes how to configure and manage worklists for WebCenter Portal and Portal Framework applications.

Always use Fusion Middleware Control or WLST command-line tool to review and configure back-end servers for WebCenter Portal and Portal Framework applications. Any changes that you make to WebCenter Portal and Portal Framework applications, post deployment, are stored in MDS metatdata store as customizations. See Section 1.3.5, "Oracle WebCenter Portal Configuration Considerations."

Note:

Changes that you make worklist configuration, through Fusion Middleware Control or using WLST, are not dynamic, so you must restart the managed server on which WebCenter Portal is deployed for your changes to take effect. See Section 7.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments."

This chapter includes the following topics:

• Section 20.1, "Configuration Roadmaps for Worklist"

• Section 20.2, "About BPEL Connections"

• Section 20.3, "BPEL Server Prerequisites"

• Section 20.4, "Setting Up Worklist Connections"

• Section 20.5, "Specifying the BPEL Server Hosting WebCenter Portal Workflows"

• Section 20.6, "Configuring WebCenter Portal Workflow Notifications to be Sent by Email"

• Section 20.7, "Troubleshooting Issues with Worklists"

Permissions:

To perform the tasks in this chapter, you must be granted the WebLogic Server Admin role through the Oracle WebLogic Server Administration Console and the Administrator role in the deployed application:

• WebCenter Portal: Administrator role granted through Portal Builder Administration.

• Portal Framework application: Administrator role granted through the Administration Console.

For more information about roles and permissions, see Section 1.8, "Understanding Administrative Operations, Roles, and Tools."

20.1 Configuration Roadmaps for Worklist

Use the roadmaps in this section as a system administrator's guide through the configuration process:

• Section 20.1.1, "Roadmap - Configuring Worklist for WebCenter Portal"

• Section 20.1.2, "Roadmap - Configuring Worklist for Portal Framework Applications"

20.1.1 Roadmap - Configuring Worklist for WebCenter Portal

Figure 20-1 and Table 20-1 in this section provide an overview of the prerequisites and tasks required to use worklist in WebCenter Portal.

Figure 20-1 Configuring Worklist for WebCenter Portal

Description of ''Figure 20-1 Configuring Worklist for WebCenter Portal''

Table 20-1 Configuring Worklist for WebCenter Portal

Actor	Task	Sub-Task
Administrator	1. Install WebCenter Portal and the Oracle SOA Suite	To ensure the connection between WebCenter Portal and the BPEL server, make sure to do the following steps: Install the Oracle SOA Suite. Extend the SOA server domain with the oracle.wc_composite_template_11.1.1.jar template. For more information, see Back-End Requirements For WebCenter Portal Workflows.
Administrator	2. Configure a worklist connection using one of the following tools:Foot 1  Fusion Middleware Control (see Registering Worklist Connections Using Fusion Middleware Control) WLST (see Registering Worklist Connections Using WLST)	When using Fusion Middleware Control: 2.a Create Worklist connection 2.b Make Worklist connection 'active' When using WLST: 2.a Run createBPELconnection 2.b Run addWorklistConnection
Administrator	3. Configure WebCenter Portal workflowsFootref 1	3.a Specify the BPEL server connection used for WebCenter Portal workflows using either of the following tools: Fusion Middleware Control WLST (setSpacesWorkflowConnectionName) 3.b Configure WS-security keystore If you are not using the WebCenter Portal workflows to send group invitations to join a portal, then the security configuration is optional for worklists in an unsecured SAML environment. Group membership invitations require the SOA server to invoke a secured WebCenter Web service on the WebCenter Server when a user accepts the group invitation to join a portal. For more information, see Chapter 36, "Configuring WS-Security."
Administrator	4. (Optional) Deploy additional BPEL workflows
Administrator	5. (Optional) Configure BPEL server to use same identity store as WebCenter PortalFootref 1
Administrator	6. (Optional) Secure the connection to the BPEL server	6.a Configure single sign-on 6.b Configure WS-Security 6.c Configure SSL
End User	7. Test that worklist is working in WebCenter Portal	7.a Log in to WebCenter Portal 7.b Add a Worklist task flow to a page (see the "Adding a Worklist Task Flow to a Page" section in Building Portals with Oracle WebCenter Portal. 7.c Generate a worklist event (see the "About Worklists" section in Building Portals with Oracle WebCenter Portal. 7.d Verify event information displays in the task flow

^Footnote 1 Auto configured out-of-the-box

See Also:

Section 20.6, "Configuring WebCenter Portal Workflow Notifications to be Sent by Email" for steps to configure email notifications for your workflows.

20.1.2 Roadmap - Configuring Worklist for Portal Framework Applications

Figure 20-2 and Table 20-2 in this section provide an overview of the prerequisites and tasks required to use worklist in Portal Framework applications.

Figure 20-2 Configuring Worklist for Portal Framework Applications

Description of ''Figure 20-2 Configuring Worklist for Portal Framework Applications''

Table 20-2 Configuring Worklists for Portal Framework Applications

Actor	Task	Sub-Task
Administrator	1. Install WebCenter Portal and the Oracle SOA Suite
Developer	2. Integrate worklist in your Portal Framework application	2.a Create a Worklist connection 2.b Add the Worklist task flow to a page in JDeveloper
Developer/Administrator	3. Deploy the Portal Framework application using one of the following tools: JDeveloper (Developer) Fusion Middleware Control (Administrator) WLST (Administrator) WLS Admin Console (Administrator)
Administrator	4. Deploy additional BPEL workflows
Administrator	5. (Optional): Configure BPEL server to use same identity store as the application
Administrator	6. (Optional): Secure the connection to the BPEL server	6.a Configure single sign-on 6.b Configure WS-Security 6.c Configure SSL
Developer/Administrator	7. (Optional): Add/modify connection parameters using one of the following tools: JDeveloper, then redeploy the application (Developer) Fusion Middleware Control (Administrator) WLST (Administrator)
End User	8. Test that worklist is working	8.a Log in to the Portal Framework application 8.b Generate a worklist event 8.c Verify event information displays in the task flow

20.2 About BPEL Connections

Consider the following while working with BPEL connections:

• Worklists allows multiple connections so that WebCenter Portal users can monitor and manage assignments and notifications from a range of BPEL servers. For more information, see Section 20.4, "Setting Up Worklist Connections."

• WebCenter Portal workflows require a single connection to the BPEL server included with the Oracle SOA Suite. For more information, see Section 20.5, "Specifying the BPEL Server Hosting WebCenter Portal Workflows."

• Worklists and the WebCenter Portal workflows can share the same BPEL server connection or each connect to different BPEL servers. To enable the display of worklist items created by the workflows in the current worklist of WebCenter Portal worklists, it is recommended that the WebCenter Portal workflows and worklist share a connection.

• Worklists can be wired to multiple BPEL connections to enable aggregation of worklist items from multiple BPEL servers. For example, when the topology contains several BPEL servers running various workflow types, such as Human Resource and General Ledger servers.

• It is mandated that the BPEL connections are unique URLs. If this is not the case, then duplicate queries to the same server are created.

20.3 BPEL Server Prerequisites

Consider the following to ensure smooth functioning of worklists:

• Pages that include Worklist task flows must be secured through ADF security.

• Worklists must be configured to use an Oracle SOA Suite BPEL server that is accessible through the BPEL Worklists application. The URL is in the following format:

  http://host:port/integration/worklistapp
  

  If worklists is not running in the same domain as the Oracle SOA Suite BPEL server, then the identity store (LDAP) should be either shared (recommended) or contain identical user names.

• Clocks on the worklist's managed server and the Oracle SOA Suite BPEL's managed server must be synchronized such that the SAML authentication condition, NotBefore, which checks the freshness of the assertion, is not breached.

• No configuration-related exceptions must exist. Use the WLST command listWorklistConnections to display the configured connections and validate the connection details. After listing the connections, validate them using the URL property appended with /integration/worklistapp. Hence, verify that http://host:port/integration/worklistapp can access the BPEL Worklist application.

• If the Oracle SOA Suite BPEL's managed server is configured to use an identity store and that store does not contain BPMWorkflowAdmin, weblogic by default, then the BPMWorkflowAdmin user must be configured, as described in Section 20.7.2.2, "Shared User Directory Does Not Include the weblogic User."

• The wsm-pm application must be running on both worklists and Oracle SOA Suite's BPEL server's managed servers without any issues. This can be validated through the URL:

  http://host:port/wsm-pm/validator
  

For information on how to resolve BPEL server issues, see Section 20.7, "Troubleshooting Issues with Worklists."

This section includes the following subsections:

• Section 20.3.1, "BPEL Server - Installation and Configuration"

• Section 20.3.2, "BPEL Server - Security Considerations"

• Section 20.3.3, "BPEL Server - Limitations in WebCenter Portal"

20.3.1 BPEL Server - Installation and Configuration

Worklists relies on the Oracle BPEL Process Manager (BPEL) server, which is included with Oracle SOA Suite.

To work with worklist, you must install Oracle SOA Suite. For information about how to install Oracle SOA Suite, see the Installation Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

After installing Oracle SOA Suite, you can integrate worklists into WebCenter Portal by setting up connections to the BPEL server.

20.3.2 BPEL Server - Security Considerations

Worklists display tasks for the currently authenticated user. For portal users to store and retrieve tasks on an Oracle SOA Suite BPEL server, their user names must either exist in a shared user directory (LDAP), or be set up similarly on both the BPEL Server and the portal application (WebCenter Portal or your own Portal Framework application).

For example, if the user rsmith wants to use worklist to store and retrieve tasks from the BPEL server, you must ensure that the user rsmith exists on both the BPEL server and within WebCenter Portal.

To access BPEL task details from the WebCenter Portal worklist component, without incurring additional login prompts, WebCenter Portal and Oracle SOA Suite servers must be configured to a shared Oracle Single Sign-On server. For more information, see Section 33.2, "Configuring Oracle Access Manager (OAM)" and Section 33.3, "Configuring Oracle Single Sign-On (OSSO)."

For a secure connection you can optionally configure WS-Security between SOA and WebCenter Portal. For information, see Chapter 36, "Configuring WS-Security."

20.3.3 BPEL Server - Limitations in WebCenter Portal

Worklist task flows function inside authenticated pages only. If Worklist task flows are placed on unsecured pages, that is public pages that are not navigated to from an application on which the user has logged in, the warning message "You must log in to view Worklist content" is displayed. This is done to ensure that a session for the current users is available to determine which user's tasks are to be queried.

20.4 Setting Up Worklist Connections

This section includes the following subsections:

• Section 20.4.1, "About Worklist Connections"

• Section 20.4.2, "Registering Worklist Connections"

• Section 20.4.3, "Activating a Worklist Connection"

• Section 20.4.4, "Modifying Worklist Connection Details"

• Section 20.4.5, "Deleting Worklist Connections"

20.4.1 About Worklist Connections

Worklists enables WebCenter Portal or your ownPortal Framework applications to show authenticated users a list of BPEL worklist items currently assigned to them. BPEL worklist items are open BPEL tasks from one or more BPEL worklist repositories.

A connection to every BPEL server that delivers worklist items is required. Multiple worklist connections are allowed so that WebCenter Portal users can monitor and manage assignments and notifications from a range of BPEL servers.

If a BPEL server cannot be contacted, then the Worklist task flow indicates that the connection is unavailable and any reason for the error is recorded in the server's diagnostic log. This log is located on the server that hosts the worklist component's log directory. For example:

./user_projects/domains/base_domain/servers/WC_CustomPortal/logs/WC_CustomPortal-diagnostic.log.

For a Portal Framework application: ./user_projects/domains/base_domain/servers/WC_CustomPortal/logs/WC_CustomPortal-diagnostic.log.

Note that these examples are for a domain named base_domain, which is the default, but can be defined differently during domain creation.

WebCenter Portal requires a BPEL server connection to support its internal workflows, that is, membership notifications and portal subscription requests. For more information, see Section 20.5, "Specifying the BPEL Server Hosting WebCenter Portal Workflows."

Worklists can share the SOA instance connection and by doing so, display worklist items relating to portal activity in the Worklist task flow of each user.

20.4.2 Registering Worklist Connections

This section includes the following subsections:

• Section 20.4.2.1, "Registering Worklist Connections Using Fusion Middleware Control"

• Section 20.4.2.2, "Registering Worklist Connections Using WLST"

20.4.2.1 Registering Worklist Connections Using Fusion Middleware Control

To register a Worklist connection:

1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal or the Portal Framework application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Portal"

   • Section 6.3, "Navigating to the Home Page for Portal Framework Applications"

2. Do one of the following:

   • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

   • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

3. On the WebCenter Portal Service Configuration page, select Worklist.

4. To register a new connection, click Add (Figure 20-3).

   Figure 20-3 Configuring Worklist Connections

   
   Description of ''Figure 20-3 Configuring Worklist Connections''
   
   

5. Enter a unique name for the Worklist connection and set it as the active connection (Table 20-3). This connection is picked up after you restart the managed server.

   Table 20-3 Worklist Connection - Name

   Field	Description
   Connection Name	Enter a unique name for the connection. The name must be unique (across all connection types) within WebCenter Portal. This name may be displayed to users working with the worklist feature in WebCenter Portal. Users may organize their worklist assignments through various sorting and grouping options. The option "Group By Worklist Server" displays the name you specify here so it's important to enter a meaningful name that other users will easily recognize, for example, Human Resources.
   Active Connection	Select to activate this worklist connection in WebCenter Portal. Once activated, worklist items from the associated BPEL server display in users' worklists. Multiple worklist connections may be active at a time, enabling WebCenter Portal users to monitor and manage assignments and notifications from a range of BPEL servers. If you need to disable a connection for any reason, deselect this option. (Edit mode only.) Check boxes indicate whether other components share this connection: Worklist Indicates whether the worklist displays items associated with this connection. Spaces Application Indicates whether WebCenter Portal uses the same BPEL server connection for internal workflows, such as membership notifications, subscription requests, and more. The BPEL server that provides this functionality is the BPEL server included with the Oracle SOA Suite. For more information, see Section 20.5, "Specifying the BPEL Server Hosting WebCenter Portal Workflows." Although not shown here, the notifications might be set up to use the BPEL server connection too. See Section 19.3, "Setting Up Notifications." Before modifying connection properties, consider the impact to any other components that share this connection.

   
   

6. Enter connection details for the BPEL server (Table 20-4).

   Table 20-4 Worklist Connection - Connection Details

   Field	Description
   BPEL Soap URL	Enter the URL required to access the BPEL server. Use the format: protocol://host:port For example: http://mybpelserver.com:8001 Note: WebCenter Portal uses the BPEL server included with the Oracle SOA Suite to implement WebCenter Portal workflows. If you are setting up the workflow connection, make sure you enter the SOA Suite's BPEL server URL here. For more information, see Section 20.5, "Specifying the BPEL Server Hosting WebCenter Portal Workflows."
   SAML Token Policy URI	Select the SAML (Security Assertion Markup Language) token policy this connection uses for authentication. SAML is an XML-based standard for passing security tokens defining authentication and authorization rights. An attesting entity (that has a trusted relationship with the receiver) vouches for the verification of the subject by method called sender-vouches.Options available are: SAML Token Client Policy (oracle/wss10_saml_token_client_policy) - Select to verify your basic configuration without any additional security. This is the default setting. SAML Token With Message Protection Client Policy (oracle/wss10_saml_token_with_message_protection_client_policy) - Select to increase the security using SAML-based BPEL Web Services. If selected, you must configure keys stores both in WebCenter Portal and in the BPEL application. For information, see Chapter 36, "Configuring WS-Security." Global Policy Attachment - Select this option when your environment supports Global Policy Attachment.
   Recipient Key Alias	The recipient key alias to be used for message protected SAML policy authentication. Required only when the BPEL server connection is using a SAML token policy for authentication and WebCenter Portal's worklist is using multiple BPEL server connections. For example, myKey To determine the recipient key alias for a complex topology, see Section 36.3, "Configuring WS-Security for a Complex Topology."
   Link URL	Specify the URL used to link to the BPEL server. Required only if it is different to the BPEL SOAP URL, for example, when SSO or HTTPS is configured. Use the format: protocol://host:port For example, http://mySSO.host.com:7777 For performance reasons, in an HTTPS or SSO environment, the Link URL specifies user access to BPEL worklist items, through HTTPS or SSO Web servers, whereas the BPEL SOAP URL specifies direct access to BPEL Web services, without redirection through HTTPS or SSO Web servers.

   
   

7. Click OK to save this connection.

8. Click Test to verify if the connection you created works.

   For a successful connection, the Test Status message displays the advice that to start using the new (active) connection, you must restart the managed server on which the WebCenter Portal is deployed. For more information, see Section 7.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments."

   See Section 20.7, "Troubleshooting Issues with Worklists" if the test fails.

   Tip:

   To activate newly registered connections, perform the steps described in Section 20.4.3, "Activating a Worklist Connection."

20.4.2.2 Registering Worklist Connections Using WLST

Use the WLST command createBPELConnection to create a BPEL server connection. For command syntax and examples, see the "createBPELConnection" section in the WebLogic Scripting Tool Command Reference.

To configure a worklist to actively use a new BPEL server connection, some additional configuration is required. For more information, see Section 20.4.3.2, "Activating a Worklist Connections Using WLST."

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Note:

To activate newly registered connections, perform the steps described in Section 20.4.3, "Activating a Worklist Connection."

To start using the new (active) connection you must restart the managed server on which WebCenter Portal is deployed. For more information, see the "Starting and Stopping Managed Servers Using the Command Line" section in the Administrator's Guide.

20.4.3 Activating a Worklist Connection

In WebCenter Portal and Portal Framework applications, multiple Worklist connections may be active at a time. Multiple connections enable WebCenter Portal users to monitor and manage assignments and notifications from a multiple BPEL servers. From time to time you may need to temporarily disable an active connection so no errors or warnings are logged or displayed in the user interface, if the worklist queries a SOA server which is undergoing maintenance.

This section includes the following subsections:

• Section 20.4.3.1, "Activating a Worklist Connections Using Fusion Middleware Control"

• Section 20.4.3.2, "Activating a Worklist Connections Using WLST"

20.4.3.1 Activating a Worklist Connections Using Fusion Middleware Control

To activate or disable a Worklist connection:

1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal or the Portal Framework application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Portal"

   • Section 6.3, "Navigating to the Home Page for Portal Framework Applications"

2. Do one of the following:

   • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

   • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

3. On the WebCenter Portal Services Configuration page, select Worklist.

   The Manage Worklist Connections table indicates currently active connections (if any).

4. Select the Worklist connection you want to activate (or disable), and then click Edit.

5. Select the Worklist check box to activate this Worklist connection in the WebCenter Portal.

   Once activated, worklist items from the associated BPEL server display in Worklist task flows. If you need to disable a connection for any reason, deselect this option.

6. Click OK to update the connection.

7. Click Test to verify if the connection you activated works.

   For a successfully activated connection, the Test Status message displays the advice that to start using the updated connection, you must restart the managed server on which WebCenter Portal is deployed. For more information, see Section 7.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments."

20.4.3.2 Activating a Worklist Connections Using WLST

Use the WLST command addWorklistConnection to activate an existing BPEL connection for worklists. For command syntax and examples, see the "addWorklistConnection" section in the WebLogic Scripting Tool Command Reference.

To subsequently disable a BPEL connection used by worklists, run the WLST command removeWorklistConnection. Connection details are retained but the connection is no longer named as an active connection. For syntax details and examples, see the "removeWorklistConnection" section in the WebLogic Scripting Tool Command Reference.

Use listWorklistConnections to see which connections are currently active.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Note:

To start using the active connection you must restart the managed server on which WebCenter Portal is deployed. For more information, see the "Starting and Stopping Managed Servers Using the Command Line" section in the Administrator's Guide.

20.4.4 Modifying Worklist Connection Details

This section includes the following subsections:

• Section 20.4.4.1, "Modifying Worklist Connection Details Using Fusion Middleware Control"

• Section 20.4.4.2, "Modifying Worklist Connection Details Using WLST"

20.4.4.1 Modifying Worklist Connection Details Using Fusion Middleware Control

To update worklist connection details:

1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal or the Portal Framework application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Portal"

   • Section 6.3, "Navigating to the Home Page for Portal Framework Applications"

2. Do one of the following:

   • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

   • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

3. On the WebCenter Portal Services Configuration page, select Worklist.

4. Select the Worklist connection you want to activate, and then click Edit.

5. Edit connection details, as required.

   For detailed parameter information, see Table 20-4, "Worklist Connection - Connection Details"

6. Click OK to update the connection.

7. Click Test to verify if the updated connection works.

   For a successfully updated connection, the Test Status message displays the advice that to start using the updated connection, you must restart the managed server on which the WebCenter Portal is deployed. For more information, see Section 7.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments."

20.4.4.2 Modifying Worklist Connection Details Using WLST

Use the WLST command setBPELConnection to edit existing BPEL server connection details. For command syntax and examples, see the "setBPELConnection" section in the WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Note:

To start using the updated (active) connection you must restart the managed server on which WebCenter Portal is deployed. For more information, see the "Starting and Stopping Managed Servers Using the Command Line" section in the Administrator's Guide.

20.4.5 Deleting Worklist Connections

Several WebCenter Portal components can share the same worklist connection, that is, worklists, notifications, and workflows. Before you delete a worklist connection, navigate to the Application Configuration page in Fusion Middleware Control (WebCenter Portal > Settings > Application Configuration) to verify whether workflows and notifications are using the connection.

This section includes the following subsections:

• Section 20.4.5.1, "Deleting Worklist Connections Using Fusion Middleware Control"

• Section 20.4.5.2, "Deleting Worklist Connections Using WLST"

20.4.5.1 Deleting Worklist Connections Using Fusion Middleware Control

To delete a worklist connection:

1. Log in to Fusion Middleware Control and navigate to the home page for WebCenter Portal or the Portal Framework application. For more information, see:

   • Section 6.2, "Navigating to the Home Page for WebCenter Portal"

   • Section 6.3, "Navigating to the Home Page for Portal Framework Applications"

2. Do one of the following:

   • For WebCenter Portal - From the WebCenter Portal menu, select Settings > Service Configuration.

   • For Portal Framework applications - From the Application Deployment menu, select WebCenter Portal > Service Configuration.

3. On the WebCenter Portal Services Configuration page, select Worklist.

4. Select the Worklist connection you want to delete, and then click Delete.

5. To confirm, click Yes.

6. To effect this change you must restart the managed server on which the application is deployed. For more information, see Section 7.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments."

20.4.5.2 Deleting Worklist Connections Using WLST

Use the WLST command deleteConnection to remove a BPEL connection previously registered for worklist. For command syntax and examples, see the "deleteConnection" section in the WebLogic Scripting Tool Command Reference.

Use the WLST command removeWorklistConnection remove a BPEL server that is configured in adf-config.xml. Worklist no longer uses the connection specified but BPEL server connection details are retained in connections.xml for future use.

Use the WLST command deleteConnection to remove a BPEL server connection from connections.xml.

For command syntax and detailed examples, see the "removeWorklistConnection" and the "deleteConnection" sections in the WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

Restart the managed server so that the changes can take place.

20.5 Specifying the BPEL Server Hosting WebCenter Portal Workflows

WebCenter Portal uses the BPEL server included with the Oracle SOA Suite to host internal workflows, such as portal membership notifications, portal subscription requests, and so on. To enable workflow functionality inside the WebCenter Portal application, a connection to this BPEL server is required.

Note:

WebCenter Portal workflows must be deployed on the SOA managed server that WebCenter Portal is configured to use. See also, the "Back-End Requirements for WebCenter Portal Workflows" chapter in Installation Guide for Oracle WebCenter Portal.

To configure a connection to WebCenter Portal workflows:

1. Login to Fusion Middleware Control, and navigate to the home page for WebCenter Portal.

   See Section 6.2, "Navigating to the Home Page for WebCenter Portal."

2. From the WebCenter Portal menu, select Settings > Application Configuration.

   Figure 20-4 Choosing the BPEL Server Where WebCenter Portal Workflows are Deployed

   
   Description of ''Figure 20-4 Choosing the BPEL Server Where WebCenter Portal Workflows are Deployed''
   
   

3. From the Connection Name drop-down list, select the name of the connection you require.

   The connections on offer are those currently configured for the Worklist service in WebCenter Portal.

   Make sure that you select the connection that points to the SOA instance in which WebCenter Portal workflows are deployed. If that connection is not listed, you must create it. To define the connection, see Section 20.4, "Setting Up Worklist Connections."

4. Click Apply.

5. Restart WC_Spaces, the managed server on which the WebCenter Portal application is deployed, to effect this change.

   See Section 7.2, "Starting and Stopping Managed Servers for WebCenter Portal Application Deployments."

20.6 Configuring WebCenter Portal Workflow Notifications to be Sent by Email

WebCenter Portal provides human workflows (requiring human interaction), which are integrated with SOA workflows. The SOA server can configure email so that notifications are delivered to a user's inbox, where the user can accept or reject the notification.

This section describes how to enable email notifications and configure your mail server details to have WebCenter Portal workflow notifications sent to users by email.

1. Use Fusion Middleware Control to update SOA to enable email notifications. Under the SOA server, select SOA Administration, then Workflow Config, as shown in Figure 20-5.

   Figure 20-5 SOA Administration - Workflow Config

   
   Description of ''Figure 20-5 SOA Administration - Workflow Config''
   
   

2. With Email selected as the Notification Mode, provide valid email accounts to use, (Figure 20-6).

   Figure 20-6 Email Notification Mode Properties

   
   Description of ''Figure 20-6 Email Notification Mode Properties''
   
   

3. Click Go to the Messaging Driver page (Figure 20-6).

4. Select the Configure Driver icon for your User Messaging Email Driver (Figure 20-7).

   Figure 20-7 Associated Drivers

   
   Description of ''Figure 20-7 Associated Drivers''
   
   

5. On the Configuration page for the email driver, do the following:

   • Under Common Configuration, enter your Default Sender Address. For Supported Protocols and MailAccessProtocol, enter IMAP (Figure 20-8).

     Figure 20-8 Configuration Page for the Email Driver

     
     Description of ''Figure 20-8 Configuration Page for the Email Driver''
     
     

   • Under Driver-Specific Configuration, enter your email connection details, such as host, port, SSL, and incoming users/passwords, as shown in Figure 20-9 and Figure 20-10.

     Figure 20-9 Driver-Specific Configuration

     
     Description of ''Figure 20-9 Driver-Specific Configuration''
     
     

     Figure 20-10 Driver-Specific Configuration, Continued

     
     Description of ''Figure 20-10 Driver-Specific Configuration, Continued''
     
     

     See Also:

     "Configuring Oracle User Messaging Service" in Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for detailed information about driver properties and UMS configuration

6. Save the configuration updates and restart the SOA managed server. (No configuration or restart is required for WebCenter Portal.)

   When a user is invited to join a portal, they are sent an email including Accept or Reject links to the invitation.

   (Optional) You can validate that your configuration is correct by sending a sample email from Fusion Middleware Control.

7. From the Community Workflows, select Human Workflow (Figure 20-11)

   Figure 20-11 Human Workflow

   
   Description of ''Figure 20-11 Human Workflow''
   
   

   The Human Workflow Engine home page appears (Figure 20-12).

8. Review the email addresses in the Notification Management tab.

   The Notification Management tab provides options to view bad email addresses and resend notifications

   Figure 20-12 Human Workflow Engine Home

   
   Description of ''Figure 20-12 Human Workflow Engine Home''
   
   

9. Click Send Test Notification to verify your configuration.

10. Click Send (Figure 20-13).

    Figure 20-13 Test Notification

    
    Description of ''Figure 20-13 Test Notification''
    
    

    After sending the test notification, confirm that the email is received.

    Note:

    There are four workflows that generate an email where users can act upon the notification via email. In the portal administration settings Members page, you can add people and edit email notification messages. For more information, see the "Managing Members and Assigning Roles" section in Administering Oracle WebCenter Portal.

20.7 Troubleshooting Issues with Worklists

Worklists relies on several middleware components to display worklist items to logged-in users and therefore, several factors may cause worklists to fail. The issues and solutions discussed in this section relate to some common problems you may encounter.

See Also:

Appendix G, "Troubleshooting Oracle WebCenter Portal"

This section includes the following subsections:

• Section 20.7.1, "Unavailability of Worklists Due to Application Configuration Issues"

• Section 20.7.2, "Unavailability of Worklists Due to Server Failure"

• Section 20.7.3, "Email Notifications Not Working"

Note:

To identify causes of failures, examine log files on the managed servers hosting worklist processes and the managed servers for any SOA BPEL servers you have configured.

20.7.1 Unavailability of Worklists Due to Application Configuration Issues

Issues described in this section pertain to the unavailability of worklist—Worklist task flows display the message The Worklist service is unavailable with the following warning:

Either no BPEL connections are configured, or there is an issue with the existing connection configuration. Verify that at least one BPEL Worklist connection is configured for this application, and that no unresolved "ConfigurationExceptions" exceptions are logged.

This section includes the following subsections:

• Section 20.7.1.1, "adf-config.xml Refers to a Non-Existent BPEL Connection"

• Section 20.7.1.2, "adf-config.xml Has No Reference to a BPEL Connection"

• Section 20.7.1.3, "No Rows Yet Message Displays"

20.7.1.1 adf-config.xml Refers to a Non-Existent BPEL Connection

Problem

The connection listed in the adf-config.xml file does not exist in the application's connections.xml file. The following entries exist in the diagnostic log file for the managed server on which the application is running:

[2009-03-22T13:33:54.140+00:00] [DefaultServer] [WARNING] [WCS-32008] [oracle.webcenter.worklist.config][tid: [ACTIVE].ExecuteThread: '12' for queue: 'weblogic.kernel.Default (self-tuning)'] userId: user][ ecid: 0000I0iOmdTFk3FLN2o2ye19kTB0000V,0][APP: Worklist#V2.0 arg: Human Resources The BPEL Connection named 'connection_name' was not present in the connections.xml file. This will prevent the Worklist service from being able to interact with the required this BPEL connection.

Solution

Either create a BPEL connection with the name stated in the log, or remove the connection. For more information about how to update the worklist configuration post deployment, see Section 20.4, "Setting Up Worklist Connections."

During development, see the "Integrating Worklists" section in Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

To find out which connections names are referenced and to validate the worklist configuration, run the WLST command, listWorklistConnections(appName='myApp', verbose=true). For more information, see the "listWorklistConnections" section in WebLogic Scripting Tool Command Reference.

20.7.1.2 adf-config.xml Has No Reference to a BPEL Connection

There is no reference to a worklist connection in the application's adf-config.xml, but this connection exists in the connections.xml file.

Problem

In diagnostic log files for the managed server on which the application is running, you see entries such as the following:

[2009-03-23T10:23:56.943+00:00] [DefaultServer] [WARNING] [WCS-32009] [oracle.webcenter.worklist.config] [tid: [ACTIVE].ExecuteThread: '21' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: user] [ecid: 0000I0mqx8Fk3FLN2o2ye19lqBV000008,0] [APP: Worklist#V2.0] The Worklist service does not have a ConnectionName configuration entry in adf-config.xml that maps to a BPELConnection in connections.xml, therefore the Worklist service was not configured for this application.

Solution

Configure a connection to at least one BPEL server so that the worklist can query worklist items.

Post deployment, create Worklist connections through WLST or Fusion Middleware Control. For information, see Section 20.4.2, "Registering Worklist Connections." During development, create Worklist connections through Oracle JDeveloper. For information, see the "Integrating Worklists" section in Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper. Do not modify adf-config.xml and connections.xml files manually.

20.7.1.3 No Rows Yet Message Displays

Problem

The Worklist task flow continues to display the No Rows Yet message.

Solution

The following are possible solutions to address this problem:

• No 'Assigned' worklist items exist for the logged in user:

  If worklist items are assigned to the logged-in user and the state of these items is Assigned, then they always show in the Worklist task flow. The No Rows Yet message indicates that no assigned Worklist items exist for the logged-in user. This is not an issue, but expected behavior.

  To confirm that this message is displaying correct information, open the Oracle SOA Suite BPEL Worklist application, and check whether any worklist items exist. The URL of BPEL Worklist application is: http://host:port/integration/worklistapp. Where host and port are the same as those used in the Worklist connection.

• The ADF page on which the Worklist task flow exists is not ADF-secured:

  The Worklist task flow is not able to query the Worklist repository, because there is no authenticated user associated with the application session to access the Oracle SOA Suite BPEL server. Apply the ADF security on the page. For information, see the "Setting Security for Worklists" section in Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

20.7.2 Unavailability of Worklists Due to Server Failure

Server failure is the likely cause of an issue if a worklist connection exists, and the Worklist task flow shows the The Worklist service is unavailable warning. In case of multiple connections, the More items not currently available message displays. These generic warning messages display when there is an issue with worklist interactions with the Oracle SOA Suite BPEL repository.

To identify the root cause of the issue, examine the managed server's diagnostic logs at the time when it fails. In some cases, it is necessary to also examine the log files of the managed server on which the Oracle SOA Suite BPEL processes run. Typically, an entry such as the following exists in diagnostic logs of the worklist application's managed server:

[2009-03-23T11:35:21.735+00:00] [DefaultServer] [ERROR] [WCS-32100] [oracle.webcenter.worklist.model] [tid: [ACTIVE].ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: user] [ecid: 0000I0n7GBZFk3FLN2o2ye19lrBX00000L,0] [APP: Worklist#V2.0] [arg: WebCenter Worklist] The WebCenter Worklist has queried the BPEL Worklist connection named 'WebCenter Worklist', and encountered a WebCenter Executor error. Please see related exception for details. If the WebCenter Worklist is running in an Application Server, check to see if the wsm-pm application is up and running.

This states that there is an issue with the wsm-pm application that is used for WS security. There can also be some other causes related to the exception. It is recommended that you examine the logged exceptions on both the WebCenter managed server and the configured Oracle SOA suites managed servers when these issues occur.

This section includes the following sub sections:

• Section 20.7.2.1, "Users Mismatch in Identity Stores"

• Section 20.7.2.2, "Shared User Directory Does Not Include the weblogic User"

• Section 20.7.2.3, "Issues with the wsm-pm Application"

• Section 20.7.2.4, "Clocks are Out of Sync for More Than Five Minutes"

• Section 20.7.2.5, "Worklist Timed Out or is Disabled"

20.7.2.1 Users Mismatch in Identity Stores

Mismatch in identity stores used by the managed server on which the Worklist task flow is running and that of the Oracle SOA Suite BPEL server.

Problem

If a user exists in the worklist managed server's identity store but not in the Oracle SOA Suite's identity store, then the following messages display:

In the diagnostic logs of the worklist's managed server:

[2009-03-23T11:35:21.407+00:00] [DefaultServer] [ERROR] []
[oracle.webcenter.worklist.config] [tid: pool-1-daemon-thread-12] [userId: Luke]
[ecid: 0000I0n7GBZFk3FLN2o2ye19lrBX00000L,0:1:3] [APP: Worklist#V2.0] Error in
workflow service Web service operation invocation.[[
Error in workflow service Web service operation invocation. The error is .
Verify that the SOAP connection information for the server is correct.
 ORABPEL-30044
Error in workflow service Web service operation invocation.
Error in workflow service Web service operation invocation. The error is .
Verify that the SOAP connection information for the server is correct.
    at
oracle.bpel.services.workflow.query.client.TaskQueryServiceSOAPClient.convertSOAPF
aultException(TaskQueryServiceSOAPClient.java:242)
    at
oracle.bpel.services.workflow.query.client.TaskQueryServiceSOAPClient.invoke(TaskQ
ueryServiceSOAPClient.java:203)
    at
oracle.bpel.services.workflow.query.client.TaskQueryServiceSOAPClient.authenticate
(TaskQueryServiceSOAPClient.java:253)
    at
oracle.bpel.services.workflow.query.client.AbstractDOMTaskQueryServiceClient.authe
nticate(AbstractDOMTaskQueryServiceClient.java:164)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at
sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
    at
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
    at java.lang.reflect.Method.invoke(Method.java:597)
    at oracle.webcenter.concurrent.MethodTask.call(MethodTask.java:34)
    at oracle.webcenter.concurrent.Submission$2.run(Submission.java:492)
    at java.security.AccessController.doPrivileged(Native Method)
    at oracle.security.jps.util.JpsSubject.doAsPrivileged(JpsSubject.java:313)
    at oracle.webcenter.concurrent.Submission.runAsPrivileged(Submission.java:499)
    at oracle.webcenter.concurrent.Submission.run(Submission.java:433)
    at
oracle.webcenter.concurrent.Submission$SubmissionFutureTask.run(Submission.java:779)
    at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:441)
    at java.util.concurrent.FutureTask$Sync.innerRun(FutureTask.java:303)
    at java.util.concurrent.FutureTask.run(FutureTask.java:138)
    at
oracle.webcenter.concurrent.ModifiedThreadPoolExecutor$Worker.runTask(ModifiedThre
adPoolExecutor.java:657)
    at
oracle.webcenter.concurrent.ModifiedThreadPoolExecutor$Worker.run(ModifiedThreadPo
olExecutor.java:682)
    at java.lang.Thread.run(Thread.java:619)
]]
[2009-03-23T11:35:21.735+00:00] [DefaultServer] [NOTIFICATION] []
[oracle.webcenter.worklist.config] [tid: pool-1-daemon-thread-15] [userId: Luke]
[ecid: 0000I0n7GBZFk3FLN2o2ye19lrBX00000L,0:1:6] [APP: Worklist#V2.0]
TaskServiceSOAPClient: soapFault:[[
<env:Fault
xmlns:ns0="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-sece
xt-1.0.xsd"xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <faultcode>ns0:FailedAuthentication</faultcode>
   <faultstring>FailedAuthentication : The security token cannot be authenticated
or authorized.</faultstring>
   <faultactor/>
</env:Fault>
]]

In the diagnostic logs of the Oracle SOA Suite's managed server:

[2009-03-23T04:52:07.909-07:00] [soa_server1] [ERROR] [WSM-00008] [oracle.wsm.resources.security] [tid: [ACTIVE].ExecuteThread: '2' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: <anonymous>] [ecid: 0000I0nB64fFk3FLN2o2ye19lrBX00000O,0:1:3:1] [WEBSERVICE_PORT.name: TaskQueryServicePortSAML] [APP: soa-infra] [J2EE_MODULE.name: /integration/services/TaskQueryService] [WEBSERVICE.name: TaskQueryService] [J2EE_APP.name: soa-infra] Web service authentication failed.

Solution

The same users must exist in identity stores of both managed servers. For information, see the "Setting Security for Worklists" section in Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

This can be easily accomplished with a common LDAP identity store. A useful check is to validate that you can log in to the Oracle SOA Suite's BPEL worklist application with the user ID for which the worklist is unavailable. That is, try accessing the integration worklist application at: http://host:port/integration/worklistapp. Where the host and port are the same as those used in the worklist connection for the task flow application.

20.7.2.2 Shared User Directory Does Not Include the weblogic User

Problem

BPEL Web services cannot respond to requests received from the worklist because the shared user directory does not include the weblogic user.

Solution

Ensure that you have tried the solution provided in Users Mismatch in Identity Stores. If that solution did not resolve the issue, then try the solution described in this section.

If Oracle SOA Suite is connected to a shared user directory (LDAP), and the user weblogic does not exist in the identity store, then the following step assigns the BPMWorkflowAdmin role to a valid user in the identity store. Use WLST to revoke an application role from SOAAdmin and grant it to a member of the external identity store. This can be done by running the following WLST command from the SOA_ORACLE_HOME. For example:

cd SOA_ORACLE_HOME/common/bin/
wlst.sh
connect('weblogic','weblogic', '## soa host ##:## soa administration port ##')
revokeAppRole(appStripe="soa-infra", appRoleName="BPMWorkflowAdmin",
     principalClass="oracle.security.jps.service.policystore.ApplicationRole", principalName="SOAAdmin")
grantAppRole(appStripe="soa-infra", appRoleName="BPMWorkflowAdmin",
     principalClass="weblogic.security.principal.WLSUserImpl", principalName="user")

In this example, the LDAP identity store has a user named user. If the user to which you want to grant the BPMWorkflowAdmin role does not exist in the LDAP identity store, then you must restart the Oracle SOA Suite's managed server to make this change effective.

20.7.2.3 Issues with the wsm-pm Application

Problem

Issue with the wsm-pm application on either the worklist's managed server, or the Oracle SOA Suite's managed server, or on both.

Solution

The wsm-pm application manages the Web service security policies that control the SAML authentication in the worklist. To validate the wsm-pm application, log in to the wsm-pm application's validation page as a user with administrative rights. Use this format for validation: http://host:port/wsm-pm/validator. If there are no issues with this application, then accessible policies must display. If policies do not display, then investigate the related logged information on the server whose wsm-pm application is failing.

20.7.2.4 Clocks are Out of Sync for More Than Five Minutes

Due to security reasons, the Web service security interaction between the worklist's managed server and that of the Oracle SOA Suite BPEL must take place with a time difference of less than five minutes. That is, the clocks on both host machines must have a time difference of less than five minutes, otherwise authentication fails. The SAML assertion uses the NotBefore condition to verify this.

Problem

Clocks of the worklist's managed server and the Oracle SOA Suite BPEL's managed server are out of sync for more than five minutes.

Solution

Ensure that the current time is not set to earlier than the SAML assertion's clockskew, which is 300 seconds by default.

Either match the time on the machines, or configure the agent.clock.skew property (in seconds) in the policy-accessor-config.xml file. This file is located in the DOMAIN_HOME/config/fmwconfig directory.

20.7.2.5 Worklist Timed Out or is Disabled

Problem

The worklist cannot obtain a query result from the Oracle SOA Suite BPEL server within a defined period.

The worklist issues queries to the Oracle SOA Suite BPEL server using concurrent threads. These threads are allotted a certain amount of time in which to respond. If these threads do not respond in the allotted time, for example 15 seconds, then the worklist times out the call, and it allows the task flow to display the unavailability message. In such a case, log files include related exceptions such as the following:

[2009-03-03T12:09:34.769-08:00] [WLS_Spaces] [ERROR] [WCS-32103]
[oracle.webcenter.worklist.model] [tid: [ACTIVE].ExecuteThread: '3' for queue:
'weblogic.kernel.Default (self-tuning)'] [userId: user] [ecid:
0000HzDx68KC0zT6uBbAEH19fOWs00002q,0] [APP: webcenter] Unable to query BPEL repository.[[
oracle.webcenter.concurrent.TimeoutException: Execution timedout
      queued :     1 ms
   suspended :     0 ms
     running : 15389 ms
     timeout : 15000 ms
     service : Worklist
    resource : ir
      source : oracle.webcenter.concurrent.CallableTask@bf3952
(oracle.webcenter.concurrent.CallableTask)
  submission : 150
        at
oracle.webcenter.concurrent.Submission.transitionTo(Submission.java:595)
        at oracle.webcenter.concurrent.Submission.timeout(Submission.java:634)
        at
oracle.webcenter.concurrent.InternalExecutorService.checkForTimeouts(InternalExecutorService.java:566)
        at
oracle.webcenter.concurrent.InternalExecutorService.access$300(InternalExecutorService.java:18)
        at
oracle.webcenter.concurrent.InternalExecutorService$1.run(InternalExecutorService.java:352)
        at java.util.TimerThread.mainLoop(Timer.java:512)
        at java.util.TimerThread.run(Timer.java:462)]]

Solution

If errors such as this occur consistently, then there may be fundamental issues with the resources available to the managed servers running the worklist and the Oracle SOA Suite BPEL server.

Validate that the volume of users and resources provided is adequate to run these servers in the infrastructure provided.

If you are unable to improve the SOA server's performance, then increase the timeout threshold using the Enterprise Manager System MBean Browser (adding a new timeout for the "Worklist").

For details, see the "Configuring Concurrency Management" section in the Performance Tuning Guide.

Note:

Continuous occurrence of TimeoutExceptions can also disable the worklist. Due to which it cannot connect to the BPEL instance that is failing to respond quickly. In such a case, the logs contain oracle.webcenter.concurrent.DisabledException exceptions. These exceptions are related to the worklist failure.

20.7.3 Email Notifications Not Working

Problem

Notifications for workflows are not being sent by email, as described in Section 20.6, "Configuring WebCenter Portal Workflow Notifications to be Sent by Email."

Solution

Check the error logs on the WebCenter and SOA servers for errors at the time when the invite process is instigated. If there appears to be an issue with the email configuration, then validate that you can use the exact same LDAP settings and user accounts to send and receive emails using a different email client.