It's been a while since my last entry and recently I have been spending quite a bit of time understanding how the Out-of-Office (OOF) APIs work.  The OOF feature was introduced in K2 blackpearl 0807 and this allowed end users to delegate work items to other people when they were away.

The nice thing is that:

1. OOF is now integrated natively into K2 blackpearl rather than as an add-on (like K2.net 2003).
2. Both the work list user and the delegate are able to see the same work item (this was different in K2.net 2003 where the OOF user’s work items were moved completely to the delegate).
3. You can now delegate to a single user or multiple users.  K2.net 2003 only supported delegating to one user.
4. You can now specify exceptions for specific user(s) based on specific client activities in processes.  So you can have the option to specify that a particular sensitive financial approval activity should not be delegated.
5. Enhancements in the SourceCode.Workflow.Client API to support OOF.

Touching specifically on point 5, I and some of my guys (DC and Nuqman) have been spending a good amount of time with the APIs.  There’s quite a lot changes to cater for the OOF functionality.  Note that there are also new articles in the SDK documentation that covers the more important aspects that you need to know.

The two key articles are:

• Processes > Accessing > How to Open a Worklist when Out of Office is Activated
• Users > Out of Office Status > How to set a users Out of Office Status

Now let’s focus on the OpenWorklist method call.  To support the OOF items, you need to know utilize the new filters in the WorklistCriteria object to return items that belong to both the work list user and also other users.  So if you were doing a custom work list, the code would now look like this:

Dim criteria As New WorklistCriteria

criteria.Platform = “ASP”

criteria.AddFilterField(WCLogical.Or, WCField.WorklistItemOwner, "Me", WCCompare.Equal, WCWorklistItemOwner.Me)

criteria.AddFilterField(WCLogical.Or, WCField.WorklistItemOwner, "Other", WCCompare.Equal, WCWorklistItemOwner.Other)

oWorklist = oConn.OpenWorklist(criteria)

 

Not too big a major change but important to note if you are planning to support OOF functionality in your custom work list.  You will also note that these filters are specified in the default workspace work list and also the SharePoint Work List webpart settings.

Now in terms of opening the work item, there was an introduction of a new method to open up shared items called OpenSharedWorklistItem.   So if you wanted to open a work item from your client page (i.e. your approval page), the code would look something like this.

Dim sharedUser As String

Dim managedUser As String

sharedUser = Request.QueryString("SharedUser")

managedUser = Request.QueryString("ManagedUser")

If sharedUser = String.Empty And managedUser = String.Empty Then

  oWi = oConn.OpenWorklistItem(SN, "ASP")

ElseIf sharedUser = String.Empty And Not managedUser = String.Empty Then

  ' Check if the worklist item from a subordinate user

  oWi = oConn.OpenManagedWorklistItem(managedUser, SN)

Else

  ' Check if the worklist item is for an Out of Office shared user

  oWi = oConn.OpenSharedWorklistItem(sharedUser, managedUser, SN)

End If

 

Now note that the last Else handler only executes when the sharedUser string is not empty.  So take note that the OpenSharedWorklistItem method is able to take in both empty and non-empty strings for the managedUser field.

You probably know that the serial number parameter (SN) is automatically generated by the K2 server and appended to the client page URL for you.  So that leaves these two parameters call ManagedUser and SharedUser.  Where do you get these from?  In the default K2 workspace, you will notice that these are appended for you by the K2 workspace when needed.

However, if you are creating your own custom work list, you need to append these fields yourself to the work item URL.

1)      SharedUser – This indicates the original user of the work item.  The way to check this is to compare the identity of the user to the work item’s AllocatedUser property.  If it does not match the identity of the work list user, then the work item is a shared work item.  So you could use this check condition before appending the SharedUser tag to the URL that you launch the work item.

sURL = oWorkItem.Data + (oWorkItem.AllocatedUser.ToLower() == oConn.User.FQN.ToLower() ? "" : "&SharedUser=" + oWorkItem.AllocatedUser.Replace(@"\", @"\\"))

2)      ManagedUser – Not OOF related but this applies when you have access to your subordinate’s work list (as defined in Active Directory).  This indicates the managed user work list that you are working with.  When opening a managed user’s work list, you would specify an additional criteria in the WorklistCriteria object.

worklistCriteria.ManagedUser = "K2:<My Domain>\<User ID>";

Now once this is done, you also need to append the ManagedUser parameter to the URL as well.  This will allow you to open up the managed user’s work item correctly.

Ok, this mostly covers what you need to know when dealing with the work item and work list interaction with OOF in the picture.  I hope that the readers out there will find this useful when building custom .NET applications that revolve around K2.  Cheers.

---

Posted Thu, Feb 26 2009 3:11 PM by johnny