For information about human task concepts, see Getting Started with Human Workflow .
For information about troubleshooting human workflow issues, see section "Human Workflow Troubleshooting" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
For information about installing and using the organizational hierarchy of users and groups known as the demo user community, see Appendix "Installing the Demo User Community in the Database" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
Oracle SOA Suite provides a graphical tool, known as the Human Task Editor, for modeling your task metadata.
The modeling process consists of the following:
Creating and modeling a human task service component in the SOA Composite Editor
Associating it with a BPEL process
Generating the task form for displaying the human task during runtime in Oracle BPEL Worklist Application.
To use the Human Task Editor, you must understand human task design concepts, including the following:
The types of users to which to assign tasks
The methods by which to assign users to tasks (statically, dynamically, or rule-based)
The task participant types available for modeling a task to which you assign users
The options for creating lists of task participants
The participants involved in the entire life cycle of a task
This section provides a brief overview of these modeling tasks and provides references to specific modeling instructions.
For more information about using the SOA Composite Editor, see Getting Started with Developing SOA Composite Applications.
For information about available samples, see Human Workflow Tutorial.
The Human Task Editor enables you to specify human task metadata such as task outcome, payload structure, assignment and routing policy, expiration and escalation policy, notification settings. This information is saved to a metadata task configuration file with a
.task extension. In addition, some workflow patterns may also need to use the Oracle Business Rules Designer to define task routing policies or the list of approvers.
After you create a Human Task you can configure its metadata using the Human Task Editor. For a detailed description of the metadata and configuration procedures, see Configuring Human Tasks .
You define the metadata for the human task in either of two ways:
By dragging a human task from the Components window into a BPEL process in Oracle BPEL Designer and clicking the Add icon in the Create Human Task dialog that automatically is displayed. This displays a dialog for creating the human task service component. When creation is complete, the Human Task Editor is displayed.
By dragging a human task service component from the Components window into the SOA Composite Editor. This displays a dialog for creating the human task component. When creation is complete, the Human Task Editor is displayed.
For more information, see Creating Human Tasks.
You can associate the
.task file that consists of the human task settings with a BPEL process in Oracle BPEL Designer. Association is made with a human task that you drag into your BPEL process flow for configuring, as shown in Figure 28-1.
Figure 28-1 Dragging a Human Task into a BPEL Process
You also specify the task definition, task initiator, task priority, and task parameter mappings that carry the input data to a BPEL variable. You can also define advanced features, such as the scope and global task variables names (instead of accepting the default names), task owner, identification key, BPEL callback customizations, and whether to extend the human task to include other workflow tasks.
When association is complete, a task service partner link is created. The task service exposes the operations required to act on the task.
You can also create the human task as a standalone component only in the SOA Composite Editor and not associate it with a BPEL process. Standalone human task service components are useful for environments in which there is no need for any automated activity in an application. In the standalone case, the client can create the task themselves.
For more information, see Associating Human Tasks with BPEL Processes.
You can generate a task form using the Oracle Application Development Framework (ADF). This form is used for displaying the task details on which you act at runtime in Oracle BPEL Worklist Application.
For information on generating the task form, see Designing Task Forms for Human Tasks .
The Human Task Editor enables you to define the metadata for the task. The editor enables you to specify human task settings, such as task outcome, payload structure, assignment and routing policy, expiration and escalation policy, notification settings, and so on.
You create a human task service component in the SOA Composite Editor or in Oracle BPEL Designer. After creation, you design the component in the Human Task Editor. The method by which you create the human task service component determines whether the component can be associated later with a BPEL process service component or is a standalone component in the SOA Composite Editor.
You can create a human task using the SOA Composite Editor. You can use this method to create a human task to later associate with a BPEL process or use as a standalone component.
To create a human task service component in the SOA Composite Editor:
Go to the SOA project in which to create a human task service component in the SOA Composite Editor.
From the Components window list, select SOA.
The list refreshes to display service components and service adapters.
From the list, drag a Human Task into the designer.
The Create Human Task dialog appears.
In the Name field, enter a name.
The name you enter becomes the
.task file name.
Note the Create Composite Service with SOAP Bindings check box. The selection of this check box determines how the human task service component is created.
To create a human task service component that you later associate with a BPEL process service component, do not select the Create Composite Service with SOAP Bindings check box. The human task service component is created as a component that you explicitly associate with a BPEL process service component. Figure 28-2 provides details.
Figure 28-2 Human Task Component
To create the human task service component as a standalone component in the SOA Composite Editor, select the Create Composite Service with SOAP Bindings check box. This creates a human task service component that is automatically wired to a Simple Object Access Protocol (SOAP) web service. Figure 28-3 provides details.
Figure 28-3 Standalone Human Task Component
This web service provides external customers with an entry point into the human task service component of the SOA composite application.
For more information about creating a human task service component in the SOA Composite Editor, see Getting Started with Developing SOA Composite Applications.
You can create a human task using Oracle BPEL Designer. Generally you use this method when you want to create a human task to use with a BPEL process.
To create a human task in Oracle BPEL Designer:
The Create Human Task dialog appears.
The name you enter becomes the
.task file name.
The Human Task Editor appears.
You can also create a human task that you later associate with a BPEL process by selecting New from the File main menu, then selecting SOA Tier > Service Components > Human Task.
When a human task is created, the following folders and files appear:
The human task settings specified in the Human Task Editor are saved to a metadata task configuration file in the metadata service (MDS) repository with a
.task extension. This file appears in the Applications window under SOA_Project_Name > SOA. You can re-edit the settings in this file by double-clicking the following:
.task file in the Applications window in either the SOA Composite Editor or Oracle BPEL Designer
The human task icon in the SOA Composite Editor or in your BPEL process in Oracle BPEL Designer.
This reopens the
.task file in the Human Task Editor.
A Human Tasks folder containing the human task you created appears in the Structure window of the SOA Composite Editor.
Figure 28-4 shows these folders and files.
Figure 28-4 Human Task Folders and Files
For information about available samples, see Human Workflow Tutorial.
After creating a human task, modify its settings using the Human Task Editor.
For more information on how to configure a human task, see Configuring Human Tasks .
You can save your human task changes at any time. The task can be re-edited at a later time by double-clicking the metadata task configuration
.task file in the Applications window.
To exit the Human Task Editor and save your changes:
To associate the human task service component created in the SOA Composite Editor with a BPEL process, follow these instructions. When association is complete, a task service partner link is created in Oracle BPEL Designer. The task service exposes the operations required to act on a task.
For more information about creating a human task, see Creating Human Tasks.
There are two ways to associate a human task service component with a BPEL process:
If you have created a human task service component in the SOA composite application, drag a human task activity into the BPEL process in Oracle BPEL Designer. Then, select the existing human task service component from the Task Definition list of the Create Human Task dialog. You can then specify the task title, initiator, parameter values, and other values.
If you have not created a human task service component, drag the human task activity into the BPEL process in Oracle BPEL Designer Then, click the Add icon to the right of the Task Definition list in the Create Human Task dialog. This action enables you to specify the name of the new human task service component, the parameters, and the outcomes. The Human Task Editor then opens for you to design the remaining task metadata. After design completion, close the Human Task Editor.
To associate a human task with a BPEL process:
.taskfile of the human task service component.
The Human Task dialog appears.
Figure 28-6 Task Definition List Selection
.task file of the human task service component is associated with the BPEL process.
After you complete association of your human task activity with a BPEL process and close the Create Human Task dialog, you can always re-access this dialog by double-clicking the human task activity in Oracle BPEL Designer.
If you delete the wire between a BPEL process and the human task service component that it invokes, the invoke activity of the human workflow is deleted from the BPEL process. However, the taskSwitch switch activity for taking action (contains the approve, reject, and otherwise task outcomes) is still there. This is by design for the following reasons:
The switch activity contains user-entered BPEL code.
The switch can be reused if the intention for deleting the wire is only to point to another human task.
Deleting the switch is a single-step action.
If you then drag and drop a human task service component into the BPEL process to use the same taskSwitch switch activity, a new taskSwitch switch activity is created. You then have two switch activities in the BPEL process with the same name. To determine which one to delete, you must go into the approve, reject, and otherwise task outcomes of the taskSwitch switch activities to determine which is the older, modified switch and which is the newer switch.
Figure 28-7 shows the General tab that displays after you select the human task.
Figure 28-7 Human Task — General Tab (After Selection)
The General tab of the Human Task activity enables you to perform the tasks shown in Table 28-1:
The title displays the task in Oracle BPEL Worklist Application during runtime. This is a mandatory field. Your entry in this field overrides the task title you entered in the Task Title field of the General section of the Human Task Editor described in How to Specify a Task Title.
In the Task Title field of the General tab, enter the task title by entering the title manually. Alternatively, click the icon to the right of the field to display the Expression Builder dialog to dynamically create the title.
You can also combine static text and dynamic expressions in the same title. To include dynamic text, place your cursor at the appropriate point in the text and click the icon on the right to invoke the Expression Builder dialog.
You can specify a task initiator. The initiator is the user who initiates a task. The initiator can view their created tasks from Oracle BPEL Worklist Application and perform specific tasks, such as withdrawing or suspending a task.
To specify the task initiator and task priority:
jcooper) or click the icon to display the Expression Builder dialog for dynamically specifying an initiator. This field is optional. If not specified, the initiator defaults to the task owner specified on the Advanced tab of the Human Task dialog. The initiator defaults to
bpeladminif a task owner is also not specified.
For more information about specifying the priority in the Human Task Editor, see How to Specify a Task Title.
The task parameter table shown in Figure 28-8 displays a list of task parameters after you complete the Task Title and Initiator fields.
Figure 28-8 Task Parameter Table
To specify task parameters:
The Task Parameters dialog appears.
Figure 28-9 Variables Tree
Figure 28-11 shows the Advanced tab.
Figure 28-11 Create Human Task — Advanced Tab
The Advanced tab of the Human Task activity enables you to perform the tasks shown in Table 28-2:
Table 28-2 Human Task - Advanced Tab
|For this Field...||See...|
Global Task Variable Name
Include task history from
You are automatically provided with default scope and global task variable names during human task activity creation. However, you can specify custom names that are used to name the scope and global variable during human task activity creation.
To specify a scope name and a global task variable name:
This BPEL scope encapsulates the entire interaction with the workflow service and BPEL variable manipulation.
This is the name of the BPEL task variable used for the workflow interaction.
The task owner can view tasks belonging to business processes they own and perform operations on behalf of any of the task assignees. Additionally, the owner can also reassign, withdraw, or escalate tasks.
If you do not specify a task initiator on the General tab of the Human Task dialog, it defaults to the owner specified here. In the Owner field of the Advanced tab, enter the task owner name or click the icon to the right to use the Expression Builder to dynamically specify the owner of this task.
The identification key can be used as a user-defined ID for the task. For example, if the task is meant for approving a purchase order, the purchase order ID can be set as the identification key of the task. Tasks can be searched from Oracle BPEL Worklist Application using the identification key. This attribute has no default value.
In the Identification Key field of the Advanced tab, enter an optional identification key value to specify a key.
The identity realm name is used for the task when multiple realms are configured. You cannot have assignees from multiple realms working on the same task. This field is required if you are using multiple realms. To specify an identity context, in the Identity Context field of the Advanced tab, enter a value
The stripe name of the application contains the application roles used in the task. To specify an application context, in the Application Context field of the Advanced tab, enter a value.
This feature enables one human task to be continued with another human task. There are many scenarios in which you have related tasks in a single BPEL process. For example, assume you have the following:
A procurement process to obtain a manager's approval for a computer
Several BPEL activities in between
Another task for the IT department to buy the computer
The participant of the second task may want to see the approval history, comments, and attachments created when the manager approved the purchase. You can link these different tasks in the BPEL process by chaining the second task to the first task with this option.
For chained tasks, the title of the new task cannot be set from the task metadata (
.task file). For example, assume existing Task A is chained with new task Task B, and Task B has a new title set in the Human Task Editor; this title is not recognized. Therefore, if the chained task requires a different title, it must be set in the task instance before calling the task service
reinitiate operation. If a BPEL process is initiating the tasks, set the task title before the workflow service APIs are called. If a Java program is calling the workflow APIs programatically, then it must set the title.
To include the task history of other tasks:
When a human task is continued with another human task, the following information is carried over to the new workflow:
Task payload and the changes made to the payload in the previous workflow
Comments added to the task in the previous workflow
Attachments added to the task in the previous workflow
In the Include task history from list, all existing workflows are listed.
For example, a hiring process is used to hire new employees. Each interviewer votes to hire or not hire a candidate. If 75% of the votes are to hire, then the candidate is hired; otherwise, the candidate is rejected. If the candidate is to be hired, an entry in the HR database is created and the human resources contact completes the hiring process. The HR contact also must see the interviewers and the comments they made about the candidate. This process can be modeled using a parallel participant type for the hiring. If the candidate is hired, a database adapter is used to create the entry in the HR database. After this action, a simple workflow can include the task history from the parallel participant type so that the hiring request, history, and interviewer comments are carried over. This simple workflow is assigned to the HR contact.
Clear old payload and recreate
This option is applicable when the payload attributes in the XML files of the human tasks involved in this extended workflow are different. For example, the payload attribute for the human task whose history you are including has three extra attributes than the payload of the other human task.
Use existing payload
This option is applicable when the payload attributes in the XML files of the human tasks involved in this extended workflow are the same.
When you have completed modeling the human task activity, the human task is generated in the designer.
Figure 28-12 shows how a workflow interaction is modeled. Figure 28-12 also illustrates the interaction when no BPEL callbacks are modeled. In this case, after a task is complete, the BPEL process is called back with the completed task. No intermediary events are propagated to the BPEL process instance. It is recommended that any user customizations be done in the first assign, AssignTaskAttributes, and that AssignSystemTaskAttributes not be changed.
Figure 28-12 Workflow Interaction Modeling
Click the Expand icon next to the human task activity in Oracle BPEL Designer to display its contents, as shown in Figure 28-13.
Figure 28-13 Expanding the Human Task Activity
If intermediary events must be propagated to the BPEL process instance, select the Allow task and routing customization in BPEL callbacks check box in the Events section of the Human Task Editor. When this option is selected, the workflow service invokes callbacks in the BPEL instance during each update of the task. The callbacks are listed in the
TaskService.wsdl file and described as follows:
This callback is invoked when the task is completed, expired, withdrawn, or errored.
This callback is invoked when the task is assigned to a new set of assignees due to the following actions:
Skip current assignment
Override routing slip
This callback is invoked for any other update to the task that does not fall in the
onTaskAssigned callback. This includes updates on tasks due to a request for information, a submittal of information, an escalation, a reassign, and so on.
This callback is invoked for any update to a subtask.
Figure 28-14 shows how a workflow interaction with callbacks is modeled. After this task is initiated, a while loop is used to receive messages until the task is complete. The while loop contains a pick with four onMessage branches — one for each of the above-mentioned callback operations. The workflow interaction works fine even if nothing is changed in the onMessage branches, meaning that customizations in the onMessage branches are not required.
In this scenario, a workflow context is captured in the BPEL instance. This context can be used for all interaction with the workflow services. For example, to reassign a task if it is assigned to a group, then you need the workflow context for the
reassignTask operation on the task service.
It is recommended that any user customizations be performed in the first assign, AssignTaskAttributes, and that AssignSystemTaskAttributes not be changed.
Figure 28-14 Workflow Interaction Modeling (with Callbacks)
If you must change a generated human task activity, note the following details:
Do not modify the assign tasks that are automatically created in a switch activity when you add a human task to a BPEL process flow. Instead, add a new assign activity outside the switch activity.
If the parameter passed into a human task is modified (for example, you change the parameter type in the Edit Task Parameter dialog), you must open the human task activity in the BPEL process flow and click OK to correct the references to the payload variable. Not doing so causes the parameter name to change and become uneditable.
If the task outcomes in the Human Task Editor are modified, you must edit the human task activity and click OK. The switch case is then updated based on the changes to the outcomes.
If you make any changes to the translatable strings of the title or category of a task in the resource bundle, those changes do not appear in any instances of that task that are already initiated. However, they do appear in instances of that task that are initiated after you make the changes.
When you copy comments to a human task, make sure that those comments do not contain the task ID. The taskId element must be empty.
Deleting a partner link that was generated by a human task (for example, human_task_name.TaskService in the Partner Links swimlane) causes the human task to become unusable. If you delete the partner link, you must delete the human task activity in Oracle BPEL Designer and start over again.
In many cases, the outcome of a task determines the flow of the business process. To facilitate modeling of the business logic, when a user task is generated, a BPEL switch activity is also generated with prebuilt BPEL case activities. By default, one case branch is created for each outcome selected during creation of the task. An otherwise branch is also generated in the switch to represent cases in which the task is withdrawn, expired, or in error.
The task carries a payload in it. If the payload is set from a business process variable, then an assign activity with the name
copyPayloadFromTask is created in each of the case and otherwise branches to copy the payload from the task back to its source. If the payload is expressed as other XPath expressions (such as
ora:getNodes(...)), then this assign is not created because of the lack of a process variable to copy the payload back. If the payload does not require modification, then you can remove the assign generated in the switch-case after the task scope.
By default, the switch activity contains case statements for the outcomes only. The other task conclusions are captured in the otherwise branch. These conclusions are as follows:
The task is withdrawn.
The task is in error.
The task is expired.
If business logic must be added for each of these other conclusions, then case statements can be added for each of the preceding conditions. The case statements can be created as shown in the following BPEL segment. The XPath conditions for the other conclusions in the case activities for each of the preceding cases are shown in bold in the following example:
<switch name="taskSwitch"> <case condition="bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'COMPLETED' and bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:conclusion') = 'ACCEPT'"> <bpelx:annotation> <bpelx:pattern>Task outcome is ACCEPT </bpelx:pattern> </bpelx:annotation> ... </case> <case condition= "bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'WITHDRAWN'"> <bpelx:annotation> <bpelx:pattern>Task is withdrawn </bpelx:pattern> </bpelx:annotation> ... </case> <case condition= "bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'EXPIRED'"> <bpelx:annotation> <bpelx:pattern>Task is expired </bpelx:pattern> </bpelx:annotation> ... </case> <case condition= "bpws:getVariableData('SequentialWorkflowVar1', '/task:task/task:state') = 'ERRORED'"> <bpelx:annotation> <bpelx:pattern>Task is errored </bpelx:pattern> </bpelx:annotation> ... </case> <otherwise> <bpelx:annotation> <bpelx:pattern>Task is EXPIRED, WITHDRAWN or ERRORED </bpelx:pattern> </bpelx:annotation> ... </otherwise> </switch>
To enable text files to be attached to a human task, you must set a flag that describes whether the content of text attachments is encoded. This flag is named
isContentEncoded.You can set this flag by customizing the BPEL code in any Human Workflow sample that includes a human task. To do this customization, in the
.bpel file in the sample, enter the following copy rule in the BPEL assign activity code:
<copy> <from>true()</from> <to>$initiateTaskInput.payload/task:task/task:attachment/task:isContentEncoded </to> </copy>
Once you have entered this copy rule, you can either save the file and continue designing the BPEL process or, if you have finished designing, you can deploy the process.