Retrieving the worklist with WorklistCriteria

If you have a large number of tasks on your task list, you may need to limit the number of tasks returned. You may also need to locate tasks based on some criteria, filtering and sorting your task list programmatically. To limit the number of worklist items returned by the OpenWorklist method, you create a WorklistCriteria object to build up a combination of filtering and sorting statements, and then pass this object to the Openworklist() method

If you want to retrieve all worklist items available on the server as opposed to only worklist items for the current user, see the topic Working with the management (global) Worklist.
Returning the worklist can be an "expensive" operation and K2 recommends using WorklistCriteria to limit the number of worklist items returned. You should not retrieve the entire worklist recursively, since this can negatively impact the performance of the K2 server.

The code snippet shows how to retrieve a person’s task list with an example of a WorklistCriteria object that limits tasks to workflows in the folder MyFolder with a priority of 1, and sorted in descending order by the date started. The example loops through each worklist item and reads data about the item.

 This sample code requires references to the assemblies:

  • SourceCode.HostClientAPI
  • SourceCode.Workflow.Client

using (SourceCode.Workflow.Client.Connection K2Conn = new Connection()) {
 //open a simple connection
 K2Conn.Open("localhost");

 //build up criteria for filtering and sorting
 SourceCode.Workflow.Client.WorklistCriteria K2Crit = new WorklistCriteria();
 //example:
 //filter for workflows in MyFolder
 K2Crit.AddFilterField(WCField.ProcessFolder, WCCompare.Equal, "MyFolder");
 //filter for workflows with priority 1
 K2Crit.AddFilterField(WCLogical.And, WCField.ProcessPriority, WCCompare.Equal, 1);
 //sort by workflow start date, descending
 K2Crit.AddSortField(WCField.ProcessStartDate, WCSortOrder.Descending);
 //open the worklist with the given criteria
 SourceCode.Workflow.Client.Worklist K2WList = K2Conn.OpenWorklist(K2Crit);

 //iterate over the worklist items in the worklist
 foreach (SourceCode.Workflow.Client.WorklistItem K2WLItem in K2WList) {
  //do something with the worklist item
  //you can query properties/objects contained in the worklist item object
  string serialNumber = K2WLItem.SerialNumber;
  string status = K2WLItem.Status.ToString();
  string Folio = K2WLItem.ProcessInstance.Folio;
 }
}

Using WorklistCriteria

To use the WorklistCriteria class, do the following:

  1. Open a workflow connection.
  2. Create an instance of the class.
  3. Add your criteria filters.
  4. Pass the object into the OpenWorklist method and (optionally) perform some action on them.
  5. Close or dispose the connection if you didn't wrap your code in a using statement.

The code snippet below shows you where to add your filters.

 This sample code requires references to the assemblies:

  • SourceCode.HostClientAPI
  • SourceCode.Workflow.Client

using(SourceCode.Workflow.Client.Connection K2Conn = new Connection()) {
 //open a simple connection
 K2Conn.Open("localhost");

 SourceCode.Workflow.Client.WorklistCriteria wlCrit = new SourceCode.Workflow.Client.WorklistCriteria();

 // Add filters here...

 // Execute OpenWorklist with filter
 SourceCode.Workflow.Client.Worklist myWorkList = K2Conn.OpenWorklist(wlCrit);

 // print result
 foreach(SourceCode.Workflow.Client.WorklistItem wlItem in myWorkList) {
  //do something with the worklist item
  Console.WriteLine("{0,-8}\t{1,-20}\t{2,-20}\t{3,-10}",
   wlItem.SerialNumber,
   wlItem.ProcessInstance.Folio,
   wlItem.ProcessInstance.Name,
   wlItem.Status);
 }
}

WorklistCriteria filter basics

To add a filter, you need to call the AddFilterField which has three variations:

wlCrit.AddFilterField( < WCField > , < WCCompare > , < Object > );
wlCrit.AddFilterField( < WCLogical > , < WCField > , < WCCompare > , < Object > );
wlCrit.AddFilterField( < WCLogical > , < WCField > , < SubField > , < WCCompare > , < Object > );

