One of the most common questions I've heard on Workflow Studio is how you can initiate the execution of workflows from an ASP.NET web page.  The web is a great platform for delivering applications to end-users, and more and more applications are being delivered by a web browser each day.  How cool would it be to kick off a workflow within Workflow Studio based on a user-action performed inside a web application?  In this blog I'm going to show you how to do it and I'll give you the tools to customize this further to meet the needs of your application.

Example Usage
Before I go into the details about how the sample web application works, I want to quickly provide an example of why you may want kick off workflow execution from a web page.  As you think about your business, ask yourself what it takes to get a new hire set up with new credentials across all of the systems in your environment.  You need an Active Directory account, application accounts, HR accounts, credentials supplied to your single sign-on solution, etc. 

To accommodate this scenario, you can build a web page that presents a form to an admin to gather details about a new user, what groups they should belong to, and what applications/resources they need to access.  This web page can call a workflow within Workflow Studio passing in the details about the user, and the workflow can automate the provisioning of the Active Directory account and application accounts across various systems.  That's a pretty powerful system and would greatly simplify a lot of the complexities for performing those actions manually.  Building that type of workflow might take some custom development effort, but Workflow Studio 1.1 already provides activities for provisioning user accounts in Active Directory to help get you started.

ASP.NET Web Application Overview
The sample web application that I'm providing here is functionally equivalent to the sample Windows application that I provided in the last blog.  To compare and contrast the differences between automating workflows with a Windows and Web application, I wanted to keep the functionality and UI mainly the same.  The web version of the application is shown below.

I describe my adventures for coding this application in the bottom of this article.  To sum up, this application really has two parts.  You have the ASP.NET application that contains the ASPX page and code-behind page.  You also have a COM object that you need to install inside Component Services. (I have steps for doing all this below). 

When you click the Execute Workflow button inside the web page, the ASPX page gathers what workflow you are executing and what runtime it is deployed on.  It then calls the COM object to actually execute the workflow.  The COM object uses the Workflow Studio Powershell cmdlets for communicating with Workflow Studio.  I was getting security issues when I tried to run those functions within the context of IIS.  By creating a COM object and placing that object within Component Services, I was able to overcome the issues I was having. 

For more information on how this application works, feel free to check out the previous article of this blog series.  I described in great detail how the Windows version of this application functions, so I'll refer you to that article for the extra details.  For more information on why I needed to build the COM object, refer to the Lessons Learned section at the bottom of this article.

Downloads:
Download the ASP.NET web application IIS files
Download the ASP.NET web application source code

Prereqs for using the ASP.NET application:
Before you set up this web application on your Workflow Studio machine, you will need to have the following installed and/or configured beforehand:

• Workflow Studio 1.1
• Powershell 1.0
• IIS installed with ASP.NET enabled
• IIS configured with the ASP.NET v2.0.50727 web service extension set to Allowed
• Determine or specify an account within the Workflow Studio Console for executing the workflows.  This is done within the Security section.
• Pre-deploy the Workflow you want to execute within the Workflow Studio Console.  See Part 1 of this blog series for more information.

Setting up the ASP.NET application:
To set up this sample web application, follow the steps in the sections below.

Application Setup

• Copy the IIS files from the ZIP above to C:\Citrix (or any accessible location on your Workflow Studio machine)
• Update the web.config file with the appropriate impersonation account.  This account should have permissions to execute workflows within Workflow Studio and should be the same account that is added to Component Services later in these steps.  

IIS Setup

• Open IIS and create a virtual directory for the application.  Point the virtual directory to the folder specified above.  Enable script execution on the directory.
• View the properties of the virtual directory in IIS. In the ASP.NET tab, set the ASP.NET version to 2.0.50727.

Component Services Setup

• Launch Component Services by navigating to Start->All Programs->Administrative Tools->Component Services
• Within Component Services, navigate to Computers->My Computer->COM+ Applications.  Right-click COM+ Applications and select New->Application
• The wizard now starts.  Create an empty application
• Specify a name such as "WFSCOM" and select Server Application
• Set the application identity to a Workflow Studio admin account
• Create a new role called "Access"
• Add the Workflow Studio admin account to the Access role
• Complete the wizard
• After the COM+ application is created, add a new component to the COM+ application.  Navigate to Computers->My Computer->COM+ Applications->WFSCOM->Components.  Right-click Components and select New->Component.
• The wixard now starts.  Choose to install a new component
• Browse to the WFSCOM.dll file (C:\Citrix\WFSWebClient\bin\WFSCOM.dll).
• Complete the wizard
  

You should now see the WFSCOM.WFSAction COM object listed within the Components section.  In the Interfaces section, there is an inteface called IWFSAction that contains the methods of our COM object.  The ASP.NET code calls the COM object to execute these methods.  Since this object resides inside Component Services, these methods run outside the context of IIS under the Workflow Studio admin account that we specified above. 

