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

Workflow Studio includes two tutorials that can be accessed from the Help menu. When you first launch Workflow Studio, you are in the management console:

The first tutorial can be accessed by clicking on the "Help...Getting Started" menu option. This will launch the Getting Started guide which is a tutorial that will walk you through the process of downloading a sample Workflow called ExportServices from CDN (using the built-in Community tab) and then running that workflow from the management interface.
Note: The tutorial is in PDF format. On many systems nothing will happen when you click on the "Help...Getting Started" link if you don't already have a PDF viewer already installed. Sorry about that - we will fix that in the next release.

The second tutorial is available from the Designer interface. The Designer interface is what is used to create or edit a workflow and looks very similar to the Tech Preview user interface:

This tutorial will take you through the process of creating the sample workflow that you saw in the first tutorial. This will demonstrate many of the techniques you will use to build workflows.

If you have any questions on either of these tutorials - post them here. In a future post I will explain some more details behind the Designer interface. Look for more tutorials and samples soon as well.

Many people have asked me how to build custom dialogs in Workflow Studio. Enough people have asked that I have built custom dialogs as native tasks in Workflow Studio and I have also built them in PowerShell (something you could do right now with the tech preview.) Before I post more information on how to do this though I want to better understand why people want to have custom dialogs.

An example that I often hear is that someone wants to modify one of our samples to prompt the user for their username and password in the same dialog instead of using two dialogs. Another example I hear is that people would like a multi-column display tool (like a grid) to display the contents of objects output from other tasks. When people ask me for this I begin to wonder how they plan to use the workflow once they get beyond testing it. When we created those samples we included the user input to ensure that the user is aware of what the workflow is doing and to provide a way for them to input the settings specific to their environment. We expect that most people will deploy workflows with these settings pre-configured in the tasks directly or by using the "Set Variable Value" task and that any output would be to XML files or other tasks.

I wrote a post on IT Process Automation with Workflow Studio that looks at some of the use cases we expect Workflow Studio to be used for. Read through that earlier post for a little deeper look at how I think workflows will be used.  [And if you think I am wrong please leave me a comment or send me an email...]

With that post in mind, I believe that the people requesting richer interaction from a workflow are either looking to do a lot of "On-Demand Automation" or they are looking for Workflow Studio to offer a richer set of debugging tools for desiging and debugging workflows. If you have read this far then take my poll and tell me which you think it is for you?

Why do you want a richer set of Input/Ouput tasks in Workflow Studio?	Choose
To make designing and debugging workflows easier - I would delete them before deploying.
Because I expect to use "On-Demand Automation" type tasks heavily and not schedule workflows to run automatically
I don't need richer user interface options

Building your first workflow with Citrix Workflow Studio is incredibly easy. We include many templates with the Tech Preview that allow you to see how the product works quickly and easily.

First go download the product - http://www.citrix.com/wfsinsider (MyCitrix login required, but it is painless to get one.)

Once you download and install the product you will see the following the first time you launch it:

Just click the box where it says "Create a new workflow based on a Workflow Template" and you will see the following:

Provide a name for your new workflow and select one of the workflow templates that we included with the product. The easiest one to set up and understand for your first time is the one under "Windows Management" called "Start Stopped Services". Select that one from the list and click "OK". You should see the Workflow Studio Designer interface with the template loaded like this:

 You now have built your first workflow. Click "Start" to run the workflow and you should be presented with a list of the services that are currently in a stopped state on your machine. Much like the following:

If you select one or more services and click "OK" Workflow Studio will attempt to start those services.

Note: If the service is disabled Workflow Studio will not be able to start it and will return an error. Take a look at the workflow and see if you can modify it to exclude the services that are in a disabled state.

I would love to see comments on what people think about Workflow Studio and what they would like to use it for in their environment. I plan to post some more advanced workflow samples in coming weeks, so let me know what you would like to see.