Designing Task Forms for Human Tasks

30 Designing Task Forms for Human Tasks

Learn how to 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 information about troubleshooting human workflow issues, see section "Human Workflow Troubleshooting" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

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.

Figure 30-1 shows the Oracle JDeveloper ADF Task Flow Based on Human Task option where you start creating a task form.

Figure 30-1 ADF Task Flow Based on a Human Task, in Oracle JDeveloper

Description of "Figure 30-1 ADF Task Flow Based on a Human Task, in Oracle JDeveloper"

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. The following example shows a sample header:

<af:outputText value="#{bindings.createdDate.inputValue}"
                        id="ot15">
         <f:convertDateTime type="#{pageFlowScope.dt}"
                              timeZone="#{pageFlowScope.tz}"
                              dateStyle="#{pageFlowScope.df}"
                              timeStyle="#{pageFlowScope.tf}"/>
         </af:outputText>

30.2 Associating the Task Flow with the Task Service

When you create an ADF task flow based on a human task, you must select a task metadata file to generate the data control. This data control is used to lay out the content on the page and connect to the workflow service engine at execution time to retrieve task content and act on tasks.

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 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.

To autogenerate an ADF task form, access the human task in the SOA composite application (form and task are in the same application). See How To Create an ADF Task Flow from the Human Task Editor, for more information.

To create an ADF task form in a separate application, create the new application and project and browse for the .task file for the human task. See How To Create an ADF Task Flow Based on a Human Task, for more information.

An ADF task form does not validate user inputs. The only validation that is done is to check that mandatory inputs have values. You should review your task forms and add additional validators as needed.

30.3.1 How To Create an ADF Task Flow from the Human Task Editor

The.task file that specifies the human task is easily associated with the task flow when the two are located in the same application.

To create an ADF task flow for a human task:

Open the BPEL process within the SOA composite application.
Double-click the human task activity and click Edit.

Figure 30-2 shows the Human Task dialog.

Figure 30-2 Editing a Human Task

Description of "Figure 30-2 Editing a Human Task"
In the .task tab (shown in Figure 30-3), click Form and select Auto-Generate Task Form.

Figure 30-3 Creating a Task Flow from the Human Task Editor

Description of "Figure 30-3 Creating a Task Flow from the Human Task Editor"
Provide a project name and a directory path (or use the default) and click OK.

The taskDetails1_jspx icon appears in the designer, as shown in Figure 30-4.

Figure 30-4 The taskDetails1_jspx Icon

Description of "Figure 30-4 The taskDetails1_jspx Icon"

The task flow and task form are complete and ready to be deployed.

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 > Custom 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.
1. If the human task is in the same application as the task definition, then click File System to use the file browser to navigate to the .task file, which is typically in the composite directory.
2. If the human task is in a different application, then click SOA-MDS to use the MDS resource catalog and find the .task file in the composite application.
3. 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.

To continue creating the task form, see the following:

How To Create a Task Form Using the Complete Task with Payload Drop Handler.

How To Create Task Form Regions Using Individual Drop Handlers.

30.3.3 What Happens When You Create an ADF Task Flow Based on a Human Task

With an ADF task flow based on a human task, the task flow application has task data controls that wire the task form with the workflow services. The data controls provide the following:

Various parameters and operations to access task data and act on it
Drop handlers with which you can create interface regions to display the contents of the task

The human task-aware data controls appear in the Data Controls panel of the Oracle JDeveloper Applications window, as shown in Figure 30-5.

Figure 30-5 The Task Collection in the Data Controls Panel

Description of "Figure 30-5 The Task Collection in the Data Controls Panel"

The data controls for the task (represented by the Task node in Figure 30-5) have drop handlers to render the task form. See Creating a Task Form, for more information.

30.3.4 What You May Need to Know About Having Multiple ADF Task Flows That Contain the Same Element with Different Meta-attributes

You must create separate ADF task flows if both contain the same element, but with different meta-attributes specified (for example, editable and noneditable).

