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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:

1
2
3
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

  Copy

  WorklistItemStatus

  1
  2
  3
  4
  //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.

1
2
// 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 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

1
2
3
4
5
6
7
8
9
10
11
12
// ( 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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;
    }
}