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

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;
}
DataField Names in a processinstance object are not strongly-typed. You will need to read and write DataFields by passing the name of the field as a string-indexed value. Ensure that the name you pass exactly matches the name of the datafield as defined in the workflow definition.

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: 

//Starting a process instance synchronously
K2Conn.StartProcessInstance(K2Proc, true);
Starting workflows synchronously (Sync=true) is slower than starting workflows asynchronously (Sync=false), and you should not use the Synchronous-style execution unless there is a specific reason to do so.