Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 5 (11.1.5)

Part Number E15524-10
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

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

38 Managing Tasks from an Oracle ADF Application

This chapter describes what your ADF application needs to do to assign tasks to users or groups.

When to implement: When your ADF application needs to assign tasks to users or groups.

Design Pattern Summary: An ADF task flow in a web application contains a page where a user action invokes an ADF Business Components object that performs some logic. Because of this user action, a task must be assigned to another user. For example, an employee uses an ADF web application to submit an expense report. The page used to create the expense report is within an ADF task flow. When the expense report is submitted, a task needs to be raised to the employee's manager so that he or she can approve or reject the expense report. To make this happen, when the ADF Business Components object is invoked, it invokes a BPEL process service component that uses a human task service component to assign the task to the manager. Once the human task service component is invoked, the manager uses the Worklist application to complete the task, in this case the approval or rejection of the expense report. The Worklist application also uses an ADF task flow to present those pages to the manager.

This design pattern uses BPEL so as to enable orchestration after the task is submitted.

Involved components:

Note:

BPEL is not a requirement for working with human tasks. However, BPEL is used when orchestrating tasks after the end-user submits the human task, for example to approve or reject forms filled out by the end-user.

Instead of using the worklist application, you could use a custom task application or APIs.

38.1 Introduction to the Recommended Pattern

Oracle Fusion applications may need to assign users tasks that they need to complete. The application needs to notify users of assigned tasks, then provide a way for them to complete the tasks. The SOA composite project may include a BPEL process that assigns tasks to users as part of the process flow. The human workflow service can be used to accomplish this. The workflow component also includes an out of the box worklist application displaying all the tasks assigned to a particular user or group. You can use the ADF task flow to create UI pages listing pending tasks. These are displayed upon logging in to the worklist application.

To develop this pattern, an ADF application can invoke an SOA composite application, as described in Chapter 32, "Initiating a SOA Composite from an Oracle ADF Web Application." A human task service component can be included in the composite that assigns tasks to users or roles. This component includes a task editor used to design the metadata for the task, an ADF task flow for creating task forms for the human interaction, and the out-of-the-box Worklist application for users to access tasks and act on them. The Worklist application can use an ADF task flow to manage the pages needed to complete the tasks.

This pattern is recommended for the following reasons:

Figure 38-1 shows the recommended pattern.

Figure 38-1 Recommended Pattern

ADF BC invokes BPEL flow and Human Workflow

This chapter explains how to implement the recommended pattern.

38.2 Other Approaches

There are no other supported approaches to this use case.

38.3 Example

Following is an example that illustrates the design pattern.

An Expense application contains an ADF task flow used to create an expense report and submit it for approval. When the user submits the expense report, a BPEL process service component is invoked that contains a human task service component, which assigns the task of approving expense report to the user's supervisor. The human task service component notifies the supervisor that an expense report needs to be approved. When the supervisor logs into the Worklist application, he sees notification of an expense report that requires approval. The Worklist application contains an ADF task flow that allows the supervisor to either approve or reject the expense report.

The sample code for this use case can be downloaded from Oracle SOA Suite samples.

38.4 How to Manage a Human Task Flow from an ADF Application

There are three high-level steps needed to invoke a human task flow from an ADF web application:

  1. Create and deploy the ADF web application that contains the UI necessary to invoke the SOA composite that contains the human work flow.

  2. Create the SOA composite that contains a mediator, BPEL process service component, and human task component that will assign the task to the user.

  3. Create the ADF task flow based on the human task component. This will provide the UI necessary for the user to resolve the task.

These procedures are detailed in the remainder of this section.

