Using Java APIs for Oracle Human Workflows

In continuation of my previous blogpost where I had discussed how we can use the web service APIs for Human Workflow components in Oracle SOA Suite 11g this blog will discuss how we can use the JAVA API’s to query and interact with worklist task items.

The earlier blog post can be viewed here

https://beatechnologies.wordpress.com/2011/08/22/oracle-human-workflow-web-service-apis/

As previously discussed Oracle SOA Suite 11g has workflow API’s implemented both in JAVA as well as standard soap based web services. In some obvious cases there might be need to write some client side java code to interact with the workflow components.

Similar to the web service API’s I will talk about the two Java classes that is to be used for the purpose.

ITaskQueryService

This class provides a programmatic means for retrieving tasks, task details etc. To use this class to get access to task information and details we typically have to do the following

• Write a remote client to connect to the remote SOA Suite server from the java class and get a client object.
• Use an authentication method to authenticate a user and obtain an authenicated workflow context from the remote client object.
• Use the obtained workflow context and a task list method to retrieve tasks that match some filter criterion viz taskNumber as displayed on the worklist page or taskStatus.
• Use the context and a task details method to drill down on a task in the list (retrieve task details and actions that can be performed on the task)

ITaskService

The ITaskService class can be used to perform operations client operations on the task like adding/removing documents and comments, withdrawing/reassigning tasks, deleting/purging tasks etc.

The ITaskService uses the task query service to look up to a specific task and then do task operations on to them.

Writing the Java Client

I had followed the below steps to create a java client from the workflow classes.

Created a Java Project in JDeveloper and called it HumanTaskAPI. The libraries that have to be added to this project is shown below

Next create a class called TaskAuthenticationClient that would create a client object for the remote workflow service by looking up the server JNDI and also create a remote context for both the ITaskQueryService and ITaskService.

Here is the code snippet containing the explanatory comments along with it

package blog.oracletechnologies.sales;

import java.util.HashMap;
import java.util.Map;

import oracle.bpel.services.workflow.WorkflowException;
import oracle.bpel.services.workflow.client.IWorkflowServiceClient;
import oracle.bpel.services.workflow.client.IWorkflowServiceClientConstants;
import oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
import oracle.bpel.services.workflow.query.ITaskQueryService;
import oracle.bpel.services.workflow.task.ITaskService;

public class TaskAuthenticationClient {
public TaskAuthenticationClient() {
super();
}

public IWorkflowServiceClient getWorkflowServiceContext () throws WorkflowException {

//Create WorflowServiceClient by looking up to the service JNDI
String domainUrl ="t3://localhost:4003"; // host:port of the soa server
Map<IWorkflowServiceClientConstants.CONNECTION_PROPERTY, String> connProperties = new HashMap<IWorkflowServiceClientConstants.CONNECTION_PROPERTY, String>();
connProperties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.CLIENT_TYPE,WorkflowServiceClientFactory.REMOTE_CLIENT);
connProperties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_PROVIDER_URL,domainUrl);
connProperties.put(IWorkflowServiceClientConstants.CONNECTION_PROPERTY.EJB_INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory");
IWorkflowServiceClient workflowServiceClient = WorkflowServiceClientFactory.getWorkflowServiceClient(connProperties, null, null);
return workflowServiceClient;
}

//Get the task query service handle
public ITaskQueryService getTaskQueryServiceRemoteContext () throws WorkflowException {
ITaskQueryService taskQueryService = getWorkflowServiceContext().getTaskQueryService();
return taskQueryService;
}

public ITaskService getTaskServiceRemoteContext () throws WorkflowException {
//Get the task service handle
ITaskService taskService = getWorkflowServiceContext().getTaskService();
return taskService;
}
}

Next create a class TaskQueryServiceClient that has two methods viz queryWorklistTasks() and getTaskDetailsByNumber()  that fetches task details from the soa workflow component.

The queryWorklistTask() operation accepts tow inputs objects. One is a Predicate object that determines what tasks need to be queried, the ordering and paging of result etc. The other input is a list of queryColumns that determines which columns in the task detail will be part of the output Task object.

The complete Class with a main() is copied below

package blog.oracletechnologies.sales;

import java.io.StringWriter;

import java.util.ArrayList;
import java.util.List;

import javax.xml.transform.OutputKeys;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;

import oracle.bpel.services.workflow.IWorkflowConstants;
import oracle.bpel.services.workflow.WorkflowException;
import oracle.bpel.services.workflow.query.ITaskQueryService;
import oracle.bpel.services.workflow.repos.Predicate;
import oracle.bpel.services.workflow.repos.TableConstants;
import oracle.bpel.services.workflow.task.model.Task;
import oracle.bpel.services.workflow.verification.IWorkflowContext;

import org.w3c.dom.Element;

