Connection String Samples

This topic provides some typical samples of connection strings.

K2 client API .DLLs that you reference, like the HostClientApi.dll, SmartObject.Client.dll and the Workflow client API, are thread safe. If you open a connection with the API, you should close and dispose of the connection object.

These examples assume the default security labels are in place, where the 'K2' security label works with Active Directory and the 'K2SQL' security label works with the SQL User Manager.

For claims authentication and custom user managers, the following properties in the connection string remain the same as for windows authentication:
host={MachineName};
port={K2PortNumber};
Integrated=true;
IsPrimary=true;
Authenticate=true

Note on the CachePassword Property

The SCConnectionStringBuilder class includes the Boolean CachePassword property. If a connection supplies a password, the CachePassword property behaves in the following way:

  • If the property is not specified (not set to either true or false), the connection will use the password supplied for the session but will not cache it in the database. If there is already a password cached in the database, it remains as is.
  • If the property is set to true, it caches the password supplied for the session in the database.
  • If the property is set to false, it does not cache the password supplied for the session in the database, and clears the password if there was one cached.

Caching passwords is a security risk because cached passwords could be exposed during an attack on the SQL server.

Make a connection under the currently Windows Identity that is running this code

//Make a connection under the currently Windows Identity that is running this code
SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder builder = new SCConnectionStringBuilder();
builder.Authenticate = true; //whether to authenticate the user's credentials against the security provider, usually true
builder.Host = "localhost"; //name of the K2 host server, or the name of the DNS entry pointing to the K2 Farm
builder.Port = 5555; //use port 5252 for SourceCode.Workflow.Client connections, port 5555 for everything else
builder.Integrated = true; //true = use the logged on user, false = use the specified user
builder.IsPrimaryLogin = true; //true = re-authenticate user, false = use cached security credentials
builder.SecurityLabelName = "K2"; //the name of the security label to use for authentication

Force the connection under a specific AD Identity

//Force the connection under a specific AD Identity
SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder builder = new SCConnectionStringBuilder();
builder.Authenticate = true; //whether to authenticate the user's credentials against the security provider, usually 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; //true = use the logged on user, false = use the specified user
builder.IsPrimaryLogin = true; //true = re-authenticate user, false = use cached security credentials
builder.SecurityLabelName = "K2"; //the name of the security label to use for authenticating the credentials below
builder.WindowsDomain = "domain"; //when using AD, the name of the domain for the user to be authenticated
builder.UserID = "username"; //user name to be authenticated
builder.Password = "password"; //password for the user to be authenticated, unencrypted
builder.CachePassword = false; //password is not cached and clears a previously cached password from the database

Make a connection that authenticates against the K2 SQL User Manager

//Make a connection that authenticates against the K2 SQL User Manager
SourceCode.Hosting.Client.BaseAPI.SCConnectionStringBuilder builder = new SCConnectionStringBuilder();
builder.Authenticate = true; //whether to authenticate the user's credentials against the security provider, usually 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; //true = use the logged on user, false = use the specified user
builder.IsPrimaryLogin = true; //true = re-authenticate user, false = use cached security credentials
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

Using the connection string

Once you have constructed the connection string, you can use it to establish a connection to K2. Here are same examples:

//Using the connection string

//SourceCode.Workflow.Client
SourceCode.Workflow.Client.Connection WorkflowClientConnection = new Connection();
WorkflowClientConnection.Open("localhost", builder.ConnectionString);

//SourceCode.Workflow.Management
SourceCode.Workflow.Management.WorkflowManagementServer WorkflowManagementConnection = new WorkflowManagementServer();
WorkflowManagementConnection.Connection.Open(builder.ConnectionString);

//SourceCode.SmartObjects.Client
SourceCode.SmartObjects.Client.SmartObjectClientServer SmartObjectClientServerConnection = new SmartObjectClientServer();
SmartObjectClientServerConnection.CreateConnection();
SmartObjectClientServerConnection.Connection.Open(builder.ConnectionString);