To invoke a human work flow from an ADF application:

  1. Create an ADF application that contains a page that will raise an event, as described in Section 32.4, "How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application".

  2. Create an SOA composite application component that includes a mediator service component, along with a BPEL process service component that the mediator service component invokes when the ADF Business Components event is raised. Follow the procedures as documented in Section 32.4, "How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application".

  3. In the SOA composite application, create a human task service component that uses the payload of the message received from the mediator service component to provide any parameters needed to create the task in the workflow.

    For detailed procedures on creating a human task service, see the chapter "Designing Human Tasks" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

    When creating the human task service, note the following:

    • The task will require details about the assignee, task parameters, and so on. However, you do not need to capture the entire object used to create the task in the task parameters. You only need to include enough information to make the assignment decision and to then query the object using the service interfaces for the ADF Business Components application module.

      For example, in the expense report sample application, you might create parameters for the expense report number, the "submitted by" value, and optionally the amount. This would be the only information needed to dynamically assign the task to the submitter's manager.

    • You can assign tasks statically or dynamically. Make sure that any user to whom the task is assigned is seeded in the identity management store (for more information, see Section 38.6, "Securing the Design Pattern").

    • You should model any email or other notifications as part of the task metadata. For example, you may want to model an email to the supervisor when the task is assigned to them and an email to the initiator when the task is completed. For more information about notifying users of changes to task status, see the chapter "Designing Human Tasks" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

  4. In the BPEL process, add a human task activity and wire it to the human task service component. In the human task activity, specify which BPEL variables map to the data required for the task.

    Once you create the human task activity, a switch statement is automatically inserted that contains various branches based on the previously specified outcome of the human task. Based on how the outcome impacts the specific use case, additional business logic should be inserted inside the branches.

    For example, in the expense report example, you might include a branch that calls the ADF Business Components object to update the state of the expense report to Approved. This can be done by exposing the ADF Business Components application module as a service and then invoking it from BPEL as a SOAP service. For more information, see Chapter 35, "Manipulating Back-End Data from a SOA Composite."

  5. Create an ADF task flow based on the human task service component. This will be the flow used in the worklist application that displays the pages the user views to complete the task.

    For detailed procedures, see the chapter "Designing Human Tasks" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

    Note the following:

    • When creating the task flow, select the .task file created in Step 3. This automatically generates a task data control that can access the task parameters and perform actions on the task such as Approve and Reject.

    • On the JSP pages, use the drop handlers on the task data control to insert sections such as Task Header, Comments and Attachments, Approval History, and so on.

    • Use the ADF Business Components data control to pull in any transactional data, such as line items. You can use the object id (available in task parameters) in the query API for the ADF Business Components.

    • Drag and drop any custom actions (for example, approve or reject) on the form. You can also include system actions (for example, escalate, reassign, delegate) on the form.

    • Note that by default, the first page in the task flow is sent in email notifications. The buttons on the page are replaced with ReplyTo links for actions such as Approve and Reject, allowing the user to approve or reject the object in the task from the email. You can also model a different page for email approval.

  6. Deploy the SOA composite and the ADF task flow for the human task service to the standalone WLS where the SOA infrastructure has been installed.

    Deploy the task from the application menu and the SOA composite from the project menu.

38.5 Other Approaches

You can deploy the human task flow to a remote server without SOA infrastructure.

For more information, see the section "How To Deploy a Task Display Form to a non-SOA Oracle WebLogic Server" in the chapter "Designing Task Forms for Human Tasks" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

38.6 Securing the Design Pattern

Note:

In order to use the ADF Security Wizard, developers must start up JDeveloper with a role profile that supports JAAS-XS security, such as the Oracle CRM Application Developer Role. To deploy an SOA composite to a WLS container, the application deployer must start up JDeveloper using the default role.

The human task service uses Java platform security (JPS) for accessing user/role profile information. JPS supports multiple providers, such as XML and XS.

The default authentication provider in Oracle WebLogic Server is WLSAuthenticator, while the authorization provider is based on the JPS policy store.

The default security configuration uses the Oracle WebLogic Server embedded LDAP as the identity store and system-jazn-data.xml as the policy store. This configuration is held in the workflow-identity-config.xml file, as shown in Example 38-1.

Example 38-1 Identity Service Configuration

<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig" >
  <configurations>
    <configuration realmName="jazn.com">
      <provider providerType="JPS" name="JpsProvider" service="Identity">
        <property name="jpsContextName" value="default" />
      </provider>
    </configuration>
  </configurations>
</ISConfiguration>

Fore more information regarding configuring or updating the human workflow Identity Service, see the section "Configuring the Identity Service" in the chapter "Configuring Human Workflow Service Components and Engines" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

For more information, see the chapter "Configuring the OPSS Security Store" in the Oracle Fusion Middleware Application Security Guide.

Note:

As other applications plan to use XS database as a repository, XML-based providers must synchronize with the XS database whenever changes occur to user or role related data.

38.7 Verifying the Deployment

