We're updating some of our product names. K2 Five will soon be Automation On-Prem. You may see both product names in our help pages while we make this change.

Using the SOAP WCF service

This content applies to legacy components (such as K2 Studio and K2 for Visual Studio), legacy assemblies, legacy services or legacy functionality. If you have upgraded from K2 blackpearl 4.7 to K2 Five, these items may still be available in your environment. These legacy items may not be available in new installations of K2 Five. These legacy items may also not be available, supported, or behave as described, in future updates or versions of K2. Please see the legacy component support policy for more information about support for these components.

These steps explain how to use the Workflow SOAP WCF service. In this example, we will start a new process instance.

Step 1: Determine the URL for the Workflow WCF Service in your K2 environment and test the URL

Determine the URL for the Workflow WCF service in your K2 environment. The URL usually looks something like this:
http(s)://[K2 website]/K2Services/WCF.svc
(Examples: http://k2.denallix.com/K2Services/WCF.svc, https://k2.denallix.com/K2Services/WCF.svc)

Open the URL with a web browser like Internet Explorer, and verify that you are able to browse to the service. You should see a page that looks something like this:

Step 2: Create a new Project in Visual Studio and add a reference to the SOAP service

In the Service References for your project, add a new service reference to the URL that you determined in step 1, and give the service reference an obvious name (this code sample assumes you named the service reference WorkflowRuntimeWCFService)

Step 3: Set up your application’s configuration file for basicHTTPBinding settings

Change each of the 4 basicHttpBinding entries in your application’s web.config or app.config file to set the security mode and transport. The specific settings you need to use will depend on whether your service is accessed through HTTP or HTTPS, and your application's security settings. We have provided two example configurations for the <basicHttpBinding> values in the <system.serviceModel> node below; your application may require different settings.

Sample for HTTP Service

<basicHttpBinding>
    <binding name="BasicHttpBinding_IProcessNavigationService">
        <security mode="TransportCredentialOnly">
            <transport clientCredentialType="Ntlm" proxyCredentialType="None"
        realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
        </security>
    </binding>
    <binding name="BasicHttpBinding_IWorklistNavigationService">
        <security mode="TransportCredentialOnly">
            <transport clientCredentialType="Ntlm" proxyCredentialType="None"
        realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
        </security>
    </binding>
    <binding name="BasicHttpBinding_IIdentityService" >
        <security mode="TransportCredentialOnly">
            <transport clientCredentialType="Ntlm" proxyCredentialType="None"
        realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
        </security>
    </binding>
    <binding name="BasicHttpBinding_ICoreService" >
        <security mode="TransportCredentialOnly">
            <transport clientCredentialType="Ntlm" proxyCredentialType="None"
        realm="" />
            <message clientCredentialType="UserName" algorithmSuite="Default" />
        </security>
    </binding>
</basicHttpBinding>

Sample for HTTPS Service

Step 4: Set up your web application’s configuration file for Windows authentication

If you are creating a web application, change your application’s web.config file to set the authentication mode for your site to windowsAuthentication and impersonate the user’s identity. The sample below shows one sample of this configuration, your values may be different.

<system.webServer>
    <security>
        <authentication>
            
            <anonymousAuthentication enabled="false" />
            
            <windowsAuthentication enabled="true" />
        </authentication>
    </security>
    <system.web>
        <authentication mode="Windows"></authentication>
        <identity impersonate="true"/>
    </system.web>
</system.webServer>

Step 5: Import the namespace for the new Service Reference

Add a using statements to import the necessary namespaces, including the service reference, e.g.

using WorkflowWebServiceWCF.WorkflowRuntimeWCFService;
using System.Xml;
using System.Collections.Generic;

Step 6: Add the code that instantiates the Web Service and starts a new workflow instance

The code sample assumes you set the name of the reference to the service to "WorkflowWebServiceWCF.WorkflowRuntimeWCFService")

//instantiate the process service
WorkflowRuntimeWCFService.ProcessNavigationServiceClient processSvcClient = new ProcessNavigationServiceClient();

//instantiate a process instance to hold the ProcessInstance object
ProcessInstance k2ProcInst = new ProcessInstance();

//provide the path to the workflow that you want to start
k2ProcInst.FullName = @"[ProjectFolder]\[Process Name]"; //e.g. k2ProcInst.FullName = @"K2Samples\Sample Workflow";
//set the folio (optional)
k2ProcInst.Folio = "[Folio Value]";

//set the datafields if needed, by declaring a List of DataField
List <DataField> dataFieldsCollection = new List     <DataField>();
//populate the data field values by adding items to the DataField List
//string field example
dataFieldsCollection.Add(new DataField() { Name = "[StringFieldName]", Value = "[FieldValue]" });
//date field example. Dates require special massaging, otherwise you get XMLAny errors.
//In this sample we’ll take the current date.
//Note the use of the XmlConvert function. You may need to do this with other datafield types as well.
dataFieldsCollection.Add(new DataField() { Name = "[DateFieldName]", Value = XmlConvert.ToString(DateTime.Now, XmlDateTimeSerializationMode.Local) });

//Once datafields values are set, pass the collection to datafields into the process instance object’s DataField array
k2ProcInst.DataField = dataFieldsCollection.ToArray();

//start the workflow
//Note: if you defined process datafields or XML fields, set the appropriate boolean value to true
processSvcClient.StartNewProcessInstance(k2ProcInst, false, false, false, true, false);
//Note: some versions of K2 may require you to handle an unexpected "to open" error, e.g.
try
{
    processSvcClient.StartNewProcessInstance(k2ProcInst, false, false, false, true, false);
}
catch (Exception ex)
{
    if (!ex.Message.Contains("to open"))
    { throw; }
}