This is the second part of a four-part series on automating the execution of workflows within Citrix Workflow Studio.  In the first blog of the series, I discussed the basics for using Powershell to automate the execution of workflows.  In this blog, we will expand on that topic to discuss how we can pass parameters into the workflow, making our workflows much more dynamic and flexible for supporting different types of situations.

Understanding Global Properties
The key to passing parameters into a workflow is to use the global properties of the workflow.  You access the global properties within the Citrix Workflow Studio Designer by navigating to Workflow->Manage Global Properties from the file menu (shown below).

The Manage Global Properties dialog allows you to specify the global properties of the workflow.  Essentially, all you need to do here is to define the names of the global properties and their property type (String, Boolean, Integer, etc.).  I personally like to pre-fix my global properties with the letter "g" to make them easily identifiable when assigning them to activities.  You can also optionally define a default value for a global property if you want to.

Then within your workflow, you bind the global properties to the activities within the workflow.  When you edit a bindable property for an activity, you'll get an editor such as is shown below.  On the left-hand side, select Global Properties within the drop-down.  The global properties should all be listed and easily identifiable by the letter "g" in front of the name (if you named them this way).  Just select a global property and add it to the text editor to use it. 

When global properties are defined for a workflow, you define the values of the global properties when scheduling a job within the Workflow Studio Console. 

Creating a Powershell Script that passes parameters into the workflow
If you want to automate the execution of the workflow with Powershell, the Powershell script can also set the values of the global properties to pass into the workflow being executed. 

To pass parameters into the workflow, the Powershell script will have a structure similar to below.  This sample script shows how to pass two parameters into the workflow.  What we are doing here is creating a hash table that represents the name/value pairs of the global properties.  This hash table is then provided as a parameter into the schedule-workflow cmdlet.  Please note that the schedule-workflow cmdlet should be all on one line (it was split on two lines here for better readability).

#Set variables for the workflow
$strWorkflowName = "Workflow1"
$strParam1Name = "Name1"
$strParam1Value = "Value1"
$strParam2Name = "Name2"
$strParam2Value = "Value2"

#Add the Workflow Studio snap-ins to the current Powershell session
Get-PSSnapin -registered | Add-PSSnapin

#Get reference to the Workflow Studio runtime
$rt = Get-WorkflowRuntime

#Get reference to the deployed workflow
$workflow = get-deployedworkflow -workflowruntime $rt -workflowname $strWorkflowName -includeschedule

#Create hash table of parameter values to pass into workflow
$params = @{$strParam1Name = $strParam1Value; $strParam2Name = $strParam2Value}

#Schedule the workflow to run immediately
schedule-workflow -workflowruntime $rt -workflowstrongname $workflow.WorkflowStrongName
-workflowparameters $params -runimmediately

Example:
To illustrate how the passing of parameters works, let's use the SQL Server Activity Library within our workflow. This is an activity library that you can download and leverage yourself for communicating with a SQL Server database.  The beginning point of our workflow is shown below. 


In this workflow, we are using the SQLExecute activity for executing an UPDATE command on a SQL Server database.  The initial SQL UPDATE command is shown below.  Since we are hardcoding the Employee ID and Phone Number into the SQL statement here, the initial usability of this workflow is pretty limited.  It would be much better if we could make this SQL statement adaptable for different employee IDs and phone numbers.


To make this SQL statement more dynamic, we need to create global properties to represent the Employee ID and Phone Number.  Notice the prefix "g" we are using to denote the global properties.  This will make them easy to find when applying them to an activity.


Once the global properties are defined, we can use them within the SQLExecute activity.  In the screen shot below, the SQL Command is updated to reference the global Employee ID and Phone Number properties created above.


Our workflow is pretty dynamic now.  We can pass the Employee ID and Phone Number as parameters into the workflow.  When the workflow is executed, it will use the passed in values as part of this SQL statement.

The Powershell Script to automate the execution of this workflow is shown below.  Please note that the schedule-workflow cmdlet should be all on one line (it was split on two lines here for better readability).

#Set variables for the workflow
$strWorkflowName = "Workflow1"
$strParam1Name = "gEmployeeID"
$strParam1Value = "101"
$strParam2Name = "gPhoneNumber"
$strParam2Value = "555-123-4567"

#Add the Workflow Studio snap-ins to the current Powershell session
Get-PSSnapin -registered | Add-PSSnapin

#Get reference to the Workflow Studio runtime
$rt = Get-WorkflowRuntime

#Get reference to the deployed workflow
$workflow = get-deployedworkflow -workflowruntime $rt -workflowname $strWorkflowName -includeschedule

#Create hash table of parameter values to pass into workflow
$params = @{$strParam1Name = $strParam1Value; $strParam2Name = $strParam2Value}

#Schedule the workflow to run immediately
schedule-workflow -workflowruntime $rt -workflowstrongname $workflow.WorkflowStrongName
-workflowparameters $params -runimmediately

Final thoughts:
If you want to try out these Powershell scripts yourself, you'll need to follow the setup instructions as outlined in the first blog of this series. 
In the final two blogs of this series, we are going to take these Powershell scripts to the next level by converting them to an actual C# program. As you'll soon see, you'll use the information contained in these first few blogs to understand how the C# programs actually work.  Stay tuned!

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