To properly verify this design pattern, you should test and deploy your ADF application, deploy the SOA composite application and the ADF task from for the Worklist application, and then run the ADF application.

To verify this design pattern:

  1. Test your Oracle ADF web application using the various testing and debugging methods described in the chapter "Testing and Debugging ADF Components" of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition). Be sure to enable the ADF Business Components runtime logging by setting the Java VM parameter jbo.debugoutput=console. Doing so logs the event and its payload in the JDeveloper log console.

  2. Use Oracle Enterprise Manager Fusion Middleware Control Console to view the SOA composite application and ensure it was properly deployed. For more information about using Fusion Middleware Control Console, see the chapter "Deploying SOA Composite Applications" of the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

  3. Run the ADF application and invoke the method that raises the event.

    Alternatively, you can use the Composite initiate page in Enterprise Manager to send a test message to the BPEL process service component. Note that this bypasses the mediator service component and directly calls the BPEL process service component which in turn invokes the human task service component.

    The web service ending point for each of the services in the composite is

    http://HOST_NAME:PORT/fabric/application name/composite_name/service_name
    

    For example:

    http://localhost:8888/fabric/OrderBookingApp/OrderProcessing/Client
    
  4. View the ADF Business Components runtime log to view the event and payload. For more information about the log, see the chapter "Testing and Debugging ADF Components" of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

  5. Use Oracle Enterprise Manager Fusion Middleware Control Console to check if an instance of the SOA composite application has been created. The process should be in running state and waiting at the human task step.

    For more information about Fusion Middleware Control Console, see the chapter "Deploying SOA Composite Applications" of the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

  6. Log in to the worklist application to view the task created for the supervisor. The worklist application is located at http://hostname/integration/worklistapp/

    Click Approve or Reject to complete this task.

    If successful, the status of the task will be updated on the home page the Worklist application.

  7. In Fusion Middleware Control Console, check that the human task has completed. This ensures that the waiting BPEL process can proceed with the subsequent steps.

38.8 Troubleshooting the Use Case

Following are tips that may help resolve common issues that arise when developing or running this use case.

38.8.1 Worklist Notification Locale Does Not Honor the Regional Applications Session Setting

When logging into the worklist application, both the worklist and human task details honor the regional setting in the Applications Core session. However, the notification locale does not honor the regional setting of the Applications Core session.

Notifications cannot consider the Applications Core sessions of the worklist application.

Consider a task being assigned to user jcooper. The user jcooper may not be logged into the worklist at the time, but notifications must be sent to jcooper when the task is assigned.

To do so, implement oracle.bpel.services.workflow.task.INotificationCallback. You can add print statements to the implementation and verify the values that are returned.

38.8.2 Task Does Not Display in Worklist Application

If you are not able to find the task in the worklist application, try the following:

  • Login to the worklist application with weblogic as the user. Navigate to the Administration Tasks tab. This will list all the tasks in the system. Locate the task that was created and validate the state (it should be ASSIGNED) and the assignees.

  • Alternatively, log in to Oracle Enterprise Manager Fusion Middleware Control Console at http://HOST_NAME:PORT/em and click the instance ID to display an audit track window. In the audit track view, click the BPEL instance and select the Flow-Debug tab to display the BPEL audit trail. Check the following values in the initiateTaskResponse:

    • task:task/task:systemAttributes/task:state: This should be ASSIGNED

    • task:task/task:systemAttributes/task:assignees: This displays the assignees of the task

  • Check the following log files and the shell where the server was started to make sure that there are no errors (for information about logging, see Section 38.8.4, "Logging").

    • MW_HOME/user_projects/domains/<domain name>/config/config.xml

    • MW_HOME/user_projects/domains/soainfra/logs/startsoa.log

    • MW_HOME/user_projects/domains/soainfra/servers/AdminServer/tmp/_WL_user/soa-infra/77op2b/war/WEB-INF/application.log

    Any exception where the exception stack trace has classes from package oracle/bpel/services/workflow indicates a workflow exception.

  • Use the web services page http://HOST_NAME:PORT/integration/services/IdentityService/identity to check user and group properties. Users and groups may be seeded differently from what is assumed and may therefore cause unexpected results.

38.8.3 Task Details Do Not Display in the ADF Task Flow

