30 Designing Task Forms for Human Tasks

This chapter describes how developers can design and customize task forms for human tasks by using ADF task flows in Oracle JDeveloper. Human tasks enable users to interact with the business process. Each task has two parts—the task metadata and the task form. The task form is used to display the contents of the task to the user's worklist.

Oracle BPM Worklist displays all worklist tasks that are assigned to a user or a group. When a worklist user drills down into a specific task, the task form renders the details of that task. For example, the task form for the Fusion Order Demo ApprovalHumanTask shows order information such as the order total and ship-to information.

30.1 Introduction to the Task Form

If your SOA composite includes a human task, then you need a way for users to interact with the task. The integrated development environment of Oracle SOA Suite includes Oracle Application Development Framework (Oracle ADF) for this purpose. With Oracle ADF, you can design a task form that depicts the human task in the SOA composite.

The task form is a Java Server Page XML (.jspx) file that you create in the Oracle JDeveloper designer where you created the SOA composite containing the human task. You must set the page encoding to UTF-8 in Oracle JDeveloper before creating the Java Server Page XML file. You can do this in Oracle JDeveloper by choosing Tools > Preferences > Environment, and selecting UTF-8 using the Encoding dropdown list.

30.1.1 What You May Need to Know About Task Forms: Time Zone Conversion

Time zone conversion is not automatic for datetime elements in the task payload when a task form is created. You must add the <af:convertDateTime> tag to enable time zone conversion on a datetime element. See any standard task header time label for an example. Example 30-1 shows a sample header.

The hwtaskflow.xml file is used to capture the details on connecting with the service engine. By default, it uses remote EJBs to connect to the workflow server. The SOA server URL and port are automatically determined by using WebLogic Server runtime MBeans. However, you can override these by explicitly specifying the URL and port information here.

Seed a user that has ORMI privileges so that the task details application can connect to the workflow service. You can seed this user by using Oracle Enterprise Manager Fusion Middleware Control.

30.3 Creating an ADF Task Flow Based on a Human Task

ADF task flows are used to model the user interface for the task details page. You can create the task flow in the same application that contains the human task or in a separate application.

You must have previously created a human task (.task file) as part of a SOA composite before you can create a task flow. See Chapter 28, "Creating Human Tasks" for how to create the.task file.

If the task flow is in the same application as the human task, create a different project for the task flow. If the SOA composite contains multiple human tasks, create a separate project for each ADF task flow associated with each human task. By using an ADF task flow, you create data controls based on the task parameters and outcomes.

30.3.2 How To Create an ADF Task Flow Based on a Human Task

The ADF Task Flow Based on Human Task option (shown in Figure 30-1) creates an ADF task flow and additional artifacts to make deployment easier. When you select the .task file to associate with the ADF task flow, human task data controls are created based on the task parameters and outcomes. These are then available to use in the JSPX page. You must have access to the SOA composite project while creating the task flow project.

To create an ADF task flow based on a human task:

From the File main menu, select New > Applications > SOA Application.

Click OK.

Provide an application name and directory information (or accept the default), and click Finish.

Right-click the project name and select New.

Under Web Tier, select JSF.

Select ADF Task Flow Based on Human Task and click OK.

In the SOA Resource Browser, find and select the .task file where you defined the human task and click OK.

If the human task is in the same application as the task definition, then click File to use the file browser to navigate to the .task file, which is typically in the composite directory.

If the human task is in a different application, then click Resource Palette to use the MDS resource catalog and find the .task file in the composite application.

If the .task file is located within the current application, then click Application.

This displays the Create Task Flow dialog and creates the data controls.

In the Create Task Flow dialog, accept the defaults and click OK.

The taskDetails1_jspx icon appears in the designer, as shown in Figure 30-4. The task flow has a view, a control flow, and a task return.

As a prerequisite, you first must register the library JAR file in Oracle JDeveloper.

To create the library JAR file for custom page templates:

From the Tools menu, select Manage Libraries.

Click New.

The Create Library dialog appears.

Highlight Class Path, and click Add Entry.

