This is the third part of a four-part series on automating workflow execution within Citrix Workflow Studio.  In the first two parts of the series, I discussed how you can create Powershell scripts to execute workflows.  Part 1 provided a high-level overview of creating Powershell scripts for automating workflow execution and Part 2 expanded on those scripts to discuss how to pass parameters into the workflow.  In this blog, I will discuss how you can automate workflow execution with a custom Windows application.  The sample .NET application I built is shown below.  I am providing both the executable and full source code to allow you to expand upon this solution to meet the needs of your environment.

When would I need to use a custom application for executing workflows?
A lot of you might be asking the question – “If we can use the Workflow Studio Console to execute workflows, why would I need a custom application to do that for me?”.  The answer really comes down to how you need to execute certain workflows in your environment.  If you need to execute workflows “on-demand” or “on a schedule“, the Workflow Studio Console would meet those needs.  Just open the Workflow Studio Console and schedule a job to run immediately or on a pre-determined schedule.  However, if you need “event-driven” automation where a third-party application kicks off the execution of a workflow based on an event happening, that is where you need to be able to hook into Workflow Studio with a custom solution to perform that type of automation. 

The custom application provided in the Downloads section below provides a sample for how you can tie any .NET windows application to Workflow Studio for executing workflows.  Feel free to try out the sample application on your Workflow Studio machine.  The full source code is also provided to allow you to customize and extend the application further based on what you need to do.

Download the application executable here
Download the application source code here

Preparing your Workflow Studio environment to use the custom application:
The custom application needs to run on a machine that contains Workflow Studio since it ties into Powershell and calls the Workflow Studio cmdlets for performing various actions on Workflow Studio.  In your Workflow Studio Console, you will need to pre-deploy the workflow that you want to automate (see Part 1 for more information on pre-deploying workflows).  The workflow that you want to automate can include parameters as well.  Parameters for a workflow are defined in the Workflow Studio Designer under the Global Properties section (see Part 2 for more information on defining workflow parameters).

This custom application functions as any typical Windows application in that it runs under the context of the logged-on user account.  The logged-on account needs to have permissions in Workflow Studio to execute workflows.  These permissions are defined in the Security section of the Workflow Studio Console.  For simplicity, I typically add the user accounts as a “Workflow-Admin“, but you can play with the security roles here to determine what roles are actually needed.

Using the custom application:
To use the custom application, log onto your Workflow Studio machine with an account that has permissions to execute workflows within Workflow Studio.  Place WFSWorkflowExecute.exe on your Workflow Studio machine.  When you launch the application, the initial view is shown below.

Click the Get Runtimes button to get the Workflow Studio runtimes that are installed on the local machine.  The runtimes are listed within the combo-box below and the name of the runtime specifies which account the runtime is running under.  

When a runtime is selected, all of the workflows that are deployed on that runtime are listed as well.  To execute a certain workflow, you need to know which runtime you deployed the workflow on.   This sample application also provides the version of the workflow as you may have deployed two different versions of the same workflow to the same runtime.  Using the version numbers helps you keep them straight.

When you want to execute a workflow, you need to know if that workflow requires any parameters.  The workflow parameters are defined in the Workflow Studio Designer in the Global Properties section of the workflow.  As mentioned above, Part 2 of this blog series goes into detail on how to define and use parameters inside a workflow.

When specifying workflow parameters inside the custom application, the parameter name is case sensitive.  (Notice how I kept the parameter name as “gMessage”).  If you mistype the parameter name or use the wrong case, you will get an error message when executing the workflow stating that the parameter name is not recognized.  Just keep this in mind as you type the name of the parameters into the application.

Click the Execute Workflow button to execute the workflow.  If the workflow was successfully executed, you’ll get a pop-up message indicating success.

To verify the workflow was executed, you can open the Workflow Studio Console and check out the Jobs section.

Understanding the source code:
A lot of you out there will want to customize this application in your own environment.  I developed this application with C# using Visual Studio 2008 and the Powershell SDK.  Your development machine will also need Powershell 1.0 and Citrix Workflow Studio.  For advice on setting up your Visual Studio environment, check out this article.  If you follow the steps in that article, you’ll just need to add the Powershell SDK and you should be all set.

The Powershell SDK is included as part of the Windows Software Development Kit.  You can get information on the Poweshell SDK here.  I downloaded the full ISO and it took me quite a while to get it.  When you are ready to install, you don’t need everything in the setup wizard.  The Powershell SDK link provided above actually tells you what you specifically need to install to just get the Powershell SDK.  To use the Powershell SDK inside your Visual Studio project, the project will need to reference System.Management.Automation.dll.  

Once you get your development machine set up, you can open the solution that I provided above inside Visual Studio.  Essentially all this custom application does is use the Powershell SDK APIs to execute cmdlets on Powershell.  Since Workflow Studio provides Powershell cmdlets to automate various tasks, we can use the Powershell SDK to automate many Workflow Studio functions. 

From my personal experience, using the Powershell SDK takes a little time getting used to.  What I found to be helpful is to first write out the Powershell commands in Notepad and test them within Powershell to make sure they are functioning as expected.  If you are working with Powershell variables, use the echo statement frequently to understand the current value of the variable.  Then when you are ready to use the Powershell SDK in your Visual Studio project, you can convert each of your Powershell statements to the equivalent Powershell SDK code.  In the source code that I provided for this custom application, I put comments into the code to explain what Powershell command I was trying to execute within that code block.  Reviewing those comments should help you to get started with understanding how to use the Powershell SDK.  For example, here is the ExecuteWorkflow() function that is used by the custom application.  Stepping through this code inside Visual Studio and watching the variables is another great way to learn this code.