When you begin learning Workflow Studio, you quickly learn that the Workflow Studio Designer can execute workflows for initial testing purposes and the Workflow Studio Console can execute workflows as a scheduled job.  A lot of people have been asking about how you can automate the execution of a workflow from an external system, such as Powershell, a Windows application, and an ASP.NET web application.  The real power of Workflow Studio is being able to execute a workflow when you want it to run, either manually, on a schedule, or on-demand when needed by external systems. 

This is the first blog of a new series I'm starting on how you can automate the execution of workflows from external systems, beginning with Powershell.  One thing I didn't realize when I started using Workflow Studio was how much this product was connected to Powershell.  Essentially, any action you can perform within the Workflow Studio Console has an equivalent Powershell cmdlet for it.  Using these cmdlets allows us to automate the various tasks within the Workflow Studio Console, such as executing the workflows themselves.

Workflow Setup:
If you want to execute a workflow with Powershell, the workflow needs to be in the Ready state within the Workflow Studio Console.  One thing that I prefer to do to keep the Powershell script fairly short is to pre-deploy the workflow to the Jobs section in the Workflow Studio Console.  When you pre-deploy a workflow, you are just making it available to execute as a Job without actually executing it yet.  By doing this simple step ahead of time, we can actually cut our Powershell script in half.  Please note that this is just a one time step - once you deploy it to the Jobs section you really don't have to open the Workflow Studio Console again (unless you want to make changes to your workflow itself).  The two screen shots below demonstrate how to pre-deploy the workflow to the Jobs section.

Registration of Xceed DLLs:
The Workflow Studio cmdlets leverage a few Xceed DLLs on the system.  These Xceed DLLs are part of the Workflow Studio installation and need to be present within the global assembly cache (GAC) in order for several of the Workflow Studio cmdlets to run properly.  Workflow Studio 1.1 does not actually place these DLLs into the GAC so you need to do that manually for this release.  I was told in future releases that this step will already be done for us.

There are three Xceed DLLs you need to place into the GAC:  Xceed.Compression.dll, Xceed.FileSystem.dll, and Xceed.ZIP.dll

Drag these DLLs from the C:\Program Files\Citrix\Workflow Studio folder to the C:\Windows\Assembly folder.  This process adds them to the GAC.  The end result is shown below.

Powershell Setup:
An interesting thing to note about Powershell is that scripting is turned off by default.  You can't execute a Powershell script until you enable scripting at a desired level.  I'm not exactly sure why Microsoft chose to do that since Powershell is supposed to be a scripting language, but it is fairly easy to enable scripting.

Launch Powershell (Start->Programs->Windows Powershell 1.0->Windows Powershell) and type the following command to get the current execution setting:

Get-ExecutionPolicy

If the execution policy is set to Restricted, you need to enable script execution by typing the following command:

Set-ExecutionPolicy RemoteSigned

Powershell Script:
The table below is a sample Powershell script for executing a workflow on your Workflow Studio machine.  I've tested the Workflow Studio cmdlets pretty extensively and this seems to be the simplest script I was able to create to execute a workflow. 

To use this script in your environment, just copy and paste this script into Notepad, and rename the file as a .PS1 file.  Then update the value of the $strWorkflowName variable to be the name of the workflow you want to execute.  In my next blog, I'll explain how you can tweak this script to pass parameters into the workflow.  The script below will work for any workflow that does not require parameters.

#Set variables for the workflow
$strWorkflowName = "Workflow1"
 
#Add the Workflow Studio snap-ins to the current Powershell session 
Get-PSSnapin -registered | Add-PSSnapin
 
#Get reference to the Workflow Studio runtime
$rt = Get-WorkflowRuntime
 
#Get reference to the deployed workflow
$workflow = get-deployedworkflow -workflowruntime $rt -workflowname $strWorkflowName -includeschedule
 
#Schedule the workflow to run immediately
schedule-workflow -workflowruntime $rt -workflowstrongname $workflow.WorkflowStrongName -runimmediately

Executing the Powershell script:
After the PS1 file is created, place it within an accessible place on your Workflow Studio machine.  For example, I've placed my scripts within C:\Citrix\PowershellScripts.  One thing I found out is that you want the path to the script to have no spaces, so keep that in mind as you place your PS1 file into a directory.

Next, open the Run window and type the statement below to execute your Powershell script (my script was called ExecuteWorkflow.ps1)
           powershell.exe -noexit C:\Citrix\PowershellScripts\ExecuteWorkflow.ps1

The -noexit switch above keeps the Powershell window open after the script is executed.  If the script execution was successful, you should see a Job ID as noted below.  This tells you that the workflow was successfully executed.

Troubleshooting the Powershell script:
If you are having issues with your Powershell script, the approach I typically take for troubleshooting is to launch Powershell and execute each line of the script manually until you come across the error.  Powershell can be launched from the Start Menu (Start->Programs->Windows Powershell 1.0->Windows Powershell) or by typing Powershell.exe in the Run window.

If you receive Access Denied errors, there is a good chance that the account you are running Powershell under is not a Workflow Studio admin, or does not have permissions within Workflow Studio to execute various workflow actions.  Check that your logged on user account is either a Workflow Studio admin or has these permissions.  These permissions are set inside the Workflow Studio Console within the Security section.

Most of the commands in the script above use variables.  To see the value of a variable, use the echo statement. For example:

echo $strWorkflowName

echo $workflow.WorkflowStrongName

Get-Command -PSSnapin citrix*

The output of the above statement is shown below:

If you want more information on how to use a specific Workflow Studio cmdlet, use a statement such as this:

Get-Help schedule-workflow

Blogs in this series:

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