The Select Path Entry dialog appears.

Select the class path for the library, and click Select.

The class path is displayed below Class Path and the library JAR file name is displayed in the Library Name field. Ensure that the library name you select ends with a suffix of .jar. Figure 30-8 provides details.

Tabbed templates in which the payload and comments, attachment, and history sections are displayed on a separate tab: taskDetailsTemplate2.jspx

In the Name and Definition page of the Custom Task Flow wizard, select Packaged, then select either Default or Tabbed.

Custom page templates that you define. In the Name and Definition page of the Custom Task Flow wizard, select Custom, then select the library name and the template name.

You package a page template and its artifacts into an ADF library JAR file. These JAR files can be packaged, deployed, discovered, and used like any other Oracle library component. The wizard prompts you to specify the JAR name and template location in the JAR.

Page templates let you define entire page layouts, including values for certain attributes of the page. When pages are created using a template, they all inherit the defined layout. When you make layout modifications to the template, all pages that consume the template automatically reflect the layout changes.

The templates used in the wizard generate content for the following six facets:

Actions

Attachments

Body

Comments

Header

History

For the action, header, and body facets, you can pick the content and attributes to be displayed and then fine tune the layout.

All six facets are defined in the default page templates. In the case of custom templates, you use these exact facet names in your template. If your template does not include these facets, then the facet content is not generated in the JSPX file.

If you do not want to include page templates in your task form, select None in the Name and Definition page. In this case, the wizard generates a task form with a header, body (one or more), and footer, and provides for tabular formatting into columns and rows. You can select any of the task (system) actions to display on the form and you can specify that the custom actions defined for the human task appear on the form as buttons. Any or all parts of the payload can be selected to appear, as well as attachments and comments.

In the Form Name field, provide the name of the form (.jspx file) that is to be generated at the end of the wizard. If you do not provide a name, then the default name, Humantasknumber_Form, is provided. Ensure that valid characters are used in the name. Spaces are not permitted.

Specify the Task Flow Name, that is, the name of the ADF task flow that is generated at the end of the wizard. Accept the default name of Humantasknumber_TaskFlow or specify a different name.

In the Page Templates section, select either:

Packaged: Select this to use one of the default page templates, then select the particular template from the list.

Click Next. This form is created as an ADF task flow and added to the project. The Header page appears.

On the Header page, shown in Figure 30-10, perform the following procedures and click Next.

In the Actions facet section, select the options to include in the title bar of the task form:

Other actions (menu): Lists the system actions that are possible for the task, such as Request Information, Reassign, Renew, Suspend, Escalate, and Save.

Outcomes (buttons): Displays buttons for task actions that are defined in the human task, such as setting task outcomes.

In the Header facet section, enter the number of display columns. If you want each header label to display in its own column, then enter the same number as the number of headers you move into the Selected list. If you enter 1, but select 7 headers, all 7 headers appear in one column.

On the Body page, shown in Figure 30-11, perform the following procedures in the Body facet section to set up the form, and click Next:

Enter a title that describes the body panel.

Enter the number of columns for row 1. For a simple form, you may want to enter the same number as you entered for the number of header columns.

Click the Add (+) button to add more rows. For each new row, you can also specify the number of columns. Each row can have its own column layout. For each column in each row, a body page is created, labeled Row1, Column1, and so on.

The Footer page that displays is based upon the page template you selected on the Name and Definition page in Step 6 (either Default Page Template or Custom Page Template).

If you selected Default Page Template, the Footer page shown in Figure 30-13 is displayed. Deselect any comments, attachments, or history facet that you do not want to include in the footer, and click Next. By default, the comments, attachments, and history facets are all selected.

This option creates the combination of all the preceding task form components (the task header, task history, task actions, and task comments and attachments), plus the interface for the payload. The payload interface is created as follows:

All text nodes are created as text input fields.

If an element has maxOccurs="unbounded", then it appears as a table.

Nested tables are not rendered; that is, if an element has maxOccurs="unbounded" and it has a child with maxOccurs="unbounded", then the child element is not rendered.