Lessons learned from developing this application
Developing an ASP.NET web application that executes workflows actually turned out to be a little more difficult than building the equivalent Windows application.  With a Windows application, the application runs under the context of the logged-on user account. If that logged on user had permissions to execute workflows inside Workflow Studio, that user would be able to use the custom Windows application without issues.  With a Web application, the application runs under the context of IIS.  You can modify the account that runs a web application in a few places.  (1) Editing the properties of the virtual directory or (2) Including a <identity impersonate="true"> tag inside the web.config file of the ASP.NET application. 

Armed with that knowledge I set out to build the ASP.NET application.  The approach I initially took was to take all of the code I had inside the Windows application and paste it into the ASPX page and code-behind page.  The only thing I changed was I replaced all of the Windows controls with Web controls and I changed how I sent messages back to the user.  When debugging this application inside Visual Studio, my application actually ran fine.  However when I deployed it to IIS and ran it, that was a different story.  I kept on getting Access Denied messages whenever I wanted to retrieve the workflow list or execute a workflow.  Something inside those functions was causing me issues...

After much debugging, I deduced that the code that was causing the Access Denied messages was when I was trying to get a reference to the deployed workflow inside my PowerShell SDK code.  For whatever reason, IIS just did not have the permissions to execute the Workflow Studio Powershell cmdlet called get-deployedworkflow.  I put this section of code below so you are aware of which section I was having issues with.

//Get reference to the deployed workflow. We are executing the Powershell command below:
//$workflow = get-deployedworkflow -workflowruntime $runtime -workflowname $strWorkflowName -includeschedule
l_objPipeLine = l_objRunspace.CreatePipeline();
l_objCommand = new Command("get-deployedworkflow");
l_objCommand.Parameters.Add("workflowruntime", l_objRuntime);
l_objCommand.Parameters.Add("workflowname", l_strWorkflowName);
l_objCommand.Parameters.Add("includeschedule");
l_objPipeLine.Commands.Add(l_objCommand);
l_objCommandResults = l_objPipeLine.Invoke();   //Get Access Denied here when running this code in IIS
PSObject l_objWorkflow = l_objCommandResults[0];
l_objPipeLine = null
 
 

After playing with the Virtual Directory account settings and web.config impersonation settings for a while, I still was not able to get past the Access Denied message.  I would have thought that setting the web.config <identity> tag to the Workflow Studio admin account would have done the trick, but I still received that error message.  So I then I went to Plan B and thought of a different approach.  What if I take that particular code outside of IIS and put it into a more controlled environment where I can run it under whatever account I want and not have to worry about IIS getting in the way? 

That solution was Component Services.  I'm not an everyday developer (probably have one development project a year), but I remembered using Component Services many years back with a MFCOM application I wrote.  (MFCOM is the XenApp API).  With that application, I wanted to be sure that my MFCOM code would run under the context of a XenApp admin account and not the logged on user account.  So creating a COM object and placing that object within Component Services allowed me to run it under whatever account I needed.  With Component Services, you also have the choice of running the COM object in-process as a library application or out-of-process as a server application.  When you run it out of process, it is executed within a different memory space than the calling application.  Creating a COM object and executing it as a server application under the context of a Workflow Studio admin account was the missing ingredient for the Web Application that I was building.  Since it runs out-of-process, IIS can't get in the way and mess with those security permissions any more!

Although most of the Workflow Studio cmdlets functioned fine when running within IIS, I decided to move the entire Powershell SDK functions themselves to the COM object that I would run within Component Services.  Although this sounds really complicated, the good news is that I've done all the work for you.  The COM object that I am providing within this article has all the functions you need for executing a workflow.  If you want to create your own ASP.NET application that executes workflows, you just need to add my COM object to Component Services on your Workflow Studio machine, and then call the methods of the COM object inside your ASPX page.  If you are reading this article, I would venture to guess that you might have quite a bit of experience in working with ASP.NET so you should have the tools you need to proceed from here. 

About the source code:
The source code above includes both the ASP.NET web application and the COM object for executing the workflows.  Your development machine will need Visual Studio 2008, Workflow Studio, Powershell 1.0, Powershell SDK, and IIS. 

If you want to step through the code within Visual Studio, you'll need to place the COM object within Component Services on your development machine.  You can follow the manual steps above for doing this or use the regsvcs utility.  To use regsvcs.exe, open the Visual Studio command prompt and type a command such as this:

regsvcs /c "C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\WFSWebClient\WFSCOM\bin\Debug\WFSCOM.dll"
 
 

I tried to code the COM object so that you wouldn't need to make any changes to it if you just wanted to execute workflows on Workflow Studio.  If you do need to make changes to the COM object for any reason, remove the COM object from Component Services.  If you placed the COM object within the global assembly cache (GAC), remove it from the GAC as well.  (The GAC resides in C:\Windows\Assembly.  Just right-click on the WFSCOM assembly to un-install it).  Then open the Visual Studio solution and make changes to the WFSCOM project as you need to.  Re-compile the project.  When you are ready to re-deploy the COM object, add WFSCOM.dll to the global assembly cache (GAC) to get a new type library (.tlb file).  To add it to the GAC, just execute a command such as below.  Then re-add WFSCOM.dll back to Component Services using the regsvcs command above.  If you open Component Services, you should now see the WFSCOM COM+ application listed.

