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 must be raised to the employee's manager so that they 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. After 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:
ADF web application that includes an ADF Business Components object and an ADF task flow that contains the UI pages where the end user submits data.
SOA composite with a mediator component that listens for events raised by the ADF application. The mediator invokes a BPEL service component that uses an included human task component.
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.
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 Initiating a SOA Composite from an 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:
You can do any required validation of the data in the ADF Business Components layer as opposed to the process.
You can pass only minimal data from the ADF web application into the process. Using this approach, you can pass just header level information required to route the task, (for example an expense ID, amount, requester). All other information remains in the database and is accessed in the task form by reference. The task form is used to display relevant details to the user. The data is therefore not carried through the process.
Figure 40-1 shows the recommended pattern.
Figure 40-1 Recommended Pattern
This chapter explains how to implement the recommended pattern.
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 must 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.
There are three high-level steps needed to invoke a human task flow from an ADF web application:
Create and deploy the ADF web application that contains the UI necessary to invoke the SOA composite that contains the human work flow.
Create the SOA composite that contains a mediator, BPEL process service component, and human task component that will assign the task to the user.
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:
Related Links
The following documents provide additional information related to subjects discussed in this section:
For detailed procedures on creating a human task service, see the chapter "Creating Human Tasks" in the Developing SOA Applications with Oracle SOA Suite.
For more information about notifying users of changes to task status, see the chapter "Creating Human Tasks" in the Developing SOA Applications with Oracle SOA Suite.
For more information about creating an ADF task flow based on the human task service component, see the chapter "Creating Human Tasks" in the Developing SOA Applications with Oracle SOA Suite.
You can deploy the human task flow to a remote server without SOA infrastructure.
Related Links
For more information about deploying human task flows to remote servers without SOA infrastructure, 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 Developing SOA Applications with Oracle SOA Suite.
Note:
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 40-1.
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.
Related Links
The following documents provide additional information related to subjects discussed in this section:
For more information about 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 Administering 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 Applications Security Guide.
Example 40-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>
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:
Related Links
The following documents provide additional information related to subjects discussed in this section:
For more information on testing and debugging your Oracle ADF web application, see the chapter "Testing and Debugging ADF Components" of the Developing Fusion Web Applications with Oracle Application Development Framework.
For more information about using Fusion Middleware Control Console, see the chapter "Deploying SOA Composite Applications" of the Developing SOA Applications with Oracle SOA Suite.
For more information about the ADF Business Components runtime log, see the chapter "Testing and Debugging ADF Components" of the Developing Fusion Web Applications with Oracle Application Development Framework.
For more information about Fusion Middleware Control Console, see the chapter "Deploying SOA Composite Applications" of the Developing SOA Applications with Oracle SOA Suite.
Following are tips that may help resolve common issues that arise when developing or running this use case.
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.
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 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.
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 Logging. Set the log level to FINE and deploy the task flow again. After you do this, you should see error messages in the log file. $OC4J_HOME/j2ee/home/log/oc4j/log.xml 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
You can set logging for the Workflow application and for the ADF task flow.
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 40-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 40-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>
To enable ADF logging for the task flow, add fragments shown in Example 40-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 40-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>
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.
Related Links
For more information about managing tasks from an ADF application, see the chapter "Managing SOA Composite Application Instances" in the Administering Oracle SOA Suite and Oracle Business Process Management Suite.