If there are multiple levels of nesting, then drag and drop the individual sections and use a standard ADF drop handler.

Complete Task without Payload

This option creates the combination of all of the preceding task form components (the task header, task history, task actions, and task comments and attachments).

Task Details for Email

This option creates an ADF region that renders well when sent by email. It generates the form shown in Figure 30-18.

All the standard header fields are added to the task form. This includes the task number and title; the state, outcome, and priority of the BPEL process, and information about who created, updated, claimed, or is assigned to the task. The header also displays dates related to task creation, last modification, and expiration. You can add or remove header fields as required for your task display.

The following task actions appear from the Actions dropdown list or as buttons. The tasks that appear depend on the state of the task (assigned, completed, and so on) and the privileges that are granted to the user viewing the task. For example, when a task is assigned to a group, only the Claim button appears. After the task is claimed, other actions such as Reject and Approve appear.

The first three custom actions appear on the task form as buttons: Claim, Dismiss, and Resume. Only those buttons applicable to the task appear. Other actions are displayed under the Actions list, starting with Request for Information, Reassign, and Route. Systems actions—Withdraw, Pushback, Escalate, Release, Suspend, and Renew—follow the custom actions, followed by the Save button. These actions require no further dialog to complete.

Claim—A task that is assigned to a group or multiple users must be claimed first. Claim is the only action available in the Task Action list for group or multiuser assignments. After a task is claimed, all applicable actions are listed.

Note:

If an FYI task is sent to multiple users, a user must first select the Claim button to claim the task before they can dismiss it.

Dismiss—This action is used for a task that requires the person acting on the task to acknowledge receipt, but not take any action (like an FYI).

Resume—A task that was halted by a Suspend action can be worked on again. See Suspend.

Request for Information—You can request more information from the task creator or any of the previous assignees. If reapproval is not required, then the task is assigned to the next approver or the next step in the business process.

Reassign—Managers can reassign a task to reportees. The Reassign option also provides a Delegate function. A task can be delegated to another user or group. The delegated task appears in both the original user's and the delegated user's worklists. The delegated user can act on behalf of the original assignee, and has the same privileges for that task as the original assignee.

Route—If there is no predetermined sequence of approvers or if the workflow was designed to permit ad hoc routing, then the task can be routed in an ad hoc fashion. For such tasks, a Route button appears on the task details page. From the Routing page, you can look up one or more users for routing. When you specify multiple assignees, you can choose whether the list of assignees is for simple (group assignment to all users), sequential, or parallel assignment. In the case of parallel assignment, you provide the percentage of votes required for approval.

Withdraw—Only the task creator can withdraw (cancel) the task. The Comments area is available for an optional comment. The business process determines what happens next.

Pushback—This action sends a task up one level in the workflow to the previous assignee.

Escalate—An escalated task is assigned to the user's manager. The Comments area is available for an optional comment.

Release—Releasing a task makes it available to other assignees. A task assigned to a group or multiple users can then be claimed by the other assignees.

Suspend—This action suspends the expiration date indefinitely, until the task is resumed. Suspending and resuming tasks are available only to users who have been granted the BPMWorkflowSuspend role. Other users can access the task by selecting Previous in the task filter or by looking up tasks in the Suspended status. Buttons that update a task are disabled after suspension.

Renew—Renewing a task extends the task expiration date seven days (P7D is the default). The renewal duration is controlled from Oracle Enterprise Manager Grid Control. A renewal appears in the task history. The Comments area is available for an optional comment.

Save—Changes to the task are saved.

While you are creating a task form, all possible system action buttons appear, although only those actions that are appropriate for the task state and fit the user's privileges appear in the worklist.

Task History

The history of task actions appears on the task details page, and is displayed in the worklist as a history table. The history includes the following fields:

Task Header provides both header and task actions, so you do not need the Task Action drop handler when you use Task Header. Use Task Action when you want the actions dropdown menu and buttons, but not header details.

Drag the payload data collection to the left of the Panel Group Layout area.