gacutil.exe /i "C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\Projects\WFSWebClient\WFSCOM\bin\Debug\WFSCOM.dll"
 
 

I hope this blog series on automating Workflow Studio will help you out with your projects.  Happy coding!

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
Automating workflow execution for Citrix Workflow Studio using an ASP.NET web application (this one)

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.

Downloads:
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.

public string ExecuteWorkflow(Hashtable objFunctionParameters, Hashtable objWorkflowParameters)
{
   try
   {
      //Declare local variables
      string l_strReturn = "Executing workflow";
      string l_strWorkflowName = objFunctionParameters["WorkflowName"].ToString();
      string l_strRuntimeName = objFunctionParameters["RuntimeName"].ToString();
      Hashtable l_objWorkflowParameters = objWorkflowParameters;

      //Create a runspace containing the Workflow Studio snap-ins
      RunspaceConfiguration l_objRSConfiguration = RunspaceConfiguration.Create();
      PSSnapInException l_objSnapInException = null;
      l_objRSConfiguration.AddPSSnapIn("Citrix.WorkflowStudio.Azman", out l_objSnapInException);
      l_objRSConfiguration.AddPSSnapIn("Citrix.WorkflowStudio.Core", out l_objSnapInException);
      l_objRSConfiguration.AddPSSnapIn("Citrix.WorkflowStudio.DataStore", out l_objSnapInException);
      l_objRSConfiguration.AddPSSnapIn("Citrix.WorkflowStudio.Installer", out l_objSnapInException);
      Runspace l_objRunspace = RunspaceFactory.CreateRunspace(l_objRSConfiguration);
      l_objRunspace.Open();

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

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

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

      //Close the runspace
      l_objRunspace.Close();

      //Return success
      l_strReturn = "Job completed!";
      return l_strReturn;
   }
   catch (Exception objException)
   {
      //Initialize error message
      string l_strError = "";
      l_strError = "An error has occurred. The error is \"" + objException.Message.ToString() + "\". ";
      return l_strError;
   }
}

I just recently posted a SQL Server activity library to the Citrix Developer Network (CDN).  The SQL Server activity library allows you to execute SQL statements (SELECT, INSERT, UPDATE, DELETE, etc.) on a Microsoft SQL Server database as part of a workflow within Citrix Workflow Studio.  The activity library, setup instructions, and full source code can be downloaded here.

I actually needed this type of library for a Workflow Studio project I'm currently on.  I coded the activity library to be general enough for anyone to use within their own environments.  The environment I've been using with this activity consists of Workflow Studio 1.1 and SQL Server 2005.  I haven't tested with other versions of SQL Server, but I am providing the full source code to this library in case you need to tweak anything.

There are two activities within the SQL Server activity library:

• SQLSelect activity - used to run SELECT queries on a database.  The output of this activity is a collection containing the query results.  Since the output is a "collection" type object, you can loop through this collection within Workflow Studio using the For Each Object activity and dump the collection contents to an XML file via the ExportToXML activity.
• SQLExecute activity - used to run INSERT, UPDATE, and DELETE queries on a database.  The output of this activity is a string containing the number of records affected by the SQL statement.

There are five properties that need to be set on the SQLSelect/SQLExecute activities:

• Database Server - SQL Server machine hosting the database
• Database Name - Name of the database to connect to 
• SQL Command - SQL statement to execute on the database 
• SQL Username - SQL Server username for connecting to the database 
• SQL Password - SQL Server password for connecting to the database 

The SQL Command property will be set differently based on which SQL activity you are using.  The SQLSelect activity will expect a SELECT statement here.  The SQLExecute activity will expect an INSERT, UPDATE, or DELETE statement here (essentially any non-SELECT query).

The SQL Server activity library was developed using the Workflow Studio SDK:
If you need to review the code and make changes, I highly recommend reviewing my previous blog series on using the Workflow Studio SDK.  This blog series will help you get your Visual Studio development environment up and running so you can make changes to the code. 

For the programmers out there, the activities themselves leverage the standard ADO.NET objects for connecting to a SQL Server database and executing a command.  If you are familiar with ADO.NET, then the code should be fairly straightforward to walk through.

Finally:

When you check out the CDN you'll see the full setup and usage instructions so I didn't restate them here.  The SQL queries you execute can be static (using hard-coded values) or dynamic (based on the bindable properties of other activities within the workflow).  This makes this activity pretty flexible to use in any kind of situation or query you may encounter.  Have fun and I hope this helps you out as well!