WCField is the list of properties you can filter on:

  • ActivityData
  • ActivityDescription
  • ActivityExpectedDuration
  • ActivityMetaData
  • ActivityName
  • ActivityPriority
  • ActivityStartDate
  • ActivityXml
  • EventDescription
  • EventExpectedDuration
  • EventMetaData
  • EventName
  • EventPriority
  • EventStartDate
  • None
  • ProcessData
  • ProcessDescription
  • ProcessExpectedDuration
  • ProcessFolder
  • ProcessFolio
  • ProcessFullName
  • ProcessID
  • ProcessMetaData
  • ProcessName
  • ProcessPriority
  • ProcessStartDate
  • ProcessStatus
  • ProcessXml
  • RowNumber
  • SerialNumber
  • WorklistItemOwner
  • WorklisItemStatus
    WorklistItemStatus comparison uses the following values:
    0 = Available
    1 = Open
    2 = Allocated
    3 = Sleep
    //If you want to filter Worklist Items with a status of “Available”, the code will look like this:
    // 0 = available, 1 = open, 2 = allocated, 3 = sleep
    wlCrit.AddFilterField(WCField.WorklistItemStatus, WCCompare.Equal, 0);
    Worklist myWorkList = wfConn.OpenWorklist(wlCrit);

WCCompare lists the comparison operators you can use in the filter:

  • Equal
  • Greater
  • GreaterOrEqual
  • Less
  • LessOrEqual
  • Like
  • NotEqual
  • NotLike

WCLogical is the joining operator between two filters:

  • And
  • AndBracket
  • EndBracket
  • Or
  • OrBracket
  • StartBracket

SubField is a string value used to reference additional key names during comparison, for example a Data Field name.

// If you want to filter by Process, Activity Data, or Xml Field, you need to pass in the field name, in the SubField:

wlCrit.AddFilterField(WCLogical.And, WCField.ProcessData, "ItemId", WCCompare.Equal, 36);

Object is an object value for the comparison you set up.

Using AND / OR logical operators

AND / OR logical operators work as in this example:

// In this AND join example, we create a filter that requires the Process Name starts with “C” and the Worklist Item status to be “Open”.

//Process Name starts with "C"
wlCrit.AddFilterField(WCField.ProcessName, WCCompare.Like, "C%");

// AND status = "Open"
wlCrit.AddFilterField(WCLogical.And, WCField.WorklistItemStatus, WCCompare.Equal, 1);
// In this OR join example, we create a filter that requires the Worklist Item status to be “Available” or “Open”.

// Status = "Available"
wlCrit.AddFilterField(WCField.WorklistItemStatus, WCCompare.Equal, 0);

// OR status = "Open"
wlCrit.AddFilterField(WCLogical.Or, WCField.WorklistItemStatus, WCCompare.Equal, 1);

Using the other operators

The operators other than the AND / OR logical operators, do the following:

  • StartBracket: draws the ( operator for the given filter
  • AndBracket: adds the AND operator and closes the filter with a ) operator
  • OrBracket: adds the OR operator and closes the filter with a ) operator
  • EndBracket: closes the filter with a ) operator, if you have a StartBracket in earlier code

// ( ProcessName LIKE 'B%'
wlCrit.AddFilterField(WCLogical.StartBracket, WCField.ProcessName, WCCompare.Like, "B%");

// AND Folio LIKE 'B%150520-0002'
wlCrit.AddFilterField(WCLogical.And, WCField.ProcessFolio, WCCompare.Like, "B%150520-0002");

// )
wlCrit.AddFilterField(WCLogical.EndBracket, WCField.None, WCCompare.Equal, null);

// AND Status = "Available"
wlCrit.AddFilterField(WCLogical.And, WCField.WorklistItemStatus, WCCompare.Equal, 0);

Using criteria to return a worklist faster

Using the NoData and Platform parameters in worklist criteria can help to reduce the amount of time it takes to retrieve a worklist. When you call OpenWorklist with the NoData flag set, no data field values are returned.

using (SourceCode.Workflow.Client.Connection K2Conn = new Connection()) {
 //open a simple connection
 K2Conn.Open("localhost");

 //use criteria to build a faster worklist retrieval
 SourceCode.Workflow.Client.WorklistCriteria K2Crit = new WorklistCriteria();
 K2Crit.NoData = true; //faster, does not return the data for each item
 K2Crit.Platform = "ASP"; //helps when multiple platform are used
 //Open the Worklist and get the worklistitem count
 SourceCode.Workflow.Client.Worklist K2WList = K2Conn.OpenWorklist(K2Crit);
 //get the number of items in the worklist
 int workItemCount = K2WList.TotalCount;
 //iterate over the worklist items in the worklist
 foreach(SourceCode.Workflow.Client.WorklistItem K2WLItem in K2WList) {
  //do something with the worklist item
  //you can query properties/objects contained in the worklist item object
  string serialNumber = K2WLItem.SerialNumber;
  string Folio = K2WLItem.ProcessInstance.Folio;
 }
}