Workflow Client Connections

Establishing a connection with the Workflow.Client class is the first step to perform workflow runtime interaction. The Connection object is the entry point for subsequent calls to the K2 server when using the Workflow Client assemblies, and once you have opened a connection, you can perform actions like retrieving worklists, completing worklist items or starting process instances.

Under the covers, the Connection object uses RPC calls to the K2 server to execute methods with a proprietary message format. By default, communication to the K2 server when using the Workflow Client API is via Port 5252, although you may have selected a different port when installing K2

The simplest way to open a connection is just to specify the K2 server name, in which case the connection to K2 will be established as the current Windows user account (so-called Integrated authentication). The code snippet below shows how to open and close a K2 connection in the simplest possible way, using the current user’s Active Directory credentials and opening a connection on the default 5252 port.

1
2
3
4
5
6
7
8
SourceCode.Workflow.Client.Connection WorkflowClientConnection = new SourceCode.Workflow.Client.Connection();
WorkflowClientConnection.Open("[ServerName]");

//do things with the connection

//connection must be closed once you are done
WorkflowClientConnection.Close();

If you need to build up a more advanced connection (for example a different security provider, username or port) you can import the SourceCode.Hosting.Client namespace from the SourceCode.HostClientAPI.dll assembly and instantiate a ConnectionStringBuilder object to construct a more advanced connection string. This is especially important when you need to pass through alternative security credentials or are using a custom security provider to authenticate a non-Active Directory user account. The code snippet below illustrates how to build up a custom connection string and then open the connection as a user, using the K2 SQL User Manager authentication provider for authentication.

See the topic Connection String Samples for some more samples of typical connection strings.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder builder = new SCConnectionStringBuilder();
builder.Authenticate = true;
builder.Host = "localhost"; //server name of the K2 host server
builder.Port = 5555; //use port 5252 for SourceCode.Workflow.Client connections
builder.Integrated = false;
builder.IsPrimaryLogin = true;
builder.SecurityLabelName = "K2SQL"; //the name of the security label to use for authenticating the credentials below
builder.UserID = "username"; //user name to be authenticated
builder.Password = "password"; //password for the user to be authenticated
//open the connection
SourceCode.Workflow.Client.Connection WorkflowClientConnection = new SourceCode.Workflow.Client.Connection();
WorkflowClientConnection.Open("[ServerName]", builder.ToString());
//do things with the connection
//connection must be closed once you are done
WorkflowClientConnection.Close();

Once the connection is open, the process instance can be accessed and used. Once the required interaction with a process has finished the connection must be closed using the connection.Close() method. The recommended approach is to use try{...} catch{...} finally{...} blocks or using{...} blocks to ensure that connections are closed once they are no longer needed. The code samples below illustrate some ways you can manage connections when using the Workflow Client classes.

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
//manually closing the connection
SourceCode.Workflow.Client.Connection WorkflowClientConnection = new SourceCode.Workflow.Client.Connection();
WorkflowClientConnection.Open("[ServerName]");
//do something with the connection
//close the connection when it is no longer needed
WorkflowClientConnection.Close();

//using a try..catch..finally block
SourceCode.Workflow.Client.Connection WorkflowClientConnection1 = new SourceCode.Workflow.Client.Connection();
WorkflowClientConnection1.Open("[ServerName]");
try {
 //do something with the connection
} catch {
 //do something with exceptions
} finally {
 //make sure the connection is closed when it is no longer needed
 WorkflowClientConnection1.Close();
}

//using a using block will call close and dispose when the using statement exits
using (SourceCode.Workflow.Client.Connection WorkflowClientConnection2 = new SourceCode.Workflow.Client.Connection()) {
    WorkflowClientConnection2.Open("localhost");
 //do something with connection once opened
}