Starting an instance of a workflow

This example shows how to use the Workflow Client to start a new workflow instance, including examples of setting data field values in the workflow.

This sample code requires references to the assemblies:

• SourceCode.HostClientAPI
• SourceCode.Workflow.Client

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
26
27
28
29
30
31
32
33
34
35
36
37
using(SourceCode.Workflow.Client.Connection K2Conn = new Connection()) {
    //simple connection used, for simplicity
    K2Conn.Open("localhost");

    //create a new process instance object, using the full name of the workflow
    SourceCode.Workflow.Client.ProcessInstance K2Proc = K2Conn.CreateProcessInstance(@"[project]\[folder]\[workflowname]");

    //Set some properties for the process instance
    //setting the folio
    K2Proc.Folio = "ProcessFolio";
    //setting datafields (datafields are accessed and set by name.)
    //Take care to specify a value of the correct data type for the targeted field
    K2Proc.DataFields["StringDataField"].Value = "somevalue";
    K2Proc.DataFields["IntegerDatafield"].Value = 1;
    //XML fields are set using a XML-formatted string
    System.Xml.XmlDocument xmlDoc = new XmlDocument();
    //do some work with the XML document
    //pass the XML document to the XML field as a string
    K2Proc.XmlFields["XMLDataField"].Value = xmlDoc.ToString();

    //you can iterate over the data fields collection as well
    foreach(DataField dataField in K2Proc.DataFields) {
        //do something with each datafield, e.g. read name or set value
        string fieldName = dataField.Name;
        string fieldValue = dataField.Value.ToString();
    }

    //Start the process instance
    K2Conn.StartProcessInstance(K2Proc);

    //Starting a process instance synchronously
    K2Conn.StartProcessInstance(K2Proc, true);

    //If needed, read the resulting process instance ID
    int ProcessInstanceId = K2Proc.ID;
}

Starting an instance of a workflow synchronously

The StartProcessInstance method has an overload method that accepts a parameter called Sync.

This setting effectively determines how quickly K2 will respond with a success message after the workflow has started. If you start a workflow Synchronously (in other words, the Sync parameter’s value is True), K2 will not respond with a success message until the next wait-state in the workflow is reached. A wait-state could be something like an activity with a client event, or an activity with a start rule. Essentially, this parameter tells K2 to perform all the activities and events in the workflow until the workflow is waiting for something or someone. Only when this wait-state is reached will the method return to the calling application. When starting a workflow is this manner, you are ensured that all the intermediate workflow activities and events leading up to the wait state have been completed.

This Synchronous style of execution is mostly used in screen-flow applications or automated testing, because you want to be sure that the first client event is created before the StartProcessInstance call returns. When the call returns, you would normally search through the user’s worklist for the resulting task and then perform the next action, rather than polling the user's worklist several times and waiting for the task to appear.

In the majority of cases you will want to start a workflow asynchronously because you do not need to wait for activities or events to complete. This is also the default behavior, unless you specifically override by setting the Sync parameter to true, as shown in the following code snippet: 

1
K2Conn.StartProcessInstance(K2Proc, true);