public class TaskQueryServiceClient {
public TaskQueryServiceClient() {
super();
}

public static IWorkflowContext getWorkflowContext () throws WorkflowException {
return getTaskQueryService().authenticate("weblogic", "welcome123".toCharArray(), null);
}
public static ITaskQueryService getTaskQueryService () throws WorkflowException {
TaskAuthenticationClient authenticationClient = new TaskAuthenticationClient();
ITaskQueryService taskQueryService =authenticationClient.getTaskQueryServiceRemoteContext();
return taskQueryService;
}
public static Predicate getTaskPredicate () throws WorkflowException {
Predicate statePredicate=  new Predicate(TableConstants.WFTASK_STATE_COLUMN,Predicate.OP_EQ,IWorkflowConstants.TASK_STATE_ASSIGNED);
return statePredicate;
}
public static List<String> getTaskQueryColumns () throws WorkflowException {
// Set up list of columns to query. Also remember that only these columns will be fetched in taskQuery.
List<String> queryColumns = new ArrayList<String>();
queryColumns.add("TASKNUMBER");
queryColumns.add("TASKID");
queryColumns.add("TASKNUMBER");
queryColumns.add("TITLE");
queryColumns.add("OUTCOME");
queryColumns.add("STATE");
queryColumns.add("PRIORITY");
return queryColumns;
}

public void queryWorklistTasks(Predicate statePredicate, List<String> queryColumns) throws WorkflowException
{
//Query a list of tasks - list of Task objects
List taskList = getTaskQueryService().queryTasks(getWorkflowContext(),
queryColumns, //Custom Defined QueryColumns list
null, // Do not query additional info
ITaskQueryService.AssignmentFilter.MY_AND_GROUP,
null, //No keywords
statePredicate, //Custom Defined Predicate
null, // No Task Ordering ordering
0,0);  // Do not page the query result
// Print exisiting Assigned tasks
if (taskList != null)
{
System.out.println("Result of queryTask Opeartion");
System.out.println("Total number of tasks: " + taskList.size());
System.out.println("Tasks List: ");
Task task = null;
for (int i = 0; i < taskList.size(); i++)
{
task = (Task) taskList.get(i);
System.out.println("Task Number: " + task.getSystemAttributes().getTaskNumber());
System.out.println("Task Id: " + task.getSystemAttributes().getTaskId());
System.out.println("Title: " + task.getTitle());
System.out.println("Priority: " + task.getPriority());
System.out.println("State: " + task.getSystemAttributes().getState());
}
}
}
public void getTaskDetailsByNumber(String taskNumber) throws WorkflowException,TransformerConfigurationException,TransformerException {
// Query a list of tasks - list of Task objects
Task task = getTaskQueryService().getTaskDetailsByNumber(getWorkflowContext(),Integer.valueOf(taskNumber));
// Print exisiting Assigned tasks
System.out.println("Result of getTaskDetailsByNumber Opeartion");
System.out.println("Task Number: " + task.getSystemAttributes().getTaskNumber());
System.out.println("Task Id: " + task.getSystemAttributes().getTaskId());
System.out.println("Title: " + task.getTitle());
System.out.println("Priority: " + task.getPriority());
System.out.println("State: " + task.getSystemAttributes().getState());
// This allows we to get the task payload (task data specific to our application). This is in XML format
List list = task.getPayload().getContent();
System.out.println("Task Payload : ");
for (int i = 0; i < list.size(); i++)
{
Element taskDetails = (Element) list.get(i);
printElement(taskDetails);
}
}
 public static void  printElement (Element element) throws TransformerConfigurationException,TransformerException
 {
TransformerFactory transFactory = TransformerFactory.newInstance();
Transformer transformer = transFactory.newTransformer();
StringWriter buffer = new StringWriter();
transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");
transformer.transform(new DOMSource(element),new StreamResult(buffer));
String str = buffer.toString();
System.out.println(str);
}
public static void main (String args[]) throws WorkflowException,TransformerConfigurationException,TransformerException
{
TaskQueryServiceClient taskQueryClient = new TaskQueryServiceClient();
taskQueryClient.queryWorklistTasks(getTaskPredicate(),getTaskQueryColumns());
taskQueryClient.getTaskDetailsByNumber("200783");
}
}

Running the java class will print the result of the task in the output console.

Finally the last thing that this article will show is a simple demonstration of how we can update an existing task with some extra comment. For this we would first need to fetch/query the specific task and use the ITaskService  class object to add an additional comment in the task.

Below is the TaskUpdateServiceClient class that has an addCommentToTask() method that takes a taskNumber as input and adds a user comment to it. This is very similar that we did with the Web service API.

The class also contains a main() method so that it can be run as a standalone class. Run the class and verify whether the comment has been added to the task comment section in the task.

package blog.oracletechnologies.sales;

import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.TransformerException;

import oracle.bpel.services.workflow.StaleObjectException;
import oracle.bpel.services.workflow.WorkflowException;
import oracle.bpel.services.workflow.task.ITaskService;
import oracle.bpel.services.workflow.task.model.Task;

public class TaskUpdateServiceClient {
public TaskUpdateServiceClient() {
super();
}

public static ITaskService getTaskService() throws WorkflowException
{
TaskAuthenticationClient authenticationClient =new TaskAuthenticationClient();
ITaskService taskService =authenticationClient.getTaskServiceRemoteContext();
return taskService;
}

public void addCommentToTask(String taskNumber) throws TransformerConfigurationException,TransformerException,WorkflowException,StaleObjectException
{
TaskQueryServiceClient taskQueryScvClient = new TaskQueryServiceClient();
Task task = taskQueryScvClient.getTaskQueryService().getTaskDetailsByNumber
(taskQueryScvClient.getWorkflowContext(),Integer.valueOf(taskNumber));

if (task != null)
{
TaskAuthenticationClient authenticationClient =new TaskAuthenticationClient();
authenticationClient.getTaskServiceRemoteContext().addComment(taskQueryScvClient.getWorkflowContext(), task, "Comment Added From Java Client");
}

}
public static void main (String args[]) throws WorkflowException,TransformerConfigurationException,TransformerException,StaleObjectException {
TaskUpdateServiceClient taskUpdateServiceClient = new TaskUpdateServiceClient();
taskUpdateServiceClient.addCommentToTask("200783");
}
}

As you can see in the screenshot above that the comment that we added from the Java client reflects in the task detail page of the worklist user interface.

The ITaskQueryService and ITaskService offers an large set of methods that can be used further to exhaustively query and interact with worklist tasks in the Human Workflow component.

The JDeveloper Java project used in this article can be downloaded from here.

Another important note is that if you plan to use the code in the examples above make sure to handle and throw errors judiciously by having a suitable try-catch mechanism.

.