For example, assume you perform the following tasks.

Create two task form applications for a SOA composite application:
- Task form application one (for example, named EnterBankDetails.task) has one editable payload (for example, named BankDetails) and one noneditable payload (for example, named Employee).
- Task form application two (for example, named ValidatePersonalInformation.task) has one editable payload (for example, also Employee).
While creating the task form, the wizard provides you with the option to define the ADF table for payload Employee.
Complete the wizard, then deploy the process.
Invoke the process.
Log in to Oracle BPM Worklist.

There is a Validate Personal Information task (for ValidatePersonalInformation.task).
Select the task.

Employee details are available for modification, as expected.
Add a new record, then approve the task.
Select the Enter Bank Details task (for EnterBankDetails.task). In the task form, the Insert New and Delete buttons are still present for Employee data, even though it is a noneditable payload.
Click Delete, then select Approve. The payload gets deleted.

Ensure that you create two separate ADF task flow applications because both contain the Employee element, but with different meta-attributes specified (editable and noneditable).

30.4 Creating a Task Form

You can create a task form by using the Auto-Generate Task Form option, the Launch Task Form Wizard option, or by using human task drop handlers.

For how to use the Auto-Generate Task Form option, see How To Create an Autogenerated Task Form.
For how to use the Launch Task Form Wizard option, see How To Create a Task Form Using the Custom Task Form Wizard.
For how to use human task drop handlers, see the following:

Note:

A task form name must begin with a letter of the alphabet, either upper or lower case. It should contain only letters of the alphabet and the numbers zero (0) through nine (9).

30.4.1 How To Create an Autogenerated Task Form

Autogenerating a task form opens a default template that you can then modify.

To create an autogenerated task form:

Open the BPEL process within the SOA composite application.
Double-click the human task activity and click Edit.
From the .task editor, click Create Form and select Auto-Generate Task Form, as shown in Figure 30-6.

Figure 30-6 Creating a Task Form

Description of "Figure 30-6 Creating a Task Form"
Provide a project name and a directory path (or use the default) and click OK.

The default form opens in the taskDetails1.jspx tab. The default form for ApprovalHumanTask is shown in Figure 30-7.

Figure 30-7 Autogenerated Task Form for ApprovalHumanTask

Description of "Figure 30-7 Autogenerated Task Form for ApprovalHumanTask"

30.4.2 How to Register the Library JAR File for Custom Page Templates

You can optionally specify your own custom page templates in the Custom Task Form wizard. As described in How To Create a Task Form Using the Custom Task Form Wizard, you select Custom in the Name and Definition page of the Custom Task Form Wizard and select the library and .jspx template.

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.

Figure 30-8 Custom Library JAR File

Description of "Figure 30-8 Custom Library JAR File"
Select the Deployed by Default check box.
Click OK.

When you run the Custom Task Form wizard, you select the Custom radio button on the Name and Definition page, and select the library and template that you registered.

30.4.3 How To Create a Task Form Using the Custom Task Form Wizard

This wizard enables you to create a task form using ADF page templates and standardized task regions. The page templates can be either of the following:

Default page templates that are automatically provided at the following location:
```
[JDeveloper_Home}/jdeveloper/soa/modules/oracle.soa.worklist_11.1.1/adflibWorklistComponents.jar
```
The default page templates are:
- Nontabbed, default template: taskDetailsTemplate.jspx
- 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.

To create a custom task form:

Open the BPEL process within the SOA composite application.
Double-click the human task activity, and click the Edit icon.

The Human Task Editor appears.
Above the editor, click Form and select Launch Task Form Wizard.
Provide a project name and a directory path (or use the default), and click OK. The Custom Form Wizard displays the Name and Definition screen as shown in Figure 30-9.

Figure 30-9 Custom Task Form Wizard: Form Name and Definition

