Using K2 Workflow Client API

[Updated: 4/6/2015]: Added reference to usage of WorklistCriteria here.

The SourceCode.Workflow.Client assembly provides the access to interact with the K2 blackpearl Server in the context of a User. This means that the API will not be able to query, for example, for all Users who has a Worklist Item from a specific Process. You will need to use SourceCode.Workflow.Management assembly for this. This API, however will allow the current User to impersonate as any other User within K2, if the account has the Impersonate rights on the Workflow Server. We will see more about this. Now down to the basics.


K2 Workflow Client API

Adding a reference to the assembly
  1. SourceCode.Workflow.Client
  2. SourceCode.Hosting.Client

These 2 assemblies can be found in the following location:

  • GAC – This is if you are working from within the K2 sever
  • K2 blackpearl’s bin folder – If you have the client components installed on your machine. The default path is C:\Program Files (x86)\K2 blackpearl\bin.
  • K2 Host Server’s bin folder – If you are working from within the K2 server. The default path is C:\Program Files (x86)\K2 blackpearl\Host Server\bin.

Note: The API call is carried out via RPC, so it means that as long as you have the required DLLs with your application, you will be able to make the call even if you did not install the K2 Client Components on that machine.


 

Open a connection to K2 blackpearl server

To open a connection, you only need the following:

For the Open method, there are a couple of variations:

  • Open(string Server): This requires a server name that can be resolved by the DNS/Host File or an IP.
  • Open(string Server, string ConStr): The 2nd parameter provides a connection string information. See ConnectionSetup.ConnectionString property.
  • Open(ConnectionSetup setup): This requires a ConnectionSetup object. You can provide a different log in credentials here.

 

User Property

Once the connection is opened, the User property will show the current logged on account:

111-User_Property
Connection object’s User property

If you find that the User property does not match the current logged on User in your ASP.NET page, it means that your web.config file is not configured to impersonate the current logged on User. Make sure the following is present in your web.config file:


 

Impersonate another User

If the current logged on User has the Impersonate rights on the Workflow Server:

You can execute the following code to impersonate as any User within the K2 environment:


 

Closing a connection to K2 blackpearl server

When you are done with the connection, always remember to close it by calling on the Close or Dispose method. You should always wrap the connection in a Using block:

Or a try-catch and/or finally block:


 

Start a Process Instance

To start a new process instance (a.k.a new workflow instance),  you will need to create a ProcessInstance object first.

The path to process is a combination of the root project folder name, followed by any folders’ name till the process. So in the following example:

111-Project_process_path
K2 Designer for Visual Studio

111-Workspace_Process_path
K2 Workspace

The path will be “TestProject1\ModuleA\Process1”.

With the ProcessInstance object created, you will be able to update the Folio and process level Data Fields before the process instance starts. This procedure is optional.

When the necessary updates on the ProcessInstance object is completed, you will need the Connection object’s StartProcessInstance method call to kick start the process instance.

Note: The StartProcessInstance method runs asynchronously by default. If you need the method to be executed synchronously, pass a 2nd parameter “true”:


 

Opening a Worklist

A work list (task list) is a collection of work list items (task list items) that is assigned to the current logged on user. You need to call on the OpenWorklist method of the Connection object and it will return a Worklist object, which is a collection of WorklistItems. The following is a sample method call:

Note: The OpenWorklist method without any input parameter will return the entire collection of WorklistItems of the current User. This is not going to be efficient and very time consuming if the current User has thousands of tasks. To overcome this, we should use a Filter with the OpenWorklist method, which we will discuss in a separate article you can find here. [Updated: 4/6/2015]


 

Open WorklistItem

Now, the WorklistItem is a single task assigned to the current User. It has the information of the current process instance and also the Activity Destination Instance. This means that we can draw the following information from it (Just to name a few):

  • WorklistItem.ProcessInstance.Folio: The Folio of the current process instance.
  • WorklistItem.ProcessInstance.DataField[“myField”].Value: Get the process level data field.
  • WorklistItem.Data: The full URL of the task form.
  • WorklistItem.Actions: The configured Actions for this task.

To open a work list item, it means getting K2 to assign a slot to this user. This method will also validate if the current user is the valid Destination User and whether the work list item is still available for actioning.

SN stands for Serial Number, which is an identifier that the K2 server will insert as a query string parameter with the task form URL.

Just for information, the serial number comprises of:

  • Process Instance Id; and
  • Activity Destination Instance Id

The 2 values will be separated by an underscore ‘_’ symbol. For example: SN=123_45


 

Execution the work list item action

And of course, with the WorklistItem, you will be able to execute the configured Action (i.e. when User clicks on the Approve button).

Note: The action name needs to be spelled exactly the same as configured in the process.

Note: The Execute method runs asynchronously by default. If you need the method to be executed synchronously, pass a 2nd parameter “true”.


Samples

Here are some “more complete” sample codes if you are still unclear:

Start a new process instance

Open work list

Open work list Item

Execute an action


 

Have fun!!

 

Leave a Reply

Your email address will not be published. Required fields are marked *