A great way to learn how to use the Workflow Studio SDK is to look at code examples that you can try and implement yourself.  The Activity Developer's Guide provides a few simple activities to help get you started.  If you are looking for a more robust activity sample to set up and review, I just recently posted a sample activity called AppList to the CDN site for you to download.  The AppList activity, setup instructions, and full source code can be downloaded here.

What is the AppList activity?
The AppList activity is a sample activity based on MFCOM that retrieves the list of applications that are published within a XenApp 4.5 farm.  This activity communicates with a XenApp 4.5 server, so you'll need a XenApp 4.5 farm in order to run and test this activity.  Even if you do not have a XenApp server handy, you can at least review the source code to get more details of how to code your activities.

The output of this activity is a collection of application objects, where each application object contains details about a published application in the farm.  By returning a collection of objects, you can use the other activities within Workflow Studio to loop through this collection or output the entire collection contents to an XML file (see picture below).   

Sample workflow
In the workflow pictured above, the "AppList" activity retrieves the list of published applications.  The output of this activity is then tied to the "ExportToXML" activity to export the contents to an XML file.  The XML file will contain a list of the applications published within the XenApp farm along with their various attributes (executable path, description, window size, audio setting, etc). 

The screen shot below shows a sample XML file that is generated. The first application listed here is "Notepad", along with various attributes for how Notepad was published.  If you want a quick way of archiving how all of your applications are published, this is a nice and simple way of doing so without having to visit the properties of each published application within the Access Management Console. 

How is this sample useful?
I've spent most of this blog explaining what this activity does.  But the real reason for posting this activity is the source code.  Feel free to open the source code inside Visual Studio to get an idea of how this type of activity is coded.  Take a look at the MFCOM code for pulling back the list of published applications.  MFCOM is a pretty robust API and I only tapped into a few objects to make this activity happen.  You can do so much more with it to perform other actions on XenApp.  In the near future I hope to provide more blogs about this particular example and explain the various sections of the code.  In the mean time, feel free to try to get it up and running, step through the code, and experiment (test environments only please!). 

What is MFCOM?
For those of you not familiar with MFCOM, MFCOM is the name of the API provided by XenApp for performing various administrative actions on a XenApp farm via code.  MFCOM (MetaFrame Component Object Model) has been around for quite some time across several different releases (XenApp, Presentation Server, and MetaFrame).  When you use MFCOM, you'll quickly realize that a lot of the actions that you can normally do within the Access Management Console you can also do with MFCOM API calls.

MFCOM has a client/server architecture where the MFCOM client is the client machine running your MFCOM program and the MFCOM server is the XenApp Server itself.  In the case of our Workflow Studio activity discussed here, the Workflow Studio machine is considered the MFCOM client.  MFCOM clients communicate with MFCOM servers via DCOM calls.  When you install MFCOM on your Workflow Studio machine, the installation will have you specify the XenApp server you want to communicate with via DCOM.  You do not need to make any updates or changes to your XenApp server as the server-side MFCOM components are already implemented by the XenApp installation.

Additional Resources:
If you want more information on the Workflow Studio SDK, feel free to check out my SDK blog series.

If you want to step through the AppList source code while running the activity within Workflow Studio, you should check out this post on how to set this up.

It's now time to wrap up this series on the Workflow Studio SDK and talk about a pretty handy topic for debugging the activities that you create within Visual Studio.  If you have developed code in the past, you know that one of the most handy ways to debug your code is to step through your code in real-time as the program is running.  As you step through your code, you can check the programming logic and make sure it is executing as expected.  You can also "watch" variables as they are declared and populated with values.  Watching variables is especially important if they are being filled from backend database calls or APIs. 

In this article, I'm going to show you how you can step through your Visual Studio code in real-time as your activity is being executed within the Workflow Studio Designer.  As always, I'll keep the process simple and break it down into the following steps:
• Step 1 - Initial setup
• Step 2 - Place break points in the Visual Studio project
• Step 3 - Verify the project build settings
• Step 4 - Attach Visual Studio to the WorkflowExpressRuntime.exe process
• Step 5 - Start the workflow within the Workflow Studio Designer
• Step 6 - Step through your code in Visual Studio when your break points are hit
 

Step 1 - Initial setup
Workflow Studio needs to be installed on your Visual Studio development machine.  This allows Visual Studio to attach to the various Workflow Studio processes for stepping through your code (as discussed in a later step).

Next, when you are ready to test your workflow and step through your code, you essentially need two programs running.  First, you need your Visual Studio project opened so you can step through your code.  Second, you need the Workflow Studio Designer opened so you can place your activity in a workflow and initiate the test.  If you do not know how to add your activity to the Workflow Studio Designer, please refer to my last blog (Part 4) on how to test your new Activity DLL within Workflow Studio. 

I'm going to use the same "AdvancedDelay" example that I discussed in the last blog to illustrate the step-through process.  My workflow is shown below.  The activity I'm trying to step-through is the AdvancedDelay activity.  This activity inserts a delay into the workflow for a specified amount of time (about 5000 milliseconds in this example).  When this activity completes, a message box will pop up via the MessageBox activity.

