Monitoring Run-Time Workflow Instances

This section describes how to monitor run-time workflow instances, including the following topics:

• Getting Workflow Instances

• Checking for Workflow Instances

• Getting Workflow Instance Tasks

• Getting Workflow Instance Information

• Getting a Count of Workflow Instances

• Deleting Workflow Instances

• Querying the Run-Time Workload

• Querying the Run-Time Statistics

For information about monitoring run-time workflow instances using the WebLogic Integration Studio, see Monitoring Workflows in Using the WebLogic Integration Studio.

 

---

Getting Workflow Instances

To get a list of template and template definition instances in an organization, use the following com.bea.wlpi.server.admin.Admin methods, respectively.

Method 1

public java.util.List getTemplateInstances(
  java.lang.String templateId,
  java.lang.String orgId,
  boolean bStarted,
  java.util.Date from,
  java.util.Date to,
  int start,
  int max
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

Method 2

public java.util.List getTemplateDefinitionInstances(
  java.lang.String templateDefinitionId,
  java.lang.String orgId,
  boolean bStarted,
  java.util.Date from,
  java.util.Date to,
  int start,
  int max
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

Table 22-1 getTemplateInstances() and getTemplateDefinitionInstances() Method Parameters  

Parameter	Description	Valid Values
templateId	ID of the template for which you want to get instances.	Valid template ID. To get the template ID, you need to obtain the TemplateInfo object corresponding to the template for which you want to get instances, as described in Getting the Templates for an Organization. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateInfo object, see TemplateInfo Object. The getId() method returns the templateId. Each templateId may have multiple definitions. To determine which template definition to use, WebLogic Integration selects the version with the most relevant effective date (current or past) and expiration date (current or future) from the set of active template definitions. For information about defining the effective and expiration dates for the template definitions and about how to make them active, see Defining Workflow Templates in Using the WebLogic Integration Studio.
templateDefinitionId	ID of the template definition for which you want to get instances.	Valid template definition ID. To get the template definition ID, you need to obtain the TemplateDefinitionInfo object corresponding to the template definition for which you want to get instances, as described in Creating a Template Definition. To get the template definition ID, use the following com.bea.wlpi.common.TemplateDefinitionInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateDefintionInfo object, see TemplateDefinitionInfo Object.
orgId	ID of the organization for which you want to get template or template definition instances.	Valid organization ID. For information about getting the organization IDs, see Managing the Active Organization.
bStarted	Boolean flag specifying whether to query by start date or completion date.	true (instance start date is used for the query) or false (instance completion date is used for the query).
from	Lower bound of the date range.	java.util.Date object.
to	Upper bound of the date range.	java.util.Date object.
start	Offset at which the returned list starts, enabling clients to display long lists incrementally.	Integer value.
max	Maximum number of items to return, enabling clients to limit the number of items displayed at one time.	Integer value.

 

These methods return a list of com.bea.wlpi.common.InstanceInfo objects corresponding to the template and template definition instances, respectively. To access information about each instance, use the InstanceInfo object methods described in InstanceInfo Object.

For example, the following code gets all template and template definition instances, respectively, corresponding to the specified ID value, for the organization specified by the value of the activeOrgId variable. In this example, admin represents the EJBObject reference to the Admin EJB.

List tempinst = admin.getTemplateInstances(templateId,
   activeOrgId, true, dateFrom, dateTo, 20, 20);

List tempdefinst = admin.getTemplateDefinitionInstances(
   templatedefId, activeOrgId, true, dateFrom, 
   dateTo, 20, 20);

In the examples, the following parameters are set:

• bStarted is set to true, so information is queried by the start date.

• Lower and upper bounds of the date range are set using the dateFrom and dateTo java.util.Date object variables, respectively.

• Offset value is set to 20.

• Maximum number of values displayed at any given time is set to 20.

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

 

---

Checking for Workflow Instances

This section describes the methods that you can use to check for a workflow template or template definition instance.

Checking for a Workflow Template Instance

To check whether a workflow template instance is currently running, use the following com.bea.wlpi.server.admin.Admin method:

public boolean checkForTemplateInstances(
  java.lang.String templateId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the checkForTemplateInstances() method parameter for which you must specify a value.

Table 22-2 checkForTemplateInstances() Method Parameter  

Parameter	Description	Valid Values
templateId	ID of the template for which you want to check for running instances.	Valid template ID. To get the template ID, you need to obtain the TemplateInfo object corresponding to the template for which you want to check for instances, as described in Getting the Templates for an Organization. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateInfo object, see TemplateInfo Object. The getId() method returns the templateId. Each templateId may have multiple definitions. To determine which template definition to use, WebLogic Integration selects the version with the most relevant effective (current or past) and expiration (current or future) dates from the set of active template definitions. For information about defining the effective and expiration dates for the template definitions, and about how to make them active, see Defining Workflows Templates in Using the WebLogic Integration Studio.

The method returns a Boolean value indicating whether or not a template instance exists.

For example, the following code checks whether a template instance, corresponding to the specified ID value, is currently running. admin represents the EJBObject reference to the Admin EJB.

boolean tempexists = admin.checkForTemplateInstances(templateId);

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

Checking for a Workflow Template Definition

To check for a workflow template definition instance, use the following com.bea.wlpi.server.admin.Admin method:

public java.util.List checkForTemplateDefinitionInstances(
  java.lang.String templateDefinitionId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the checkForTemplateDefinitionInstances() method parameter for which you must specify a value.

Table 22-3 checkForTemplateInstances() Method Parameter  

Parameter	Description	Valid Values
templateDefinitionId	ID of the template definition for which you want to check for instances.	Valid template definition ID. To get the template definition ID, you need to obtain the TemplateDefinitionInfo object corresponding to the template definition for which you want to get instances, as described in Creating a Template Definition. To get the template definition ID, use the following com.bea.wlpi.common.TemplateDefinitionInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateDefintionInfo object, see TemplateDefinitionInfo Object.

 

The method returns a Boolean value indicating whether or not a template or template definition instance exists.

For example, the following code checks whether or not any template definition instances exist corresponding to the specified ID value. In this example, admin represents the EJBObject reference to the Admin EJB.

boolean tempexists = admin.checkForTemplateInstances(templateId);

boolean tempdefexists = admin.checkForTemplateDefinitionInstances(
   templateDefinitionId);

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

 

---

Getting Workflow Instance Tasks

To get a list of tasks in a workflow instance, use the following com.bea.wlpi.server.admin.Admin method:

public java.util.List getInstanceTasks(
  java.lang.String instanceId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the getInstanceTasks() method parameter for which you must specify a value.

Table 22-4 getInstanceTasks() Method Parameter  

Parameter	Description	Valid Values
instanceId	ID of the workflow instance for which you want to get tasks.	Valid workflow instance ID. To obtain the workflow instance ID, you need to obtain the InstanceInfo object corresponding to the instance for which you want to get tasks, as described in Getting Workflow Instances. To get the instance ID, use the following com.bea.wlpi.common.InstanceInfo method: public final java.lang.String getId() Note: For more information about the methods available to the InstanceInfo object, see InstanceInfo Object.

The 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 the tasks for the workflow instance specified by the value of the instanceId variable. admin represents the EJBObject reference to the Admin EJB.

List tasks = admin.getInstanceTasks(instanceId);

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

 

---

Getting Workflow Instance Information

To get workflow instance information, use the following com.bea.wlpi.server.admin.Admin method:

public com.bea.wlpi.common.InstanceInfo getInstanceInfo(
  java.lang.String instanceId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the getInstanceInfo() method parameter for which you must specify a value.

Table 22-5 getInstanceTasks() Method Parameter  

Parameter	Description	Valid Values
instanceId	ID of the workflow instance for which you want to get information.	Valid workflow instance ID. To obtain the workflow instance ID, you need to obtain the TaskInfo object corresponding to the task for which you want to get workflow instance information, as described in Getting Tasks. To get the task ID, use the following com.bea.wlpi.common.TaskInfo method: public final java.lang.String getInstanceId() Note: For more information about the methods available to the TaskInfo object, see TaskInfo Object.

The method returns a com.bea.wlpi.common.InstanceInfo object. To access information about the workflow instance, use the InstanceInfo object methods described in InstanceInfo Object.

For example, the following code gets the information for the workflow instance specified by the value of the instanceId variable. admin represents the EJBObject reference to the Admin EJB.

InstanceInfo = admin.getInstanceInfo(instanceId);

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

 

---

Getting a Count of Workflow Instances

To get a count of workflow instances and/or completed workflow instances, use the following com.bea.wlpi.server.admin.Admin methods, respectively.

Method 1

public int getInstanceCount(
  java.lang.String templateId
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

Method 2

public int getInstanceCount(
  java.lang.String templateI,
  boolean completed
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

Table 22-6 getInstanceCount() Method Parameters  

Parameter	Description	Valid Values
templateId	ID of the template for which you want to get instances.	Valid template ID. To get the template ID, you need to obtain the TemplateInfo object corresponding to the template for which you want to get instances, as described in Getting the Templates for an Organization. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateInfo object, see TemplateInfo Object. The getId() method returns the templateId. Each templateId may have multiple definitions. To determine which template definition to use, WebLogic Integration selects the version with the most relevant effective date (current or past) and expiration date (current or future) from the set of active template definitions. For information about defining the effective and expiration dates for the template definitions and about how to make them active, see Defining Workflow Templates in Using the WebLogic Integration Studio.
completed	Boolean flag specifying whether to count completed workflow instances only.	true (count completed workflow instances only) or false (count all workflow instances).

 

Each method returns an integer value corresponding to the number of workflow instances counted based on the specified criteria.

For example, the following code gets the count of all workflow instances and all completed workflow instances, respectively, corresponding to the specified ID value. In this example, admin represents the EJBObject reference to the Admin EJB.

int count = admin.getInstanceCount(templateId);

int completeCount = admin.getInstanceCount(templateId, true);

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

 

---

Deleting Workflow Instances

Using the methods described in this section, you can delete:

• A specific workflow instance

• All workflow instances in an organization

Deleting a Specific Workflow Instance

To delete a specific workflow instance, use the following com.bea.wlpi.server.admin.Admin method:

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

The following table describes the deleteInstance() method parameter for which you must specify a value.

Table 22-7 deleteInstance() Method Parameter  

Parameter	Description	Valid Values
instanceId	ID of the workflow instance for which you want to get tasks.	Valid workflow instance ID. To obtain the workflow instance ID, you need to obtain the InstanceInfo object corresponding to the instance for which you want to get tasks, as described in Getting Workflow Instances. To get the instance ID, use the following com.bea.wlpi.common.InstanceInfo method: public final java.lang.String getId() Note: For more information about the methods available to the InstanceInfo object, see InstanceInfo Object.

For example, the following code deletes the instance specified by instanceId. In this example, admin represents the EJBObject reference to the Admin EJB.

admin.deleteInstance(instanceId);

Deleting All Instances of a Workflow Template or Template Definition

To delete instances of a workflow template or template definition in an organization, use the following com.bea.wlpi.server.admin.Admin methods, respectively.

Method 1

public void deleteTemplateInstances(
  java.lang.String templateId,
  java.lang.String orgId,
  boolean bStarted,
  java.util.Date from,
  java.util.Date to
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

Method 2

public void deleteTemplateDefinitionInstances(
  java.lang.String templateDefinitionId,
  java.lang.String orgId,
  boolean bStarted,
  java.util.Date from,
  java.util.Date to
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

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

Table 22-8 deleteTemplateInstances() and deleteTemplateDefinitionInstances() Method Parameters  

Parameter	Description	Valid Values
templateId	ID of the template for which you want to delete instances.	Valid template ID. To get the template ID, you need to obtain the TemplateInfo object corresponding to the template for which you want to delete instances, as described in Getting the Templates for an Organization. To get the template ID, use the following com.bea.wlpi.common.TemplateInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateInfo object, see TemplateInfo Object. The getId() method returns the templateId. Each templateId may have multiple definitions. To determine which template definition to use, WebLogic Integration selects the version with the most relevant effective date (current or past) and expiration date (current or future) from the set of active template definitions. For information about defining the effective and expiration dates for the template definitions and about how to make them active, see Defining Workflow Templates in Using the WebLogic Integration Studio.
templateDefinitionId	ID of the template definition for which you want to delete instances.	Valid template definition ID. To get the template definition ID, you need to obtain the TemplateDefinitionInfo object corresponding to the template definition for which you want to delete instances, as described in Creating a Template Definition. To get the template definition ID, use the following com.bea.wlpi.common.TemplateDefinitionInfo method: public final java.lang.String getId() Note: For more information about the methods available to the TemplateDefintionInfo object, see TemplateDefinitionInfo Object.
orgId	ID of the organization for which you want to delete template instances or template definition instances.	Valid organization ID. For information about getting organization IDs, see Managing the Active Organization.
bStarted	Boolean flag specifying whether to delete by start or completion date.	true (instance start date is used for the delete) or false (instance completion date is used for the delete).
from	Lower bound of the date range.	java.util.Date object.
to	Upper bound of the date range.	java.util.Date object.

For example, the following code deletes all template instances or template definition instances, respectively, corresponding to the specified ID value, and for the organization specified by value of the activeOrgId variable. In this example:

• bStarted is set to true, so information is queried by the start date.

• Lower and upper bounds of the date range are set using the dateFrom and dateTo java.util.Date object variables, respectively.

In the following example, admin represents the EJBObject reference to the Admin EJB.

admin.deleteTemplateInstances(templateId, activeOrgId, true, 
  dateFrom, dateTo);

admin.deleteTemplateDefinitionInstances(
   templatedefId, activeOrgId, true, dateFrom, dateTo);

For more information about the deleteInstance(), deleteTemplateInstances(), and deleteTemplateDefinitionInstances() methods, see the com.bea.wlpi.server.admin.Admin Javadoc.

 

---

Querying the Run-Time Workload

To query the run-time workload, use the following com.bea.wlpi.server.admin.Admin method:

public java.util.List workloadQuery(
  java.lang.String xml
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the workloadQuery() method parameter for which you must specify a value.

Table 22-9 workloadQuery() Method Parameter  

Parameter	Description	Valid Values
xml	Run-time workload query request.	XML document that is compliant with the Workload Request DTD, as described in Workload Request DTD.

This method returns a workload report in XML format that is compliant with the Workload Response DTD, as described in Workload Response DTD.

For example, the following code initiates a query on the run-time workload, based on the contents of the workloadReq XML document, which is compliant with the Workload Request DTD.

String workloadresp = workloadQuery(workloadReq);

This method writes its response in the file workloadresp, in a format that is compliant with the Workload Response DTD. For more information about the workloadQuery() method, see the com.bea.wlpi.server.admin.Admin Javadoc.

 

---

Querying the Run-Time Statistics

To query the run-time statistics, use the following com.bea.wlpi.server.admin.Admin method:

public java.util.List statisticsQuery(
  java.lang.String xml
) throws java.rmi.RemoteException, 
  com.bea.wlpi.common.WorkflowException

The following table describes the statisticsQuery() method parameter for which you must specify a value.

Table 22-10 statisticsQuery() Method Parameter  

Parameter	Description	Valid Values
xml	Run-time statistics query request.	XML document that is compliant with the Statistics Request DTD, as described in Statistics Request DTD.

This method returns a statistics report in XML format that is compliant with the Statistics Response DTD, as described in Statistics Response DTD.

For example, the following code initiates a query on the run-time statistics, based on the contents of the statisticsReq XML document, which is compliant with the Statistics Request DTD.

java.lang.String statisticsresp = statisticsQuery(statisticsReq);

This method writes its response in the file statisticsresp, in a format that is compliant with the Statistics Response DTD. For more information about the statisticsQuery() method, see the com.bea.wlpi.server.admin.Admin Javadoc.