<span class="code-keyword">public</span> string ExecuteWorkflow(Hashtable objFunctionParameters, Hashtable objWorkflowParameters)
   <span class="code-keyword">try</span>
      <span class="code-comment">//Declare local variables
</span>      string l_strReturn = <span class="code-quote">"Executing workflow"</span>;
      string l_strWorkflowName = objFunctionParameters[<span class="code-quote">"WorkflowName"</span>].ToString();
      string l_strRuntimeName = objFunctionParameters[<span class="code-quote">"RuntimeName"</span>].ToString();
      Hashtable l_objWorkflowParameters = objWorkflowParameters;

      <span class="code-comment">//Create a runspace containing the Workflow Studio snap-ins
</span>      RunspaceConfiguration l_objRSConfiguration = RunspaceConfiguration.Create();
      PSSnapInException l_objSnapInException = <span class="code-keyword">null</span>;
      l_objRSConfiguration.AddPSSnapIn(<span class="code-quote">"Citrix.WorkflowStudio.Azman"</span>, out l_objSnapInException);
      l_objRSConfiguration.AddPSSnapIn(<span class="code-quote">"Citrix.WorkflowStudio.Core"</span>, out l_objSnapInException);
      l_objRSConfiguration.AddPSSnapIn(<span class="code-quote">"Citrix.WorkflowStudio.DataStore"</span>, out l_objSnapInException);
      l_objRSConfiguration.AddPSSnapIn(<span class="code-quote">"Citrix.WorkflowStudio.Installer"</span>, out l_objSnapInException);
      Runspace l_objRunspace = RunspaceFactory.CreateRunspace(l_objRSConfiguration);

      <span class="code-comment">//Get reference to the Workflow Studio runtime that was passed in.
</span>      <span class="code-comment">//We are executing the Powershell command below:
</span>      <span class="code-comment">//$rt = Get-WorkflowRuntime -ServiceName $ServiceName
</span>      Pipeline l_objPipeLine = l_objRunspace.CreatePipeline();
      Command l_objCommand = <span class="code-keyword">new</span> Command(<span class="code-quote">"get-workflowruntime"</span>);
      l_objCommand.Parameters.Add(<span class="code-quote">"ServiceName"</span>, l_strRuntimeName);
      Collection&lt;PSObject&gt; l_objCommandResults = l_objPipeLine.Invoke();
      PSObject l_objRuntime = l_objCommandResults[0];
      l_objPipeLine = <span class="code-keyword">null</span>;

      <span class="code-comment">//Get reference to the deployed workflow that was passed in.
</span>      <span class="code-comment">//We are executing the Powershell command below:
</span>      <span class="code-comment">//$workflow = get-deployedworkflow -workflowruntime $rt -workflowname $strWorkflowName -includeschedule
</span>      l_objPipeLine = l_objRunspace.CreatePipeline();
      l_objCommand = <span class="code-keyword">new</span> Command(<span class="code-quote">"get-deployedworkflow"</span>);
      l_objCommand.Parameters.Add(<span class="code-quote">"workflowruntime"</span>, l_objRuntime);
      l_objCommand.Parameters.Add(<span class="code-quote">"workflowname"</span>, l_strWorkflowName);
      l_objCommand.Parameters.Add(<span class="code-quote">"includeschedule"</span>);
      l_objCommandResults = l_objPipeLine.Invoke();
      PSObject l_objWorkflow = l_objCommandResults[0];
      l_objPipeLine = <span class="code-keyword">null</span>;

      <span class="code-comment">//Schedule the workflow to run immediately.
</span>      <span class="code-comment">//We are executing the Powershell command below:
</span>      <span class="code-comment">//schedule-workflow -workflowruntime $rt -workflowstrongname $workflow.WorkflowStrongName -workflowparameters $wfparameters -runimmediately
</span>      l_objPipeLine = l_objRunspace.CreatePipeline();
      l_objCommand = <span class="code-keyword">new</span> Command(<span class="code-quote">"schedule-workflow"</span>);
      l_objCommand.Parameters.Add(<span class="code-quote">"workflowruntime"</span>, l_objRuntime);
      l_objCommand.Parameters.Add(<span class="code-quote">"workflowstrongname"</span>, l_objWorkflow.Properties[<span class="code-quote">"WorkflowStrongName"</span>].Value.ToString());
      l_objCommand.Parameters.Add(<span class="code-quote">"workflowparameters"</span>, l_objWorkflowParameters);
      l_objCommand.Parameters.Add(<span class="code-quote">"runimmediately"</span>);
      l_objCommandResults = l_objPipeLine.Invoke();
      l_objPipeLine = <span class="code-keyword">null</span>;

      <span class="code-comment">//Close the runspace
</span>      l_objRunspace.Close();

      <span class="code-comment">//Return success
</span>      l_strReturn = <span class="code-quote">"Job completed!"</span>;
      <span class="code-keyword">return</span> l_strReturn;
   <span class="code-keyword">catch</span> (Exception objException)
      <span class="code-comment">//Initialize error message
</span>      string l_strError = "";
      l_strError = <span class="code-quote">"An error has occurred. The error is \"</span><span class="code-quote">" + objException.Message.ToString() + "</span>\<span class="code-quote">". "</span>;
      <span class="code-keyword">return</span> l_strError;

Blogs in this series:
Using Powershell to automate workflow execution within Citrix Workflow Studio
Passing parameters into a workflow within Citrix Workflow Studio
Automating workflow execution for Citrix Workflow Studio using a .NET windows application (this one)
Automating workflow execution for Citrix Workflow Studio using an ASP.NET web application