Step 2 - Place break points in the Visual Studio project
Once you have your activity placed in a workflow within the Workflow Studio Designer, you can place break points in your Visual Studio project.  In this example, I placed a breakpoint in the line of code that is actually performing the delay here.  Within the execution section of my activity project, the Sleep() call is actually performing the delay.  I want to step through this code myself to make sure it works while my workflow is running.

Step 3 - Verify the Project Build settings.
Your Visual Studio project needs to be set up in a certain way in order for you to step through your code in real-time.  The following two screen shots show how I have my project set up.  You can access these same screens by going to the Properties of the activity project. 

I actually did not have to make any changes to the project settings as is shown here - my project was already set up correctly based on the project template.  Your project is most likely already set up this same way as well.  I really wanted to give you these screens here for reference in case you were playing with these properties during the development stage.  A few things you'll need to check at the least:
• Your project should be in "Debug" mode instead of "Release" mode. 
• The "Optimize code" setting should be disabled
• In the Advanced dialog, the "Debug Info" setting should be set to "full".

Step 4 - Attach Visual Studio to the WorkflowExpressRuntime.exe process
Next, navigate to Tools-->Attach to Process within Visual Studio.  In the Attach to Process dialog, select "WorkflowExpressRuntime.exe".  This is the process used by the Workflow Studio Designer for executing workflows.  If you do not see this process listed, it means that you do not have the Workflow Studio Designer open.   

If you are curious about what the "WorkflowRuntimeHostService.exe" process is, that is the process used by Workflow Studio for executing regular jobs.  If you want to step through your code when executing a job instead of using the Workflow Studio Designer, you can attach to that process instead and then run a job containing this activity.  It's pretty cool we have some flexibility here for stepping through our code in either situation!

Step 5 - Start the workflow within the Workflow Studio Designer
Once Visual Studio is attached to the correct process, we are ready to begin our test.  Start the workflow within the Workflow Studio Designer.  When our custom activity is executing (AdvancedDelay1), any break points that are hit within our code will automatically bring up Visual Studio at those break points.

Step 6 - Step through your code in Visual Studio when the break points are hit
Our break points are now getting hit and we can begin stepping through our code.  The standard way to step through your code in C# is with the following keys - Step Over (F10), Step Into (F11), Step Out (Shift + F11), and Continue Execution (F5).

In our example below, we set a break point when our Sleep() command actually performs the delay.  If you execute this statement, the sleep will actually occur for the specified amount of time as specified within the activity (which is 5 seconds here). 

Final remarks:
You should now be well on your way for creating custom activities within Visual Studio, testing them, and stepping through your code for advanced debugging.  I hope this series was helpful and stay tuned for more information on using the SDK.  If there are certain topics that you would like us to focus on in the future, please let us know!

Blogs in this series:
• Getting Started
• Setting up your Visual Studio development environment
• Anatomy of a Workflow Studio activity project
• Testing your Workflow Studio activity project
• Stepping through your Visual Studio code (this one)

After attending Citrix Synergy last week, I wanted to come back and complete this 5 part series that I started before the conference began.  In the last article (Part 3), I discussed the anatomy of a Workflow Studio project.  The information in that article should help you get started in coding your activities.  Next on the list is to discuss how to test your activity project within Workflow Studio once you've completed a bulk of the code in Visual Studio.

If you want to follow along with me, you should create the AdvancedDelay activity project as outlined within the Workflow Studio Developers Guide.  The AdvancedDelay activity inserts a delay into your workflows for a specified amount of time.  As discussed in the Developers Guide, the code that you add is pretty straightforward.  You are just adding a property to specify the delay time and a sleep command in the execution section to perform the actual delay.

To make the testing process simple, I'll break it up into the following sections.  Each section is discussed in more detail below.
• Before you begin
• Build your solution in Visual Studio
• Copy the activity DLL to the Workflow Studio activities folder
• Launch Workflow Studio and create a new workflow project
• Add the activity to the workflow project and run/test the workflow

Before you begin
Before you compile your project, you should check out a few settings that are placed at the top of your activity file.  If you are following the AdvancedDelay example, open the AdvancedDelay.cs file and check out the activity settings at the top.
• DisplayNameAttribute - this is the name of the activity as it will appear in the Workflow Studio Designer.
• ActivityTreePath - this is the location that the activity will be placed in within the Workflow Studio Designer activity pane.  In the example below, I'm placing this activity within the General/Custom Activities folder.  You can place this activity anywhere in the activity pane.

Build your solution in Visual Studio
You build the solution like any other Visual Studio project.  Just navigate to Build-->Build Solution in the file menu.  Verify that the build succeeds within the Output window at the bottom of Visual Studio. 