Description of "Figure 30-9 Custom Task Form Wizard: Form Name and Definition"
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.
- Custom: Select the library and template. If no library is listed, click Manage Libraries and follow the instructions in How to Register the Library JAR File for Custom Page Templates.
Click Next. 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.
- Move header labels into the Selected list and reorder them as needed.
  
  Figure 30-10 Custom Task Form Wizard: Setting Up the Header
  
  Description of "Figure 30-10 Custom Task Form Wizard: Setting Up the Header"
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.
  
  Figure 30-11 Custom Task Form Wizard: Setting Up the Body
  
  Description of "Figure 30-11 Custom Task Form Wizard: Setting Up the Body"
  
  Note:
  
  If you specify rows or columns for which no payload data appears, then an empty panel group is displayed. You can use this blank section to add content to the form later by using data controls.
On the Row1 Column1 page, shown in Figure 30-12, move all or part of the payload to the Selected list and click Next.

Figure 30-12 Custom Task Form Wizard: Selecting the Body Fields

Description of "Figure 30-12 Custom Task Form Wizard: Selecting the Body Fields"
For any Rown Columnn page after Row1 Column1, repeat Step 10 and click Next.

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.

Figure 30-13 Custom Task Form Wizard: Selecting the Footer Fields for the Default Page Template

Description of "Figure 30-13 Custom Task Form Wizard: Selecting the Footer Fields for the Default Page Template"
On the Summary page, shown in Figure 30-14, inspect your selections. Click Back to make changes or click Finish.

This form is created as an ADF task flow and added to the project.

Figure 30-14 Custom Task Form Wizard: Summary

Description of "Figure 30-14 Custom Task Form Wizard: Summary"

The Designer initializes and the form_name.jspx tab is displayed, as shown in Figure 30-15 (upper part of tab) and Figure 30-16 (lower part of tab).

Figure 30-15 Custom Task Form (Upper Part of Tab)

Description of "Figure 30-15 Custom Task Form (Upper Part of Tab)"

Figure 30-16 Custom Task Form (Lower Part of Tab)

Description of "Figure 30-16 Custom Task Form (Lower Part of Tab)"

30.4.4 How To Create a Task Form Using the Complete Task with Payload Drop Handler

The human task drop handlers appear in the context menu of the designer, as shown in Figure 30-17.

Figure 30-17 Human Task Drop Handlers for Creating the Task Form

Description of "Figure 30-17 Human Task Drop Handlers for Creating the Task Form"

Other ADF drop handlers—for forms, tables, trees, and so on (shown in Figure 30-17)—can also be used to create task forms.

To create a task form using the Complete Task with Payload drop handler:

In the designer, double-click taskDetails1_jspx.
In the Create JSF Page dialog, provide a file name and directory information (or accept the defaults) and click OK.
In the Data Controls panel of the Applications window, expand the human task node, then the getTaskDetails node, and then the Return node.
Drag the Task icon into the taskDetails.jspx window.
Select Human Task, and then Complete Task with Payload.
In the Edit Action Binding dialog, shown in Figure 30-18, click OK.

Figure 30-18 Edit the Action Binding

Description of "Figure 30-18 Edit the Action Binding"
In the next Edit Action Binding dialog, the data collection is selected, as shown in Figure 30-19; click OK.

Figure 30-19 Select the Data Collection and Action

Description of "Figure 30-19 Select the Data Collection and Action"

The task form is displayed, as shown in Figure 30-20.

Figure 30-20 Task Form

Description of "Figure 30-20 Task Form"

30.4.4.1 Complete Task with Payload

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.

30.4.4.2 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).

30.4.4.3 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-21.

Figure 30-21 Task Form for Email Notification

Description of "Figure 30-21 Task Form for Email Notification"

See Creating an Email Notification , for more information.

30.4.4.4 Task Header

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.

Figure 30-22 shows an example of header information.

Figure 30-22 Header Information

Description of "Figure 30-22 Header Information"

Buttons for task actions are also created in the header, as shown in Figure 30-23.

Figure 30-23 Task Header: Task Action Buttons

Description of "Figure 30-23 Task Header: Task Action Buttons"

