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