Copy the activity DLL to the Workflow Studio activities folder
After you compile the project, a DLL is produced that contains your activity project code.  This DLL is typically found in a sub-directory where your Visual Studio project resides on the system.  In my environment, this DLL was found in my user profile since my Visual Studio projects are all written to my user profile ("C:\Documents and Settings\Administrator\My Documents\Visual Studio 2008\ProjectsAdvancedDelay\AdvancedDelay\bin\Debug").

Copy the activity DLL (AdvancedDelay.dll in this example) and paste into "C:\Program Files\Citrix\Workflow Studio".  Your DLL will need to be here in order for Workflow Studio to use it. 

Note:  If your project happens to reference other 3rd party DLLs that you added manually to the project (for example, mfcom.dll for tying into XenApp), you'll need to add these extra DLLs to the above folder as well.  This allows the Workflow Studio Designer and Runtime to pick up these references to allow you to run the activity.  In our example here, our AdvancedDelay activity project is pretty simple and we didn't add a reference to another 3rd party DLL so we can bypass this action.

Launch Workflow Studio and create a new workflow project
With your activity DLL now in the right location, launch Workflow Studio and create a new workflow project.  I typically like to create new workflow projects for testing activities, but you can also edit existing workflow projects if you desire.

Add the activity to the workflow project and run/test the workflow
The Workflow Studio Designer should now be displayed.  If this is your first time testing the activity, the activity will not yet be displayed within the activity pane.  To add the activity as an available activity within the pane, navigate to Tools-->Choose Activities.  Browse to the activity, verify it is selected, and close the Choose Activities dialog.  Notice the "Toolbox Location" field on this dialog.  This is the location we specified in our code where this activity will be placed within the activity pane.

Verify the activity is now listed within the activity pane.  Drag the activity to the designer surface and configure the properties as needed.  Start the activity and verify that it runs as expected.  

In the example below, I configured the AdvancedDelay activity to run for 5000 milliseconds (5 seconds).  I then placed a message box beneath the delay.  When running the activity, it should take about 5 seconds for the message box to pop up.  If it does, I know this activity is running as expected. 

One final note:

If you find that you need to make code changes to your activity, just open up Visual Studio, update your code, and recompile your project.   You'll then need to place the updated DLL back in the C:\Program Files\Citrix\Workflow Studio folder in order for Workflow Studio to pick it up.  If you get an "Access Denied" type message, this typically means that you'll need to close Workflow Studio (Console and Designer) in order to successfully overwrite the existing DLL that is in that location.  The Workflow Studio executables will have a lock on that DLL if you just used a previous version of that DLL in a workflow.

Once you can copy the updated DLL to that location, re-open Workflow Studio, and edit your workflow project.  When you edit your project, your workflow will automatically be referencing the new DLL.  You don't have to re-browse for the activity and add it to the activity pane.  Make the appropriate property changes and workflow changes and re-execute your workflow. 

In the next blog, I'll explain how you can step through your code in real-time in case you wanted to perform more robust troubleshooting at this stage.  Stay tuned!

Blogs in this series:
• Getting Started
• Setting up your Visual Studio development environment
• Anatomy of a Workflow Studio activity project
• Testing your Workflow Studio activity project (this one)
• Stepping through your Visual Studio code

When you create a new Workflow Studio activity project within Visual Studio, the templates provide you with a pretty comprehensive and documented activity class file.  In the screen shot below,  I minimized a lot of the code, but you can see the primary sections of the activity file within the project. 
The primary sections of this file are listed below:

• Using statements
• General activity properties
• Class constructor
• Standard properties
• Dependency properties
• Activity execution section
• Property validation section
  

In this blog, I'll discuss at a high level each of these primary sections.  I won't detail the meaning of all of the attributes and properties that are present as they are pretty well documented within the Activity Developers Guide and within the comments of the class file itself.  This blog is really meant to give you an overview of what is actually in here so you can navigate to the appropriate section as you develop your activity.

1. Using statements:
There is a long list of using statements at the top that define the references for the class.    What you should notice here is that the last five all come from Workflow Studio.  If your activity references a third party DLL, you'll most likely need to add more using statements to make sure your references are all in place.

using Citrix.WorkflowStudio.Common;
using Citrix.WorkflowStudio.CustomActivities.Designers;
using Citrix.WorkflowStudio.CustomActivities.Editors;
using Citrix.WorkflowStudio.CustomActivities.Serializers;
using Citrix.WorkflowStudio.User;

2. General activity properties:
Right beneath the using statements is a section called "Attribute Definitions and Comments".   This section contains a series of general properties for the activity.  The comments provided within this section explain these settings pretty well.  A few of them you should take note of are below.

[DisplayNameAttribute(@"AdvancedDelay")]
This is the name of the activity displayed within the Workflow Studio Designer.

[Description(@"This activity will delay for a specified amount of time")]
This is the description of the activity displayed within the Workflow Studio Designer.  When you select the activity in the Activity pane, the description is shown in the lower-left corner of the Designer.