30.4.4.5 Task Actions

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.
- Pushback is designed to work with single approvers and not with group votes. Pushback from a stage with group vote (or parallel) scenario to another stage is not allowed. Similarly, you cannot push back from a single assignee to a group vote (or parallel) scenario.
Dismiss—This action is used for a task that requires the person acting on the task to acknowledge receipt, but not take any action (such as 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. Note: Pushback is designed to work with single approvers and not with group votes. Pushback from a stage with group vote (or parallel) scenario to another stage is not allowed. Similarly, you cannot push back from a single assignee to a group vote (or parallel) scenario.
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.

30.4.4.6 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:

Version number
Participant name—the person who acted on the task
Action—for example, if the task was approved or assigned
Updated By—name of the person who last updated the task
Action date

See Figure 32-20 and Figure 32-21 for how task history is displayed in Oracle BPM Worklist, including the options to take a history snapshot, list future participants, and list full task actions.

30.4.4.7 Task Comments and Attachments

A trail of comments with the comment date and comment writer's user name is maintained throughout the life cycle of a task.

Files or reference URLs associated with a task can be added by any of the human task participants.

Figure 30-24 shows an example of the comments and attachments region.

Figure 30-24 Comments and Attachment Region

Description of "Figure 30-24 Comments and Attachment Region"

30.4.5 How To Create Task Form Regions Using Individual Drop Handlers

You can create a display form with multiple regions using the individual Task Header, Task Action, Task History, and Task Comment and Attachment drop handlers shown in Figure 30-25.

Figure 30-25 Using Human Task Drop Handlers

Description of "Figure 30-25 Using Human Task Drop Handlers"

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.

To create the task form without building each region individually, see How To Create a Task Form Using the Complete Task with Payload Drop Handler.

Before you create this task form, you must have created the following:

A new application and SOA project, and a human task service.
An ADF task flow based on the human task. See Introduction to the Human Workflow Tutorial for more information.

To create task form regions using individual drop handlers:

In the designer, double-click taskDetails1.jspx.
In the Create JSF Page dialog, provide a file name and directory information (or accept the defaults) and click OK.
In the Data Controls panel of the Applications window, expand the human task node, then the getTaskDetails node, and then the Return node.
Drag the Task icon into the taskDetails.jspx window.
Select Human Task, and then Task Header.

This creates the Actions dropdown list and buttons for task actions, as shown in Figure 30-26, and header details, as shown in Figure 30-27.

Figure 30-26 Designing the Task Form: Buttons for Task Actions

Description of "Figure 30-26 Designing the Task Form: Buttons for Task Actions"

Figure 30-27 Designing the Task Form: Task Headers

Description of "Figure 30-27 Designing the Task Form: Task Headers"
Drag additional Task icons into the JSPX designer, selecting these options with each iteration:
- Human Task, then Task History
- Human Task, then Task Comment and Attachment
The task form now has multiple regions for task action dropdown lists and buttons, task header details, task history, and comments and attachments.

To continue creating the task form, see Step 1 in How To Add the Payload to the Task Form.

30.4.6 How To Add the Payload to the Task Form

In addition to adding the payload, you can create task form regions. See Step 1 in How To Create Task Form Regions Using Individual Drop Handlers.

To add the payload to the task form:

From the Components window, select ADF Faces.
Expand Layout.
Drag Panel Group Layout between the Header and Comment sections.
In the Data Controls panel, expand Task, and then Payload.
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.

Figure 30-28 Adding ADF Read-Only Fields to the Task Form Payload Region

Description of "Figure 30-28 Adding ADF Read-Only Fields to the Task Form Payload Region"
In the Edit Form Fields dialog, accept the defaults and click OK.

This creates read-only fields in the payload region, between the Details and History sections.

The payload regions appear, as shown in Figure 30-29.

Figure 30-29 The Payload Region of the Task Form

Description of "Figure 30-29 The Payload Region of the Task Form"

The task form, shown in Figure 30-30, is complete and ready to be deployed.

Figure 30-30 The Task Form (taskDetails.jspx)

Description of "Figure 30-30 The Task Form (taskDetails.jspx)"

30.4.7 What Happens When You Create a Task Form

The form you designed is saved in the .jspx file at

JDev_Oracle_Home\mywork\task_form_application_name\project_name\public_html

The task form is ready to be deployed. See Deploying a Composite Application with a Task Flow.

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.

Figure 30-31 Refreshing Data Controls

Description of "Figure 30-31 Refreshing Data Controls"

To refresh the data control:

Right-click the data control.
Select the Edit Definition option to display the Refresh Data Control dialog, as shown in Figure 30-32.

Figure 30-32 The Refresh Data Control Button

Description of "Figure 30-32 The Refresh Data Control Button"

30.6 Securing the Task Flow Application

You can use any container-based security for securing the task flow.

See Requirements for Client Applications For Identity Propagation , for more information. Form-based authentication and SSO-based authentication are available for web security.

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.
Custom email notification—Use the Task display for email drop handler to create a custom email notification task page.

Notifications from Human Workflow to review notification settings as part of a human task definition (.task file).

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 Applications window, 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 Components window, 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.

Figure 30-33 shows an example using the name EmailPage.

Figure 30-33 Creating the Email Page

Description of "Figure 30-33 Creating the Email Page"
From the Components window, drag Router into the designer.
Click router1 below the icon and enter a router name.

Figure 30-35 shows an example using the name PageRouter.
To ensure that the router is called, right-click the router icon and click Mark Activity > Default Activity, as shown in Figure 30-34.

Figure 30-34 Marking the Router as the Default Activity

Description of "Figure 30-34 Marking the Router as the Default Activity"
Click the router - router_name - Property Inspector tab.
In the default-outcome field, enter default.
Click Add, and in the Outcome field, enter the name of the email notification page.
Use the Expression Builder to enter the following in the expression field: #{pageFlowScope.bpmClientType=="notificationClient"}
In the Components window, click Control Flow Case.
In the designer, drag from the router page icon to taskDetails1.jspx.

The control flow is automatically labeled default, as shown in Figure 30-35.

Figure 30-35 Connecting the Control Flow

Description of "Figure 30-35 Connecting the Control Flow"
In the Components window, click Control Flow Case.
In the designer, drag from the router page icon to the email notification page icon.
Click the control-flow-case - email_page_name - Property Inspector tab.
From the from-outcome list, select the name of the email notification page.

Figure 30-36 shows the completed control flow.

Figure 30-36 Completed Control Flow for an Email Notification

Description of "Figure 30-36 Completed Control Flow for an Email Notification"

To continue creating the email notification page, see Step 1 in Creating an Email Notification Page.

30.7.1.2 Creating an Email Notification Page

Creating an email notification page is similar to creating a task form, with the addition of defining layout and inline styles.

To create an email notification page:

In the designer, double-click EmailPage.
In the Create JSF Page dialog, provide a file name and directory information (or accept the defaults) and click OK.

The EmailPage.jspx tab opens in the designer.
From the Components window, drag any of the Common Components (for an image, for example) or Layout components into the designer.
For the layout component you selected, provide alignment and other details in the Property Inspector tab.

Figure 30-37 shows the layout fields available when Panel Group Layout is selected.

Figure 30-37 Specifying a Layout

Description of "Figure 30-37 Specifying a Layout"
Expand Appearance, Style and Theme, Behavior, Advanced, Customization, and Annotations to specify other details, as shown in Figure 30-38.

Figure 30-38 Specifying a Layout: More Details

Description of "Figure 30-38 Specifying a Layout: More Details"
From the Data Controls panel, expand the human task node, then the getTaskDetails node, and then the Return node.
Drag Task into the panel group layout area.
Select Human Task, and then Task details for email, as shown in Figure 30-39.

Figure 30-39 Human Task Drop Handlers

Description of "Figure 30-39 Human Task Drop Handlers"

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.

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 How To Create an Email Notification, for more information.

Security issues can also prevent the form from being rendered correctly. See Securing the Task Flow Application, for more information.

30.8 Deploying a Composite Application with a Task Flow

The composite application that contains the task flow must be deployed before you can use the task form in the Worklist Application.

The process for deploying an application with a task flow is basically the same as deploying any SOA composite application, as described in How To Deploy a Composite Application with a Task Flow. See Deploying SOA Composite Applications for more information.

30.8.1 How To Deploy a Composite Application with a Task Flow

An application server connection is required to do the following.

To deploy a composite application with a task flow:

Right-click the composite application name, select Deploy, and then application_name > to > application_server_connection.

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.

The following example shows a sample wf_client_config.xml file.

<?xml version="1.0" encoding="UTF-8" ?>
xmlns="http://xmlns.oracle.com/bpel/services/client">
    <server default="true" name="default">
        <localClient>

<participateInClientTransaction>false</participateInClientTransaction>
        </localClient>
        <remoteClient>
            <serverURL>t3://my_host.us.example.com:8001</serverURL>

<initialContextFactory>weblogic.jndi.WLInitialContextFactory</initialContextFactory>

<participateInClientTransaction>false</participateInClientTransaction>
        </remoteClient>
        <soapClient>

<rootEndPointURL>http://my_host.us.example.com:8001</rootEndPointURL>
        </soapClient>
    </server>
</workflowServicesClientConfiguration>

30.8.4.2 Configuring Unique Cookie Context Paths for the Session Tracking Cookies

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 such as 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:

/my-application-context-root

30.8.4.3 Deploying oracle.soa.workflow.jar to a non-SOA Oracle WebLogic Server

The oracle.soa.workflow.jar shared library is needed on the non-SOA Oracle WebLogic Server. It is available from

ORACLE_JDEV_HOME\jdeveloper\soa\modules\oracle.soa.workflow_11.1.1

Use Oracle WebLogic Server Administration Console to deploy the JAR file.

To deploy oracle.soa.workflow.jar:

Go to Oracle WebLogic Server Administration Console at
```
http://remote_hostname:remote_portnumber/console
```
In the Domain Structure area, click Deployments.
Click Install, as shown in Figure 30-40.

Figure 30-40 Oracle WebLogic Server Administration Console: List of Deployments

Description of "Figure 30-40 Oracle WebLogic Server Administration Console: List of Deployments"

In the Path field, provide the following path and click Next.

ORACLE_JDEV_HOME/jdeveloper/soa/modules/oracle.soa.workflow_11.1.1/oracle.soa.workflow.jar

Keep the same name for the deployment and click Next, as shown in Figure 30-41.

Figure 30-41 Oracle WebLogic Server Administration Console: Install Applications Assistant

Description of "Figure 30-41 Oracle WebLogic Server Administration Console: Install Applications Assistant"
Select the Deploy as Library option and click Finish.
Confirm that the oracle.soa.workflow(11.1.1,11.1.1) library is in the Active state, as shown in Figure 30-42.

Figure 30-42 Oracle WebLogic Server Administration Console: The oracle.soa.workflow Active State

Description of "Figure 30-42 Oracle WebLogic Server Administration Console: The oracle.soa.workflow Active State"

See Defining the Foreign JNDI Provider on a non-SOA Oracle WebLogic Server, to continue.

30.8.4.4 Defining the Foreign JNDI Provider on a non-SOA Oracle WebLogic Server

Use Oracle WebLogic Server Administration Console to complete this portion of the task.

To define the foreign JNDI provider:

In the Domain Structure area, expand Services and click Foreign JNDI Providers.
Click New.
In the Name field, enter ForeignJNDIProvider-SOA, as shown in Figure 30-43, and click Next.

Figure 30-43 Creating a Foreign JNDI Provider

Description of "Figure 30-43 Creating a Foreign JNDI Provider"
Click the ForeignJNDIProvider-SOA link.
Do the following and click Save.
- For Initial Context Factory, enter weblogic.jndi.WLInitialContextFactory.
- For Provider URL, enter t3://soa_hostname:soa_portnumber/soa-infra.
  
  In a clustered environment, for Provider URL, enter http://soa_hostname:soa_portnumber/soa-infra.
- For User, enter weblogic.
- For Password, enter weblogic.
Figure 30-44 shows the page where you enter this information.

Figure 30-44 Defining the Foreign JNDI Provider

Description of "Figure 30-44 Defining the Foreign JNDI Provider"

See Defining the Foreign JNDI Provider Links on a non-SOA Oracle WebLogic Server, to continue.

30.8.4.5 Defining the Foreign JNDI Provider Links on a non-SOA Oracle WebLogic Server

Use Oracle WebLogic Server Administration Console to complete this portion of the task.

To define the foreign JNDI provider links:

In the Domain Structure area, expand Services and click Foreign JNDI Providers.
Click the ForeignJNDIProvider-SOA link.
Click the Links tab.
Click New.

Figure 30-45 shows the Links tab.

Figure 30-45 Defining the Foreign JNDI Provider Links: The Links Tab

Description of "Figure 30-45 Defining the Foreign JNDI Provider Links: The Links Tab"
Do the following and click OK.
- For Name, enter RuntimeConfigService.
- For Local JNDI Name, enter RuntimeConfigService.
- For Remote JNDI Name, enter RuntimeConfigService.
Figure 30-46 shows where you do this.

Figure 30-46 Defining the Foreign JNDI Provider Links: Link Properties

Description of "Figure 30-46 Defining the Foreign JNDI Provider Links: Link Properties"
Do the following and click OK.
- For Name, Local JNDI Name, Remote JNDI Name, enter ejb/bpel/services/workflow/TaskServiceBean.
- For Name, Local JNDI Name, Remote JNDI Name, enter ejb/bpel/services/workflow/TaskMetadataServiceBean.
- For Name, Local JNDI Name, Remote JNDI Name, enter TaskReportServiceBean.
- For Name, Local JNDI Name, Remote JNDI Name, enter TaskEvidenceServiceBean.
- For Name, Local JNDI Name, Remote JNDI Name, enter TaskQueryService.
- For Name, Local JNDI Name, Remote JNDI Name, enter UserMetadataService.

See Including a Grant for bpm-services.jar, to continue.

30.8.4.6 Including a Grant for bpm-services.jar

To include a grant for bpm-services.jar, edit the system-jazn-data.xml file and then restart the non-SOA Oracle WebLogic Server.

To include a grant for bpm-services.jar:

Locate the system-jazn-data.xml file by navigating to the domain directory, soa-infra, and then to
```
ORACLE_WEBLOGIC_INSTALL/user_projects/domains/your_domain_name/config/fmwconfig
```

In system-jazn-data.xml, add the following grant. (If all or some portion of the grant exists, then add only what is missing.)

<grant>
  <grantee>
   <codesource>
    <url>file: ORACLE_JDEV_HOME/jdeveloper/soa/modules/oracle.soa.workflow_
11.1.1/bpm-services.jar</url>
   </codesource>
  </grantee>
  <permissions>
   <permission>
    <class>oracle.security.jps.JpsPermission</class>
    <name>VerificationService.createInternalWorkflowContext</name>
   </permission>
  <permission>
  <class>oracle.security.jps.service.credstore.CredentialAccessPermission
  </class>
  <name>credstoressp.credstore.BPM-CRYPTO.BPM-CRYPTO</name>
  <actions>read,write</actions>
  </permission>
  <permission>
   <class>oracle.security.jps.JpsPermission</class>
   <name>IdentityAssertion</name>
   <actions>*</actions>
  </permission>
 </permissions>
</grant>

Restart the non-SOA Oracle WebLogic Server.

See Deploying the Application, to continue.

30.8.4.7 Deploying the Application

Deploy the application that contains the task form to a non-SOA Oracle WebLogic Server the same way other applications are deployed. When you set up the application server connection, specify the domain on the non-SOA server (the domain you specified in Step 1 of Including a Grant for bpm-services.jar.. See Deploying SOA Composite Applications for information on deploying applications.

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 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 Administering 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 Task details not found for this task 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.

See Using for information on how to act on tasks.

Note:

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 404 Not Found error is displayed rather than the message Details not available for task. To avoid the 404 Not Found 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.

Figure 30-47 Worklist Task Details Page

Description of "Figure 30-47 Worklist Task Details Page"

The task form is available in Oracle BPM Worklist after you log in. See How To Log In to the Worklist for instructions.

30.10 Displaying a Task in an Email Notification

Learn how to display a task in an email notification.

Figure 30-48 shows how an email task notification appears in email.

Figure 30-48 Email Task Notification

Description of "Figure 30-48 Email Task 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.
In the WorkflowLabels.properties file, modify the following strings:
```
TASK_NOTIF_MSG.WORKLIST_APPLICATION=Worklist Application
TASK_NOTIF_MSG.WORKSPACE_APPLICATION=Workspace Application
```
For more details on how to modify the resource bundle string, see the workflow-110-workflowCustomizations sample.
Update the Workflow Custom Classpath URL configuration parameter on your instance.
You do not have to deploy the WorkflowLabels.properties file as an application for it to work. Instead, you can do either of the following:
- Host it on the file system, using a URL beginning with file:/// to point to the appropriate location.
- Host the file in MDS, using a URL beginning with oramds:///....

30.10.2 Changing the URL of the Worklist Application in Task Notifications

To change the text in a task notification:

Log in to Oracle Enterprise Manager Fusion Middleware Control.
In the navigator, expand the SOA folder.
Right-click soa-infra, and select SOA Administration > Workflow Config > Task tab.

The Workflow Task Service Properties page appears.
Expand Advanced.

Modify the Worklist Application URL. For example, you can change an existing entry like this:

http://[HTTP_HOST]:[HTTP_PORT]/integration/worklistapp/TaskDetails?taskId=PC_HW_TASK_ID_TAG

to something like this:

http://[HTTP_HOST]:[HTTP_PORT]/patch/info/page.jspx?taskId=PC_HW_TASK_ID_TAG

For information about showing or hiding the URL of the Worklist Application, see How to Display the URL in Notifications.

30.11 Reusing the Task Flow Application with Multiple Human Tasks

You can reuse a single task flow application with multiple human tasks. To use this feature, all human tasks must have both the payload elements and the outcomes must be identical.

30.11.1 How To Reuse the Task Flow Application with Multiple Human Tasks

Open the TASKFLOW_PROJ_DIR\adfmsrc\hwtaskflow.xml file.
For each additional human task, add the following element inside the file (at the bottom just before </hwTaskFlows>):
```
<hwTaskFlow>
  <WorkflowName>$TASK_NAME</WorkflowName>
  <TaskDefinitionNamespace>$TASK_NAMESPACE</TaskDefinitionNamespace>
  <TaskFlowId>$TASK_FLOW_NAME</TaskFlowId>
  <TaskFlowFileName>$TASK_FLOW_FILENAME</TaskFlowFileName>
</hwTaskFlow
```
where:
- $TASK_NAME is replaced with the name of the human task inside the .task file (value of the <name> element).
- $TASK_NAMESPACE is replaced with the namespace of the human task inside the .task file (value of the attribute targetNameSpace of element <taskDefinition>).
- $TASK_FLOW_NAME is copied from the existing <hwTaskFlow>/<TaskFlowId> element.
- $TASK_FLOW_FILENAME is copied from the existing <hwTaskFlow>/<TaskFlowFileName> element.

30.11.2 How to Reuse the Task Flow Application with Different Actions

You can reuse a single task flow that has different actions for different tasks. To do this:

Define all actions in the task that you use to generate the taskflow.
In any given task, disable the actions that you do not want to include.