If you are not able to see the human task details when you click on the task in the worklist application, try the following:

  • For design time issues, make sure you start JDeveloper using jdev.exe instead of jdevw.exe in a Windows environment. This brings up a console window in the background that shows any error messages or stack traces.

  • If you see any errors during deployment of the ADF task flow, check the following:

    • The ADF task flow for the human task service is deployed on the same instance as the SOA server. If it is deployed to a server without SOA infrastructure, make sure to correctly follow the steps for deploying task flows.

    • Check if the taskflow.properties file exists in your project and has the following settings:

      human.task.lookup.type=LOCAL
      
    • Check that all shared libraries are installed to the WLS instance where the task flow is deployed, including adf.oracle.domain, adf.oracle.domain.webapp, JSF, JSTL and oracle.soa.workflow or any shared library specified in weblogic-application.xml. You can verify this by logging into Oracle WebLogic Server Console as an administrator, and clicking Deployments.

  • If you see the task in the task list but you get an error when clicking on the task title, try the following:

    • Determine if there were any deployment errors.

    • Enable logging for ADF as described in Section 38.8.4, "Logging." Set the log level to FINE and deploy the task flow again. Once you do this, you should see error messages in the log file.

    • If you get any errors on the task details screen when performing any operations, check the following log files:

      • MW_HOME/user_projects/domains/DOMAIN_NAME/servers/ADMIN_SERVER_NAME/logs/DOMAIN_NAME.logl

      • MW_HOME/user_projects/domains/DOMAIN_NAME/servers/SERVER_NAME/logs/SERVER_NAME.log

38.8.4 Logging

You can set logging for the Workflow application and for the ADF task flow.

38.8.4.1 Workflow Logging

To enable debug logging for the workflow service, add a new log_handler and logger for oracle.bpel.services in ORACLE_HOME/j2ee/home/config/j2ee-logging.xml as shown in Example 38-2. After these changes are made, you must restart the server. When this logger is added, the logs will be found in MW_HOME/user_projects/domains/<domain name>/config/config.xml.

Example 38-2 Adding a New Log Handler

<?xml version="1.0" encoding="iso-8859-1"?>
 
<logging_configuration>
 
 <log_handlers>
   ......
 
   <log_handler name="oracle-bpel-services-handler"
                class="oracle.core.ojdl.logging.ODLHandlerFactory">
     <property name="path" value="../log/wls/bpel/services"/>
     <property name="maxFileSize" value="10485760"/>
     <property name="maxLogSize" value="104857600"/>
     <property name="encoding" value="UTF-8"/>
     <property name="supplementalAttributes" 
               value="J2EE_APP.name,J2EE_MODULE.name,
                      WEBSERVICE.name,WEBSERVICE_PORT.name"/>
   </log_handler>
 
 </log_handlers>
 
 <loggers>
   .......
 
   <logger name="oracle.bpel.services" level="FINEST" useParentHandlers="false">
       <handler name="oracle-bpel-services-handler"/>
   </logger>
 
 </loggers>
 
</logging_configuration>

38.8.4.2 ADF Task Flow Logging

To enable ADF logging for the task flow, add fragments shown in Example 38-3 to MW_HOME/user_projects/domains/DOMAIN/soainfra/config/fmwconfig/servers/AdminServer/logging.xml and restart the server.

MW_HOME/user_projects/DOMAIN/domains/<domain name>/config/config.xml

Example 38-3 Adding Fragments to the Logging File

<logger name='oracle.adf' level='FINE' useParentHandlers='false'>
    <handler name='wls-domain'/>
    <handler name='console-handler'/>
</logger>
<logger name='oracle.adfinternal' level='FINE' useParentHandlers='false'>
    <handler name='wls-domain'/>
    <handler name='console-handler'/>
</logger>
<logger name='oracle.jbo' level='FINE' useParentHandlers='false'>
    <handler name='wls-domain'/>
    <handler name='console-handler'/>
</logger>

38.9 What You May Need to Know About Managing Tasks from an ADF Application

Tasks are linked to the composite instance that created them. When a new version of the BPEL process service component or workflow service component is deployed, any existing composite and associated task instances are marked stale. You can clean up stale composites using Oracle Enterprise Manager Fusion Middleware Control Console. Cleaning up stale composite instances automatically deletes the associated task instances as well.

For more information, please refer to the chapter "Managing SOA Composite Applications" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.