Managing Tasks

Tasks are defined as part of the template definition creation process, as described in Creating a Template Definition.

This section describes how to manage tasks, including the following topics:

• Getting Tasks

• Assigning a Task

• Getting Task Counts

• Marking a Task Complete or Incomplete

• Setting Task Properties

For more information about the methods described in this section, see the com.bea.server.admin.Admin Javadoc. For information about managing tasks using the WebLogic Integration Studio, see Defining Workflow Templates in Using the WebLogic Integration Studio.

 

---

Getting Tasks

To get a list of the tasks defined for a particular workflow template, use one of the following com.bea.wlpi.server.admin.Admin methods:

public javautil.List getTasks(
  java.lang.String assigneeId,
  java.lang.String orgId,
  boolean role
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

public javautil.List getTasks(
  java.lang.String assigneeId,
  java.lang.String orgId,
  boolean role,
  boolean incompleteonly,
  boolean sortAscending
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the parameters for the getTasks() method for which you must specify values.

Table 15-1 getTasks() Method Parameters  

Parameter	Description	Valid Values
assigneeId	ID of the assignee (user or role) for whom you want to get a list of tasks.	String specifying a valid user or role. For information about getting a list of current users or roles, see Configuring the Security Realms.
orgId	ID of the organization for which you want to get tasks.	String specifying a valid organization ID. For information about getting a list of all organization IDs, see Getting All Organizations.
role	Boolean flag specifying whether the assignee specified for the assigneeId parameter is a role (true) or user (false).	true (role) or false (user).
incompleteonly	Boolean flag specifying whether you want to return only those tasks that are incomplete (true) or all tasks (false).	true (incomplete tasks only) or false (all tasks).
sortAscending	Boolean flag specifying whether to sort tasks in ascending order (true) or descending order (false) based on time and date stamp.	true (ascending order) or false (descending order).

 

Each method returns a list of com.bea.wlpi.common.TaskInfo objects. To access information about each task, use the TaskInfo object methods described in TaskInfo Object.

For example, the following code gets a list of the tasks for the ROLE1 role (notice that the role parameter is set to true) in the ORG1 organization. In this example, admin represents the EJBObject reference to the Admin EJB.

List taskList = admin.getTasks("ROLE1", "ORG1", true);

For more information about the getTasks() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

 

---

Assigning a Task

To change the user or role to which a task is assigned, or to unassign a task, use the following com.bea.wlpi.server.admin.Admin methods, respectively:

public void taskAssign(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String taskId,
  java.lang.String assignTo,
  boolean bRole,
  boolean bLoadBalance
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

public void taskUnassign(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String taskId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the parameters required by the taskAssign() and taskUnassign() methods for which you must specify values.

Table 15-2 taskAssign() and taskUnassign() Method Parameters  

Parameter	Description	Valid Values	Valid For . . .
			taskAssign()	taskUnassign()
templateDefinitionId	ID of the template definition from which the workflow instance containing the task was instantiated.	String specifying a valid template definition ID. To get the template definition ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getTemplateDefinitionId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.	+	+
instanceId	ID of the workflow instance containing the task.	String specifying a valid instance ID. To get the instance ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getInstanceId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.	+	+
taskId	ID of the task that you want to assign or unassign.	String specifying a valid task ID. To get the task ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getTaskId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.	+	+
assignTo	ID of the assignee (user or role) to whom you want to assign tasks.	String specifying a valid user or role. For information about getting a list of current users or roles, see Configuring the Security Realms.	+
bRole	Boolean flag specifying whether or not the assignee specified for the assigneeId parameter is a role (true) or user (false).	true (role) or false (user).	+
bLoadBalance	Boolean flag specifying whether or not load balancing should be performed within the specified role. (This setting is valid only if the bRole value is set to true.)	true (perform load balancing) or false (do not perform load balancing).	+

 

The actual assignee to whom the task is assigned depends on the following:

• Whether any task reroutings currently exist for the specified assignee.

• Whether or not the bRole and bLoadBalance arguments are set to true, indicating that load balancing is in effect. In this case, the WebLogic Integration process engine reviews the number of tasks assigned to all users in a role (for whom there are no reroutings currently in effect), identifies the user with the least number of assigned tasks, and assigns the task to this user.

For example, the following code assigns a task to the user joe. In this example, admin represents the EJBObject reference to the Admin EJB.

admin.taskAssign(
  task.getTemplateDefinitionId(), 
  task.getInstanceId(), 
  task.getTaskId(), 
  "joe", 
  false, 
  false
);

The following code unassigns the same task.

admin.taskUnassign(
  task.getTemplateDefinitionId(), 
  task.getInstanceId(), 
  task.getTaskId(), 
  "joe", 
  false, 
  false
);

The template definition, workflow instance, and task IDs are obtained using the methods associated with the com.bea.wlpi.common.TaskInfo object, task. The task object can be obtained using the methods described in Getting Tasks.

For more information about the com.bea.wlpi.common.TaskInfo methods, see TaskInfo Object, or the com.bea.wlpi.common.TaskInfo Javadoc.

For more information about the taskAssign() and taskUnassign() methods, see the com.bea.wlpi.server.admin.Admin Javadoc.

 

---

Getting Task Counts

To get the number tasks assigned to a particular user, use the following com.bea.wlpi.server.admin.Admin method:

public int[] getTaskCounts(
	java.lang.String assigneeId,
	java.lang.String orgId,
	boolean isRole
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the parameters for the second getTaskCounts() method for which you must specify values.

Table 15-3 getTasks() Method Parameters  

Parameter	Description	Valid Values
assigneeId	ID of assignee (role or user) for whom to get tasks.	Valid user or role ID. For information about getting a list of current users or roles, see Configuring the Security Realms.
orgId	ID of the organization for which you want to get tasks.	String specifying a valid organization ID. For information about getting a list of all organization ids, see Managing the Active Organization.
isRole	Boolean flag specifying whether or not the assignee specified for the assigneeId parameter is a role or user.	true (role) or false (user)

This method returns an array of five elements, as defined in the following table.

Table 15-4 getTaskCounts() Method Array Elements  

Element	Description
TASKCOUNT_TOTAL	Total number of tasks assigned to the user/role.
TASKCOUNT_PENDING	Number of assigned tasks that are pending.
TASKCOUNT_INACTIVE	Number of assigned tasks that are inactive.
TASKCOUNT_COMPLETED	Number of assigned tasks that are completed.
TASKCOUNT_OVERDUE	Number of assigned tasks that are overdue.

 

For example, the following code gets the task counts for the current user, and stores the counts in the taskCounts[] array. In this example, admin represents the EJBObject reference to the Worklist EJB.

int taskCounts[] = admin.getTaskCounts("ROLE1", "ORG1", true);

Task counts are stored in the elements fo the taskCounts[] array. For example, taskCounts[TASKCOUNT_TOTAL] specifies the task count total, taskCounts[TASKCOUNT_PENDING] specifies the pending task count total, and so on.

For more information about the getTaskCounts() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

 

---

Marking a Task Complete or Incomplete

To mark a task as complete (done) or incomplete (undone), use the following com.bea.wlpi.server.admin.Admin methods, respectively:

public void taskMarkDone(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String taskId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

public void taskUnmarkDone(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String taskId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the taskMarkDone() and taskUnmarkDone() method parameters for which you must specify values.

Table 15-5 taskMarkDone() and taskUnmarkDone() Method Parameters  

Parameter	Description	Valid Values
templateDefinitionId	ID of the template definition from which the workflow instance containing the task was instantiated.	String specifying a valid template definition ID. To get the template definition ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getTemplateDefinitionId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.
instanceId	ID of the workflow instance containing the task.	String specifying a valid instance ID. To get the instance ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getInstanceId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.
taskId	ID of the task that you want to mark complete or incomplete.	String specifying a valid task ID. To get the task ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getTaskId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.

 

The taskMarkDone() method sets the task Completed value to the current date and time, and results in the sequential execution of all the actions associated with the specified task's Marked Done event. The taskMarkDone() method, however, has no effect on a task that has already been marked complete. For information about defining the Marked Done event for a task, see "Working with Nodes" in Defining Workflow Templates in Using the WebLogic Integration Studio.

The taskUnmarkDone() method clears the Completed date. The method does not result in the execution of the actions associated with the specified task's Activated event.

For example, the following code marks the specified task as complete, sets the Completed value to the current date and time, and executes the actions associated with the specified task's Marked Done event. In this example, admin represents the EJBObject reference to the Admin EJB.

admin.taskMarkDone(
  task.getTemplateDefinitionId(), 
  task.getInstanceId(), 
  task.getTaskId()
);

The following code marks the same task as incomplete, and clears the Completed date:

admin.taskMarkUndone(
  task.getTemplateDefinitionId(),
  task.getInstanceId(),
  task.getTaskId()
);

The template definition, workflow instance, and task IDs are obtained using the methods associated with the com.bea.wlpi.common.TaskInfo object, task. The task object can be obtained using the methods described in Getting Tasks.

For more information about the com.bea.wlpi.common.TaskInfo methods, see TaskInfo Object, or the com.bea.wlpi.common.TaskInfo Javadoc.

For more information about the taskMarkDone() and taskMarkUndone() methods, see the com.bea.wlpi.server.admin.Admin Javadoc.

 

---

Setting Task Properties

To set task properties, use following com.bea.wlpi.server.admin.Admin method:

public void taskSetProperties(
  java.lang.String templateDefinitionId,
  java.lang.String instanceId,
  java.lang.String taskId,
  int priority,
  boolean doneWithoutDoit,
  boolean doitIfDone,
  boolean unmarkDone,
  boolean modify,
  boolean reassign
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the taskSetProperties() method parameters for which you must specify values.

Table 15-6 taskSetProperties() Method Parameters  

Parameter	Description	Valid Values
templateDefinitionId	ID of the template definition corresponding to the task.	String specifying a valid template definition ID. To get the template definition ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getTemplateDefinitionId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.
instanceId	ID of the workflow instance corresponding to the task.	String specifying a valid instance ID. To get the instance ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getInstanceId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.
taskId	ID of the task that you want to mark complete or incomplete.	String specifying a valid task ID. To get the task ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getTaskId() For information about getting the TaskInfo object, see Getting Tasks. For more information about the methods available to the TaskInfo object, see TaskInfo Object.
priority	Task priority.	0=low, 1=medium, or 2=high.
doneWithoutDoIt	Permission to mark task as complete using the methods described in Marking a Task Complete or Incomplete.	true (enabled) or false (disabled).
doitIfDone	Permission to execute a task after it has been marked as complete using the method described in Executing a Task.	true (enabled) or false (disabled).
unmarkDone	Permission to mark a task as incomplete using the methods described in Marking a Task Complete or Incomplete.	true (enabled) or false (disabled).
modify	Permission to modify the task run-time properties using the taskSetProperties() method.	true (enabled) or false (disabled).
reassign	Permission to reassign a task to another participant using the method described in Assigning a Task	true (enabled) or false (disabled).

 

For example, the following code sets the default task priority to medium (1) and enables (sets to true) all other task properties. In this example, admin represents the EJBObject reference to the Admin EJB.

admin.taskSetProperties(
   task.getTemplateDefinitionId(), 
   task.getInstanceId(), 
   task.getTaskId(), 
   1, 
   true, 
   true, 
   true, 
   true, 
   true
);

The template definition, workflow instance, and task IDs are obtained using the methods associated with the com.bea.wlpi.common.TaskInfo object, task. The task object can be obtained using the methods described in Getting Tasks.

For more information about the com.bea.wlpi.common.TaskInfo methods, see TaskInfo Object, or the com.bea.wlpi.common.TaskInfo Javadoc.

For more information about the taskSetProperties() method, see the com.bea.wlpi.server.admin.Admin Javadoc.