Searching for Process Instances

You can programmatically search for process instances by using the Java API and web services. A process instance is an occurrence of a specific process that was started by an invocation method such as the Invocation API or from within Workspace. For example, when you invoke a long-lived process by using the Invocation API, a process instance is created.

Searching for a process instance lets you track its information, such as its status. That is, a process instance can be in one of the following states:

  • Completed: Indicates that the process instance is complete

  • Completing: Indicates that the process instance is about to complete

  • Initiated: Indicates that the process instance has been initiated

  • Running: Indicates that the process instance is currently running

  • Suspended: Indicates that the process instance is suspended

  • Suspending: Indicates that the process instance is about to be suspended

  • Terminated: Indicates that the process instance was terminated before all operations in the process were completed

  • Terminating: Indicates that the process instance is about to be terminated

  • Unsuspending: Indicates that the process instance is about to be unsuspended

When searching for processes, you can specify search criteria, such as the process name, that lets you select specific process instances.

Note: The name of the service that is invoked when searching for process instances is TaskManagerQueryService.

Summary of steps

To search for process instances, perform the following tasks:

  1. Include project files.

  2. Create a TaskManagerQueryService Client API object.

  3. Specify search criteria.

  4. Perform the search.

  5. Iterate through the returned process instances.

Include project files

Include necessary files into your development project. If you are creating a client application by using Java, include the necessary JAR files. If you are using web services, make sure that you include the proxy files.

Create a TaskManagerQueryService Client API object

Before you can programmatically search for process instances, you must create a TaskManagerQueryService object.

Specify search criteria

To search for process instances, define search criteria. You can, for example, search for all process instances that are based on a specific process. In this situation, all process instances that are based on the process are returned.

Perform the search

After you specify search criteria, you can perform the search. All process instances that conform to the search criteria are returned within a list.

Iterate through the returned process instances

Iterate through the returned list to retrieve each process instance. After you obtain a process instance, you can obtain information about it. For example, you can determine its status.

Search for process instances using the Java API

Search for process instances by using the TaskManagerQuery service API (Java):

  1. Include project files

    Include client JAR files, such as adobe-taskmanager-client-sdk.jar, in your Java project’s class path.

  2. Create a TaskManagerQueryService Client API object

    • Create a ServiceClientFactory object that contains connection properties.

    • Create a TaskManagerQueryService object by invoking the TaskManagerClientFactory object’s static getQueryManager method and passing the ServiceClientFactory object.

  3. Specify search criteria

    • Create a ProcessSearchFilter object that is used to define search criteria by using its constructor.

    • Define search criteria by invoking an appropriate method that belongs to the ProcessSearchFilter object. For example, to define the process on which a process instance is based, invoke the ProcessSearchFilter object’s setServiceName method, and pass a string value that specifies the process name.

  4. Perform the search

    Search for process instances by invoking the TaskManagerQueryService object’s processSearch method and passing the ProcessSearchFilter object. This method returns a java.util.List instance where each element is a ProcessInstanceRow instance that represents a process instance that conforms to the specified search criteria.

  5. Iterate through the returned process instances

    • Create a java.util.Iterator object by invoking the java.util.List object’s iterator method. This object lets you iterate through the java.util.List instance to retrieve process instances.

    • Iterate through the java.util.List object to determine where process instances are present. If they are present, each element is a ProcessInstanceRow instance.

    • Retrieve information about a process instance by invoking an appropriate method that belongs to the ProcessInstanceRow object. For example, to get the status of the process instance, invoke the ProcessInstanceRow object’s getProcessInstanceStatus method. If the process instance is completed, this method returns ProcessInstanceRow.STATUS_COMPLETED.

Search for process instances using the web service API

Search for process instances by using the TaskManagerQuery service API (Java):

  1. Include project files

    • Create a Microsoft .NET client assembly that consumes the TaskManagerQueryService WSDL using Base64 encoding. To create a proxy object that lets you invoke its operations by using a web service, specify the following WSDL definition:

      http://localhost:8080/soap/services/TaskManagerQueryService?WSDL
    • Reference the Microsoft .NET client assembly in your client project.

  2. Create a TaskManagerQueryService Client API object

    • Using the Microsoft .NET client assembly, create a TaskManagerQueryServiceService object by invoking its default constructor.

    • Set the TaskManagerQueryServiceService object’s Credentials data member with a System.Net.NetworkCredential value that specifies the user name and password value.

  3. Specify search criteria

    • Create a ProcessSearchFilter object that is used to define search criteria by using its constructor.

    • Define search criteria by assigning a value to the appropriate data member that belongs to the ProcessSearchFilter object. For example, to specify the process on which a process instance is based, assign a string value that specifies the process name to the serviceName data member.

  4. Perform the search

    Search for process instances by invoking the TaskManagerQueryServiceService object’s processSearch method and passing the ProcessSearchFilter object. This method returns anarray of Objects where each element is a ProcessInstanceRow object that represents a process instance that conforms to the specified search criteria.

  5. Iterate through the returned process instances

    • Iterate through the Object array by creating a loop structure and, for each element, cast the element value to a TaskRow instance.

    • Retrieve information about a task by getting the value of an appropriate data member that belongs to the TaskRow object. For example, to get the task identifier value, get the value of the TaskRow object’s taskId data member.

// Ethnio survey code removed