An alternative to dropping the payload node onto the form is to expand the payload node and drop the necessary child elements onto the form. For example, to create a read-only form for the VacationRequest payload, expand the payload node, drag the Vacation Request Process Request node onto the form, and select Forms > ADF Read-only Form.

From the context menu, select Forms, then ADF Read-only Form, as shown in Figure 30-28.

30.5 Refreshing Data Controls When the Task XSD Changes

When task metadata changes, refresh the Data Controls view (XSD changes are not refreshed) that is based on that task metadata. The refresh functionality re-creates the data control. Figure 30-31 shows the Refresh option.

If you are sending a notification as email, do not secure the URL with "/notification/secure" to use container-based security because this is accessed by SOA APIs using an internal context that cannot be created outside of SOA. The URL pattern inside security cannot contain "/" (all URLs) and "//notification".

No additional steps are required for identity propagation. Identity is automatically propagated to the server EJBs.

30.7 Creating an Email Notification

A task form is used to provide an email notification, if email notification is defined as part of the human task. Options for email notification include:

Default email notification—Use the first page of the task form that you create for the human task. The content is sent as an HTML-based email. Images in the task flow are included as attachments so that the notification can be viewed in disconnected mode. All drop handlers, including Complete Task with Payload and Complete Task without Payload, are suitable for emails.

30.7.1 How To Create an Email Notification

To send a custom email notification whose content and layout you have specified, create another JSPX file in which you design an email notification page. (Note, however, that you can use the default page for notification with no further modifications.) Create the custom notification page by using the custom and standard drop handlers, or use the email notification drop handler. In addition, do the following:

Add a router to the task flow. The router directs the task flow to send either the email notification page or the default page, depending on the control flow based on the bpmClientType page flow scope value.

Edit the generated inline CSS to customize the page. No additional CSS is included at runtime and the ADF CSS is not available at runtime. See the samples notification-101 and notification-102 available with the Oracle SOA Suite samples.

Reference images directly from the HTML or JSF page. (Indirect references, for example, an included JSF that in turn includes the image, are not allowed.)

30.7.1.1 Creating a Task Flow with a Router

The control flow case with a router enables you to direct the request to a specific page based on certain parameters. For an ADF task flow based on a human task, you need a special page for email notifications. This section describes how to create a special page for email notifications.

To create a task flow with a router:

In the Application Navigator, expand the task flow project and double-click project_name_TaskFlow.xml.

The XML file opens in the designer. In the diagram view, you see the taskDetails1.jspx icon.

From the Component Palette, select ADF Task Flow, and drag the View icon into the designer.

Click view1 below the icon and enter a name for the email notification page.

This drop handler includes a header with inline style, a payload using ADF, and a comment using inline style. Because the payload is dynamically generated, it does not include an inline style.

In general, you can find the inline styles for the Header section for each component and use the same style for the Content section for the respective components.

In the Edit Action Bindings dialog, select the data collection and click OK.

The email task form is complete and ready to be deployed.

30.7.2 What Happens When You Create an Email Notification Page

The email notification page is sent as HTML content in the email message body. Images on the page are inlined as attachments. Relative URLs are converted to absolute URLs.

30.7.3 What You May Need to Know About Creating an Email Notification Page

A notification may not display correctly in email if the styles used in the fields of the form are not valid for email. Editing the generated inline CSS to customize the page may be required. See Section 30.7.1, "How To Create an Email Notification," for more information.

If you do not have a connection, select New Connection and use the Application Server Connection wizard.

In the Select Deployment Targets dialog, select a server instance.

Click OK.

30.8.2 How To Redeploy the Task Form

If you change the task form and want to redeploy it, repeat the deployment step. (Right-click the task form application name, select Deploy, and then application_name > to > application_server_connection.) A message asking you if you want to undeploy the form is displayed. Click OK and deploy the task form again.

30.8.3 How To Deploy a Task Flow as a Separate Application

If you want to deploy the task flow as a separate application, outside of the SOA composite application, then create an application and project as a container for the task flow. After you deploy the SOA composite application, deploy the task flow application.

