Using the API 101

13 Apr

I was at one of the K2 Roadshows recently and the main question on everyone’s mind was, surprisingly, how to best go about using K2’s API. This isn’t going to be an in-depth answer but hopefully it will give people an idea of where to start.

First we need to clear up some concepts. The K2 Host Server is actually made up of a number of components or Hosted Services. Some examples of hosted services are:

  • Environment Library Server – this is the hosted service you query every time you want the environment fields for a particular environment
  • Licensing Management Server – The name speaks for itself
  • Event Bus Server
  • etc.

There are 2 hosted services which are important to get your head around, and these are:

  • Workflow Server – To do all things workflow-related.
  • SmartObject Server – To do all things SmartObject related.

Keep these 2 hosted services in mind because almost everything you do with the K2 API will be essentially communicating with these 2 hosted services. So how do we communicate?

Communication with the hosted services is always via a TCP connection. By default you’re going to be using port 5555, the only exception being the workflow server which uses port 5252. These ports can be configured and changed during the installation, but you wouldn’t want to.

So in a nutshell, here’s what you do to use the API:

  1. Open a TCP connection to the hosted service you need to connect to
  2. Make the call
  3. Close the TCP connection

Here’s an example of using the API to get the worklist of the person who is currently logged in (something you would need to do if you were building a custom task list, for example):

string K2ServerName = "localhost";
SourceCode.Workflow.Client.Connection connection = new SourceCode.Workflow.Client.Connection();
SourceCode.Workflow.Client.Worklist workList = connection.OpenWorklist();

That’s about it, but I want to mention some best practices. First of all, re-use the same connection for all the calls you need to make, as shown below:

string K2ServerName = "localhost";
SourceCode.Workflow.Client.Connection connection = new SourceCode.Workflow.Client.Connection();
...Make many calls using the active connection...

Secondly, if you encounter an exception while making the API calls you will never get to the line which closes the connection, which will leave you with open connections. This is obviously not what you want, so you should create your connection using a ‘Using’ statement so that the connections are closed for you as soon as you’re done with them (all K2 connections implement BaseAPIConnection which in turns implements IDisposable). Here’s how you do that:

string K2ServerName = "localhost";
using (SourceCode.Workflow.Client.Connection connection = new SourceCode.Workflow.Client.Connection())
    SourceCode.Workflow.Client.Worklist workList = connection.OpenWorklist();

Hope that helps…

Leave a comment

Posted by on April 13, 2011 in K2 API


Leave a Reply

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