[ActivityTreePath(@"Windows PowerShell/Utilities")]

This is the folder location for where the activity is placed within the Activity pane of the Workflow Studio Designer.  A forward slash is used to specify a subfolder.

3. Class constructor:
The class constructor is next.   This code gets executed when the activity is placed on the drag-and-drop surface within the Designer.  The most common thing you'll need to do in the constructor is to initialize the values of your properties. 
 

4. Standard properties:
The section for standard properties is listed after the class constructor.   A sample one is provided in the template which is commented out.   This sample is mainly here to give you the syntax for defining a sample property if you would like to use one within your code.

What you really need to know is that there are two types of properties you can define within the class - standard properties and dependency properties.  The primary difference between them is that dependency properties are "bindable" to other activities whereas standard properties cannot be bound.   Dependency properties have much more flexibility than standard properties due to being bindable.   In the Designer, bindable properties allow their values to come from other activities.  Bindable properties can also be used as input to properties of other activities.  Due to this flexibility, dependency properties are much more common to use than standard properties and you should probably define all of your properties as dependency properties first, then fall back to being standard if the bindable behavior is not desired.

5. Dependency properties:
The dependency property section is listed after the standard property section.  As stated in the section above, dependency properties are much more common to use than standard properties since they can be bound to the properties of other activities.  Their flexibility makes them a much better choice in most cases.

The activity template gives you a series of sample dependency properties that are commented out.   I won't go into all of the code for this property here (it's explained pretty well within the Activity Developers Guide).  I'll just highlight a portion of the settings here...

[DefaultValue("0")]
This is the default value of the property.  Default values can also be set within the class constructor.  When using the Workflow Studio Designer, if the property value is ever set to something different than this default value, the value is shown as bold within the Designer to indicate it has changed.

[DisplayName(@"DelayTime")]
This is the name of the property as shown within the Workflow Studio Designer.  This name should be intuitive and easy for admins to understand.

[Description(@"Amount of time to sleep in ms")]
This is the description of the property as shown within the Workflow Studio Designer.  When you select the property in the Designer, this text is shown in the lower-right corner of the Designer.

[Browsable(true)]
This setting defines whether this property is visible within the Workflow Studio Designer.  If set to true, it is displayed within the Designer when the activity is selected.  If you don't want admins to know about this property or see it within the Designer, you can set browsable to false.

[InputAttribute]
A property can either be an input property or output property.  Input properties define some value that is inputted into the activity.  Output properties define something that is returned by the activity after the activity is executed.  The use of the [InputAttribute] or [OutputAttribute] declaratation defines what icons should be used for this property in the Workflow Studio Designer.

6. Activity execution section:
After all of the properties are defined, the next section is the Execute() function.   This function gets called when the activity is executed by Workflow Studio.  All of the execution logic should go into this function.    

The Execute() function provides a try/catch block.  Put all of your execution logic in the try block.  Don't touch the ExpandStringProperties() call at the top as this function will dynamically retrieve the property values set within the Workflow Studio Designer at runtime so that you can use them within the try block.

7. Property validation section:
The last section of the file defines how property validation is performed within the Workflow Studio Designer.  If you have used the out-of-the-box activities within the Designer, you may have noticed that some activities have required properties that need to be set in order for them to be valid.  These properties provide a red X or yellow warning icon to inform admins that they are required or desired to be set.  You can set up the same type of functionality for your properties through the code in this section.  There are a lot of comments within this section to explain how to set up your properties for validation, so I won't go into this here.   I may blog about this in the future as it could be a big discussion on its own.

Blogs in this series:

• Getting Started
• Setting up your Visual Studio development environment
• Anatomy of a Workflow Studio activity project (this one)
• Testing your Workflow Studio activity project
• [Stepping through your Workflow Studio activity project code]
  

I recommend having a separate Development machine and Test machine for working with the SDK.  I have mine set up as follows:

• Development machine - contains Visual Studio 2008, Workflow Studio 1.0, and the Workflow Studio 1.0 SDK (C# templates).
• Test machine - just has Workflow Studio 1.0 on it for testing activities created on the development machine.   Having a separate box for testing allows you to be sure that your activity works on a non-development machine.

One thing you may notice is that I have the full Workflow Studio 1.0 product on my development machine as well.  The benefit of placing Workflow Studio on the development machine is that it allows you to step through your code in Visual Studio by attaching to the key Workflow Studio processes.   I'll go into more detail on that later in this blog series.   Technically you can get by without installing Workflow Studio on your dev machine by copying over 5 key DLLs from another Workflow Studio installation.  The Activity Developers Guide provides details on how to locate and copy these DLLs if you wanted a more minimal installation. 

1 - My initial development machine layout:
When I started building my Dev machine I had a barebones Windows Server 2003 installation:

• Windows Server 2003 SP1
• IIS with ASP/ASP.NET enabled
  

2 - Install the prereqs for Visual Studio 2008 and Workflow Studio 1.0:
Next, I installed the prereqs for Workflow Studio and Visual Studio listed below. 

• Windows Server 2003 SP2
• .NET Framework 3.5 SP1
• Powershell 1.0
• SQL Express 2005
  

3 - Install Visual Studio 2008
Third, I installed the Visual Studio product.

• During installation, select at least the C# language since the WFS Activity templates are based on C#. You can choose other languages as well if you want to use this machine for other purposes later on.
• After installation, launch Visual Studio and select the C# development layout on the first time use screen.   I've tried both the VB IDE layout and C# IDE layout and the C# layout makes it a lot easier to set up the "stepping through code" settings for later on. 
  

4 - Install Workflow Studio 1.0
Fourth, I installed Workflow Studio 1.0.

• During installation, point to your SQL Database installation (mine was local SQLEXPRESS).  When configuring the Runtime Service, I added one service that is tied to my local admin account.
• After installation, launch Workflow Studio and ensure you can access the Workflow Studio Console 
  

5 - Install Workflow Studio 1.0 SDK
Finally, I installed the Workflow Studio SDK.   This installation adds 4 templates to Visual Studio (2 project templates and 2 class templates)

• During installation, take all of the defaults.
• After installation, launch Visual Studio and verify that these templates are present.  Essentially, try to create a new C# project and the Workflow Studio project templates should be listed there. 
  
  

After completing the final step, you're all set to start writing custom activities.   If this is your first time developing an activity I definitely recommend checking out the Activity Developers Guide that explains how to create a few sample activity projects. 

Blogs in this series:

• Getting Started
• Setting up your Visual Studio development environment (this one)
• Anatomy of a Workflow Studio activity project
• Testing your Workflow Studio activity project
• Stepping through your Visual Studio code

I've been using the Workflow Studio SDK for about a month and just wanted to share with everyone some things I've learned along the way.   I figured a good approach to get the word out to our partners, customers, and Consulting teams about how to use the Workflow Studio SDK was to try a blogging series.    Over the course of the next few weeks I'll blog about some of the fundamentals of using the Workflow Studio SDK.  This is part 1 of the series in answering some of the beginning questions.

What is the Workflow Studio SDK?

The Workflow Studio SDK is a series of C# templates for Visual Studio 2008 that allows you to create activities for Workflow Studio.  There are two types of activities you can create using the templates:

• Powershell Activity - this is an activity based on a Powershell command.  When you choose this activity type within Visual Studio, the Powershell Converter opens where you select the Powershell command you want to transform into an activity.  The Powershell Converter then creates the activity code based on the Powershell command(s) that were selected.  You can then further modify this code to customize as you see fit.
• Standard Activity - this is an activity used for standard actions not based on Powershell commands.   Essentially, you will create a standard activity if you are not creating an activity based on a Powershell command.  The code you get looks about 95% the same with a few differences.
  

What skills do I need to use the Workflow Studio SDK?

From a programming side I would say you need a basic background in using Visual Studio and C#.    The templates are only available in C#, so if you are a VB or VB.NET programmer you'll have to walk on the other side of the fence here.  

My personal coding experience mainly comes from web development (HTML, JavaScript, ASP, etc.) several years back.   I'm not an extensive coder but I do understand the object-oriented programming principles.   Using the SDK was my first time to extensively use C# and if you understand coding principles and object-oriented programming, it's really a matter of learning the new syntax.   For example, for me I found myself asking things like "I know how to create properties in VB, how do I do this in C#?"

In addition to the recommendations above, I would definitely recommend playing with the Workflow Studio product before you start using the SDK (that's probably a given ).   You'll want to understand how activities tie to each other through binding, as you'll be creating "bindable" properties in your code.  

Using the SDK might sound pretty complex at the beginning, but the templates you are given have so many comments that they really guide you through the process as well.

Where can I find the Workflow Studio SDK?

The SDK can be found on the Citrix Developer Network site (http://community.citrix.com/cdn/wf/sdks).

Is there a Developer's Guide for getting started with the SDK?

Yes, a great guide is available on the Citrix Developer Network site (http://community.citrix.com/cdn/wf/sdks).  If you are new to using the SDK this guide is a must for getting started.  You should come here first before venturing out on your own.  This guide will walk you through creating two sample activities:

• "GetDate" Powershell activity - creates an activity based on the "Get-Date" powershell command.  This activity returns the current date/time of the system.
• "AdvancedDelay" Standard activity - creates an activity that allows you to specify a time delay for your workflow.   For example, in Workflow Studio if you want the runtime to pause a certain length of time before continuing with executing the rest of the workflow, you can add the AdvancedDelay activity to pause a certain amount of time. 
  

Upcoming blogs in this series:

• Getting Started (this blog)
• Setting up your Visual Studio development environment
• Anatomy of a Workflow Studio activity project
• Testing your Workflow Studio activity project
• Stepping through your Visual Studio code