30.8.4 How To Deploy a Task Form to a non-SOA Oracle WebLogic Server

This section describes how to deploy a task form to a non-SOA Oracle WebLogic Server.

30.8.4.1 Before Deploying the Task Form: Port Changes

If you are not using the default values for RMI or HTTP ports, open the wf_client_config.xml file in Oracle JDeveloper to change values.

When you want to deploy task details on non-SOA servers, you must configure the wf_client_config.xml file. This file should be created and added to the task details project only if the task detail is deployed to a separate managed server that is not the SOA server. The <serverURL> and <rootEndpointURL> in the file should refer to the SOA server host name and port number.

Before deploying the task form to a non-SOA Oracle Weblogic Server, ensure that the session tracking cookie of your task-form web application is configured with a cookie trigger path unique to your application. This ensures that your task form application has its unique session tracking cookie and cannot be overwritten by the session tracking cookies created for other Oracle BPM applications like Oracle BPM Worklist or Oracle Business Process Management Workspace.

To configure the session cookie trigger path, in JDeveloper, open the weblogic.xml file in your web project. Choose the overview tab in your .xml file editor, and choose the session. In the cookie trigger path field, enter the application context path of your web application. For example, if the URL of your application is http://host:port/my-application-context-root in which my-application-context-root is the name of your application context root, then the cookie trigger path is set as follows:

30.8.5 What Happens When You Deploy the Task Form

When the task form is deployed, an automatic association is created between the task metadata and the task flow application URL. Use Oracle Enterprise Manager 11g Fusion Middleware Control to update this mapping. Access the task flow component in the Component Metrics table for a specific SOA composite application. The Administration tab shows the URI for the task form. See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite for more information. If the task flow is configured for HTTPS access, you may need to do additional settings in Enterprise Manager.

Note:

For the task form association to happen automatically, the SOA server must be running. If the association does not happen, then you receive the message Taskdetailsnotfoundforthistask when you try to access the task form for that task in Worklist Application or Oracle Business Process Management Workspace. In this case, you can either restart the application or go to Oracle Enterprise Manager and register the task form URL manually.

For the task form to work correctly, always specify the URL using the complete name for the host on which the task flow is deployed.

If you want to access the task form from a different URL that has a different port number than the hostname and port number previously set in Oracle WebLogic Server Administration Console, then you must change the port number for the front-end in Oracle WebLogic Server Administration Console and redeploy the task form so that the task details appear correctly in the worklist.

30.8.6 What You May Need to Know About Undeploying a Task Flow

When a task flow Web application is deployed, the task flow URL is registered in the database. This URL is displayed in Oracle BPM Worklist when a task is clicked and the task details are displayed. If the task flow Web application is later undeployed or stopped, the task flow URL in the database is not removed as part of the undeployment. Consequently, when you click the task in the worklist to see the task details, a 404NotFound error is displayed rather than the message Detailsnotavailablefortask. To avoid the 404NotFound error, use Oracle Enterprise Manager Fusion Middleware Control to undeploy the task flow application from the application home page.

30.9 Displaying a Task Form in the Worklist

The task form is displayed in Oracle BPM Worklist, a web-based interface for users to act on their assigned human tasks. Specific actions are available or unavailable depending on a user's privileges.

Figure 30-47 shows how the task form for the help desk request example is displayed in the Worklist Application task details page.

30.10 Displaying a Task in an Email Notification

You can click an available action, RESOLVED or UNRESOLVED, or click the Worklist Application link to log in to the worklist. Clicking an action displays an email composer window in which you can add a comment and send the email.

By default, the text in a task notification refers to "Worklist Application," but you can change that text and its associated URL.

30.10.1 Changing the Text for the Worklist Application in Task Notifications

By default, the text in a task notification refers to "Worklist Application," but you can change that text. To change it, you create a custom resource bundle and modify the appropriate strings.

To change the text in a task notification:

Open the WorkflowLabels.properties resource bundle in the sample workflow-110-workflowCustomizations.