Workflow Studio 2.

2012 Citrix Systems, Inc. All rights reserved. Terms of Use | Trademarks | Privacy Statement

Contents

Workflow Studio 2.5 About This Release Introduction About Citrix Workflow Studio Source Components of Workflow Studio About Activity Libraries To access the Citrix Developer Network About Workflows and Jobs Management Interface for Workflows and Jobs General Steps for Using Imported Workflows Workflow Source Files About the Database About the Security Role Store Known Issues System Requirements Supported Systems and Products Install and Set Up To install Workflow Studio To configure Workflow Studio To install activity libraries To add a workflow runtime To uninstall Workflow Studio or activity libraries To start Workflow Studio Get Started with Workflow Studio Starting Workflow Studio Importing the Sample Workflow Testing the ExportServices Workflow Creating and Scheduling a Job Get Started with Workflow Studio Designer

6 7 9 10 12 13 14 15 16 17 18 19 20 21 26 27 28 29 32 34 35 36 37 38 39 40 42 43 45

About the Sample Workflow Starting Workflow Studio Designer Creating a Category and Workflow Adding Activities to a Workflow Renaming Activities Creating a Global Property Configuring Activity Properties Binding to a Global Property Testing the Workflow Manage To create a workflow category To manage categories To view and filter workflow projects To import a workflow To export a workflow To test a workflow To specify a server for running jobs To create a job To view job details and event history To view workflow details for a job instance To change job properties To manage jobs To clear job history for a runtime Customize Planning and Starting a Workflow Editing and Deleting Workflows Changing Your View of the Designer Window Working with Activities Customizing the Activities Tab Adding Activities to a Workflow Adding a Branch to a Parallel Activity Creating a Global Property Binding Activity Properties Starting a Workflow from Another Workflow Creating and Working with Snippets Creating an Activity without Writing Code Using the Delay Activity to Persist a Workflow

46 48 49 51 54 56 57 59 62 63 64 65 66 67 68 69 70 71 73 74 75 76 77 78 80 81 82 86 87 89 91 92 93 94 95 97 98

Adding Custom Code to a Workflow Adding a Missing Component Securing Workflows that Contain Password Values Working with Fault Handlers Secure About Security Roles About Security Permissions Working with Security Roles Securing Workflow Categories and Jobs Workflow Studio Development Developing Activity Libraries Preparing for Activity Library Development Activity Library Development Overview Citrix Tools and Templates Activity Library Design Considerations Installation and Setup To add assembly references To install the converter and templates To uninstall the DLL and templates Converting PowerShell Snap-ins to Activity Libraries To create an activity library project and convert an activity Reviewing and Editing the Generated Code To add references to the snap-in binary To review activity attributes To edit the input/output base classes To edit the dependency properties To review the project properties To test the activity in Workflow Studio To test an activity library that changed after installation Creating Activities from Citrix Templates To create an activity library project from a template To add an activity to the project Editing the Code Generated from a Template To change the activity attributes To define the default value for the delay activity To correct the dependency properties To add to the exception handling

99 100 101 103 104 105 108 115 117 118 119 120 121 123 124 126 127 128 129 130 131 133 134 135 137 138 139 140 142 143 144 145 146 147 148 149 150

To edit validation logic To test the standard activity in a workflow Best Practices Reference the snap-in binary To add references to the snap-in binary Change optional integer properties Use strong names for activity libraries To review the project properties Add custom activity icons and reference them To add and reference icons Determine if any overrides are needed Review validation logic Other Considerations Activity Attribute Reference General Activity Attributes PowerShell-Specific Activity Attributes Dependency Property Attributes PowerShell-Specific Property Attribute Automating Workflow Studio with PowerShell Getting Started About Workflow Studio Automation About Workflow Studio Snap-Ins To add Workflow Studio snap-ins to a PowerShell console Deploying, Running, and Managing Workflows To download a workflow to your computer To import a workflow into your Workflow Studio data store To deploy a workflow (create a job) To run a workflow and view its deployment history Adding/Removing Activity Libraries using an Installer To add an activity library to the Activities tab Versioning Activity Libraries

151 152 153 154 155 156 158 159 160 161 162 163 164 166 167 170 172 175 176 177 178 179 180 182 183 184 186 187 188 189 191

Workflow Studio
Workflow Studio provides an easy-to-use, graphical interface for workflow composition that virtually eliminates scripting. Workflow Studio acts as the glue across the IT infrastructure allowing administrators to easily tie technology components together via workflows. Workflow Studio is built on top of Windows PowerShell and Windows Workflow Foundation. This section of the library provides up-to-date product information about Workflow Studio, including the following featured topics.

Introduction About Workflow Studio Release 2.5 System Requirements Known Issues for Workflow Studio 2.5 Installing and Configuring Workflow Studio Getting Started with Workflow Studio Getting Started with Workflow Studio Designer Creating and Managing Jobs Creating and Editing Workflows Securing Operations and Data Workflow Studio Development

Review conceptual information about Workflow Studio Read about new features Read about system requirements and supported systems Get information about known issues Install, configure, and run Workflow Studio Follow this guided tutorial to learn the basics about importing, testing, and scheduling workflows Follow this guided tutorial to learn the basics about creating a workflow. Create, manage, and view Workflow Studio categories, projects, and jobs Create and edit workflows Secure runtimes, workflows, and jobs Learn about creating custom activity librarires and using PowerShell for automation

About Workflow Studio Release 2.5

Workflow Studio Release 2.5 includes new and enhanced features and activities. Security on workflows and jobs Security permissions can now be applied to workflow categories and to jobs. Workflows are protected through permissions that are applied to the categories containing the workflows. Permissions include rights such as "Workflow Admin" and "Jobs Admin." A workflow category, by default, has security permissions set to "Full Control" for the Everyone group. Jobs are protected through permissions that are applied to individual jobs. When a workflow is deployed, Workflow Studio assigns the job the same permissions as are on the category containing the workflow. You can then change the permissions on the job. For information on security, see Securing Operations and Data. Global property display name and description You can now provide descriptive information with global properties to help those running a workflow or creating a job understand the purpose of the global properties. You can specify a Display Name which will appear in the Start Workflow dialog, the Create Job wizard, and the Job Inspection window instead of the Name. (Unlike a global property Name, a Display Name can contain spaces.) You can also specify a Description which will appear as a tooltip in the Start Workflow dialog and the Create Job wizard. Performance improvements and other updates
G

The overall performance of workflow execution and the Workflow Studio interface has improved. Changes include a SQL-based tracking and persistence service, SQL-based runtime data store, Authorization Manager (AzMan) optimization, and PowerShell-based workflow optimization. Support for multiple outputs per workflow instance, enabling you to store and retrieve only the outputs you need. Support for PowerShell version 2 and for .NET version 4.0 (in addition to version 3.5, Service Pack 1).

New Activity Libraries

G

Hyper-V Activity Library: Activities to create and manage Hyper-V VMs, add storage repositories, and automate the process of taking snapshots, backing up VMs, and backing up VM metadata for site migration and disaster recovery. These activities also automate the installation and update of tools on guest Hyper-V VMs. SQL Activity Library: Activities to run SELECT, INSERT, UPDATE, and DELETE commands on a SQL Server database.

New and updated activities

About This Release

G

SNMP activities (in the Networking activity library) now support SNMP version 3 (in addition to versions 1 and 2). XenApp Activity Library: New activities that support application self-service workflows by adding and removing application accounts. XenDesktop Activity Library: New activities that support VM-based desktop groups by adding users to an existing desktop group, retrieving a list of hosted VMs, configuring how a hosting infrastructure manages VMs that are in a VM-based desktop group, and connecting to a hosting infrastructure management server. XenServer Activity Library: New activities that support desktop upgrades by setting, modifying, and retrieving the virtual CPUs and RAM allocated to a VM.

New PowerShell cmdlets

G

New PowerShell cmdlets have been added to support new functionality: Get-JobSD, Set-JobSD, Get-WorkflowOutput, and Set-CategorySecurity.

Introduction
Workflow Studio, a member of the Citrix Delivery Center product family, is an IT process automation solution that enables you to create, schedule, run, and manage workflows. The workflows tie technology components together, mechanize repetitive configuration processes, and coordinate condition-based triggers for administrative tasks. Workflow Studio integrates components in the Citrix Delivery Center enabling the IT infrastructure to operate as a dynamic delivery platform. Workflow Studio includes components that enable you to automate XenDesktop, XenApp, XenServer, and NetScaler operations. The following topics provide background information on Workflow Studio.

About Citrix Workflow Studio Source Components of Workflow Studio About Activity Libraries To access the Citrix Developer Network About Workflows and Jobs About the Database

Read about the types of automation provided by Workflow Studio Read about the components on which Workflow Studio is built and extends Read about activity libraries, the building blocks of workflows Access a wealth of information and tools on the Citrix Developer Network Get conceptual information on workflows and jobs Get conceptual information on data stores

About the Security Role Store Get conceptual information on the security role store For access to articles, blogs, video tutorials, sample workflows, and other information, go to the Citrix Workflow Studio Developer Network website at http://community.citrix.com/cdn/wf.

About Citrix Workflow Studio

Citrix Workflow Studio is built on the Microsoft .NET Framework, Windows Workflow Foundation, and Windows PowerShell. If you use Workflow Studio to deploy, manage, and run workflows, you do not need to know anything about those components. However, if you are already a Visual Studio or PowerShell user, you will find many aspects of Workflow Studio to be familiar. You can even use PowerShell cmdlets to schedule and run workflows outside of Workflow Studio. Through a graphical workflow designer, you can build full automation of your business and/or IT processes. The graphical interface virtually eliminates scripting. Typical usage scenarios include the following:
G

Dynamic resource allocation Create new virtual resources dynamically to respond to capacity needs, on-premise or off-premise by integrating with cloud providers like Amazon EC2.

Power management Power on/off physical servers based on usage; manage virtual machines; power on/off the physical host.

User provisioning Simplify the process of provisioning a new user by combining all the back-end steps into a single workflow. For example, create a user in Active Directory, create a new virtual desktop VM, and then add the VM to Citrix Provisioning Server/XenDesktop.

Disaster recovery Automatically respond to equipment failures by reconfiguring network equipment, moving virtual machines, and so on.

Product automation Automate any combination of steps from product management consoles into a single, reusable workflow.

Workflow Studio is geared specifically for automating IT processes through workflows. You use Workflow Studio for the following types of automation:
G

On-demand automation You can run a workflow at any time on-demand.

Schedule-based automation You can run a workflow according to a schedule. To schedule a workflow in Workflow Studio, you create a job for it.

10

About Citrix Workflow Studio

G

Event-driven automation You can deploy workflows that run automatically based on a condition or set of conditions.

You create and unit-test workflows in Citrix Workflow Studio Designer, which is launched from the Workflow Studio management interface. The management interface is used to schedule, manage, and monitor workflow jobs.

11

Source Components of Workflow Studio

Citrix Workflow Studio is built on top of the following Microsoft components:
G

Windows Workflow Foundation Windows Workflow Foundation is a part of the .NET Framework that enables developers to create workflow-enabled applications. Citrix Workflow Studio uses Windows Workflow Foundation as the workflow engine, hosting it in a Windows service referred to as the Workflow Runtime (WFR). Windows Workflow Foundation also provides the visual designer and the base activity library functionality. Workflow Studio extends each of these to target an IT Professional. Workflow Studio also melds Windows Workflow Foundation with PowerShell, providing native support for PowerShell activities.

Windows Presentation Foundation Windows Presentation Foundation is the platform for the Workflow Studio interface, a rehosted and extended version of the Visual Studio Workflow Designer. Citrix Workflow Studio provides additional functionality targeted at making the development experience much easier. The extensions allow Workflow Studio to be effectively used by non-developers and also provide native support for PowerShell-based activities.

Windows PowerShell Windows PowerShell is a core infrastructure component, serving as the basis for the Workflow Studio interface and automation features. Workflow Studio provides native support for PowerShell-based activities. In addition, a workflow created in Workflow Studio can be deployed and scheduled outside of Workflow Studio by any client application calling our workflow deployment and scheduling Microsoft PowerShell cmdlets.

Windows Communication Foundation Windows Communication Foundation is used to manage all of the communication between the Workflow Studio interface and each installed workflow runtime.

Authorization Manager Authorization Manager is used as a central store where Workflow Studio stores data such as role-based security configuration data and workflow metadata, providing granular control over access to workflows.

Microsoft SQL Server Microsoft SQL Server is used as the central store for workflow and job data, runtime computer information, workflow job history (tracking), and workflow job state (persistence).

12

About Activity Libraries

Activities, the building blocks of workflows, expose functionality to workflow developers. Activity libraries are built on top of PowerShell and .NET APIs to provide access to the underlying products. Citrix provides activity libraries that integrate products such as Citrix XenApp, XenDesktop, XenServer, and NetScaler. Citrix also provides general purpose activity libraries developed by Microsoft and extended by Citrix to support many Windows systems. For example:
G

The Active Directory and Group Policy libraries provide the building blocks needed to provision users and manage rights. The Networking library provides the ability to remotely shut down your Windows servers and desktops. It also supports WakeOnLAN for power on technology. The Windows and WMI libraries offer a broad range of activities for typical Windows operating system management: Reading from the Windows Registry, querying performance counters, manipulating files, and accessing any data exposed via WMI. The PowerShell library exposes the functionality of PowerShell and, in particular, allows you to import and export CSV files.

These activities make accessing WMI, VMScript, and PowerShell easy for non-developers. We also provide an SDK that can be used with Visual Studio to develop custom activities. For information about installing, finding updates to, and getting help with activity libraries, refer to To install activity libraries.

13

To access the Citrix Developer Network

The Citrix Workflow Studio Developer Network website provides access to articles, blogs, video tutorials, sample workflows, and other information. You can access the site from within the Workflow Studio management interface as follows. 1. In the Workflow Studio window navigation pane, click the Community tab. The Workflow Studio page of the Citrix Developer Network opens in the information pane. 2. In the Community tree view, click a category name such as Workflows. An RSS viewer appears in the information pane, providing searchable access to all workflows posted on the Citrix Developer Network. 3. To filter the list, start typing a term in the Search box. 4. Click an entry to view a description of the entry and a download link for it. 5. Click the download link and navigate to the location where you want to save the item.

14

About Workflows and Jobs

Workflows A workflow is a compiled set of code that performs tasks. A workflow is comprised of one or more workflow source files, including .xoml, .cs, and .xml files. A compiled workflow project exists as a .dll file, sometimes with supporting .xml files. Workflow source files and compiled workflow project files are stored in the central data store. For details about workflow source files, see Workflow Source Files Workflow Runtime A workflow runtime is a light-weight and extensible engine that executes the activities which make up a workflow. When you install Workflow Studio, a workflow runtime is created for your localhost. You can use that workflow runtime to run multiple jobs. If you need to run workflows using different user credentials, you can create other workflow runtimes on your computer. You can also create workflow runtimes on remote servers. You specify the runtime to be used to run a workflow when you run it on demand or when you create a job for it. Jobs A job is an instance of a workflow that is scheduled or deployed to a workflow runtime. A job consists of workflow project files, workflow parameters, and metadata for scheduling, security, and authentication. Related Information Management Interface for Workflows and Jobs General Steps for Using Imported Workflows To create a job

15

Management Interface for Workflows and Jobs

Administrators use the Workflow Studio interface to manage workflows and jobs (as well as security roles). The Workflows tab (in the left pane) contains a tree view of workflow categories. The workflows for a selected category appear in the middle pane. The commands that can be performed on workflows are available in the right pane, labeled Actions. The Jobs tab contains a tree view of jobs. In the jobs tree, jobs are organized by the servers on which they run. Before you can create a job or use the Jobs or Runtime Security tabs, you are prompted to add a server to the tree. You will likely add a server for your localhost and possibly one or more other servers for deploying jobs remotely. All jobs that have been run on demand, scheduled, or deployed appear in the middle pane. The commands that can be performed on jobs are available in the Actions pane. You can also right-click a job and choose Open to access the Job Inspection window where you can view the tracking data for a running workflow.

16

General Steps for Using Imported Workflows

When you install Workflow Studio, there are no available workflows or jobs. The following general steps describe the process for importing a workflow and creating a job for it: 1. Create a category for the workflow. Workflow Studio organizes workflows into categories. You must create at least one category before you can create or import a workflow. For example, you might have categories such as Audits, Backups, and Installs, with other categories nested under them. See To create a workflow category. 2. Import the workflow. Before you can run or schedule a workflow in Workflow Studio, you must import it into Workflow Studio. See To import a workflow. 3. Test the workflow on your computer. You should always test a workflow by running it on demand before you schedule it to run. Testing a workflow enables you verify that the parameters you plan to specify for the job work as expected. See To test a workflow. 4. Add a server to Workflow Studio. Before you can create a job in Workflow Studio, you must specify the server(s) on which you plan to run the job. See To specify a server for running jobs. 5. Create a job for the workflow. To run a workflow on a schedule, you create a job for it. See To create a job. When you create the job, you specify:
G

The parameters needed to run the workflow so that it can run unattended. The schedule for the job.

The workflow runtime to be used for the job. After you create a job, you can use the Workflow Studio interface to:
G G

Change a jobs parameters, schedule, and target workflow runtime. See To change job properties. Temporarily disable a job and then re-enable it. See To disable/enable a job. View job history. See To view job details and event history. Delete obsolete jobs. See To delete a job.

17

Workflow Source Files

A workflow is a set of source files that are compiled into a .dll. The source files are necessary to edit the workflow (in the Workflow Studio Designer) and the binary is necessary to execute the workflow (in the runtime engine). A workflow contains the following source files:
G

workflowName.wfsp An XML representation of the project references. This is the file that is loaded by Workflow Studio.

workflowName.xoml The XAML file that defines the visual representation of the workflow. It specifies the activities to be loaded and executed as well as an ordered representation of how the workflow will execute.

workflowName.xoml.cs The code-beside file that defines any custom code that is executed along with the activities.

AssemblyInfo.cs The standard Visual Studio file used to define the version for the workflow.

sn.key A stock signing file used to provide each workflow a strong name.

When you run a workflow, Workflow Studio compiles those files into a versioned, binary workflow. When you run a workflow from the designer, the first step is a temporary build process which creates workflow assemblies on your computer. After the workflow completes running, the temporary build files are removed from your computer (regardless of the success or failure of the run).

18

About the Database

The Workflow Studio database uses Microsoft SQL Server and supports both SQL Server and SQL Express. The database contains core data that is common among different user console instances such as workflow and job data, runtime computer information, workflow job history (tracking), and workflow job state (persistence). To log on to Workflow Studio, a Workflow Studio user must be an administrator on the database for Workflow Studio. SQL Server security is used to restrict access to tables and procedures in the database. Workflow Studio includes pre-defined security roles that include database security permissions, as described in About Security Roles. The security role store is described in About the Security Role Store. Workflow Studio supports named database instances. When you log on to Workflow Studio, you specify the database in the form server\databaseInstance. You include the database instance only if you are using SQL Express or a named instance with SQL Server. Related Information About the Security Role Store

19

About the Security Role Store

Security role data is stored either in Active Directory or in a local XML file. You must create a security role store in Active Directory if you plan to use remote runtimes. The Workflow Studio installer and configuration wizard both allow you to create a security role store in Active Directory. Workflow Studio uses the Windows Authorization Manager (AzMan) as the interface to security role data regardless of where it is stored. When security role data is stored in Active Directory, Workflow Studio also caches security role data to local XML files for consumption by local runtimes. A workflow runtime authorizes incoming requests against the security role data. The XML AzMan role store cache is managed by the WorkflowADRoleService. You specify credentials for the WorkflowADRoleService during installation or configuration. The service must run under a domain account that has rights to query the role store in Active Directory. WorkflowADRoleService first queries Active Directory for role store data (through AzMan APIs) and, if that query fails, the service uses the local cache data and logs an error event to the Windows Application Event Log. The WorkflowADRoleService query schedule configuration is stored in a .config file. If a scheduled synchronization fails to get data from Active Directory, an error event is logged to the Windows Application Event Log. Each time that WorkflowADRoleService synchronizes Active Directory and the XML role store cache, the service also replaces/resets the ACLs on the XML cache file so that only LocalSystem and the domain account that the service is running under can access the file. Related Information About the Database

20

Known Issues for Workflow Studio 2.5

Contents
G

Upgrading to Release 2.5 Finding Documentation Known Issues Issues Fixed in this Release

Upgrading to Release 2.5

As of Release 2.5, Workflow Studio runtime information is stored in an SQL database instead of an XML file. As a result of this performance improvement, information about jobs executed on a runtime as well as deployment history is lost when you upgrade to Release 2.5. To upgrade to Release 2.5 1. Obtain the Workflow Studio installation ISO image from http://www.citrix.com/wfsinsider. 2. Use Add or Remove Programs to uninstall the Activity Libraries and then to uninstall Workflow Studio. (You must uninstall the Activity Libraries first.) 3. Use the setup.exe for Release 2.5 to install Workflow Studio. 4. On the Workflow Database page of the Workflow Studio Configuration wizard, after you click Connect two buttons appear: Upgrade Database and Re-create Database. Be sure to click Upgrade Database if you want to retain the database that contains your workflows. 5. After you finish configuring Workflow Studio, use the setup.exe for Release 2.5 to install the Activity Libraries.

Finding Documentation
In addition to the information provided on this site, documentation is also available in the Workflow Studio area of the Citrix Developer Network. To access help from the Workflow Studio window:

21

Known Issues
G

Click the Workflows, Jobs, or Runtime Security tabs and then click Getting Started in the Actions pane to view quick help. From the quick help pages you can also access web-based tutorials and help. Click the Community tab to access the Citrix Workflow Studio Developer Network. Click links in the "Inside" box to access articles, blogs, sample workflows, and other information.

To access help from the Workflow Studio Designer window:

Choose Help > Help Contents. Click an activity in the Activities tab to display a description of it at the bottom of that tab. Click a property in the properties pane to display a description of it at the bottom of that pane.

Workflow Studio Issues

Workflow Studio Configuration wizard will not create database if name contains double-byte characters Although the Workflow Studio Configuration wizard will allow you to enter the double-byte characters, the Review Changes page will indicate that the database creation failed. [1008] Download link for Streaming Profiler does not work in Internet Explorer 6 The download link for Citrix Streaming Profiler in the Activity Library installation wizard does not work in Internet Explorer 6. The download link works in Internet Explorer 8 and above. [1531] Performance issues possible when Workflow Studio does not have Internet access When Workflow Studio does not have Internet access, runtimes can timeout and fail when Workflow Studio attempts to look up the certificate revocation list. You can work around this issue in any of the following ways:
G

Allow access to the following sites: http://CSC3-2004-crl.verisign.com/CSC3-2004.crl and http://crl.verisign.com/pca3.crl Set up a local hosts entry to redirect crl.verisign.com and CSC3-2004-crl.verisign.com to 127.0.0.1 to avoid the DNS lookup timeouts. Download and install the two .crl files (listed in the first bullet above) manually from Verisign. Important: You will need to do this every couple of months when they expire. For information on manually importing a CRL, refer to http://technet.microsoft.com/en-us/library/aa996972%28EXCHG.65%29.aspx. Disable certificate checking as described in this article: http://support.microsoft.com/kb/936707. You will need one configuration file for each executable in %PROGRAMFILES%\Citrix\Workflow Studio.

22

Known Issues
G

Disable certificate checking in Internet Explorer by clearing the checkbox for the "Check for publisher's certificate revocation" Security option in the Internet Options > Advanced tab. This workaround must be performed on each computer running Workflow Studio. [763]

Error indicator remains when you delete and re-add an activity If you remove from a workflow an activity that has an error indicator and then re-add the same activity in its place, the error indicator displays for the re-added activity. To clear that error indicator, configure the activity correctly and run the workflow. [1035] Unclear error message when a workflow cannot be deployed If the remote runtime on which you are attempting to create a job does not have the activity libraries used to create the workflow, a message starting with "The workflow failed validation" appears. The message does not indicate that the workflow requires additional activity libraries. You must install on a runtime any activity libraries used to create a workflow. [777] Cannot add security role assignments to built-in domain local groups When you attempt to add a security role assignment to a local group that is in the domain's Built-in CN, an error message appears. To work around this issue, you can create a group in a different container, add the built-in group to the newly created group, and then add security role assignments to the built-in group. [889] Error message when attempting to modify the role store An attempt to modify the role store from multiple computers can result in the error message "Element not found". If this occurs, restart the AD Helper Service and restart Workflow Studio. You should then be able to modify the role store. [908] Limitations in workflow, activity, and global property names The names of workflows, activities, and global properties cannot contain spaces or special characters. This is a Microsoft limitation stemming from the use of those names in namespaces. In addition, global property names cannot be the same as C# keywords, which are reserved. Creation dates shown in different formats when workflows sorted by date When you sort the workflow projects table by the Created On column, the creation dates displayed in the column and beside the Created On sort heading appear to differ. The creation date displayed in the column is shown as the local time; the creation date displayed in the sort heading is shown in GMT. [609] Workflow Studio does not support InvokeWebServiceActivity The InvokeWebServiceActivity currently cannot be used with Workflow Studio. If you need to call web services, you must write a custom activity using the Workflow Studio SDK. [295] Use of Promote Bindable Properties command can cause problems Using the command Promote Bindable Properties can cause problems with your workflow that will require you to delete and re-create the workflow.

23

Known Issues Right-click menu for Citrix If/Else activity contains an unsupported command If you right-click the Citrix If/Else activity in a workflow, the menu includes the command Add Branch. That command is not supported for the Citrix If/Else activity, which is a reimplementation of the PowerShell If/Else activity to improve usability. If you need an If/Else activity with more than two branches, use the PowerShell If/Else activity. (Note: The Citrix If/Else activity is under Workflow Control in the Activities tab. The PowerShell If/Else activity is hidden by default but can be added to the Activities tab by going to Tools > Choose Activities and selecting the checkbox for the If/Else activity that has the namespace System.Workflow.Activities.) Get PageFile Info activity throws an exception under specific conditions The Get PageFile Info activity does not run properly under Windows Vista and Windows 2008 if the Windows Virtual Memory setting is configured with the option "Automatically manage paging file size for all drives" in the Advanced System properties. The activity runs successfully if the Virtual Memory setting has a custom setting configured. Alternatively, you can use the Virtual Memory option to automatically manage paging file size and include a fault handler in your workflow to catch the exception thrown by the Get PageFile Info activity. [852] Start Workflow activity fails in one case The Start Workflow activity fails if a parent workflow running on a runtime under Local System tries to start a child workflow on a remote computer. To work around this issue, run the parent workflow from a runtime that is not running under Local System. [779] The Start Workflow Activity works in all other cases:
G

When a parent workflow running under an Active Directory account tries to start a child workflow on a remote computer (running under an Active Directory account or Local System). When a parent workflow running under an Active Directory account or Local System tries to start a child workflow on the same computer. Note that if the parent workflow is running on a runtime under an Active Directory account and the child workflow is to be started on a runtime under Local System, the Active Directory user must be granted permissions on the runtime under Local System.

XenApp Profile Application activity throws an exception when linked to a specific profile You can bind the XenApp Profile Application activity to a specific profile by specifying the "Linked Profiles Directory" and "Linked Profiles Names" parameters. Doing so results in an exception and this error message: An error has occurred. The error is The process is already in background processing mode. (Note that this is the same error you will receive if you try to use the Streaming Profiler for the same task.) [1148] XenApp Profile Application activity does not work on 64-bit platforms Currently the Profiler SDK is available for 32-bit platforms only. [1086] Serialization errors when using XenDesktop activities When you run as a job a workflow that includes XenDesktop activities, you will receive a serialization error when the job completes although the job does complete successfully. 24

Known Issues Workflows containing XenDesktop activities will fail if they include activities that trigger persistence, such as the Delay activity. [1052] XenDesktop activities cannot be used in Windows x64 environments When you run a workflow that contains a XenDesktop activity, such as Connect To Farm, the workflow fails and the Designer window Results pane contains this error: The term 'New-XdAdminConnection' is not recognized as a cmdlet, function, operable program, or script file. This issue occurs because the XDCommands cmdlet is not registered to the PowerShell snap-in. To install that cmdlet, open a PowerShell command prompt (as administrator) and run installutil. Your paths might differ from the following example:

C:\Windows\Microsoft.NET\Framework\version\installutil.exe C:\Windows\assembly\GAC_MSIL\XdsCmdlets\ve [1062] XenDesktop activities throw an exception on Windows 7 Several XenDesktop activities are known to throw an exception when a workflow is run on Windows 7. The exception message begins with: Unable to cast COM object of type 'System.__ComObject' to interface type 'MetaFrameCOM.IMetaFrameFarm7'. [1091]

Issues Fixed in This Release

The following issues were fixed since the last release.
G

Streaming Profiler should be installed before XenApp activity library is installed [1163] Incorrect error message supplied when an activity is bound to a "Get" activity that returns no objects [1116] After a Workflow Studio Designer crash, you cannot add XenApp activities until you clear the cache [1160] XenApp New Application activity parameter requirements vary based on selected Application Type [1141] XenApp Profile Application activity does not support shared path for Profile Directory [1164] XenApp Streaming Profiler cannot be installed if Streaming Profiler client is already installed [1102] Wrong message displayed in installer if activity libraries are already installed [1125] Default Computer Name value for the Active Directory Create Computer activity is invalid [1177]

25

System Requirements
The Workflow Studio installer checks for the following required components. If a component is not installed on your computer, the installer includes links for downloading and installing the component.
G

Correct Service Pack version of installed Operating System (see Supported Systems and Products) Microsoft .NET Framework 3.5 SP1 or 4.0 Windows PowerShell 2.0 Authorization Manager (part of the Windows Server Administration Tools Pack) Microsoft SQL Server 2005 or 2008

Additional requirements for activity libraries:

G

Microsoft .NET Framework 1.1: Includes the Group Policy Management Console, which is required for the Citrix-provided Group Policy activity library. XenDesktop Desktop Delivery Controller SDK 4.0: Required for the Citrix XenDesktop activity library. XenApp Streaming Profiler 5.2: Required for the Citrix XenApp activity library. Client machines where workflows with Hyper-V activities are run must be configured with DNS servers. (The client machine must be able to convert the DNS name of the Hyper-V server to its IP address.) Required for the Hyper-V activity library.

To create a role store in Active Directory, the domain functional level must be:
G

Windows 2003 or higher

26

Supported Systems and Products

The Workflow Studio administration interface is supported in English on the following Windows x86- and x64-based English and non-English operating systems:
G

Windows 7 (all editions) Windows Server 2003 (all editions) Windows Server 2008 (all editions except Core)

The Workflow Studio data store is supported on SQL Server 2005 or 2008 on the following Windows x86- and x64-based English and non-English operating systems:
G

Windows Server 2003 (all editions) Windows Server 2008 (all editions supported by SQL Server)

The workflow runtime is supported on the following Windows x86- and x64-based English and non-English operating systems:
G

Windows Server 2003 (all editions) Windows Server 2008 (all editions except Core)

Workflow Studio 2.5 is supported by and included with the following Citrix products:
G

Citrix XenApp (Advanced, Enterprise, and Platinum editions) Citrix XenDesktop (VDI, Enterprise, and Platinum editions) Citrix NetScaler (Standard, Enterprise, and Platinum editions) Citrix XenServer (Advanced, Enterprise, and Platinum editions) Citrix Essentials for Hyper-V (Enterprise and Platinum editions)

27

Installing and Configuring Workflow Studio

Workflow Studio deployment options include a full install and a runtime-only install. A full install includes a management interface, the Workflow Studio Designer, and optional runtime(s). With a full install, you can develop and test workflows, schedule and review jobs (instances of workflows that are scheduled to run or that are run on demand), and manage runtime and workflow security. SQL Server is a required component of a full install. SQL Server stores the workflows, job history (tracking), and job state (persistence). Active Directory is required if you set up remote workflow deployment. In that scenario Active Directory is where your security role stores and runtime connection points are stored. If you are not deploying workflows to remote computers, you can alternatIvely configure Workflow Studio to store those items locally in an XML file. A Workflow Studio runtime is implemented as a Windows service. A runtime enables you to execute workflows. You can have multiple servers in your deployment and each server can have multiple runtimes. A workflow runs under the context of the account used for the runtime service, enabling you to set up runtimes for different user accounts. A runtime install does not require SQL Server but you can configure a runtime to connect to SQL Server for central storage. The following topics describe how to install, configure, and start Workflow Studio.

To install Workflow Studio To configure Workflow Studio To install activity libraries To add a workflow runtime To uninstall Workflow Studio or activity libraries To start Workflow Studio

Install Workflow Studio or a runtime Configure Workflow Studio Install activity libraries Add a workflow runtime Uninstall components Start Workflow Studio

28

To install Workflow Studio

Before you install, gather the following information:

The server name or IP address of the server you will use to validate a license for Workflow Studio.
G

You will need the license server information if you use Essentials for Hyper-V, XenApp, or XenDesktop to validate your license.

If you use XenServer or NetScaler to validate your license, you must provide credentials to log in to the XenServer or NetScaler device. The workflow database server name (and instance name if using SQL Express or a named instance with SQL Server).
G

If you want to create more than one workflow runtime on your computer, the credentials you want to use for each workflow runtime service. If you plan to use Active Directory for the security role store, you will need credentials to use for the Workflow Active Directory Helper Service. The account you use must have rights to query the role store in Active Directory. (Active Directory is required for multi-server deployments.) If you plan to use the XenApp activity library, you must install a workflow runtime on a XenApp server at your site. It is recommended that you set up a XenApp server for this purpose that is not publishing applications. You can then use IMA to communicate from the XenApp server with the runtime to all the servers at your site. For third-party applications to be used in your workflows, determine whether you can communicate with them remotely. If you cannot, a runtime must be installed on the server hosting the third-party application. For example, Workflow Studio can connect to Active Directory and Group Policy remotely, so there is no need to install a runtime on a specific server. However, Windows activities that work with files and resources from performance monitor, event log, and similar tools will need to have a runtime running directly on the server hosting those resources.

Note: In Windows Server 2008, User Account Control (UAC) gives domain administrators restricted access. As a result, to install Workflow Studio on Windows Server 2008 over a Remote Desktop Session you either need to log in as a local administrator or use the Windows 2008 Server "Install Application on Terminal Server" feature available from the Windows Control Panel. To install: 1. Verify that your computer has the required software listed in System Requirements. 2. Download the Workflow Studio ISO file from the Citrix Support site. The ISO contains Setup.exe and the appropriate MSI files for your system:

29

To install Workflow Studio

G

To install the full product: WFStudio.msi for x86 systems or WFStudio_x64.msi for x64 systems. To install the workflow runtime only: WFSRuntime.msi for x86 systems or WFSRuntime_x64.msi for x64 systems. To install activity libraries: WFStudioActivities.msi for x86 systems or WFStudioActivities_x64.msi for x64 systems.

Some pre-requisite software is also available at that location. You can download it from there or from the Microsoft support site. If the installer detects a missing component, it provides a link that you can click to download or install the component. 3. Double-click Setup.exe to start the installer. 4. Click Run. 5. Click the component that you want to install:
G

Full product The Workflow Studio installers (WFStudio.msi and WFStudio_x64.msi) set up the Workflow Studio interface and runtime.

Runtime only The runtime installers (WFSRuntime.msi and WFSRuntime_x64.msi) install only the runtime. This is useful on computers that will run workflows but do not need access to the Workflow Studio interface. The full product and runtime-only option cannot be installed on the same computer.

Activity Libraries

You must install Workflow Studio before you can install an activity library. You will need to install activity libraries on development computers and on runtime servers. For installation instructions for activity libraries, see To install activity libraries. 6. The Workflow Studio Component Setup dialog indicates if any of the prerequisite software is not installed. Review the status messages for each component and follow any instructions. When you are done, click Next. 7. In the Open File dialog, click Run. 8. Follow the instructions in the installation wizard: a. In the Product Licensing Configuration dialog (displays only for full product installation), select a Citrix product for which you have a license. After you click Next, you will be prompted to log in to the server that validates your license. In some cases, the server name or IP address must include the http:// or https:// prefix. Follow the on-screen instructions. The Citrix license server validates your license if you choose any of the following Citrix products for licensing: Essentials for Hyper-V, XenApp, or XenDesktop. If you choose XenServer or NetScaler to validate your license, you must provide credentials to log in to the XenServer or NetScaler device. b. Specify an installation folder. The default installation folder is %PROGRAMFILES%\Citrix\Workflow Studio. 30

To install Workflow Studio c. Click Install and then click Finish. The Workflow Studio Configuration wizard starts. 9. Follow the instructions on each page to complete the configuration. For additional information, refer to To configure Workflow Studio. 10. When the Review Changes page appears: a. Select each task to review the pending changes. If you need to make further changes, click a page name in the navigation list. When you are done, click Review Changes. b. Click Apply. c. After all changes succeed, click Close.

31

To configure Workflow Studio

The Workflow Studio Configuration interface enables you to:
G

Specify the workflow database connection information. Enable the Net.TCP Port Sharing Service (if you need Workflow Studio to communicate with workflow runtime services on the local computer). Add/remove workflow runtimes. Configure the security role store. Configure a Windows Firewall port (if you need Workflow Studio to communicate with runtime services on other computers).

To configure Workflow Studio: 1. The configuration wizard starts during installation. To change configuration settings, run %PROGRAMFILES% > Citrix > Workflow Studio > Configure Workflow Studio. 2. Follow the instructions on each page to complete the configuration. You can navigate to the pages in any order. For more information, refer to the following notes about the pages. Page Workflow Database Description After you enter the Server and Database and click Connect, the configuration tool displays buttons. Click the button that corresponds to how you want your database handled. (The Workflow Database page is not included when the Runtime Only product is installed.) If you do not enable TCP Port Sharing, you cannot create workflow runtimes. This page is available only if TCP port sharing is enabled. You will see an entry for the workflow runtime already created for your localhost. The workflow runtime service is named WorkflowRuntimeHostService_domain_username.For example, if your system name is PC2 and your user name is jsmith, the service is named WorkflowRuntimeHostService_PC2_jsmith. You can run multiple workflows from a single workflow runtime. If you have a workflow that needs a different security context, you can create another workflow runtime for it.

TCP Port Sharing Workflow Runtimes

32

To configure Workflow Studio Security The best practice is to point all runtimes to the same role store so that you can use the same security settings on all computers. When you choose Active Directory, you configure two additional pages: Role Store and Security Service. By default, a local cache is configured for security role assignments (on the Security Service page). As a result, when Workflow Studio needs security role assigments, it obtains them from the local cache. Workflow Studio refreshes the local cache from Active Directory according to the Cache refresh interval. Use a local cache for security role assigments if the performance of the Active Directory connection is of concern. For example, if Workflow Studio is installed in a branch office and the Active Directory server is in another location, use a local cache to avoid frequent communication with Active Directory. As an alternate to changing your firewall setting, you can edit a Workflow Studio configuration file to change the protocol and port used for communications between Workflow Studio and runtime services on other computers. Contact your Citrix support representative for details. 3. After you complete your changes, click Review Changes. 4. On the Review Changes page: a. Select each task to review the pending changes. If you need to make further changes, click a page name in the navigation list. When you are done, click Review Changes. b. Click Apply. c. After all changes succeed, click Close. Firewall

33

To install activity libraries

Activity libraries extend the functionality of Workflow Studio. The Workflow Studio installation includes activities developed by Citrix that integrate products such as Citrix XenApp, XenServer, and NetScaler as well as general purpose activities developed by Microsoft and extended by Citrix. You must install activity libraries on development computers where Workflow Studio is used to create or test workflows. You must also install activity libraries on runtime servers where workflows that reference the libraries are run. If you use the XenApp activity library to create workflows that manage a XenApp farm, you must install either the full Workflow Studio product or the runtime on one of the XenApp servers in the farm. Workflows that use XenApp activities can only be run on a Workflow Studio runtime that is installed on the XenApp server. It is a good practice to check the Citrix Developer Network (CDN) website occasionally for updates to the Citrix-supported activity libraries. You can also find information about the activities on the Citrix Activity Library Reference. CDN also includes custom activity libraries developed by the Workflow Studio community. For information about installing them, see Customizing the Activities Tab. To install activity libraries: This procedure refers to files in the ISO image downloaded from the Citrix Support site, as described in To install Workflow Studio: Setup.exe and WFStudioActivities.msi for x86 systems or WFStudioActivities_x64.msi for x64 systems. 1. Verify that Workflow Studio or the Workflow Studio runtime is installed on the computer where you want to install activity libraries. 2. If you are upgrading the activity libraries from a previous release, uninstall the activity libraries before proceeding. You can uninstall them by using the installer for the previous release or by using the Windows Add or Remove Programs command. 3. Double-click Setup.exe to start the installer. The installer will check your system for System Requirements. 4. Click Run. 5. Select Activity Libraries and click Next. 6. Follow the instructions in the Workflow Studio Component Setup dialog and then click Next. 7. In the Open File dialog, click Run and then click Next. 8. Use the Custom Setup dialog to specify which activity libraries you want to install, click Next, and click Install.

34

To add a workflow runtime

You can run multiple workflows from a single workflow runtime. If you have a workflow that needs a different security context, you can create another workflow runtime for it. 1. Run %PROGRAMFILES% > Citrix > Workflow Studio > Configure Workflow Studio. 2. Click Next. The Workflow Runtime Installation dialog displays any Workflow Runtimes already created for your localhost. 3. To create another runtime, click Add and enter credentials for the Workflow Runtime. (Workflows run on that runtime will be executed using those credentials.) The Workflow Runtime service is named WorkflowRuntimeHostService_domain_username. For example, if your system name is PC2 and your user name is jsmith, the service is named WorkflowRuntimeHostService_PC2_jsmith.

35

To uninstall Workflow Studio or activity libraries

The Workflow Studio installer checks for previous versions and allows you to uninstall a previous version before proceeding with the installation. Uninstalling a previous version does not remove the database or the security role store. Thus, your workflows, job history, and security information are retained. You can remove any of the components by using the Windows Add/Remove Programs command. Note that you cannot uninstall activity libraries after you uninstall Workflow Studio. Alternatively, you can run the MSIs to uninstall the components, as follows:
G

To uninstall activity libraries, run WFStudioActivities.msi for x86 systems or WFStudioActivities_x64.msi for x64 systems. You cannot uninstall activity libraries after you uninstall Workflow Studio. To uninstall Workflow Studio, run WFStudio.msi for x86 systems or WFStudio_x64.msi for x64 systems. To uninstall a workflow runtime, run WFSRuntime.msi for x86 systems or WFSRuntime_x64.msi for x64 systems.

36

To start Workflow Studio

To log on to Workflow Studio, a Workflow Studio user must be an administrator on the database for Workflow Studio. 1. Run %PROGRAMFILES% > Citrix > Workflow Studio > Workflow Studio. 2. When prompted, enter the database connection information. For Server, enter the connection information that you specified during installation, in the form server\databaseInstance. For example, if you entered localhost\SQLEXPRESS for the Server name during installation, enter that for Server. If your SQL server is not using a named instance, just enter the server. For Workflow Studio database name enter WFDB (or the name that you specified during installation). 3. Click Logon.

To start Workflow Studio from the command line

The Workflow Studio executable is WFS.exe. You can start Workflow Studio by passing the server and database parameters to WFS.exe. For example: %PROGRAMFILES%\Citrix\Workflow Studio\WFS.exe server localhost\SQLEXPRESS database WFDB If you omit either parameter from the command line, the log-in screen appears.

37

Getting Started with Workflow Studio

After you install and configure Workflow Studio, follow the link below to begin a series of guided exercises that introduce you to workflow management concepts and tasks. You will learn how to:
G

Start Workflow Studio. Navigate from the Workflow Studio administration interface to resources on the Citrix Developer Network site and download a sample workflow. Import the downloaded workflow into your Workflow Studio database. Test the workflow from the Workflow Studio Designer window. Create and schedule a job that runs the workflow.

Click here to begin: Starting Workflow Studio

38

Starting Workflow Studio

This topic assumes that Workflow Studio and the Citrix activity libraries are installed. 1. Run %PROGRAMFILES% > Citrix > Workflow Studio > Workflow Studio. 2. When prompted, enter the database connection information. For Server, enter the connection information that you configured during installation, in the form server\databaseInstance. For example, if you entered localhost\SQLEXPRESS for the Server name during installation, enter that for Server. If your SQL server is not using a named instance, just enter the server. For Workflow Studio database name enter WFDB (or the name that you specified during installation). 3. Click Logon. The Workflow Studio windows opens. It has three main areas:
G

On the left is the navigation pane containing accordion tabs and an area where a tree view of workflows, jobs, and security roles appears. In the center is an information pane containing details about workflows, jobs, and security roles. For workflows and jobs, the upper portion of the information pane contains a table view and the lower portion displays additional information about the item selected in the workflows and jobs tables.

On the right is the actions pane containing commands applicable to the current selection. 4. To continue the tutorial, go to Importing the Sample Workflow.
G

39

Importing the Sample Workflow

The procedures in this topic direct you to the Citrix Developer Network where you will download a sample workflow and then import it into Workflow Studio. Workflow import/export enables you to share workflows with other Workflow Studio users.

To download the sample workflow

1. In the Workflow Studio window navigation pane, click the Community tab. The Workflow Studio page of the Citrix Developer Network opens in the information pane. 2. In the Community tree view, click Workflows. An RSS viewer appears in the information pane, providing searchable access to all workflows posted on the Citrix Developer Network. (The content is the same as if you had clicked the Workflows link on the web page.) 3. In the Search box, start typing Export to filter the list. 4. Click the entry ExportServices Tutorial. A description of the workflow and a download link appear. 5. Click the download link, click Save, and navigate to the location where you want to save the workflow. Note: Do not rename a workflow file. A workflow project includes several files with internal references to the workflow name. If you rename a workflow, it will not run successfully.

40

Importing the Sample Workflow

To import the sample workflow

1. In the Workflow Studio window navigation pane, click the Workflows tab. 2. Between the Workflows tree and the tabs, click the Create Category link and then enter ServerMgmt. You will import the ExportServices workflow into this category. Categories are used to organize workflows. 3. Make sure that ServerMgmt is selected in the Workflows tree. 4. In the Actions pane, click Import, navigate to ExportServices.zip (the file you downloaded), and click Open. The workflow appears in the projects table. Notice that the workflow is assigned a version number when you import it. If you were to import that same workflow again, it would appear in the projects table with the same name, but a different version number. 5. To continue the tutorial, go to Testing the ExportServices Workflow.

41

Testing the ExportServices Workflow

You can now run the workflow that you imported to test it. To do that, you open the Workflow Studio Designer, a tool used to create, edit, and test workflows. When you run a workflow from the designer, the first step is a temporary build process which creates workflow assemblies on your computer. After the workflow completes running, the temporary build files are removed from your computer (regardless of the success or failure of the run). The ExportServices workflow that you imported exports information about services on your computer to two files: RunningServices.csv and StoppedServices.csv. When you test the workflow, a dialog prompts for a path to those files. To test the ExportServices workflow 1. In the projects table, right-click the workflow name, ExportServices, and then choose Edit. Alternatively, you could select ExportServices in the projects table and then click Edit in the Actions pane. After a slight delay, the workflow opens in the designer window. 2. To run the workflow, either click the Start button on the toolbar or choose Workflow > Start. 3. When the Start Workflow dialog appears, notice that the export path is filled in. Change the path if you like and then click Finish. After the workflow compiles, the message The build was successful appears in the bottom pane of the window, the workflow starts running, and additional messages appear as each activity is performed. 4. When the workflow completes, you can use your Windows browser to navigate to the location of the .csv files. 5. You are now finished with the Workflow Studio Designer window. To close it, choose File > Exit from the designer window. 6. To continue this tutorial, go to Creating and Scheduling a Job.

42

Creating and Scheduling a Job

When you start a workflow from the Workflow Studio Designer window, it runs immediately and interactively on your desktop. To run a compiled workflow according to a schedule, you create a job for it. You also create a job when you want to deploy a workflow so it can be available to other workflows. A job consists of one or more workflows, a reference to a workflow runtime, a schedule option, and any parameters required to run the workflow. To create and schedule a job 1. Make sure that the ServerMgmt Workflow Projects table is still displayed in the Workflow Studio window. If it is not, click the Workflows tab and then click ServerMgmt in the Workflows tree. 2. Right-click the ExportServices workflow in the table and then choose Create Job. If no server has been added to Workflow Studio, the message There are currently no registered servers. appears. In that case, click the Jobs tab, click Add Server, and enter localhost. Then, click the Workflows tab and repeat this step. If you have multiple servers configured, you will be prompted to specify the server to which you want to deploy the job. Enter localhost if prompted. If your computer has more than one runtime running, you will be prompted to select a runtime. 3. In the next screen, click Custom Schedule and then click Edit Schedule. 4. Configure the New Task Schedule dialog as follows: a. From the Schedule Task drop-down menu, choose Once. b. Specify a start time that is a few minutes later than the current time. c. Click OK. 5. Click Next. 6. Because you are scheduling this job, Workflow Studio prompts you for the input needed when the workflow runs, in this case a path for saving the export files. Enter a path (ending with a backslash) and then click Finish. 7. To see your job, click the Jobs tab and then click your computer name in the Jobs tree. 8. View the Details pane at the bottom of the window. The Schedule tab in that pane describes the schedule. The Job History tab lists major events (such as created, started, completed, persisted) for jobs that have run. After you have created a job, you can change its properties such as its schedule, the runtime to be used, or the parameters required to run the workflow.

43

Creating and Scheduling a Job 9. To change a the properties of a job: In the Jobs table, right-click ExportServices and choose Properties. A Modify ExportServices Properties wizard appears. You can page through that wizard if you like and change its properties. Note: When you create a job, the same build process occurs as when you run the job, the only difference being that the built assemblies are saved to Documents and Settings\user\ My Documents on the computer where you initiated the job. You have now completed the Workflow Studio tutorial.

44

Getting Started with Workflow Studio Designer

After you install and configure Workflow Studio, follow the link below to begin a series of guided exercises that cover tasks related to workflow creation. You will learn how to:
G

Start Workflow Studio. Create a workflow category, create a workflow, and add activities. Use sequence and parallel activities. Configure activity properties using validation messages as a guide. Bind activities to properties using the interface as a guide. Create a global property and bind it to an activity. Test a workflow.

Click here to begin: About the Sample Workflow

45

About the Sample Workflow

The workflow created in this tutorial obtains a list of services running on the local computer and then exports two CSV files, one with a list of the running services and one with the stopped services. When the workflow is deployed or is run in the Designer, the user is prompted for the output path for the CSV files. A workflow consists of activities that are connected in a logical and meaningful way. An activity is an element of execution in a workflow. A little planning will help you organize activities so that a workflow is easier to work with and contains sections that you can expand and collapse. The workflow in this tutorial includes the following activities:
G

Get-Service: Gets a list of local services on a computer. Where-Object: Filters the objects (in this case, the services) that are passed to the export file. Export to CSV: Exports the list of services to CSV files.

Note: For detailed information on activities and samples of their use, refer to the Citrix Workflow Studio Developer Network. The last two activities (Where-Object and Export to CSV) are used to export the running services list and the stopped services list. You will group those activities by using a ParallelActivity containing two SequenceActivities.
G

A SequenceActivity is a composite activity that serves as a container for activities. A SequenceActivity executes the contained activities in the order in which they appear. You can collapse and expand the SequenceActivity container. You can also save a SequenceActivity as a snippet for reuse. A ParallelActivity, a composite activity that enables you to connect activities in a logical way, can also be expanded/collapsed and saved as a snippet. Note: Parallel activities in Windows Workflow Foundation are not asynchronous. The Parallel activity enables you to have multiple activities executing independent of one another in a semi-parallel fashion at run time. Refer to Microsoft Windows Workflow Foundation documentation for details on parallel activity processing.

When you have completed this tutorial, your workflow will look like this:

46

About the Sample Workflow

To continue the tutorial, go to Starting Workflow Studio Designer.

47

Starting Workflow Studio Designer

This topic assumes that Workflow Studio and the Citrix activity libraries are installed. 1. Run %PROGRAMFILES% > Citrix > Workflow Studio > Workflow Studio. 2. When prompted, enter the database connection information. For Server, enter the connection information that you configured during installation, in the form server\databaseInstance. For example, if you entered localhost\SQLEXPRESS for the Server name during installation, enter that for Server. If your SQL server is not using a named instance, just enter the server. For Workflow Studio database name enter WFDB (or the name that you specified during installation). 3. Click Logon. The Workflow Studio windows opens. It has three main areas:
G

On the left is the navigation pane containing accordion tabs and an area where a tree view of workflows, jobs, and security roles appears. In the center is an information pane containing details about workflows, jobs, and security roles. For workflows and jobs, the upper portion of the information pane contains a table view and the lower portion displays additional information about the item selected in the workflows and jobs tables.

On the right is the actions pane containing commands applicable to the current selection. 4. To continue the tutorial, go to Creating a Category and Workflow.
G

48

Creating a Category and Workflow

Workflow Studio enables you to organize workflows by grouping them into arbitrary containers called categories. For example, you might create a category named "LoadBalancing" to contain workflows related to managing load balancing or a category named "VM" to contain workflows related to managing VMs. The Workflow Studio navigation pane shows a tree view of workflow categories. The top node, Workflows, must contain at least one category before you can create a workflow. To create a category and workflow 1. Click the Workflows tab, select the Workflows node in the tree, click the Create Category link just above the tabs, and enter ServerMgmt. 2. Click ServerMgmt in the tree. 3. In the Actions pane click Create Workflow. 4. In the Create New Workflow dialog, type MyWorkflow and then click OK. The Designer window opens. It contains the following areas:
G

The Activities tab, on the left side of the Designer window, contains a tree view of the installed activity libraries. Each activity library adds one or more activities to the Activity tab. You drag and drop activities from the Activities tab to the design surface to create workflows. By default, very few of the available activities display in the Activities tab. Later in this tutorial you will learn how to show the many other activities, including those provided with PowerShell and activities created by Citrix.

A description of the selected activity appears below the Activities tab. The design surface, in the middle of the Designer window, displays a visual representation of a workflow. The design surface is where you drag and drop activities to create a new workflow. You arrange the activities in the order you want them to execute. You can rearrange activities by dragging an activity to a different location in the workflow.

The results pane, which is below the design surface, displays informational messages (), compiler errors (), and compiler warnings(). A workflow with compiler errors will not build successfully. A workflow with compiler warnings might build successfully but likely will not run correctly. The properties pane, on the right side of the Designer window, contains the properties of the activity selected on the design surface. An activity property is a configuration option that modifies the behavior of an activity. There may be zero or more properties exposed by an activity. A description of the selected property appears below the properties pane.

49

Creating a Category and Workflow 5. To continue the tutorial, go to Adding Activities to a Workflow.

50

Adding Activities to a Workflow

For background information on the activities used for this tutorial, see About the Sample Workflow. 1. You can start the workflow by dragging the main containers it will include (a SequenceActivity and a ParallelActivity) to the design surface. In the Activities tab, expand the Workflow Control tree. All of the activities listed under Workflow Control are developed by Citrix. 2.

From the Workflow Control list, drag SequenceActivity to the design surface and drop it over the Drop Activities Here label.

51

Adding Activities to a Workflow 3.

Drag ParallelActivity from the Activities tab to the design surface. Drop the ParallelActivity on the arrow below the SequenceActivity container. Note: While it is possible to nest the parallel activity inside the sequence activity, it is best to keep them separate for a cleaner visual appearance and to simplify error handling. 4. Next you will add an activity inside the sequenceActivity1 container: In the Activities tab, expand Windows PowerShell and drag Get-Service inside the sequenceActivity1 container (dropping it over the label Drop Activities Here). Note: The activities listed under Windows PowerShell are PowerShell cmdlets. Refer to Windows PowerShell documentation for information. 5. Notice the default properties for the Get-Service activity in the properties pane. For this activity, you will not change those defaults. Now you will add four activities to the parallelActivity1 container. 6. Drag the Where-Object activity from the Windows PowerShell activities list to the design surface and drop it over the Drop Activities Here label in the sequenceActivity2 52

Adding Activities to a Workflow container. 7. Drag another Where-Object activity and drop it in the sequenceActivity3 container. 8. Drag the Export to CSV activity from the Windows PowerShell activities list and drop it over the arrow that is below a whereObject activity. 9. To add the Export to CSV activity to the other sequence activity you will use a different technique: Select the sequenceActivity3 container (just click in the white space inside the container) and then double-click the Export to CSV activity (in the Windows PowerShell activities list). The activity is added to the bottom of the container. The following image shows the current view of the workflow.

Note: At any point if you need to quit this tutorial and resume later, save MyWorkflow by going to File > Save Workflow. You can reopen the workflow by selecting it in the Workflow Projects table and clicking Edit in the Actions pane. 10. To continue the tutorial, go to Renaming Activities.

53

Renaming Activities
All activities are given a default name. You will next rename the activities so that their names indicate their purpose in this particular workflow. 1. To give the first sequence activity a meaningful name, click sequenceActivity1 in the workflow to select it, in the properties pane type getServices for Name, and press Enter. Note: Rather than pressing Enter, you can press Tab or just click in the window. 2. You have completed the getServices sequence activity. Collapse it by clicking the minus icon beside getServices on the design surface. 3. Rename the four activities you just added as follows: On the design surface, click the activity to be renamed and then in the properties pane type the new name beside the (Name) label. Use the following names for the activities: whereObject = whereObjectRunning exportToCSV = exportRunningToCSV whereObject1 = whereObjectStopped exportToCSV1 = exportStoppedToCSV The workflow should match the following image.

54

Renaming Activities

4. Click parallelActivity1 to select it and then, in the properties pane, change its name to exportToCSV. The more descriptive name will be handy if you later decide to save this parallel activity as a snippet. 5. To continue the tutorial, go to Creating a Global Property.

55

Creating a Global Property

The workflow that you are creating will generate two output files. To enable an administrator to specify the destination of the output files, you will create a global property for the export path. When creating a job to run this workflow, the administrator can enter a value for the export path so that the workflow can run unattended. In this exercise you will create a global property for the export path. Later you will bind the global property to the Folder Path property of the two exportToCSV activities. 1. In the Workflow Studio Designer window menu bar, choose Workflow > Manage Global Properties and click Add. The Add Global Property dialog box opens. 2. For Name, enter ExportPath. This name will help you locate the global property when you are ready to bind to it. For this exercise, it is not necessary to enter a Display Name or Description. (If a Display Name is entered, it appears in the Start Workflow dialog, the Create Job wizard, and the Job Inspection window instead of the Name.) 3. From Type, choose String. Dialog box settings change to reflect the data type selected. 4. For Default Value, enter C:\. This is the value that will appear when the person deploying or running the workflow is prompted to enter the export path. 5. Verify that the checkbox for Prompt for value during deployment if scheduling option is Start or Custom Schedule is selected. As a result of selecting the checkbox, the person deploying the workflow will be prompted for the value (in the Create Job wizard). You would not select this checkbox if you had a another workflow or some other process that supplied the value to the workflow. 6. Click OK twice. 7. To continue the tutorial, go to Configuring Activity Properties.

56

Configuring Activity Properties

Notice the validation flag () above the top right corner of the whereObjectRunning activity. The validation flag indicates that the activity does not have enough data defined for it to pass validation and thus would prevent the workflow from executing. To define the data, you configure properties for the activity. 1. Mouse over the validation flag of the whereObjectRunning activity. When the flag appears inside of a gray box, click in that box to see the validation messages. Notice that validation flags also appear in the properties pane beside the corresponding parameters. 2. Click to select the first validation message. The corresponding property is highlighted in the properties pane and the insertion point is placed in the value field for that property. 3. Click the binding drop-down icon for the Input parameter. The binding list shows all activities that precede the activity in the workflow, along with their properties. The list also includes any global properties. The list scrolls to the previous activity, which is often the most likely activity used for binding. The icon indicates that a property is an output property and therefore the most likely choice for binding. 4. In the binding drop-down menu under getService, choose Output to bind the Where-Object activity to the output of the getServices activity. The Where-Object activity will filter the objects returned by the getServices activity. The binding string for the Input parameter displays as: Activity=getService, Path=Output. 5. Click the validation flag for whereObjectRunning. Notice that the message you selected before has been removed. Select the remaining validation message. In the properties pane, Filter Script is now highlighted. 6. Click the Filter Script row in the properties pane. Notice the and the icons.

The icon represents a dialog box and the icon signifies that the property is bindable. Workflow Studio Designer uses the property type to determine whether to present the binding drop-down list, the Edit Property dialog box, or some other dialog box appropriate for the data type. The default editor for strings is the Edit Property dialog box, where you can create a custom string if needed. 7. Click the icon and enter the following PowerShell command in the Edit Properties dialog box. This command limits the objects returned to those with a Status equal to Running: $_.Status -eq "Running" In case you are not familiar with PowerShell variables: $_ refers to the current pipeline object. The dot notation ($_.Status) refers to the Status property of the current pipeline object. 57

Configuring Activity Properties 8. Click OK. The validation flag disappears, indicating that the activity has the minimal information to build. However, the activity might need additional configuration to execute properly. You should always review the activity properties to ensure that the default settings are what you intend. 9. Repeat steps 1 through 8 for whereObjectStopped, using this Filter Script: $_.Status -eq "Stopped" 10. Click OK. When you are finished, the properties pane for whereObjectStopped should match the following image.

11. To continue the tutorial, go to Binding to a Global Property.

58

Binding to a Global Property

The workflow still has validation flags that need to be cleared before you can successfully run the workflow. In the following steps you will create a binding so that the services lists are passed to the CSV files. You will also bind to the ExportPath global property to specify the default path for the two CSV files output by the workflow. To specify the parameters for the two Export to CSV activities 1. Click the validation flag for exportRunningToCSV and select the first validation message. 2. In the properties pane, double-click then Switch Editor icon for the Folder Path property and then click the binding drop-down icon on the Folder Path row. 3. In the binding menu under the Global Properties heading, select ExportPath. The Folder Path should now be set to the following: Activity=MyWorkflow, Path=ExportPath 4. In the properties pane, enter the following file name for the File Name property: RunningServices.csv 5. Notice that there is still a validation flag for exportRunningToCSV. Click the validation flag for exportRunningToCSV and select the validation message. 6. In the properties pane, click the binding drop-down icon on the Input row. Under whereObjectRunning, choose Output. That setting binds the input of exportRunningToCSV to the output of whereObjectRunning. The validation flag for exportRunningToCSV is now removed. Before moving on, there is one more property to set for the exportRunningToCSV activity. 7. In the properties pane, click the Overwrite row and then choose True from the binding list. That setting causes the output file to be overwritten each time the workflow is run. The parameter values for exportRunningToCSV should match the following image.

59

Binding to a Global Property

8. Repeat steps 1 through 7 for exportStoppedToCSV. In summary: a. Select the exportStoppedToCSV activity, click the binding drop-down icon for the Folder Path property, and choose the ExportPath global property. b. Enter the following file name for the File Name property: StoppedServices.csv. c. Click the binding drop-down icon on the Input row. Under whereObjectStopped, choose Output. d. Click the Overwrite row and then choose True from the binding list. When you are finished, the properties pane for exportStoppedToCSV should match the following image.

9. As you work on a workflow, you are working with it on disk. To save the workflow to the database, click Save in the toolbar. The message "The build was successful" appears in

60

Binding to a Global Property the results pane. If it does not, review your workflow against the tutorial steps to fix any errors. 10. To continue the tutorial, go to Testing the Workflow.

61

Testing the Workflow

To test a workflow you run it from the Workflow Studio Designer window where it executes immediately and interactively on your desktop. Thus, you can easily alternate between testing the workflow and editing it from the same window. Note: When you want to run a compiled workflow according to a schedule, you create a job for it. You also create a job when you want to deploy a workflow so it can be called from other workflows through the Start Workflow activity. After you deploy a workflow, any edits to it are saved to another workflow with the same name but a different version number. 1. Click Start in the toolbar. 2. When prompted, enter a path for the export files and then click OK. Note: When you create a job for a workflow, you specify for the job any parameters required to run the workflow, thus enabling the workflow to run unattended. Status messages appear in the results pane. The two CSV files created by the workflow are saved in the output path you entered. You have now completed the Workflow Studio Designer tutorial.

62

Creating and Managing Jobs

The following topics describe how to manage workflow projects and to create, schedule, and manage jobs.

To create a workflow category To manage categories To view and filter workflow projects To import a workflow To export a workflow To test a workflow To specify a server for running jobs To create a job To view job details and event history To view workflow details for a job instance To manage jobs To change job properties To clear job history for a runtime

Create categories to contain related workflows Move a workflow between categories; delete a workflow or category Change your view of workflow projects Import a workflow Export a workflow to share it with others Test a workflow in Workflow Studio Designer Add the servers to which you will deploy jobs Create a job to deploy and/or schedule a workflow View jobs and their history View workflow details in the Job Inspection window Enable/disable jobs, change your view of the jobs table, delete a job, and view deleted jobs Change a job's schedule, runtime, or parameters Remove all job history for a runtime

63

To create a workflow category

You must create at least one workflow category before you can create or import a workflow. You can organize workflows by creating nested categories. 1. Click the Workflows tab. 2. In the Workflows pane, click the folder to contain the category and then click the Create Category link below the folder list. Alternatively, in the Workflows pane right-click the folder to contain the category, select Create Category, and then type a descriptive name for the category. 3. A workflow category, by default, has security permissions set to Full Control for the Everyone group. For help with changing security permissions on a category, see Securing Workflow Categories and Jobs.

64

To manage categories
Use these tasks to clean up and organize your workflow categories.

To move a workflow to a different category

1. Click the Workflows tab and then click the current category of the workflow. 2. Drag the workflow name from the workflow table and drop it in a category folder.

To delete a category
1. Click the Workflows tab and then click the category. 2. Delete the contents of the category, including workflows and nested categories: Right-click the category name in the workflow tree and then choose Delete from the menu.

To delete a workflow
1. Click the Workflows tab. 2. In the Workflow Projects table, right-click the workflow name and choose Delete. A workflow that is deployed as a job cannot be deleted. You must delete all jobs created from the workflow and then delete the workflow.

65

To view and filter workflow projects

From the Workflows tab you can view a table containing information for all workflow projects included in a particular category. You can filter, sort, and group the workflow projects table to change your view of it.

To view workflow projects

1. Click the Workflows tab. 2. In the Workflows tree view, select a workflow category name. Alternatively, double-click a workflow category name in the Workflow Items table.

To filter the workflow projects table

G

To filter the table by workflow name: In the Search Workflows box, type the first few characters of the names you want to view. To view all workflows again, clear the Search Workflows box. To filter the table by a column heading: Mouse over a column heading, click the down arrow that appears, and click an item in the menu. To clear the filter, choose Clear Filter from the menu.

To sort the workflow projects table

G

To sort the table by column: Click a table column header.

To group the workflow projects table

G

To group the table by column: Drag a column header to the space above the column headers. To nest the groupings, drag additional column headers to the group area. Hint: If you have multiple versions of a workflow, group the projects table by Name and then sort the table by version. To rearrange the groupings, drag the column header boxes inside the group area. To remove the grouping, drag the column header boxes back into the table area.

66

To import a workflow
Workflow import and export enables you to share workflows with other users and instances of Workflow Studio on other computers. When you Import a workflow, Workflow Studio unpackages the files and puts them in its database. 1. Verify that the file you plan to import has an extension of .wfsp and not .zip. If the file is zipped, unzip the file before proceeding. 2. Click the Workflows tab. 3. Click a workflow category name in the Workflows tree. 4. In the Actions pane, click Import. Alternatively, right-click in the workflow projects table and choose Import from the menu. 5. Navigate to the workflow project (.wfsp file) and click Open. The workflow appears in the Workflow Projects table. You cannot rename a workflow. Several files comprise a workflow and include references to the workflow name. Therefore, if you rename a workflow file, it will not run.

67

To export a workflow
Workflow import and export enables you to share workflows with other users and instances of Workflow Studio on other computers. When you export a workflow, Workflow Studio packages the workflow files into a single cab file and copies that file to a specified location. 1. Click the Workflows tab. 2. Click a workflow category name in the Workflows tree. 3. In the Actions pane, click Export. 4. Specify an export location and then click Save. The workflow project is saved as a .zip file. You can share the workflow with other users who must unzip the file before importing the workflow.

68

To test a workflow
Before you deploy a workflow you should run it from the Workflow Studio Designer to verify that it works as you intended. Workflows started from the designer run under the currently logged-in user context only. When you run a workflow from the designer, the first step is a temporary build process which creates workflow assemblies on your computer. After the workflow completes running, the temporary build files are removed from your computer (regardless of the success or failure of the run). 1. Click the Workflows tab. 2. Click a workflow category name in the Workflows tree. 3. Right-click a workflow name in the Workflow Projects table and choose Edit. The workflow opens in the designer window. 4. In the Workflow Studio Designer window toolbar, click the Start button. After the workflow compiles, the message The build was successful appears in the bottom pane of the window, the workflow starts running, and additional messages appear as each activity is performed.

69

To specify a server for running jobs

To deploy a job to a server (either your localhost or a remote server), the server must meet these requirements:
G

The server must have either the full Workflow Studio product or at least one Workflow Studio runtime installed. The server must have any activity libraries installed that are used on the development computers. If a workflow was signed with a certificate (to encrypt included passwords), the workflow runtime on the server must have the same security certificate used to sign the workflow project. The server must be added to the Workflow Studio interface from which you are creating or deploying the job.

Click either the Jobs or Runtime Security tab, click Add Server, and then enter the server name or IP address. For example, you might specify localhost. The server that you add must already have a Workflow Studio runtime installed. (The Add Server link does not appear if you have configured Workflow Studio to store roles in XML.)

70

To create a job
A wizard leads you through the steps of creating a job. A job references a workflow, a runtime, a schedule option, and any parameters required to run the workflow. You can also use the wizard to deploy (but not schedule or run) a workflow. It is recommended that you test a workflow before creating a job for it. Testing a workflow enables you verify that the workflow compiles successfully and that the parameters you specify for the job will work as expected when the job is deployed. 1. Click the Workflows tab. 2. In the Workflows tree, click a workflow category name. 3. In the Workflow Projects table, click a workflow name. 4. In the Actions pane, click Create Job. If you have added more than one runtime to Workflow Studio, you will be prompted to select a runtime. If you have just one runtime, the dialog that prompts for the runtime is skipped. If you do not see the runtime you want to use for the job, cancel the wizard and add the runtime, as described in To add a workflow runtime. 5. Choose a schedule type:
G

No Schedule (Deploy Only) This setting is used to deploy a workflow that will be called by other workflows or by an external interface that starts the workflow. (A workflow cannot be executed if it is not deployed.) When you use this schedule type, the job creation wizard does not prompt for parameters and the workflow is copied to the runtime but is not run. Any parameters needed to run the workflow should be specified with the Start-Workflow activity or through the external interface. A job with this schedule type will have a status of Deployed in the Jobs tab and will not be executed except when it is called by another job.

Run Immediately This setting is used to deploy a workflow and execute it one time. When you use this schedule type, the job creation wizard prompts for configuration parameters (if the workflow includes any) for the one execution. A job with this schedule type will have a status of Deployed in the Jobs tab; to run the deployed job again, you run it on demand.

Custom Schedule This setting is used to deploy a workflow and configure a task schedule in the Windows Task Scheduler. When you use this schedule type, the job creation wizard

71

To create a job prompts for configuration parameters (if the workflow includes any) to be used for each scheduled execution. A job with this schedule type will have a status of Scheduled in the Jobs tab. You schedule the job by clicking the Edit Schedule button. If you choose Custom Schedule but do not schedule the job, the job will be configured as if you had chosen the No Schedule option. Note: By default, users have access to all of the schedule types. Your Workflow Studio administrator might limit access by changing the default security role settings. 6. To configure a schedule in the New Task Schedule dialog, specify the following: a. In the Schedule tab:
G

In Schedule Task, enter a frequency or condition for running the job. In Start Time, enter the first time that you want the job to run. Based on your selection from Schedule Task, other options to refine the schedule might appear. To set more than one schedule for the job, click Show multiple schedules.

To specify start/end dates for the job or to configure a repeat frequency for the job, click Advanced. b. In the Settings tab, enter options as needed for deleting and stopping the job, as well as handling the job based on power management conditions. 7. Click Next.
G

8. If the workflow being scheduled has global properties (with the This property is a workflow parameter option set), the wizard displays the parameters so you can configure them. 9. Click Finish.

72

To view job details and event history

A job has one of the following statuses:
G

Deployed Creating a job with either the No Schedule or Run Immediately option results in the job being deployed. Such jobs have a status of Deployed in the jobs table. To determine which of the two options was used to create a job, check the Job History tab to see if the job ran once.

Scheduled Creating a job with a Custom Schedule results in the job being deployed (if it is not already deployed) and scheduled. Such jobs have a status of Scheduled in the jobs table and the schedule appears in the Schedule tab. Each time a job runs, a row is added to the Job History tab.

Disabled If a job is scheduled, you can disable it, which changes its status in the jobs table to Disabled. If you enable a disabled job, its status changes back to Scheduled (even if the schedule has expired).

Deleted Deleting a job changes its status to deleted and removes it from the jobs table (by default). However, job history is retained and can be viewed (through Show Deleted Jobs).

The status of a job determines the properties you can change and the effect of those changes, as described in To change job properties.
G

To view a list of jobs, click the Jobs tab and then select a runtime name in the Jobs tree. To view schedule details for a particular job, click the job name in the jobs table and then click the Schedule tab in the Details pane. To view the event history of a job, click the job name in the jobs table and then click the Job History tab in the details table. The Job History tab contains a row for each time a job is created, started, completed, and persisted. To update the job information, click Refresh in the Actions pane.

73

To view workflow details for a job instance

The Job Inspection window provides detailed information for all job instances, including tracking data for running workflows and information that helps you troubleshoot jobs that do not run successfully. In the Job Inspection window you can view the workflow without needing to open the Workflow Studio Designer. 1. Click the Jobs tab and then select a runtime name in the Jobs tree. 2. Right-click the job name in the jobs table and choose Open. The Job Inspection window opens. 3. In the Job Inspection window, select a job instance to view the workflow and workflow details such as the fully-qualified workflow name, the workflow runtime, and any workflow parameters.
G

To toggle the details, click the arrow to the left of Details. To troubleshoot a workflow, click an activity that has a red icon on the upper right corner of the activity bubble. Doing so highlights the corresponding activity messages. To stop, pause, and resume a running job, choose a command from the Workflow menu or click the corresponding icon in the windows toolbar. To open Workflow Studio Designer from the Job Inspection window, choose Workflow > Open.

74

To change job properties

After you create a job, you can change its schedule, the runtime to be used, and the parameters required to run the job. 1. Click the Jobs tab and then select a runtime name in the Jobs tree. 2. In the Jobs table, right-click the job name and choose Properties. The Modify Properties wizard appears. The screens in the wizard are just like those in the Create Job wizard. The status of a job determines the properties you can change and the effect of those changes, as follows:
G

For deployed jobs:

G

Choose Run Immediately to run the job once with a specified set of parameters. The parameters default to the last set used to run the job.

Choose Custom Schedule to run the job according to a schedule. For scheduled jobs:
G G

Choose Run Immediately to run the job once right now. The job also continues to run according to its schedule. If the job has parameters, any changes you make for the immediate run are also used for future scheduled runs. Choose Custom Schedule to change the parameters or schedule for future scheduled runs.

Choose No Schedule to remove the schedule from the job. For disabled jobs:
G

Changing the properties of disabled jobs has the same results as for scheduled jobs, with one exception: When you finish editing the properties, the job remains disabled. Thus, you can run a job immediately even if it has a status of disabled. For deleted jobs:
G G

You cannot change the properties of a deleted job.

75

To manage jobs
From the Jobs tab you can view a table containing information for all jobs deployed to a particular runtime. You can filter, sort, and group the jobs table to change your view of it. You can enable/disable jobs, delete jobs, and view deleted jobs.

To disable/enable a job
1. Click the Jobs tab and then select a runtime name in the Jobs tree. 2. To disable a scheduled job, right-click the job name in the jobs table and choose Disable. To enable a disabled job, right-click the job name (must have a status of Disabled) in the jobs table and choose Enable.

To filter, sort, and group the jobs table

G

You can filter, sort, and group the a jobs table using the same methods as for working with a workflow projects table, as described in To view and filter workflow projects. If create more than one job from a workflow (perhaps to deploy it to different runtimes), the job name in the jobs table will be the same for each job. in that case, grouping the jobs table by the Runtime column will make it easier to read the table.

To delete a job
1. Click the Jobs tab and then select a runtime name in the Jobs tree. 2. Right-click the job name in the jobs table and choose Delete.

To view deleted jobs

1. Click the Jobs tab and then select a runtime name in the Jobs tree. 2. In the Actions pane, click Show Deleted Jobs.

76

To clear job history for a runtime

Deleting a job changes its status but does not remove its history. You can remove all job history for a runtime by deleting the runtime and then re-adding the runtime with the same credentials. 1. From the Windows Start menu, choose All Programs > Citrix > Workflow Studio > Configure Workflow Studio. 2. When the Workflow Database Configuration screen appears, click Next. 3. In the Workflow Runtime Installation screen, click the runtime to be deleted and click Remove. 4. Click Add, enter the credentials for the runtime service, andl then click OK. 5. Click Next twice and then click Finish.

77

Creating and Editing Workflows

The following topics describe how to use the Workflow Studio Designer to create, edit, and test workflows: Planning and Starting a Workflow Editing and Deleting Workflows Plan and begin creating a workflow. Access a list of workflow projects from which you can delete a workflow or open the Workflow Studio Designer to edit a workflow Close and open panes, change the view of the design surface, view a workflow as an outline, change the order in which properties appear, switch between property editors, view cancel and fault handlers, and view workflow code and project files Add installed activities to the Activities tab, install an activity library which does not have an installer, add an activity from the GAC, and search for an activity in the Activities tab by name Add activities to the design surface, review items to verify after adding an activity, review notes related to using parallel and sequence activities Add a branch to a parallel activity and reorder parallel activity branches Create a global property that can be used in muliple activities Read about the concept of activity binding and how Workflow Studio handles binding Use the Start-Workflow activity to start another workflow from the current one Save an activity as a snippet, add a snippet to a workflow, and delete, share, and import snippets Expand the activity library by creating an activity based on another activity such as PowerShell Script, Windows Script, Command Script, and SNMP activities. Add a persistence checkpoint to a workflow. Edit the automatically generated source code (the code-beside file) Add a reference to a missing component Read about the supported encryption methods, obtain and install certificates, choose a certificate for a workflow, and view the certificate associated with a workflow

Changing Your View of the Designer Window

Customizing the Activities Tab

Adding Activities to a Workflow

Adding a Branch to a Parallel Activity Creating a Global Property Binding Activity Properties Starting a Workflow from Another Workflow Creating and Working with Snippets Creating an Activity without Writing Code Using the Delay Activity to Persist a Workflow Adding Custom Code to a Workflow Adding a Missing Component Securing Workflows that Contain Password Values

78

Customize Working with Fault Handlers Read about the Stop On Error property included for each activity and workflow, add a fault handler to an activity

79

Planning and Starting a Workflow

Before you start creating a workflow, taking the time to plan the workflow will make the creation process more efficient. 1. Create a flowchart of the process that you plan to automate. Be sure to capture all processing steps in the sequence in which they are to occur. If the flowchart becomes complex, consider breaking the complex process into smaller ones. 2. On your flowchart, indicate the activities that map to each step in the process. 3. Determine the input data required for the workflow. 4. In Workflow Studio Designer open a new workflow and add a global property for each input data item identified in the previous step. 5. Add the activities that you identified for each processing step. Be sure to rename activities, as needed, to indicate their purpose in the workflow. 6. Configure the parameters for each activity.

80

Editing and Deleting Workflows

To edit or delete a workflow
1. Click the Workflows tab and then click a workflow category name in the Workflows tree. 2. Click a workflow name in the Workflow Projects table and then click Edit or Delete in the Actions pane. The commands listed in the Actions pane are also available by right-clicking in a workflow table. For commands that operate on a particular workflow, be sure to right-click the workflow name. For other commands, you can right-click anywhere in the table. 3. Use the Workflow Studio Designer window to edit a workflow.

81

Changing Your View of the Designer Window

The following topics describe how to change the designer window to optimize your view of a workflow and its properties, handlers, and associated code.

To close and open panes

You can quickly resize the design surface by closing or opening surrounding panes. When working in the Designer window, you generally should have all three panes visible. If a command does not appear to work, make sure there are no hidden panes. From the View menu choose any of the following:
G

Left Pane: Toggles the pane containing the Activities tab. Bottom Pane: Toggles the results pane. Right Pane: Toggles the properties pane.

To change the view of the design surface

When a workflow grows larger than the design surface, zoom and navigation features make editing and reviewing the workflow easier. You can also view an outline of a workflow so you can quickly scroll the design surface to a different portion of the workflow. The icons in the following procedures are located under the vertical scroll bar for the design surface.
G

To preview how a workflow will print, click the icon and choose Print Preview. Use File > Print Setup to change the margins and other page settings. When you are done, return to the normal view: Click the icon and choose Default View. To set a zoom level, click the icon and choose an option. To determine the action that occurs when you click the design surface, click the icon and choose one of the following tools: Zoom In: Enlarges the design surface each time you click it, centering the workflow on the point that you click. Zoom Out: Reduces the design surface each time you click it. Navigation Tool: When a workflow is larger than the pane, the navigation tool enables you to grab the workflow and change its position in the pane. Default: Selects items in a workflow. When a workflow is larger than the pane, clicking the fit icon (bottom right corner of the design surface) zooms out the workflow so that it fits the pane. Click that icon again to return to

82

Changing Your View of the Designer Window the default 100% view.

To view the workflow as an outline

G

From the View menu choose Outline. Click an activity in the outline to select it on the design surface.

To change the order in which properties appear

By default, properties are shown categorized by headings such as Activities, Parameters, and Read-only Output. You can also view them alphabetically.
G

At the top of the properties pane, click the icon to view properties alphabetically or the icon to view properties categorized.

Note: Most activities have at least one output property which is listed under the Read-only Output category. Output properties can contain data that other activities in the workflow access. These properties are all read-only because they are not intended to be modified, but rather used by the activity itself at run time.

To switch between property editors

For each property displayed in the Properties pane, Workflow Studio Designer uses the property type to determine whether to display by default the binding drop-down list or a dialog box appropriate for the data type. A binding list shows all activities that precede the activity in the workflow, along with their properties. The list scrolls to the previous activity, which is often the most likely activity used for binding and includes the icon beside the output property. In the following screen samples, the default editor for the Input Required parameter is a drop-down list and the default editor for the Target Property parameter is a dialog box. Sample of drop-down list as default editor

Sample of dialog box as default editor

83

Changing Your View of the Designer Window

To choose a different property editor:

G G

Double-click the Switch Editor icon to choose the alternate editor. The Switch Editor icon then changes to . Double-click the icon switch back to the default editor. Tip: If you are familiar with the Microsoft Bind dialog and would prefer to use it instead of the dialog box provided with Workflow Studio, access it by double-clicking the icon. The Edit Property dialog is similar to the Microsoft Bind dialog except that the Edit Property dialog visually indicates output properties with an arrow icon .

To view cancel handlers and fault handlers

By default the design surface shows workflow activities. You can change the view of a workflow to see a cancel handler or fault handlers. 1. From the View menu choose Commands Pane. This command shows the Commands Pane and adds a few commands to the right-click menu. 2. Select the item for which you want to view handlers and then choose View Cancel Handler or View Fault Handlers:
G

To view a handler for a particular activity, right-click the activity (on the design surface). To return to the activity view, right-click the activity and choose View ActivityName.

To view a handler for a Sequence Activity or Parallel Activity, click the Sequence Activity icon or Parallel Activity icon in the workflow. To return to the activity view, click the same icon and choose View Sequence or View Parallel. To view a handler for the entire workflow, click the top node of the workflow . To return to the activity view, click the top node and choose View Name.

Note: When you show the Commands Pane and right-click an activity on the design surface, the menu includes some advanced commands: Generate Handlers, Promote Bindable Properties, and Bind Selected Property. Those commands, also available from the Commands Pane, are intended only for advanced users. For information on those commands, refer to the Microsoft documentation.

To view workflow code

The code for a workflow is defined in an Extensible Object Markup Language (XOML) file. You can view and edit that and other project files from the Workflow Studio Designer window.
G

Right-click the design surface and choose View Code.

84

Changing Your View of the Designer Window The XOML file opens in a new tab in the design surface area.

To view project files

You can access the project files, including the workflow code, that comprise a workflow through the Workflow Studio Designer window. 1. From the View menu choose Project to open the Project tab. 2. To open a file in a new tab in the design surface area, double-click a filename in the Project tab. The code for the workflow is in the .xoml.cs file.

85

Working with Activities

The following topics describe tasks related to using activities in workflows.
G

Customizing the Activities Tab Adding Activities to a Workflow Adding a Branch to a Parallel Activity Creating a Global Property Binding Activity Properties Starting a Workflow from Another Workflow Creating and Working with Snippets Creating an Activity without Writing Code Using the Delay Activity to Persist a Workflow Adding Custom Code to a Workflow Adding a Missing Component

86

Customizing the Activities Tab

The Workflow Studio installation includes activities developed or extended by Citrix as well as activities developed by Microsoft. Each activity is part of an activity library and each library consists of one or more .dll files. Some activities are hidden by default. Note: For information about developing activities, go to http://community.citrix.com/cdn/wf/sdks and download the Workflow Studio Activity Developers Guide.

To customize the Activities tab

G

To add installed activities to the Activities tab, choose Tools > Choose Activities, select the checkbox of the activity to be added, and then click OK. To remove an activity from the Activities tab, choose Tools > Choose Activities, select the checkbox of the activity to be removed, and then click OK. To reset the list of activities in the Activities tab to the defaults, choose Tools > Choose Activities, click Reset, and then click OK.

To install an activity library

Use the following procedure when an activity library does not have an installer. 1. Choose Tools > Choose Activities, click Browse, browse to the .dll file for that library, and click Open. 2. In the Choose Activities dialog, click the Namespace column heading to sort the activities by namespace. 3. Scroll to the namespace for the activity library you installed and select the checkbox for each activity you want to appear in the Activities tab.

To add an activity from the Global Assembly Cache (GAC)

1. Choose Tools > Choose Activities and then click Browse. 2. In the .NET tab, select the activity and click OK.

87

Customizing the Activities Tab

To search for an activity in the Activities tab by name

G

In the search bar at the top of the Activities tab, start typing the name. The list of activities displayed is filtered by your input. Note that all folders continue to display.

88

Adding Activities to a Workflow

G

To add an activity to a workflow, drag the activity from the Activities tab to the design surface. As you move an activity over the design surface notice that the activity icon and label is dimmed until the activity is positioned over a valid target location for the activity. You can also add an activity to a workflow by double-clicking the activity. The activity will be added to the end of the workflow if an activity is selected or if you have clicked in the blank area around the workflow so that no portion of the workflow is selected. To add an activity to the end of a sequence activity container, select the container and then double-click the activity.

After you add an activity to a workflow:

G

Look for a validation flag above the top right corner of the activity. The validation flag indicates that the activity does not have enough data defined for it to pass validation and thus would prevent the workflow from executing. To define the data, you configure properties for the activity in the Properties pane. You can click the validation flag to view messages which indicate the required properties. To dismiss the messages pop-up, click in the pop-up. Always review the activity properties to ensure that the default settings are what you intend. The lack of a validation flag does not ensure that a workflow will execute as you intend. In the Properties pane, verify that the default name assigned to the activity provides enough context. For example, a name such as "whereObject" or "parallelActivity1" will not be particularly helpful to anyone trying to understand the workflow. When you change a name, Workflow Studio Designer lets you know if a name already exists in the workflow and will not allow you to create duplicate names.

Consider if you want to provide additional information about an activity in the Description property. To add one line of text, just click in the box beside Description and start typing. To add multiple lines of text, click the drop-down icon on the Description row and start typing in the text box. Press Enter to start a new line (inserts a line break). When you are finished typing, press Ctrl-Enter. You can rearrange activities by dragging an activity to a different location in the workflow.
G

Be sure to use ParallelActivity and SequenceActivity to help organize your workflow and to provide sections that you can expand and collapse. A SequenceActivity executes the contained activities in the order in which they appear. You can collapse and expand the SequenceActivity container. You can also save a SequenceActivity as a snippet for reuse. A ParallelActivity, a composite activity that enables you to connect activities in a logical way, can also be expanded/collapsed and saved as a snippet.

89

Adding Activities to a Workflow While it is possible to nest a ParallelActivity inside of a SequenceActivity, it is best to keep them separate for a cleaner visual appearance and to simplify error handling.
G

Activities under Workflow Control > Debugging are intended for debugging purposes only. When a workflow is run as a job, it runs under a Windows service that does not have the ability to interact with the desktop and cannot display dialog boxes. If you include debugging activities in a workflow, they are ignored. To expose input data for a workflow, use global properties. To work with activity properties:
G

With a property name selected, use the up and down arrows to move between property names and use the Tab key to move to the corresponding property value field. After you edit a property value, press Enter to accept the edit or press Esc to cancel the edit.

90

Adding a Branch to a Parallel Activity

When you drag the parallel activity to the design surface, two branches are displayed. You can add and reorder branches as follows. Note: Parallel activities in Windows Workflow Foundation are not asynchronous. The Parallel activity enables you to have multiple activities executing independent of one another in a semi-parallel fashion at run time. Refer to Microsoft Windows Workflow Foundation documentation for details on parallel activity processing.

To add a branch to a parallel activity

G

Right-click in the parallel activity container and choose Add Branch.

To reorder parallel activity branches

G

Select the container for a parallel activity and drag it to a new location.

Example of selected parallel activity (left-most activity is selected)

91

Creating a Global Property

A global property is a parameter value that can be bound to any activity in the workflow in which it is defined. By using global properties, you can specify in one location a value that is needed for several activities. Suppose that a workflow contains several activities which require validation against the same set of credentials. By creating global properties for user name and password, you only need to specify the credentials once. In addition, global properties enable you to collect input data for a workflow during workflow deployment. The default value that you provide when creating a global property can be overridden when you create a job to deploy the workflow. Thus a workflow in which credentials are specified through global properties can be deployed by different individuals who specify their credentials when creating the workflow job.

To create a global property

1. In the Workflow Studio Designer window menu bar, choose Workflow > Manage Global Properties and click Add. 2. Specify a Name that will help you locate the global property when you are ready to bind to it. 3. Optionally, specify a Display Name, which you can use as a more user-friendly name for the global property. If you enter a display name, it will appear in the Start Workflow dialog, the Create Job wizard, and the Job Inspection window instead of the Name you entered in the previous step. The display name can be up to 256 characters and can contain spaces. 4. Optionally, enter a Description of up to 256 characters. The description appears in a tooltip (in the Start Workflow dialog and the Create Job wizard) if you mouse over the icon beside the display name. Providing a description enables you to explain the data being requested to others running a workflow. 5. Choose the data Type. 6. Specify the Default Value. The value entered here is available for design-time testing and for deployed jobs. 7. To include a prompt for this property value in the Create Job wizard, make sure that the checkbox for Prompt for value during deployment if scheduling option is Start or Custom Schedule is selected. (You would not select this checkbox if you have a another workflow or some other process that supplies the value.) 8. Click OK twice.

92

Binding Activity Properties

You bind activity properties so that activities can access and use data made available by other activities. For example, you might bind the Input property of Sort Object to the Output property of Get Process. That binding allows Sort Object to take the output data from Get Process and act on that data. The Sort Object activity then outputs the modified data set. The Get Process activity Output property data remains intact. This concept is similar to piping data between cmdlets in PowerShell, but it differs because piping data in a single PowerShell command does not preserve the data from each cmdlet in the command. However, if you use PowerShell variables to store the output of each cmdlet and then pass those variables as parameters to subsequent cmdlets, you can achieve the same behavior as experienced with Workflow Studio. Using Workflow Studio, however, removes the need for you to write the PowerShell code. Workflow Studio also includes intelligence that allows you to bind data between PowerShell activities and non-PowerShell activities. The type of data you are binding to must be the expected data type for the activity with which you are making the bind.

93

Starting a Workflow from Another Workflow

When designing a workflow, consider that you can use the Start-Workflow activity to start another workflow from the current one. As a result, you can break a complex workflow into smaller, simpler modules. The Start-Workflow activity is under Workflow Control in the Activities tab.

94

Creating and Working with Snippets

Snippets enable you to create functionality without having to write code. A snippet includes the activity properties, thus enabling you to create a reusable object that is pre-configured. Any individual activity or the composite activities (sequence activity or parallel activity) can be saved as a snippet. Some activities, referred to as meta-activities, can be used to expand the activity library through PowerShell, VBScript, SQL, and other commands, as described in Creating an Activity without Writing Code.

To save an activity as a snippet

Be aware that custom code is not saved in a snippet. To share a workflow that contains custom code, you must export the entire workflow. 1. Select the activity and then choose Edit > Save As Snippet. Tip: If you are saving a sequence activity or parallel activity as a snippet, be sure to select the outer box for the composite activity. 2. Enter a name and a description. The description that you enter will appear at the bottom of the Activity tab when you select the snippet. Note: When you save a snippet, Workflow Studio assigns it a unique ID in snippets.xml and uses only that ID to identify the snippet for processing. Thus, you do not have to be concerned about using unique names for snippets. By not using names to identify snippets, Workflow Studio avoids any name conflicts that might arise when sharing snippets with other users. 3. Click OK. The snippet is added to the Activities tab under My Snippets.

To add a snippet to a workflow

G

Drag the snippet from the Activities tab to the workflow.

To delete snippets
G

Choose Edit > Manage Snippets, select the snippets you want to delete, and click Delete.

95

Creating and Working with Snippets

To share snippets
G

Choose Edit > Manage Snippets, select the snippets you want to export, click Export, type a name for the snippet file, and click Save.

To import snippets
G

Choose Edit > Manage Snippets, click Import, navigate to the snippet file, and click Open.

96

Creating an Activity without Writing Code

As you work with Workflow Studio, you might identify tasks you would like to automate but for which no activity exists. For example, perhaps there is a particular PowerShell command that would be convenient as an activity that you could reuse and share. You can use the following "meta-activities" provided with Workflow Studio to create new activities without having to write code.
G

Command Script Get WMI Info Launch Process PowerShell Script SNMP activities Windows Script

Note: If you are a developer with a working knowledge of Microsoft Visual Studio and want to create an activity library, Citrix provides tools that enable you to create custom activity libraries from Citrix templates or from PowerShell snap-ins. For detailed instructions, refer to Developing Activity Libraries. The following steps describe the general process of creating an activity from an existing one. 1. Suppose that the activity you want to create is a PowerShell command. In that case, expand Windows Powershell in the Activities tab and drag the PowerShell Script activity to a workflow. 2. In the properties pane, change the activity name from "psScript" to a name that identifies the action to be performed by the activity. 3. For Script Code, enter the PowerShell command to be run by the activity. 4. Right-click the activity and choose Save As Snippet. For help with snippets, see Creating and Working with Snippets.

97

Using the Delay Activity to Persist a Workflow

Persistence data is a checkpoint of the state of an entire workflow saved at a point in the workflow. The value of persisting a workflow is that if anything happens to the server or runtime, the workflow can be restarted from the last checkpoint. Given that persistence is more valuable with long-running workflows, the typical IT automation workflows created by Workflow Studio are less likely to need persistence. None of the activities provided by Citrix with Workflow Studio create a persistence checkpoint. To add a checkpoint to your workflows, use the Delay Activity (provided by Microsoft) available in the Workflow Control folder. For more information about persistence data, refer to the Microsoft MSDN site.

98

Adding Custom Code to a Workflow

You may encounter situations which require that you edit the automatically generated source code (the code-beside file). The code that is automatically generated for a workflow is in an Extensible Object Markup Language (XOML) file.

To edit the workflow source code

1. Right-click the design surface and choose View Code. The XOML file displays in a new tab on the design surface. For information on DependencyProperty, PropertyMetadata, and other options in the code-beside file, see the Microsoft documentation on Workflow Foundation. 2. Edit the code as needed and then, in the Workflow Studio Designer window menu bar, choose File > Save. Any compilation errors related to the code-besides file will be displayed in the Results tab below the design surface. If there are no compilation errors, the message The build is successful appears in the Results tab. 3. To close the tab containing the code, click its close button.

99

Adding a Missing Component

When you drag an activity to the design surface, Workflow Studio creates references to all assemblies needed for that activity. In rare situations, such as a nested reference, a reference might not be created. Or, a workflow that has had an activity removed will contain a reference to the assembly for that activity although the activity is no longer in the workflow. When Workflow Studio cannot find a component, it generates a compiler error about the missing component that includes the file name needed.

To add a reference to a missing component

1. From the Workflow menu, choose Add References. 2. In the Add Reference dialog box, locate the file(s) in the .NET tab, select them, and then click OK. If you cannot locate the file(s) in the .NET tab, click the Browse tab, navigate to the file(s), and click OK.

100

Securing Workflows that Contain Password Values

A workflow might contain activities which require authentication to an external system to execute properly. Such activities usually support a password property (all Citrix-provided activities do) which allows either hard-coded passwords or password variables. In general, it is best to not store passwords in workflows so that a password change does not require an update to the workflow. However, for testing purposes, storing a password in a workflow can be convenient. To run an encrypted workflow on a remote runtime, the remote runtime must have the same X.509 certificate that was used to encrypt the workflow. If it does not have the same certificate, the deployment stops and an error indicates that the certificate must be installed on the target computer. If the Workflow Studio runtime cannot decrypt an encrypted password property, an Event Log entry indicates the error and the workflow is not executed. To ensure that workflows with embedded password values are secured, Workflow Studio supports the following encryption methods:
G

Current user certificate key encryption Current user certificate key encryption is the only encryption method available if you configure Workflow Studio to use a local data store (meaning that you cannot use remote runtimes). For this encryption method, hard-coded passwords are encrypted using the Windows Data Protection API (DPAPI) using the current user certificate key and entropy bits for the encryption. When using this encryption method, you can run workflows only on a local runtime that uses your user account.

X.509 certificate encryption Certificate inception is required to support remote runtimes. Workflow Studio supports public and private certificates. The certificates cannot be expired and must have a private key. The Workflow Studio interface enables you to choose a certificate that is already installed on your computer. You must use other software to obtain and install certificates.

101

Securing Workflows that Contain Password Values

To obtain and install certificates

G

You can obtain an SSL certificate from either an internal or public certificate authority (CA) or you can use a self-signed certificate. Consult your security department to find out the CA required by your company and the procedure for obtaining server certificates. Instructions for generating server certificates using various Web server products are available from the Web sites of popular CAs such as VeriSign. You can usually double-click a certificate to install it. You might need to use the Microsoft Management Console (MMC) Certificates snap-in. The Workflow Studio Select Certificates window lists all installed certificates.

To choose a certificate for a workflow

1. Make sure that the certificate that you want to use is already installed on the computer running Workflow Studio and on any computers where you will run the workflow remotely. 2. Open the workflow in Workflow Studio Designer. 3. From the Workflow menu, choose Select Certificate. 4. Select a certificate and click OK.

To view the certificate associated with a workflow

1. Open the workflow in Workflow Studio Designer. 2. From the Workflow menu, choose View Certificate.

102

Working with Fault Handlers

Workflow Studio catches all exceptions and stops execution when an exception is encountered. That behavior is controlled through the Stop On Error property, a Citrix extension to each activity and to a workflow itself. The Stop On Error property allows you to define the behavior of the workflow, activity by activity, when an activity encounters an error. If the Stop On Error property is set to True (the default for all new activities) and the activity encounters an error, the workflow will not process remaining activities in the workflow. If there are other branches of the workflow executing, those branches will be unaffected by the activity that encountered an error. You can add fault handlers to activities and to the overall workflow by setting up a separate workflow to handle exceptions. Each activity has an associated faultHandlers activity which is a container for faultHandler activities. Note that the container activity name, faultHandlers, is plural whereas the name for included activities, faultHandler, is singular.

To add a fault handler to an activity

1. From the View menu, choose Commands Pane. 2. Right-click the activity and choose View Fault Handlers. 3. In the Activities tab, open Workflow Control, drag FaultHandlerActivity inside the faultHandlerActivities container, and drop it over the label "Drop FaultHandlerActivityHere." FaultHandlerActivity catches a specific exception which defaults to the generic System.Exception. Thus, you can add multiple fault handlers to handle different exceptions. 4. For each FaultHandlerActivity, add one or more activities to be run for that fault. Tip: Drag a a Message Box activity to the faultHandlerActivities container to output a message about the error. The messageBox activity is under Workflow Control > Debugging. Tip: To have the fault handler stop the workflow, use the TerminateActivity (under Workflow Control).

103

Securing Operations and Data

Workflow Studio provides the following levels of security:
G

Runtime security: Runtimes are protected through security role assignments that are applied to individual runtimes or to all runtimes on a server. Security roles include rights such as "Deploy, schedule, and start jobs" and "Deploy jobs." You should control who has access to runtimes to avoid enabling anyone to run any workflow. Workflow security: Workflows are protected through permissions that are applied to the categories containing the workflows. Permissions include rights such as "Workflow Admin" and "Jobs Admin." A workflow category, by default, has security permissions set to "Full Control" for the Everyone group. When planning security, consider what permission schemes you need for workflows and then create a category for each scheme. For an example of how you might set up categories, see About Security Permissions. Job security: Jobs are protected through permissions that are applied to individual jobs. When a workflow is deployed, Workflow Studio assigns the job the same permissions as are on the category containing the workflow. You can then change the permissions on the job. When planning security, keep in mind that the security role assignments on a runtime take precedence over permissions on a job. For example, a user who does not have access to a runtime cannot schedule a workflow to run on that runtime.

The following topics describe security roles and permissions and how to use them to secure operations and data: About Security Roles About Security Permissions Working with Security Roles Securing Workflow Categories and Jobs Read about the security roles that apply to servers and runtimes Read about the security permissions that apply to workflow categories and jobs View, assign, and remove security roles Change security permissions on categories or jobs

104

About Security Roles

Workflow Studio includes pre-defined security roles that control access to Workflow Studio operations on a runtime and to the central data store. When a user is added to a role, the user is granted permissions to both Windows Communication Foundation and SQL data store elements, according to the role to which the user was added. The security role store is configured as described in To configure Workflow Studio. You can store security role assignments locally in an XML file or in Active Directory. If you store security role assignments locally, it is recommended that you back up the default XML file before making changes. The file is located in C:\Documents and Settings\All Users\Application Data\Citrix\Workflow Studio\AzmanRoleStore.xml. The installation process grants the person performing the installation full access to all Workflow Studio functions. All users with login rights have full access to the Community tab. All users with login rights have the right to view workflows and edit them, unless the user does not have the necessary permissions on the category containing the workflow. The following table describes each security role that can be assigned through the Runtime Security tab. Roles Perform all job and security operations Deploy, schedule, and start jobs Description This role provides access to all workflow and security operations on a runtime (that is, all operations listed for the other roles). Only the person who installed Workflow Studio is automatically added to this role. This role provides access to the following operations on a runtime:
G

Deploy workflows Start workflows View workflows, deployed jobs, and their history View runtimes Get and clear workflow output Update runtime logs

Resume job instances

This role provides access to the following operations on a runtime:

G

View workflows View runtimes Resume workflows Update runtime logs

105

About Security Roles Stop job instances This role provides access to the following operations on a runtime:
G

View workflows View runtimes Stop workflows Update runtime logs

Suspend job instances

This role provides access to the following operations on a runtime:

G

View workflows View runtimes Suspend workflows Update runtime logs

View jobs

This role provides access to the following operations on a runtime:

G

View workflows, deployed jobs, and their history View runtimes Access the running workflow count Update runtime logs

View security role memberships

This role provides access to the following operations on a runtime:

G

View security roles and security role assignments View runtimes Update runtime logs

Modify security role memberships

This role provides access to the following operations on a runtime:

G

View security roles and security role assignments Add, update, or remove security role assignments View runtimes Update runtime logs

106

About Security Roles Deploy jobs This role provides access to the following operations on a runtime:
G

Deploy workflows View deployed jobs and their history View runtimes Remove workflows Update runtime logs

view the currently deployed jobs Start deployed jobs This role provides access to the following operations on a runtime:
G

Run a deployed workflow Remove a deployed workflow Create a job from a workflow View workflows, deployed jobs, and their history Get and clear workflow output Delete or change job properties View runtimes Update runtime logs

Schedule deployed jobs through Task Scheduler

This role provides access to the following operations on a runtime:

G

View runtimes Run a scheduled job Update runtime logs

By default, the group NT AUTHORITY\SYSTEM is assigned to this role.

107

About Security Permissions

Workflow Studio includes pre-defined permissions that you can use to secure workflow categories and individual jobs. All workflows in a category are secured with the permissions assigned to the category. Thus, when planning workflow security consider the categories needed for the various levels of access. This security model does not support inheritance for nested categories. Workflow Studio uses Microsoft security descriptors to assign/deny rights on categories and jobs. When you add security to a workflow category or a job, you will work with the familiar Microsoft security descriptor editor. Workflow Studio handles security descriptors as follows:
G

A workflow category security descriptor is stored in the data store. When a job is created, the security descriptor for that workflow (obtained from the data store) is deployed with the job and stored on the runtime. Job-oriented operations, except for deployment operations, then checks the access provided by the security descriptor to determine if the user has permission to perform the operation. If a jobs security descriptor is null, all operations are allowed if there are no Azman roles that would deny operations. Workflow Studio encrypts security descriptors. Only a user with the right to change permissions will be able to modify a security descriptor.

The following table lists each permission that can be granted to a user or group on a workflow category or job by using the Edit Security command on the Workflows or Jobs tabs. The first six permissions listed are summary permissions that contain other summary or explicit permissions. The description of each explicit permission details the user interface functions and cmdlets to which the permission grants access. Permissions Full Control Description Contains the following summary permissions:
G

Workflow and Job Admin Permissions Admin

A workflow category or job that does not have an assigned security descriptor is treated as if it has Full Control permission. Workflow and Job Admin Contains the following summary permissions:
G

Workflow Admin Jobs Admin

108

About Security Permissions Jobs Admin Contains the following summary and explicit permissions:
G

Start Workflow Pause Jobs Resume Jobs Stop Jobs View Jobs

Workflow Admin

Contains the following explicit permissions:

G

View Workflow Create Workflow Edit Workflow Delete Workflow Test Workflow Edit Category

Start Workflow

Contains the following explicit permissions:

G

View Workflow Test Workflow Deploy Workflow Schedule Workflow

Permissions Admin

Contains the following explicit permissions:

G

Move Workflow Read Permissions Change Permissions

View Workflow

Grants access to the following functions:

G

List of workflows in the Workflows tab. Display of the workflow in the Designer.

Grants access to the following cmdlet:

G

Export-Project

109

About Security Permissions Create Workflow Grants access to the following functions:
G

List of workflows in the Workflows tab. The Create Workflows command in the Workflows tab. The Import command in the Workflows tab.

Grants access to the following cmdlets:

G

Copy-Project Import-Project Move-Project (Requires Move Workflow on the current category and Create Workflow on the new parent category.) Set-ProjectStatus (granted by Create Workflow or Edit Workflow)

Edit Workflow

Grants access to the following functions:

G

The Save Workflow command in the Designer. The Edit command in the Workflows tab. Editing of the workflow in the Designer.

Grants access to the following cmdlets:

G

Copy-Project Set-ProjectStatus (granted by Create Workflow or Edit Workflow)

Delete Workflow

Grants access to the following functions:

G

The Delete command in the Workflows tab. The Delete Category command in the Workflows tab (must also have Edit Category permission).

Grants access to the following cmdlet:

G

Remove-Project (This cmdlet returns partial results based on permissions.)

110

About Security Permissions Edit Category Grants access to the following functions:
G

The Delete Category command in the Workflows tab (must also have Delete Workflow permission on the category). The Create Category command in the Workflows tab. The Rename Category command in the Workflows tab. Ability to drag-and-drop a category.

Grants access to the following cmdlets:

G

Add-Category Remove-Category Rename-Category Move-Category (Requires Edit Category permission on the category being moved and on both the old and new parent categories.)

Test Workflow

Grants access to the following function:

G

The Start command in the Designer.

Deploy Workflow

Grants access to the following functions:

G

The Create Job command in the Workflows tab. The Delete command in the Jobs tab (must also have Schedule Workflow permission).

Grants access to the following cmdlets:

G

Get-ProjectAssembly Remove-Workflow (must also have Schedule Workflow permission) Send-Workflow Start-Workflow (must also have Schedule Workflow permission)

111

About Security Permissions Schedule Workflow Grants access to the following functions:
G

The Start and Custom Schedule option buttons in the Create Job wizard. The Enable and Disable commands in the Jobs tab. The Delete command in the Jobs tab. The Property command in the Jobs tab. The Delete command in the Jobs tab (must also have Deploy Workflow permission).

Grants access to the following cmdlets:

G

Enable-WorkflowSchedule Remove-Workflow (must also have Deploy Workflow permission) Remove-WorkflowSchedule Set-WorkflowSchedule Start-Workflow (must also have Deploy Workflow permission)

Pause Jobs

Grants access to the following function:

G

The Pause command in the Jobs tab.

Grants access to the following cmdlet:

G

Suspend-Workflow

Resume Jobs

Grants access to the following function:

G

The Resume command in the Jobs tab.

Grants access to the following cmdlet:

G

Resume-Workflow

Stop Jobs

Grants access to the following function:

G

The Stop command in the Jobs tab.

Grants access to the following cmdlet:

G

Stop-Workflow

112

About Security Permissions View Jobs Grants access to the following functions:
G

The display of a job in the Jobs tab. The Open command in the Jobs tab.

Grants access to the following cmdlet:

G

Get-DeployedWorkflow Get-ScheduledWorkflow Get-Workflow

Each of those cmdlets return partial results based on permissions. Move Workflow Grants access to the following function:
G

Ability to drag-and-drop a workflow in the Workflows tab.

Grants access to the following cmdlet:

G

Move-Project (Requires Move Workflow on the current category and Create Workflow on the new parent category. This cmdlet returns partial results based on permissions.)

Read Permissions

Grants access to the following functions:

G

The View Security command in the Workflows tab. The View Security command in the Jobs tab.

Change Permissions

Grants access to the following functions:

G

The Edit Security command in the Workflows tab. The Edit Security command in the Jobs tab.

Grants access to the following cmdlet:

G

Set-CategorySecurity Set-JobSD

Note: All users and groups have access to the Export command on the Workflows tab. All users and groups have access to the following cmdlets: Get-JobSD; Get-Project; Invoke-ScheduledWorkflow (relies on Azman security).

Permissions on the Root Category Node

The root category node in the Workflows tree contains a limited set of permissions, as follows:

113

About Security Permissions

G

The only summary rights available in the main security editor dialog are Full Control and Edit Category. The Edit Category permission on the root node enables an administrator to deny a user the ability to create categories. If a user does not have Edit Category permission on the root node, the Create Category command is disabled. If you click Advanced in the main security editor dialog, the only permissions available are Full Control, Edit Category, Permissions Admin, Read Permissions, and Change Permissions.

Scenario: Creating Categories for Workflow Permissions

This example scenario explains how to set up a few workflow categories to control workflow security. Suppose that your site has the following groups involved with Workflow Studio operations:
G

IT administrators: Responsible for creating, editing, and deleting workflows. This group's name is ITDev. Human Resources employees: Responsible for running some workflows. This group's name is HR. IT administrators: Responsible for securing Workflow Studio operations. Also responsible for creating and running some workflows. This group's name is ITAdmin.

You can handle that scenario by creating the following two categories. This scenario assumes that you will remove the default Everyone group from both of these categories. 1. Category 1 (for workflows that only the HR group can run)
G

Permissions on the ITDev group: Workflow Admin Permissions on the HR group: Jobs Admin

G Permissions on the ITAdmin group: Permissions Admin 2. Category 2 (for workflows that only the ITAdmin group can run)

Permissions on the ITDev group: Workflow Admin Permissions on the ITAdmin group: Full Control

114

Working with Security Roles

Workflow Studio enables you to assign users and/or groups to roles that provide access to tasks such as viewing, editing, scheduling, or suspending workflows. You can set the roles for the server or by workflow runtime in the Runtime Security tab of the Workflow Studio window. The installation process grants the person performing the installation full access to all Workflow Studio functions on the server, with the following default server-scoped role assignments:
G

Perform all job and security operations (user assignment) Schedule deployed jobs through Task Scheduler (group assignment)

To view security roles

1. Click the Runtime Security tab and then click the server containing the roles you want to view. The Roles table lists the roles that apply to the server (Server Scoped) as well as the roles for each runtime. 2. To view only the roles with user or group assignments, click Hide Empty Roles in the Actions pane. To view all roles, click Show Empty Roles in the Actions pane. 3. Click the arrow icons to view the user and group assignments for each role. The roles are described in About Security Roles.

To assign a role to a user or group

If you store security role assignments locally, it is recommended that you back up the default XML file before making changes. The file is located in %ALLUSERSPROFILE%\Citrix\Workflow Studio\AzmanRoleStore.xml. 1. Determine whether the role assignment is to apply to the server or to the runtime. 2. In the Runtime Security tab, click the role under Server Scoped Roles or a workflow runtime. If all roles are not displayed, click Show Empty Roles in the Actions pane. 3. In the Actions pane, click Add Role Assignment. 4. Complete the dialog and click OK.

115

Working with Security Roles

To remove a user or group from a role

Note: Removing yourself from a role might prevent you from using Workflow Studio to make further changes. 1. In the Runtime Security tab, click the role under Server Scoped Roles or a workflow runtime. 2. Click the user or group under the role you want to change. 3. In the Actions pane, click Remove from Role.

116

Securing Workflow Categories and Jobs

A workflow category, by default, has security permissions set to Full Control permission for the Everyone group. Note: The default permissions for the Everyone group include Full Control, which encompasses all access rights. Keep in mind that the Everyone group includes administrators, so the best practice is to never deny permissions on the Everyone group. Instead, add other groups and remove the Everyone group. To limit access to workflows, you create a category for each access level needed. For example, you might create a category for workflows that only certain groups can access, or a category for workflows that only certain users can deploy. When planning a category tree, be aware that security permissions are not inherited on nested categories. When a workflow is deployed, Workflow Studio assigns the job the same permissions as are on the category containing the workflow. You change category or job permissions as follows. 1. Click the Workflows or Jobs tab and then click the workflow category or job for which you want to change permissions. 2. In the Actions pane, click Edit Security. If the View Security command is available instead, you do not have the permissions needed to edit security settings. The Microsoft security descriptor dialog box opens. This is the same dialog used to assign permissions on Active Directory objects. Note that the help accessible from that dialog box contains information about features that are not available in Workflow Studio, including permission inheritance. 3. In the Permissions dialog box, the default permissions on a category are applied to the Everyone group. To add or remove groups or users, click Add and then use the Select Users, Computers, or Groups dialog box. 4. In the Permissions dialog box, notice the list of permissions. Those are summary permissions, each of which contain other summary or explicit permissions, as described in About Security Permissions.
G

To change the summary permissions for the listed groups or users, use the Allow and Deny checkboxes. To change permissions: Click Advanced. In the Advanced Security Settings dialog box, click Edit. Then, in the Permission Entry dialog box, set the permissions.

117

Workflow Studio Development

This section of the library provides up-to-date product information about Workflow Studio development, including the following featured topics.

Developing Activity Libraries Automating Workflow Studio with PowerShell

Create custom activity libraries using Citrix tools and templates which simplify the development process Use PowerShell snap-ins to automate the functionality of Workflow Studio, build self-service portals, and create installers for the activity libraries that you develop

118

Developing Activity Libraries

Workflow Studio is built on the Microsoft Workflow Foundation and shares the same underlying architecture. Thus, the same activity libraries that you build for Workflow Foundation can be used within Workflow Studio. This means that you can access all the resources and samples Microsoft has available. Citrix has developed a converter tool and templates for Microsoft Visual Studio that allow developers to easily build activity libraries to target Workflow Studio. These topics describe, for developers, how to create custom activity libraries from Citrix templates or from PowerShell snap-ins using Citrix tools. A working knowledge of Microsoft Visual Studio and standard programming techniques are assumed.

Preparing for Activity Library Development Converting PowerShell Snap-ins to Activity Libraries Creating Activities from Citrix Templates Best Practices Activity Attribute Reference

Learn about activity library uses and development, activity library design considerations, and how to install tools and templates Develop an activity library from a PowerShell snap-in by using the Citrix PowerShell Converter Develop an activity library by using the Citrix Standard Activity template for Visual Studio Review best practices for developing activity libraries Reference the activity attributes which define characteristics of an activity when it is used in Workflow Studio Designer

119

Preparing for Activity Library Development

Citrix partners are invited and encouraged to create custom activity libraries to take advantage of the benefits of Citrix Workflow Studio. Building a custom activity library for Workflow Studio is similar to building a Workflow Foundation activity library. In fact, you can build a Workflow Foundation activity library and use it in Workflow Studio. However, if you build an activity library using Citrix tools and templates, some of the development work is done for you. Also, a workflow developer using your library can take advantage of the Workflow Studio extensions that simplify workflow development and provide functionality targeted to IT administrators. These topics provide an overview to activity libraries and describe the installation requirements. Related Information Activity Library Development Overview Citrix Tools and Templates Activity Library Design Considerations Installation and Setup

120

Activity Library Development Overview

Workflow Studio, a member of the Citrix Delivery Center product family, is an IT process automation solution that is built on the Microsoft .NET Framework, Windows Workflow Foundation, and Windows PowerShell. Citrix Workflow Studio includes a re-hosted and extended version of the Workflow Foundation Designer that provides additional functionality that simplifies the creation of workflows from activities. An activity library is a collection of activities stored as a compiled binary (a .dll). Workflow Studio includes some basic activity libraries, a defined way to extend Microsoft's Workflow Foundation. Citrix is also developing activity libraries that integrate products such as Citrix XenDesktop, XenApp, XenServer, and NetScaler to enable your IT infrastructure to operate as a dynamic delivery platform. Your custom activity libraries might integrate with your own or third-party products (that have PowerShell snap-ins) to provide functionality such as the following:
G

Power Management The ability to automatically power on/off both physical and virtual servers enables you to better manage your resources and, ultimately, save on costs by having your power-hungry servers off when they are not needed.

User Provisioning Every organization has a process for provisioning and de-provisioning user accounts, but often these processes involve multiple manual steps. Automating the process end-to-end ensures that best practices are followed in exactly the same way each time.

Dynamic Resource Allocation Transform your data center into a delivery center by creating workflows that tie together your server provisioning process (both physical and virtual) with your web, desktop, and application delivery processes. Your custom activities and workflows can mechanize repetitive configuration processes and coordinate condition-based triggers for administrative tasks.

Disaster Recovery Most disaster recovery teams have a binder that lists all the activities that must take place in the face of different events. Automating all your failover scenarios and recovery events is a perfect use case for Workflow Studio. You may not be able to define all the different disasters that might happen but you can define all the different responses. Even better, you can automate the responses and just embed notifications for what the system is doing on your behalf.

Product Automation A good place to start for product automation is with the little things that bother people. There are lots of opportunities around individual products to offer additional

121

Activity Library Development Overview value and plenty of opportunity to automate around product quirks. Product automation also ensures that a process implemented around best practices is always performed the same way regardless of who runs the workflow. In addition, Workflow Studio provides a way to react to problems with software deployments automatically and resolve them without the need for user interaction.

122

Citrix Tools and Templates

Workflow Studio is built on Workflow Foundation and shares the same underlying architecture. The same activity libraries that you build for Workflow Foundation can be used within Workflow Studio. This means that you can access all the resources Microsoft has available and reference their samples. Workflow Studio extends on Workflow Foundation; some of the functionality in our Designer requires you to code your activity library to target our platform. We have developed some templates for Visual Studio that allow you to easily build activity libraries to target Workflow Studio.

PowerShell Converter
If you have a PowerShell snap-in that you would like to use in Workflow Studio as an activity library, the Citrix PowerShell Converter (a wizard and templates) help automate the process. The Converter wizard inspects the snap-in and lists all of the cmdlets available. After you select the cmdlets you want to use, the wizard generates a project with one activity per cmdlet. The wizard automates much of the activity development process: It sets up all of the references, and adds one class file for each cmdlet selected from the PowerShell snap-in. This automated process also does a reasonable job of inspecting the cmdlet parameters and converting them, but you will want to look through the parameters and the validation logic before you deploy the activities.

Standard Templates
If you want to build an activity library that targets Workflow Studio and does not use PowerShell, our basic Activity Library Project and Item templates help you get started. They set up the necessary project references and generate sample code that is heavily commented with the various parameter and validation options.

123

Activity Library Design Considerations

The core activities in Workflow Studio include support for running PowerShell commands/scripts and VBScript. While this functionality allows access to many existing Citrix APIs today, it is not an ideal solution for your customer. Accessing APIs in this manner does not expose the rich functionality available in the workflow model. For instance, when you have a script output data, other activities cannot know what data types are output and often cannot bind to individual properties on objects as a result. The best experience is to develop a native activity library and provide first-class access. The activity libraries that are included with Workflow Studio and the extensions for Windows, Active Directory, and Group Policy support provide good examples of the best way to implement an activity library. To build an activity library from a PowerShell snap-in, you must understand the snap-in to achieve the intended design goals. Considerations for designing activity libraries are as follows.
G

Consider what is the best architecture for the activity library. Ultimately, the best architecture to use when creating an activity library depends on the APIs that are available for the product you want to access and the skill set of the development team. Because Workflow Studio natively supports PowerShell cmdlets, if a PowerShell library is available for the product you want to integrate with AND that library closely matches the types of activities you would like to expose, using the converter is best. However, any technology that can be accessed from .NET can be used in an activity, so it is not necessary to create a PowerShell library solely for the purpose of translating to an activity library.

Consider what is needed (and not needed) for automation. Try to identify the most likely automation scenarios (perhaps the top ten) and design around those scenarios. Consider the types of functionality your customer wants to automate and ensure that you are providing the necessary tools. A workflow developer will use your activity libraries, plus other activity libraries, when building a workflow. Take care in naming the activities so that their purpose is obvious, even to a non-developer. And, make sure that the links between the activities needed to accomplish automation are fairly easy to bind together.

Keep in mind that activity libraries are used by workflows. Ultimately, the design of your activity library will impact the IT administrators who run workflows that use your library. Thus, you need to think in terms of workflows. For example, suppose that you are developing activities related to server maintenance. A common task in working with servers is entering credentials. An administrator should not have to enter server credentials repeatedly to use a workflow. Your activities should be designed so that workflows based on them enable administrators to run the workflow without intervention.

124

Activity Library Design Considerations What seems to make the most sense to the IT administrator is an architecture that is object-based and provides verbs that operate on those objects. For example, Get-VM retrieves a VM object and Stop-VM requires a VM object to be passed to it.
G

Consider the optimum scope of activities and activity libraries. An optimum design maintains a balance between too many specific activities versus too few general activities. When you convert a PowerShell snap-in to an activity library, the converter creates one activity for each selected cmdlet. Depending on the design of the snap-in and your target workflows, you might need to combine several commands into one activity or even separate a generated activity into multiple activities. For example, if the conversion of a PowerShell snap-in results in an activity that is too general and has many properties, you might find it better to make the activity more specific by specifying some of the properties. Suppose that the conversion resulted in an activity called Add that takes a property of the object to be added. You could edit that activity to be more specific (AddItem), prefill some of the properties, and then hide those properties so they do not appear in the Workflow Studio window. Often the APIs that exist for a product are not designed in an optimal way to be used in a workflow. For example, you need to think about the API functions and objects that are typically only used during initial setup or rarely in the life of the product. Related activities would be good candidates to hide by default (in Workflow Studio), put into a separate library, or omit.

125

Installation and Setup

Use of the Citrix templates for activity development requires the following to be installed on your development computer:
G

Microsoft Visual Studio 2008 Professional, Team, or Standard editions (the Express edition does not support Workflow Foundation) Microsoft .NET Framework 3.5 SP1 or 4.0 Windows PowerShell 2.0 Citrix Workflow Studio Alternatively, you can copy a few dlls from a Citrix Workflow Studio installation to your development computer so that Visual Studio has the required assembly references.

The Citrix templates

Related Information To add assembly references To install the converter and templates

126

To add assembly references

Note: If you choose to install Citrix Workflow Studio on your development computer, you can skip this topic. If you choose to not install Citrix Workflow Studio on your development computer, you must copy five files from a computer where Workflow Studio is installed to your development computer and add them as references to Visual Studio. The five files are components from Workflow Studio that are referenced from within the activity libraries that you create using the Citrix converter or templates.

1. On the computer where Workflow Studio is installed, open a Command Prompt. Copy each of the followi development computer:

C:\WINDOWS\assembly\GAC_MSIL\Common\1.0.0.0__78e03b5295a4e20d\Common.dll C:\WINDOWS\assembly\GAC_MSIL\CustomActivityDesigners\1.0.0.0__8a86f49e1eb569bb\CustomActivityDe C:\WINDOWS\assembly\GAC_MSIL\CustomActivityPropertyEditors\1.0.0.0__36841176f080fbec\CustomActi C:\WINDOWS\assembly\GAC_MSIL\CustomActivitySerializers\1.0.0.0__1870553f17856880\CustomActivitySe C:\WINDOWS\assembly\GAC_MSIL\User\1.0.0.0__35f94bb8b52992a3\User.dll

The destination of those files does not matter. You will browse to them from the Visual Studio Add Refer

2. In Visual Studio open the Add Reference dialog box and click Browse to locate and add the dlls listed in

127

To install the converter and templates

The Citrix Workflow Studio Developer Network website includes links to an installer for the Citrix PowerShell Converter and an installer for the Citrix templates for Visual Studio. Download and install those components as follows. 1. Navigate to http://community.citrix.com/cdn/. Mouse over Workflow Studio in the top menu bar and choose Download SDKs. 2. Copy WFSTemplates.msi to your development computer. 3. To start the installation, double-click WFSTemplates.msi. The installer first copies the Citrix PowerShell Converter DLL into the Global Assembly Cache (GAC). It then creates a folder, %PROGRAMFILES%\Citrix\Workflow Studio Templates, with one file, WFSTemplates.vsi. The installer then runs the VSI file. Next, the installer displays the Visual Studio Content Installer window. By default all Project and Item templates are selected for installation. The Project templates add required references to the activities you create from the Item templates. 4. Click Next and then Finish. The links that appear in the Visual Studio Content Installer window allow you to view the path to the installed files.

128

To uninstall the DLL and templates

1. Run Add/Remove Programs and then remove Citrix Workflow Studio Templates. 2. Delete the templates from your Visual Studio Templates directories in Documents and Settings:

G ItemTemplates\Visual C#\Citrix Workflow Studio\ G ProjectTemplates\Visual C#\Citrix Workflow Studio\

129

Converting PowerShell Snap-ins to Activity Libraries

Perform the following general tasks to develop an activity library from a PowerShell snap-in by using the Citrix PowerShell Converter. 1. Create an activity library project from a PowerShell snap-in. 2. Edit the generated code to add and change references, activity attributes, input/output base classes, and dependency properties. 3. Review the project properties and change as needed. 4. Add the new activity to Workflow Studio and use it to create a workflow. Note: The Citrix-provided documentation for Workflow Studio does not go into detail about Microsoft technologies and products such as PowerShell, Visual Studio, and the other technologies used as a foundation for Citrix Workflow Studio. Many resources for those and other topics, such as workflow and activity development, are available from the Microsoft MSDN online library and from other Microsoft and third-party vendor sources. These topics are a series of exercises that guide you through a sample conversion. Related Information To create an activity library project and convert an activity To review the project properties To add references to the snap-in binary To review activity attributes To edit the input/output base classes To edit the dependency properties To test the activity in Workflow Studio

130

To create an activity library project and convert an activity

The procedures in this topic assume that you have installed the Citrix templates. To start, you will create an activity library project in Visual Studio and then use the Citrix PowerShell Converter to convert a PowerShell cmdlet to an activity. The cmdlet that you will convert is the native Get-Date cmdlet, which returns the current date and time. 1. From the Visual Studio window, choose File > New > Project. The New Project dialog box displays a list of project types and templates. 2. In the Project Types list, select Citrix Workflow Studio. The Templates list shows the templates that you installed for Workflow Studio. 3. In the Templates list, select PowerShell Activity Library. The PowerShell Activity Library Project template is not like the other templates in that double-clicking it opens the Citrix PowerShell Converter rather than creating an activity from the template. The converter enables you to select the PowerShell cmdlets for which you want to generate activities. You can use the PowerShell Activity Library Item template to add activities to projects created by any Citrix project template. 4. Change the Name to GetDate and then click OK. The PowerShell Converter appears. 5. In the converter, click the top drop-down list to see all of the PowerShell snap-ins registered on your computer. 6. Select the snap-in named Microsoft.PowerShell.Utility and then click the List Cmdlets button. A list of the cmdlets in that PowerShell snap-in appears. Note: Notice the Refresh button across from the List Cmdlets button. If you install a new PowerShell snap-in while the converter is open, you can click Refresh to reload the list. 7. Select the cmdlets that you want to include in the project. For this exercise, select only Get-Date. In the PowerShell Converter dialog, notice the Tree Path, which is where in the Workflow Studio Designer activity tree that your custom activity will appear. Tree Path defaults to the Windows Powershell folder (which appears under the root of the Workflow Studio Designer activity tree). 8. Change the Tree Path to Windows PowerShell/Utilities. When you add your custom activity to Workflow Studio Designer, it will be located in the Workflow Studio activity tree under Windows PowerShell > Utilities.

131

To create an activity library project and convert an activity 9. To replicate the selected cmdlet in a new project, click Generate Project. Visual Studio builds a Visual Studio project, sets up all of the references, and sets the build destination. It also adds one class file for each cmdlet selected from the PowerShell snap-in. 10. Click OK when the message Generation of project GetDate completed appears. 11. To view the generated code: Right-click GetDate.cs in the Solution Explorer and choose View Code. 12. Notice the using statements in the code. Included are references to the following Workflow Studio components.

Component Common

Provides
G

Built-in validation routines. Base logic for the Workflow Studio password property. Customized ForEach, IfElse, and While constructs. Support for dynamically loading PowerShell snap-ins without needing to use Add-PSSnap-in. Support for the customized theme in the Workflow Studio Designer. Custom file browser, folder browser, text editor, and custom binding dialog support. Helper objects to make PowerShell serializable. Base classes you can derive from when building activities to simplify access to PowerShell and WMI. Native tools to support development of UI activities.

CustomActivityDesigner
G

CustomActivityPropertyEditor
G

CustomActivitySerializers
G

User
G

Those components are also included in the References list in the Visual Studio Solution Explorer. If those references are missing from the generated code, you must either install Workflow Studio on your development computer or install the required dlls.

132

Reviewing and Editing the Generated Code

While the Citrix PowerShell Converter automates much of the activity development process, a developer must tune the overall design of the activity library and edit the code to optimize use of the activities in a workflow. The comments in the generated code guide you through the editing. Note: Only the code regions covered in the following topics typically need modification. For additional help, refer to the samples and comments in the generated code. Related Information Best Practices To add references to the snap-in binary To review activity attributes To edit the input/output base classes To edit the dependency properties

133

To add references to the snap-in binary

At this point in the exercise, the Error List in the Visual Studio window has two messages related to a missing assembly reference. When you convert a PowerShell snap-in to an activity, you must edit the code to reference the snap-in binary: You must add a reference to the binary, a using statement, and an ActivityReferenceAssemblies attribute. 1. To add a reference to the binary: a. Choose Project > Add Reference. b. Click the Browse tab and navigate to:

%PROGRAMFILES%\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\Microsoft.PowerShell.Co

When you do not know which dll to reference, refer to the developer documentation for the snap-in. c. Click OK. The References list now includes an entry for the added object. 2. Add the following using statement: using Microsoft.PowerShell.Commands;

The reference and the using statement names might not match. Refer to the developer documentation fo 3. To set up the ActivityReferenceAssemblies attribute on the project:

a. Open the Attribute Definitions and Comments region and copy the following commented line to the e

// [ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0

You will need to replace the fully specified assembly name (everything inside of the double-quotes) with command provides access to that information, as follows. b. Uncomment the line, open a PowerShell window, and run the following PowerShell command: [appdomain]::currentdomain.getassemblies() | sort -property fullname | format-table fullname

A list of assembly names appears. c. From that list, copy the entire line that starts with Microsoft.PowerShell.Commands.Utility attribute will now look similar to the following:

[ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.

134

To review activity attributes

The Attribute Definitions region contains the following generated code. These attributes define characteristics of the activity when it is used in Workflow Studio Designer.

[Designer(typeof(BaseActivityDesigner))] [DisplayNameAttribute("Get-Date")] [Description(@"Gets the current date and time.")] [ActivityTreePath(@"Windows PowerShell/Utilities")] [ActivityValidator(typeof(GetDateValidator))] [ToolboxBitmapAttribute(typeof(GetDate), @"Resources.GetDate16.png")] [BaseActivityDesigner(ImageResourceName = @"Resources.GetDate32.png", AssemblyType = typeof(GetDate) [CTXPSCmdletInfoAttribute("Get-Date","Microsoft.PowerShell.Utility")] [ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.0, Cultu A summary of those activity attributes follows.

Activity Attributes Designer

Description Defines the activity designer to be used for the activity. The BaseActivityDesigner is the Citrix designer that determines the appearance of the activity in Workflow Studio Designer. The name that appears for the activity in the Workflow Studio Designer. Help text that appears in the Workflow Studio Designer under the Activity list when this activity is selected. Specifies where the activity appears in the Activity list in Workflow Studio Designer. Defines the class responsible for the activitys validation logic. That validator class appears at the end of generated code.

DisplayNameAttribute Description ActivityTreePath ActivityValidator

ToolBoxBitmapAttribute Specifies the icon used for the activity in the Activity list. BaseActivityDesigner Defines several attributes that affect the appearance of the activity bubble on the Workflow Studio design surface.

CTXPSCmdletInfoAttribute Specifies the PowerShell cmdlet to run for this activity. This one line of code is a good example of the work done for you when you convert a PowerShell cmdlet to an activity. If you were to start from the base template to develop the activity from scratch, you would need about 30 lines of code to set up a connection to PowerShell, load the runspace, load the snap-in, and call the cmdlet. 1. For the exercise, you do not need to make any changes to the attribute definitions portion of the code. Typically, you should change at least the following:

135

To review activity attributes a. Change the icon filenames in ToolBoxBitmapAttribute and BaseActivityDesigner to match your custom icons. b. Add/edit the ActivityReferenceAssemblies line. 2. Be aware that the following attributes, not added by the template, are also available. You can copy them from the comment block and modify as needed.

Activity Attributes

Description

ActivityReferenceAssemblies Specifies other assemblies to be referenced by a workflow using this activity. (You already added this in the exercise.) BindTypesOverride CTXPSParameterInfo DesignerSerializer HiddenPSSnap-in Related Information General Activity Attributes PowerShell-Specific Activity Attributes Allows you to specify additional data types to which the Input or Output properties can be bound. Maps activity properties to PowerShell parameters. Calls the Citrix BindingListSerializer. This attribute is required if your activity includes bindable properties. Specifies a PowerShell snap-in to be dynamically loaded at runtime.

136

To edit the input/output base classes

The input/output base classes enable you to hide or modify input and output properties. The GetDate activity created in these exercises will simply return the current date and time, so it does not need user input properties. You prevent the an input property, such as GetDate, from appearing in the Workflow Studio Designer Properties pane as follows. 1. In the Input/Output Base Classes region, select the following lines and then uncomment them. //[Description("<enter new description>")] //[Category("Parameters")] //[Browsable(true)] //[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)] //public override Object Input //{ // get { return base.Input; } // set { base.Input = value; } 2. Delete the Description and Category attributes. They are not needed for a hidden input property. 3. Change the Browsable attribute to false so that the Input property for GetDate will not appear in the properties list. The input base class should now contain the following lines: [Browsable(false)] [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)] public override Object Input { get { return base.Input; } set { base.Input = value; } }

137

To edit the dependency properties

A dependency property is a property to which other activities can bind. They are the properties used by the cmdlet that you converted. When an activity is added to Workflow Studio, the dependency properties appear in the right pane of the designer window (under Parameters) when you select the activity. The GetDate activity you created in these exercises does not need bindable properties, so you will remove most of them. In the dependency properties region, remove all properties except for Format. No other changes to dependency properties are needed for this exercise. If you want to change the format of the output date/time, refer to the code comments for the Format property. A summary of the Format dependency property attributes follows.

Attributes DisplayName Description Category Browsable

Description Specifies the name to appear for the property in the property grid. Contains the help text that appears below the property grid when the property is selected. Determines under which group in the property grid the property will appear. Specifies whether the property will appear in the property grid or in the MS binding dialog box.

DesignerSerializationVisibility Specifies which part of a property should be serialized by the Workflow Studio Designer. EditorAttribute CTXPSParameterInfo Related Information Dependency Property Attributes Change optional integer properties Specifies which property editors, if any, are associated with this property. Allows you to map activity properties to PowerShell parameters.

138

To review the project properties

Before you compile your work into a dll, review the project properties. Project properties control items such as the output file destination and dll signing. 1. In Visual Studio, choose Project > GetDate Properties. 2. To change the output path, click Build in the navigation tree. The default is projectFolder/bin. Change the path if you want. 3. Click Signing in the navigation tree. Notice that the Sign the assembly checkbox is selected and that there is a default key file sn.snk. That placeholder key file is not password-protected. This exercise assumes that there is no password on the key file. Note: For activities that you plan to release publicly, you should replace the key file with your own. 4. If you change any properties, right-click the GetDate tab and choose Save Selected Items. 5. Close the tab containing the project properties.

139

To test the activity in Workflow Studio

If you do not have Citrix Workflow Studio installed on your development computer, copy GetDate.dll to the computer where Workflow Studio is installed, into %PROGRAMFILES%\Citrix\Workflow Studio. After you finish a custom activity, you compile it and test your edited code. 1. To compile the code, in Visual Studio, choose Build > Build Solution. The dll will be saved to the output path specified in the project properties. 2. Start Workflow Studio and create a workflow that will include the GetDate activity: a. Click the Workflow Studio Workflows tab and then click a workflow category. (If no categories exist, you must create one.) b. In the Actions pane, click Create Workflow. c. Enter a name for the workflow and then click OK. d. When the Workflow Studio Designer opens, notice that the Activities tab does not yet include a Utilities folder (under Windows PowerShell) where the GetDate activity will be located. To see the new activity, you must install the GetDate activity library and add the new activity to the Activities tab, as follows. 3. To install the activity library in Workflow Studio: a. Choose Tools > Choose Activities. b. Click Browse, navigate to %PROGRAMFILES%\Citrix\Workflow Studio, select GetDate.dll, and click Open. 4. To add the GetDate activity to the Activities tab: In the Choose Activities dialog box, select the checkbox of the GetDate activity, and then click OK. 5. Add the following two activities to the workflow: a. In the Activities tab, open the Windows PowerShell > Utilities folder. It contains one activity, GetDate. Drag GetDate to the design surface. b. In the Activities tab, open the Workflow Control > Debugging folder and drag MessageBox to the design surface under GetDate. Your workflow should look like the following screen sample:

6. Now you will bind the output of the GetDate activity to the message text: a. Select the messageBox activity in the workflow. b.

140

To test the activity in Workflow Studio In the Properties pane to the right of the design surface, click Message Text and then click the icon to open the Edit Message Text dialog box. c. Type this text, followed by a space: The current Date/Time is: d. To add the output of the GetDate activity to that text, select Output (under the getDate1 activities) and then click Add.

7. Click OK. To test the workflow, click Start. The message box appears.

You have now completed the exercises.

141

To test an activity library that changed after installation

If you change an activity library after using an installer to install it, use this simple method to test the changes before rebuilding the installer. 1. Uninstall the Activity Library. 2. Copy the changed activity library DLL to %PROGRAMFILES%\Citrix\Workflow Studio. 3. Use the Workflow Studio Designer Choose Activities dialog to add the activity library.

142

Creating Activities from Citrix Templates

Perform the following general tasks to develop an activity library by using the Citrix Standard Activity template for Visual Studio. Projects created from the Standard Activity template are the same as projects created from the PowerShell Converter. You can use the Citrix PowerShell Activity or Citrix Standard Activity templates to add an item to either project type. 1. Create a project from the Activity Library template. 2. Add to that project an activity from the Workflow Studio Standard Activity template. 3. Edit the generated code to add and change activity attributes, the constructor, and dependency properties. 4. Add to the activity execution logic and update the validation logic. 5. Add the new activity to Workflow Studio and use it to create a workflow. Note: The Citrix-provided documentation for Workflow Studio does not go into detail about Microsoft technologies and products such as PowerShell, Visual Studio, and the other technologies used as a foundation for Citrix Workflow Studio. Many resources for those and other topics, such as workflow and activity development, are available from the Microsoft MSDN online library and from other Microsoft and third-party vendor sources. These topics are a series of exercises that guide you through a sample conversion. Related Information To create an activity library project from a template To add an activity to the project To change the activity attributes To define the default value for the delay activity To correct the dependency properties To add to the exception handling To edit validation logic To test the standard activity in a workflow

143

To create an activity library project from a template

In this series of exercises, you will create an activity that delays the processing of a workflow. (This version of the delay activity is simpler to use than the default delay activity.) 1. From the Visual Studio window, choose File > New > Project. The New Project dialog box displays a list of project types and templates. 2. In the Project Types list, select Citrix Workflow Studio. The Templates list shows the templates that you installed for Workflow Studio. 3. In the Templates list, select Activity Library. 4. Change the Name to AdvancedDelay and then click OK. A blank project opens in Visual Studio.

144

To add an activity to the project

Perform this task in Visual Studio. 1. Choose Project > Add New Item. 2. In the Add New Item dialog box, select Citrix Workflow Studio, select Standard Activity, enter the name AdvancedDelay.cs, and click Add. 3. To view the code: Select AdvancedDelay.cs in the Solution Explorer and choose View > Code.

145

Editing the Code Generated from a Template

While creating an activity from the Citrix Standard Activity template automates much of the activity development process, a developer must tune the overall design of the activity library and edit the code to optimize use of the activities in a workflow. The comments in the generated code guide you through the editing. For additional help, refer to the samples and comments in the generated code. Related Information Best Practices To change the activity attributes To define the default value for the delay activity To correct the dependency properties To add to the exception handling To edit validation logic

146

To change the activity attributes

The Attribute Definitions region contains the following generated code. In this exercise, you will change the activity description and its location in the Workflow Studio Designer activity tree.

[Designer(typeof(BaseActivityDesigner))] [DisplayNameAttribute(@"AdvancedDelay")] [Description(@"This activity will <...>.")] [ActivityTreePath(@"Folder/SubFolder")] [ActivityValidator(typeof(AdvancedDelayValidator))] [ToolboxBitmapAttribute(typeof(AdvancedDelay), @"Resources.AdvancedDelay16.png")] [BaseActivityDesigner(ImageResourceName = @"Resources.AdvancedDelay32.png", AssemblyType = typeof(Ad 1. Change the Description to: [Description(@"This activity will delay for a specified amount of time.")] 2. Change the ActivityTreePath to: [ActivityTreePath(@"Windows PowerShell/Utilities")]

147

To define the default value for the delay activity

For this exercise, you must change the constructor by defining a default value for the delay activity. 1. In the Constructor region, uncomment the line: \\this.IntegerProp = 0; 2. Change that line to: this.DelayTimeProp = 0;

148

To correct the dependency properties

For this exercise, you will uncomment a sample dependency property and edit it to correctly reference DelayTimeProp.

1. Under Dependency Properties in the Sample Integer Property region, uncomment the following code line

//public static DependencyProperty IntegerPropProperty = DependencyProperty.Register("IntegerProp", t //[DefaultValue("0")] //[Category(@"Parameters")] //[DisplayName(@"DependencyIntegerProperty")] //[Description(@"Description.")] //[Browsable(true)] //[InputAttribute] //public Int32 IntegerProp //{ // get // { // return ((Int32)(base.GetValue(IntegerPropProperty))); // } // set to // { // base.SetValue(IntegerPropProperty, value); // } //} 2. In the first line, change:
G

IntegerPropProperty to DelayTimePropProperty

IntegerProp to DelayTimeProp That code line should look like this:

G

public static DependencyProperty DelayTimePropProperty = DependencyProperty.Register("DelayTimePro 3. Change the DisplayName value to DelayTime. 4. Change the Description value to Specifies the amount of time to delay (in ms). 5. Change public Int32 IntegerProp to public Int32 DelayTimeProp. 6. Change return ((Int32)(base.GetValue(IntegerPropProperty) to return ((Int32)(base.GetValue(DelayTimePropProperty).

7. Change base.SetValue(IntegerPropProperty, value); base.SetValue(DelayTimePropPro

149

To add to the exception handling

You generally should include more specific exception handling than what is generated. By default, Workflow Studio just catches an exeception and rethrows it. In the Activity Execution Logic, under // Place your code here, add the following to the try-catch block: System.Threading.Thread.Sleep(this.DelayTimeProp); Note: Just above the try-catch block is an ExpandStringProperties method which automatically expands all the string properties and, at run time, replaces the actual values and returns the full string. Without that line of code, strings will not be expanded.

150

To edit validation logic

For this exercise, your only change to the validation logic is to uncomment and edit some Sample Property Validation code so that it correctly references DelayTimeProp. 1. Under Sample Property Validation, uncomment this line: //if (!GlobalUtilities.Int32Validates(MyActivity.IntegerProp) 2. Change that line to: if (!GlobalUtilities.Int32Validates(MyActivity.DelayTimeProp.ToString())) 3. Uncomment this line:

//errs.Add(new ValidationError(@"You must specify a value for the 'IntegerProp' property.", 101, false, @ 4. Change that line to:

errs.Add(new ValidationError(@"You must specify a value for the 'DelayTimeProp' property.", 101, false, @

151

To test the standard activity in a workflow

Follow these general steps to test an activity. The details in the steps refer to the AdvancedDelay activity that you created in this series of exercises. For addition information about testing, refer to: To test the activity in Workflow Studio. 1. Build the activity in Visual Studio. 2. Add the activity to Workflow Studio. 3. In Workflow Studio, create a workflow and add the AdvancedDelay activity to it. 4. Change the DelayTime parameter to 5000. 5. Run the workflow.

152

Best Practices
These topics describe best practices for ensuring that each activity you create from a PowerShell snap-in is usable in Workflow Studio, performs optimally in a workflow, and is consistent with other activities. Related Information Reference the snap-in binary Change optional integer properties Use strong names for activity libraries Add custom activity icons and reference them Determine if any overrides are needed Review validation logic Other Considerations

153

Reference the snap-in binary

An activity library project must reference the snap-in binary you are converting. You must add the reference to the project, add a using statement, and add an ActivityReferenceAssemblies attribute.

154

To add references to the snap-in binary

At this point in the exercise, the Error List in the Visual Studio window has two messages related to a missing assembly reference. When you convert a PowerShell snap-in to an activity, you must edit the code to reference the snap-in binary: You must add a reference to the binary, a using statement, and an ActivityReferenceAssemblies attribute. 1. To add a reference to the binary: a. Choose Project > Add Reference. b. Click the Browse tab and navigate to:

%PROGRAMFILES%\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0\Microsoft.PowerShell.Co

When you do not know which dll to reference, refer to the developer documentation for the snap-in. c. Click OK. The References list now includes an entry for the added object. 2. Add the following using statement: using Microsoft.PowerShell.Commands;

The reference and the using statement names might not match. Refer to the developer documentation fo 3. To set up the ActivityReferenceAssemblies attribute on the project:

a. Open the Attribute Definitions and Comments region and copy the following commented line to the e

// [ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0

You will need to replace the fully specified assembly name (everything inside of the double-quotes) with command provides access to that information, as follows. b. Uncomment the line, open a PowerShell window, and run the following PowerShell command: [appdomain]::currentdomain.getassemblies() | sort -property fullname | format-table fullname

A list of assembly names appears. c. From that list, copy the entire line that starts with Microsoft.PowerShell.Commands.Utility attribute will now look similar to the following:

[ActivityReferenceAssemblies(new string[] { "Microsoft.PowerShell.Commands.Utility, Version=1.0.0.

155

Change optional integer properties

The dependency property code is generated from the PowerShell snap-in. Review all dependency properties for optional integer properties and change them as follows:
G

You must modify all optional integer properties (which control how the object is displayed in Workflow Studio Designer) to be String properties. However, keep the CTXAttributeType (which controls how we send the object to PowerShell) set to Int32. Thus, data from the user is obtained as a string; Workflow Studio then converts the data to an integer before it is passed to PowerShell. As a result of those changes you can bind these parameters to any other string parameter or variable that might contain a number. Suppose that when you were creating the GetDate activity, you retained the dependency properties (which include Date, Year, Month, Day, Hour properties). Because integers cannot be null and default to zero, leaving them as integers causes zero to be sent for all the integer properties. Thus, those properties need to be strings. Note: Although the core of Workflow Foundation is very strict about data types, Workflow Studio extensions reduce what you need to know about data types and conversion.

Uncomment the EditorAttribute, which is used for strings. Search for properties with CTXPSParameterInfoAttribute.CTXAttributeType.Unknown and replace Unknown with a type that makes sense for the object (most likely it will be Object). The Unknown type is specifically included to throw a runtime error and remind you to look at it. Include additional design time and run time validation based on the integer range expected to ensure that the entry is a valid integer in the correct range. In the following code sample, the property changes just described are highlighted.

#region Year Property public static DependencyProperty YearProperty = DependencyProperty.Register("Year", typeof(String), ty [DisplayName("Year")] [Description("Specifies the year that is displayed. Enter a value from 1 - 9999. This value is displayed inst [Category("Parameters")] [Browsable(true)] [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)] [EditorAttribute(typeof(TextEditor), typeof(UITypeEditor))] [CTXPSParameterInfo("Year", AttributeType = CTXPSParameterInfoAttribute.CTXAttributeType.Int32)] //[BindTypes(new Type[] { typeof(Int32)} )] public String Year { get { 156

Change optional integer properties return ((String)(base.GetValue(GetDate.YearProperty))); } set { base.SetValue(GetDate.YearProperty, value); } }

157

Use strong names for activity libraries

Workflow Studio requires that an activity library is internally signed (that is, has a strong name). Strong-name signing gives an activity a unique identity. A strong name consists of its simple text name, version number, culture information (if provided), plus a public/private key pair. Activities created using Citrix-provided tools include a placeholder key file, sn.snk, which is not password-protected. For activities that you plan to release publicly, you should replace the key file with your own.

158

To review the project properties

Before you compile your work into a dll, review the project properties. Project properties control items such as the output file destination and dll signing. 1. In Visual Studio, choose Project > GetDate Properties. 2. To change the output path, click Build in the navigation tree. The default is projectFolder/bin. Change the path if you want. 3. Click Signing in the navigation tree. Notice that the Sign the assembly checkbox is selected and that there is a default key file sn.snk. That placeholder key file is not password-protected. This exercise assumes that there is no password on the key file. Note: For activities that you plan to release publicly, you should replace the key file with your own. 4. If you change any properties, right-click the GetDate tab and choose Save Selected Items. 5. Close the tab containing the project properties.

159

Add custom activity icons and reference them

Workflow Studio includes default icons that display in two locations in the Designer window for each activity:
G

A 16x16 icon appears to the left of the activity name in the Activities tree. The filename for this image is specified as a parameter to ToolboxBitmapAttribute. A 32x32 icon appears to the left of the activity name in the activity bubble. The filename for this image is specified as a parameter to BaseActivityDesigner.

You can replace those icons with your own.

160

To add and reference icons

Workflow Studio includes default icons that display for each activity in the Activities list and in the activity bubble. You can replace those icons with your own.

1. Make sure that your icons are PNG files and are 16 pixels square (icon for the Activities list) and 32 pixel square (icon for the activity bubble).

2. Add the icons as resources: In the Visual Studio, select the project GetDate in the Solution Explorer, cho Project > GetDate Properties, and then click the Resources tab. From the Resources tab, you can crea resources file and add the images to it. 3. In the generated code, update the filenames in the following lines:

[ToolboxBitmapAttribute(typeof(GetDate), @"Resources.GetDate16.png")] [BaseActivityDesigner(ImageResourceName = @"Resources.GetDate32.png", AssemblyType = typeof(GetDa

The default images are provided as part of the base Workflow Foundation. You will not find those images in Workflow Studio application folders.

161

Determine if any overrides are needed

The Activity Execution Logic region of the code contains samples for common overrides.
G

ExtraParameterValidation is used to perform a runtime validation of required properties. When an exception is thrown, a message is displayed in Workflow Studio Designer. AddParameters is used to add parameters to the input objects. For the GetDate example, if the dependency property Date was included in the user input, you could add a parameter that would cause the date to be passed to PowerShell only if it was set by the user. Here is a code sample for that situation: protected override void AddParameters(Command cmd) { base.AddParameters(cmd); //add the date only if supplied if (this.Date.ToString().Length > 0) { cmd.Parameters.Add("Date", true); } }

162

Review validation logic

The last region of the generated code is the validation logic. The PowerShell Converter generates validation code based on the properties marked as required in the converted PowerShell cmdlets. While that gives you a starting point, you should review the generated code and determine the changes needed for correct validation. Review the validation logic for the following items:
G

What you want to validate and how you want to validate it is not readily auto-generated. A string might need deeper inspection and validation. For example, you might want to validate that the user input satisfies the requirements of a phone number or a MAC address. Or you might want to check that an integer fits a particular range. When you add an activity to Workflow Studio Designer, the activity bubble includes a red icon which the user clicks to see a list of required properties. You can add warning messages in the validation logic. If you need to add custom validation code, add it above the StopOnError region. An activity must include the generated StopOnError validation code. Typically, if a workflow encounters an error, you just want to catch the error, ignore it, and continue the workflow. StopOnError allows you to easily do that, rather than adding and configuring error handlers. All you have to do is set the StopOnError property (automatically added to every activity based on a Citrix template) to False. Although error handling is very complex in Workflow Foundation and Workflow Studio, the Citrix StopOnError extensions greatly simplify it for you.

163

Other Considerations

Use the correct process when debugging custom activities

When you need to debug an activity that will be used in Workflow Studio, you should follow the standard Microsoft debugging principles. The only thing specific to Workflow Studio that you need to be aware of is the difference between debugging the validation logic and debugging the execution logic. You must attach Visual Studio to the correct Workflow Studio process, as follows.

To debug Validation logic (which runs at design time, such as when you specify a property) Execution logic (for a workflow run when you click Start in the Workflow Studio Designer) Execution logic (for a deployed workflow or job)

Connect Visual Studio to this process wfs.exe

Which is the Workflow Studio Designer process

WorkflowExpressRuntime.exe

Process used to run workflows from the Designer

WorkflowRuntimeHostService.exe

Service that Workflow Studio uses to run jobs

Keep the Workflow Studio Library tidy

As you test and tune an activity, you might copy the activity DLL to Workflow Studio several times. Generally, all you need to do before copying the updated activity DLL is to exit Workflow Studio. (Otherwise, you will get a message that the DLL is in use.) However, if you change the key file for the activity DLL, you should remove that activity from the Workflow Studio library before adding the updated version to avoid getting multiple copies of the activity in the library. To remove an activity from the library, you must remove the ToolBoxItem statement for the activity from the following Workflow Studio configuration files:

Documents and Settings\All Users\Application Data\Citrix\Workflow Studio\WorkflowStudio\version\WFS.Config

164

Other Considerations This file applies to your computer and must be changed (along with user.Config) if you are using the PowerShell snap-ins to install the activity you created.
G

Documents and Settings\userName>\Local Settings\Application Data\Citrix\Workflow Studio\WorkflowStudio\version\user.Config This file must be changed to update the list in the Workflow Studio Choose Activities dialog box.

Note: You can also reset the activity library to its default, thus removing all activities that you have added, by deleting those configuration files. However, your SQL server domain name and any other configuration changes you made will be lost.

Control Workflow Studio activity names

When you drag an activity onto the Workflow Studio design surface, the name of that activity is determined by a value in a file that is generated when you create the activity. The file, activityName.Designer.cs, contains the following line in the Activity Designer generated code: this.Name = Name; The Name is generated from the PowerShell snap-in name by removing the hyphen from the name (because hyphens are not supported in activity names in Workflow Foundation). For example, if you create an activity from the Get-Date snap-in, the generated name is as follows: this.Name = GetDate;

If the generated name begins with an upper case letter (GetDate), the first time you drag the GetDate activity to the Workflow Studio design surface, the activity name will have a 1 appended (GetDate1). The number is incremented for subsequent uses (GetDate2, GetDate3). If the generated name begins with a lower case letter (getDate), the first time you drag the GetDate activity to the Workflow Studio design surface, the activity name will match the generated name (getDate). A number is appended for subsequent uses (getDate1, getDate2).

165

Activity Attribute Reference

Activity attributes define characteristics of an activity when it is used in Workflow Studio Designer. For example, activity attributes:
G

Determine the appearance of an activity on the design surface Specify assemblies to be referenced by a workflow using an activity. Specify additional data types to which the Input or Output properties can be bound. Call the Citrix BindingListSerializer, which is required if an activity includes bindable properties. Control the dependency property text and behavior. Define the class responsible for an activitys validation logic. Specify the PowerShell cmdlet to run for an activity and map activity properties to PowerShell parameters.

These topics describe the activity attributes. Related Information Dependency Property Attributes General Activity Attributes PowerShell-Specific Activity Attributes PowerShell-Specific Property Attribute

166

General Activity Attributes

[Designer(typeof(ActivityDesigner))]

Defines the activity designer to use for an activity. The activity determines the appearance of the activity on the design surface its background color, selected glow, font, and icon position. BaseActivityDesigner is the Citrix-provided designer, whi an activity as follows.

[DisplayNameAttribute(@"name")]

Specifies the name of an activity. This is the name that appears Activities tree and on the activity when it is on the design surfa spaces in this name are replaced with underscore characters wh activity is dropped on the design surface.

[Description(@"text")]

Provides a brief text description of the activity. This text appea the Activities tree in the Workflow Studio Designer when the ac selected in the tree. Typically, this text is a short, high-level ov what the task does.

[ActivityTreePath(@"path/name")]

Specifies where you want the activity to appear in the Activitie Use forward slashes, not back slashes, to separate nested folde path.

[ActivityValidator(typeof(ValidatorClass))]

Defines which class is responsible for the validation logic of the Each activity typically has a dedicated validator class. If you cr activity using the Citrix activity template, the validator class re the end of the activity .cs file.

[BaseActivityDesigner(ImageResourceName = @"name.png", OptionalParameters, AssemblyType = typeof(AssemblyType))]

167

General Activity Attributes

Specifies the assembly type (required) and optionally takes one of the following parameters. Typically the appearance of the ic used with this attribute is the same as the one used for ToolboxBitmapAttribute. This image must be a 32x32 PNG file.

ImageResourceName ShineColor GlowColor GlowIntensity [ToolboxBitmapAttribute(typeof(ActivityName), @"name.png")]

BackColor MaskColor TextForeColor ShapeRadius

TextFontFam

TextFontSize Width Height

Specifies the 16x16 image file to use as the icon for the activity Activities tree. The image must be a PNG file. Typically the app of the image used for this attribute is the same as the one used BaseActivityDesigner.

[DesignerSerializer(typeof(BindingListSerializer), typeof(WorkflowMarkupSerializer))]

Calls the Citrix BindingListSerializer. This attribute is re your activity includes bindable properties (BindingList).

[ActivityReferenceAssemblies(new string[] { @"assembly" })]

Allows you to specify one or more additional assemblies that m referenced by the workflow project. By default, if an activity r an assembly, that referenced assembly will be added as a refer the workflow project. However, sometimes an assembly is not referenced to an activity and therefore needs to be specified u attribute. This informs the Workflow Studio Designer to manual specified assembly as a reference to the workflow project.

ActivityReferenceAssembliesAttribute takes one para which is a string that is expected to be the full name of the ass For example:

[ActivityReferenceAssemblies(new string[] { @"XenDotNetLibrary, Version=1.0.0.0, Culture=neu PublicKeyToken=3509c8c16f49bbe9" })]

In the process of handling this attribute to create a project refe call to Assembly.ReflectionOnlyLoad() is made, assumin the string is the assembly FullName. The ReflectionOnlyLoa is very forgiving in that it will accept just the assembly name o assembly name and version, and so on. Therefore, if you provid assembly name, it will work: [ActivityReferenceAssemblies(new string[] { @"XenDotNetLibrary" })]

Be aware that if the activity decorated by the above attribute (XenDotNetLibrary in this case) needs to reference a specific the XenDotNetLibrary assembly in the future, that string must a include the version number.

168

General Activity Attributes [BindTypesOverride("Input", new Type[] { typeof(String) })] [BindTypesOverride("Output", new Type[] { typeof(String) })]

Allows you to specify additional data types to which the Input o properties can be bound.

169

PowerShell-Specific Activity Attributes

[CTXPSCmdletInfoAttribute(@"cmdlet", @"snapIn")]

Specifies the Powershell cmdlet that an activi runs. This attribute is applicable to activity cl that inherit from PSActivityBase. PSActivityBase::Execute will execute t specified Powershell cmdlet, with the parame specified by the CTXPSParameterInfo attr

The first parameter is the cmdlet name. The s (optional) parameter is the snap-in name. If a snap-in name is specified, that snap-in will be loaded in the runspace before the cmdlet is c [CTXPSModuleInfoAttribute(@"command", @"module")]

Specifies the Powershell command that an act runs. The command may be implemented by a cmdlet, a script function, or a simple script fi attribute is applicable to activity classes that from PSActivityBase and that intend to us commands embedded in a PowerShell module

The first parameter is the command name. Th second parameter is the module that must be imported for the command. [CTXPSParameterInfo("browserName", AttributeType = CTXPSParameterInfoAttribute.CTXAttributeType.NonEmptyString)]

Maps activity properties to Powershell parame This attribute should be applied to properties dependency properties) of an activity class th inherits from PSActivityBase. The common in PSActivityBase adds the Powershell cm parameters, using the activity properties as specified by this attribute. The first paramete Powershell parameter name. The second para (AttributeType) specifies how the value for th Powershell parameter should be handled (that String, NonEmptyString, PSObject, SwitchPara and so on).

[HiddenPSSnapIn("assemblyName")]

170

PowerShell-Specific Activity Attributes

Specifies a Powershell snap-in to be dynamica loaded at runtime. This allows you to use Pow cmdlets that are not defined in a registered PSSnapin on the computer. It takes one param which is expected to be the full name of the assembly. For example:[HiddenPSSnapIn("XenAppCmdle Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")] .

When the assembly is loaded, any cmdlets wit are dynamically added to the runspace. This attribute applies to activity classes that inher PSActivityBase.

171

Dependency Property Attributes

[DefaultValue(@"value")] Specifies a value to appear in the property grid as the default value. If supplied, default values appear as normal text. When the value is changed from the default, the value appears in the property grid as bold text. This attribute alters only the behavior of the property in the property grid. The actual default value for a dependency property must be set in the constructor for the activity class. [Category(@"Parameters")] Specifies the group within the property grid where you want the property to appear. The default category for Workflow Studio activities is Parameters. Consider placing parameters that are optional under a different category. [DisplayName(@"Name")] Specifies the name of the property to appear in the left column of the property grid. [Description(@"text")] Specifies a text description of the property. This text description appears at the bottom of the property grid when the property is selected in the property grid. [Browsable(true)] Specifies whether a property is to appear in the property grid. If this attribute is omitted, the property is displayed. If this attribute is supplied and the attribute value is set to false, the property is not displayed. [InputAttribute] Indicates whether the property is an input type of property. Using this attribute simply puts an input icon next to the property in the binding drop-down. If this attribute is include, the OutputAttribute should not be included. [OutputAttribute] Indicates whether the property is an output type of property. Output properties receive a special output icon next to the property in the binding drop-down. They will always appear in the TextEditor editor, regardless of their data type. If this attribute is included, the InputAttribute should not be included. [EditorAttribute(typeof(editor), typeof(editor))]

172

Dependency Property Attributes Specifies which property editors, if any, are associated with this property. Any editor can be used. The following editors are included with Workflow Studio: BindingDropDownListEditor DropDownList DSComputerPicker DSGroupPathPicker DSObjectPathPicker DSOUPicker OpenFileEditor OpenFolderEditor PasswordEditor PropertyColumnEditor TextEditor TrusteeEditor

NamedCollectionEditor Following are the data types that can be used with other editors: EditorHelper FileWithConstructor FolderWithConstructor Notes:
G

StringEdit StringWithConstructor VariableEdit

FolderWithConstructor is used in the Windows library CopyFiles activity for the Destination Folder property. This is the data type that is used in a BindingList collection with the NamedCollectionEditor. Compare it to the OpenFolderEditor which is used on the Source Folder in that same activity. StringEdit is used in the base class for all the WMI activities on the Query Properties property (for example, Get Battery Info). This is also used as a data type in a Binding List with the NamedCollectionEditor. It provides only a Value, not a Name/Value. StringWithConstructor provides a simple collection of strings when used with the BindingList, as is done with FolderWithConstructor.

VariableEdit is used in the Active Directory activity library Set AD Object Attributes activity. It is used as the data type (in a BindingList) for the Attributes property. The editor is the NamedCollectionEditor. This provides the Name/Value pairs in the collection dialog. [ReadOnly(true)]
G

Indicates (true or false) whether the property value is allowed to change. Setting the ReadOnly attribute value to true restricts the value from being changed by the user. [DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)] This attribute takes one parameter, which is a System.ComponentModel.DesignerSerializationVisibility enumeration member:
G

Visible. Specifies that the object should be serialized. Use this value for simple (or primitive) properties. Content. Specifies that contents of the object should be serialized. Use this value for complex (or non-primitive) properties and collections.

173

Dependency Property Attributes

G

Hidden. Specifies that the object should not be serialized. Use this value when properties are changed for design-time purposes only, but should not be serialized in code.

In Workflow Studio this attribute is used for most properties to ensure proper serialization during design time. [BindTypes(new Type [] { typeof(String) } )] Specifies alternate/additional property types that are allowed to bind to this property. This attribute is used in several provided activities, but the best example is the Simple Math activity. In that activity there are two input properties for the two input numbers that are going to be used to perform a mathematic operation with. Some other activities may output numbers that can/should be used by Simple Math in varying types Int32, Int64, Float, Double, Decimal, Object, or even a String. Putting these types into the BindTypes attribute allows the input properties of the Simple Math activity to be bound to any property that is one of those types. Care must be taken to cast the input type appropriately so that exceptions are not encountered when using the bound property values in the activity. [ShowInWFSEditors] Overrides the Browsable attribute to cause properties to show up in the TextEditor editor, even though they may be hidden in the property grid itself. Related Information Change optional integer properties To edit the dependency properties

174

PowerShell-Specific Property Attribute

[CTXPSParameterInfo(@"ParameterName", AttributeType = CTXPSParameterInfoAttribute.CTXAttributeType.String)] Identifies a property as a parameter to the cmdlet. The first parameter to this attribute is the cmdlet parameter name; the second is the cmdlet parameter type. Valid parameter types are:

Boolean BoolString Dictionary Enumeration Guid Int Int32 IntList

Long

String

NonEmptyString StringList Object Password PSCredential PSObject Switch UInt UInt32 ULong

PSObjectArray Unknown

175

Automating Workflow Studio with PowerShell

Workflow Studio includes several PowerShell snap-ins that allow you to automate the functionality of Workflow Studio itself. For example, you can create customized user interfaces, automate the control of workflow jobs, build an installer for an activity library, or manage running workflows. These topics provide an introduction to using PowerShell to automate Workflow Studio. Familiarity with the Workflow Studio management interface is assumed; experience with PowerShell is recommended.

Getting Started

Review background information on Workflow Studio automation and PowerShell snap-ins; learn how to add snap-ins to a PowerShell console Deploy, run, and manage workflows using PowerShell Add an activity library to the Workflow Studio Activities tab

Deploying, Running, and Managing Workflows Adding/Removing Activity Libraries using an Installer

176

Getting Started
Workflow Studio automation takes advantage of the Microsoft PowerShell interactive command-line shell and scripting language which is revolutionizing the way IT administrators approach application and system management. Workflow Studio cmdlets enable you to replace all or any portion of the Workflow Studio management interface. For example, you can use Workflow Studio cmdlets to deploy, schedule, and manage workflows. Some of the cmdlets provide access to functionality that is not yet exposed in Workflow Studio, such as the ability to start, stop, suspend, and resume a workflow job or to handle workflow history archival. If you are not familiar with PowerShell, we encourage you to explore this very powerful interactive command-line shell and scripting language that is built on top of the Microsoft .NET Framework. The documentation provided with PowerShell is a good starting spot. Experience with PowerShell will help you get the most out of these topics and will be essential to successfully automating Workflow Studio through cmdlets. Review these topics in the order listed to learn how to use PowerShell cmdlets to automate the functionality of Workflow Studio. These topics assume familiarity with the Workflow Studio management interface. Related Information About Workflow Studio Automation About Workflow Studio Snap-Ins To add Workflow Studio snap-ins to a PowerShell console

177

About Workflow Studio Automation

Workflow Studio automation takes advantage of the Microsoft PowerShell interactive command-line shell and scripting language which is revolutionizing the way IT administrators approach application and system management. Workflow Studio includes several PowerShell snap-ins that allow you to automate the functionality of Workflow Studio. The snap-ins contain the same cmdlets that are called by the Workflow Studio user interface to support operations such as workflow deployment, scheduling, and management as well as data store managment and activity library installation. By using PowerShell for automation, you can also take advantage of the many cmdlets provided with PowerShell and written by third-parties. Primary uses for Workflow Studio cmdlets include: Deploy, schedule, and manage workflows from a command line, from systems such as Citrix EdgeSite or Microsoft Operations Manager, or from any client application. Build self-service portals that enable users to handle tasks such as reset a password or provision a virtual machine according to user selections. The portal Web page would call Citrix PowerShell cmdlets to process the requests.
G

Write an installer that adds and removes activity libraries from the Workflow Studio Designer interface.

Related Information Getting Started

178

About Workflow Studio Snap-Ins

If you have installed Workflow Studio, you have all of the components needed to use the Workflow Studio snap-ins in PowerShell:

G Microsoft .NET Framework 3.5 G Windows PowerShell 2.0 G Citrix Workflow Studio
Citrix provides the following snap-ins:
G

Citrix.WorkflowStudio.Azman Contains the Workflow Studio Authorization Manager (AzMan) cmdlets. Most of these cmdlets are not intended for your use unless you plan to write your own security interface with functionality that creates and retrieves roles. This snap-in is included with full product and runtime-only installations.

Citrix.WorkflowStudio.Core Contains the Workflow Studio core cmdlets. These cmdlets control workflow deployment, scheduling, and management. This snap-in is included with full product and runtime-only installations.

Citrix.WorkflowStudio.DataStore Contains the Workflow Studio date store cmdlets. These cmdlets enable you to perform data store-related tasks available on the Workflows and Jobs tabs of the Workflow Studio management interface. The data store is an abstraction that uses SQL, but could use an XML-based file store or another database application such as Oracle. This snap-in is not included with a runtime-only installation. (A runtime does not communicate with the database and therefore does not need this snap-in.)

Citrix.WorkflowStudio.Installer Contains the Workflow Studio installer cmdlets. These cmdlets enable you to add and remove activity libraries from the Workflow Studio Designer Choose Activities dialog. This snap-in is not included with a runtime-only installation. (A runtime does not include the Designer interface and so does not need this snap-in.)

Related Information Getting Started

179

To add Workflow Studio snap-ins to a PowerShell console

When you install Workflow Studio, it registers its snap-ins on your computer. To make those snap-ins available to a PowerShell console session, you must add them to the console. 1. Open a PowerShell console: From the Windows Start menu, choose All Programs > Accessories > Windows PowerShell. 2. To see a list of the registered snap-ins, type the following PowerShell cmdlet at the PowerShell prompt: Get-PSSnapIn -Registered The Get-PSSnapIn cmdlet lists the snap-ins. Note: The Get-PSSnapIn cmdlet output does not include the Microsoft default snap-ins. You can include them in the list by omitting the Registered parameter. 3. To add the Workflow Studio snap-ins to this PowerShell console session, pipe the output of the Get-PSSnapIn cmdlet to the Add-PSSnapIn cmdlet: Get-PSSnapIn -Registered | Add-PSSnapIn You will be asked if you want to run software from the untrusted publisher. Respond with A to add the Citrix certificate as a trusted certificate, thus avoiding these prompts in the future. The added Workflow Studio snap-ins are available to your console until you exit from it. If you need to exit the console before completing this tutorial, be sure to run the preceding cmdlet again to add the snap-ins. Alternatively, you can use the Export-Console cmdlet to save the console configuration with the added snap-ins and then subsequently open the saved console by specifying its name on the PowerShell command line:

powershell.exe -psconsolefile filename.psc1 4. To view a list of the cmdlets in a snap-in, use the Get-Command cmdlet. You can include wildcards in a snap-in name; the name value is not case-sensitive. The following command lists the cmdlets for the Citrix.WorkflowStudio.Core snap-in: Get-Command -PSSnapIn Citrix*Core 5. To view help for a cmdlet, such as for Add-Category: Get-Help Add-Category

180

To add Workflow Studio snap-ins to a PowerShell console To include a list of parameters for the cmdlet, use the Detailed parameter with Get-Help:

Get-Help Add-Category -Detailed To include information about whether a parameter is named or positional, takes input from the pipeline, and accepts wildcard characters, use the Full parameter:

Get-Help Add-Category -Full As you the topics about Workflow Studio automation, you might find it useful to review the help for the cmdlets used in the exercises. Opening a second PowerShell console for that purpose is helpful. Related Information Getting Started

181

Deploying, Running, and Managing Workflows

A primary use of Workflow Studio cmdlets is to deploy, run, and manage workflows. The exercises in these topics describe how to use Workflow Studio cmdlets to:
G

Import a workflow into your Workflow Studio database. Deploy and run the workflow. View the job history.

Those same tasks are performed through the management interface, described in Creating and Managing Jobs. Because you can use PowerShell cmdlets to perform operations on Workflow Studio objects while Workflow Studio is running, you can view the results of the various cmdlets in the Workflow Studio interface as you work through these exercises. The sample workflow used in the "Getting Started with Workflow Studio" tutorial is also used for these exercises. (To access that tutorial, start Workflow Studio and click the Getting Started link. ) To begin, you must download the workflow named ExportServices to your computer from the Citrix Developer Network. Related Information To download a workflow to your computer To import a workflow into your Workflow Studio data store To deploy a workflow (create a job) To run a workflow and view its deployment history

182

To download a workflow to your computer

The Workflow Studio page on the Citrix Developer Network contains sample workflows which you can download. In the following procedure, you will download the ExportServices Tutorial workflow. That workflow is referenced throughout the procedures in these automation topics. 1. In a Web browser, navigate to the Workflow Studio page on the Citrix Developer Network: http://community.citrix.com/cdn/wf. 2. In the box labeled Inside, click the Workflows link. 3. Click the link ExportServices Tutorial and then click the link Download ExportServices Tutorial Workflow. 4. Save the workflow to your computer.

After you download a workflow project, you must import it into your Workflow Studio data store before you can use it with Workflow Studio commands. Related Information Deploying, Running, and Managing Workflows

183

To import a workflow into your Workflow Studio data store

When you acquire a workflow (perhaps by downloading it from the Citrix Developer Network or receiving it from a colleague), you must import the workflow project into your Workflow Studio data store. In the following procedure, you will use Workflow Studio cmdlets to add a category for the project and then import the workflow project into that category in the data store. (In Workflow Studio a workflow project refers to a workflow that is not yet deployed.)

1. Cmdlets which operate on the data store require a connection to it, so you must first initialize the data s store the connection object in the variable $ds. In the following command WFDB is the default database name and localhost\SQLEXPRESS is a data differ. $ds = Initialize-DsConnection -DatabaseName WFDB -Datastore localhost\SQLEXPRESS

2. Add a category named MyTools for the ExportServices project. For convenience, you will store the cate The following command references the variable $ds, which contains the connection object. $category = Add-Category $ds -Name MyTools

By default, the category is added to the root Workflows category. Note that the DataStore parameter have to be included in the command.

3. To see the category you added in the Workflow Studio interface, start Workflow Studio and click the Wo running, click the Workflows tab, right-click in the tree view (left pane), and select Refresh.

4. Now you will use the Import-Project cmdlet to import the ExportServices workflow project into the MyTo ID by using the PowerShell dot notation to specify the property ID with the variable $category. Be su parameter the path where you downloaded ExportServices.zip. $project = Import-Project -CategoryID $category.ID -Datastore $ds -ProjectDirectory c:\Documents and

5. View the results of those commands in the Workflow Studio interface. To refresh the Workflows Project select Refresh. Click MyTools in the Workflows tree to see that the ExportServices workflow project is n

Related Information 184

To import a workflow into your Workflow Studio data store Deploying, Running, and Managing Workflows

185

To deploy a workflow (create a job)

In this exercise you will deploy and run the ExportServices workflow. The workflow exports information about services on your computer to two files: RunningServices.csv and StoppedServices.csv. Like most cmdlets that operate on workflows, the Send-Workflow cmdlet requires as input the workflow runtime object (to indicate the target runtime), the fully qualified workflow name in the form Name.Name, and a second identifier for the workflow such as the assembly file name. 1. Store the workflow runtime object in a variable so you can easily reference it: $rt = Get-WorkflowRuntime

2. The workflow that you imported is in a zip file. To access information such as its assembly file name, you

Export-project -Datastore $ds -WorkflowID $project.ID -TargetDirectory 'c:\Documents and Settings\kathy If a folder that you specify with -targetdirectory does not exist, the Export-Project cmdlet creates it. 3. To deploy the workflow to a runtime (thus creating a job):

$workflow = Send-Workflow $rt -Name ExportServices.ExportServices -AssemblyFile 'c:\Documents and Se

4. You can now view the deployed workflow in the Workflow Studio interface: Click the Jobs tab and then i

Related Information Deploying, Running, and Managing Workflows

186

To run a workflow and view its deployment history

After a workflow is deployed to a runtime, you can run it. In this exercise, you will run the workflow immediately.

1. To run the workflow you will need to reference a property in the workflow deployment object (which yo variable $workflow). To view the properties of $workflow: $workflow The list of properties that appear include the following: Runtime Server: MOUNTAIN

WorkflowName : ExportServices.ExportServices WorkflowStrongName : ExportServices, Version=1.0.3246.33047, Culture=neutral, PublicKeyToken=d9 DeploymentInstanceId : 65942ed7-79e2-4041-8a0f-6ac407868b2e DeployedOn : 5/27/2009 10:51:01 AM DeployedBy_Name : MOUNTAIN\user DeployedBy_SID : S-1-5-21-1520102332-1894890864-2995376939-1006

2. To schedule the workflow you will reference the workflow strong name by using the PowerShell dot nota the property WorkflowStrongName with the variable $workflow.

Set-WorkflowSchedule -WorkflowRuntime $rt -WorkflowStrongName $workflow.WorkflowStrongName -Ru The workflow saves two .csv files (RunningServices.csv and StoppedServices.csv) to C:\. 3. To view the deployment history for the workflow: Get-DeploymentHistory -WorkflowRuntime $rt -WorkflowStrongName $workflow.WorkflowStrongName

4. To view a subset of the deployment history in the Workflow Studio interface, click the Jobs tab, select t server in the Jobs tree, select the workflow in the jobs table, and click Open in the Actions pane.

Related Information Deploying, Running, and Managing Workflows

187

Adding/Removing Activity Libraries using an Installer

After you create an activity library you should write an installer so that users can easily add it to Workflow Studio. Your installer must call the Add-ActivityLibraryToTree cmdlet, included in the Installer snap-in. The Add-ActivityLibraryToTree cmdlet is the equivalent of using the Browse function from the Choose Activities dialog to add an activity library to the Activities tab. Your installer should also call the Remove-ActivityLibraryFromTree cmdlet. The Remove-ActivityLibraryFromTree cmdlet is the equivalent of using the Reset function from the Choose Activities dialog to restore the activities list back to its default setting. Before you add an activity library to Workflow Studio, we recommend that you install the activity library in the Global Assembly Cache (GAC) so that you can support multiple versions of the libraries. Related Information Versioning Activity Libraries To add an activity library to the Activities tab

188

To add an activity library to the Activities tab

The Add-ActivityLibraryToTree cmdlet includes parameters that enable you to control access to an activity library. You can set the following policies by using variations of the cmdlet:
G

Show the activity library in the Activities tab for the current user only. If the current user clicks Reset in the Tools > Choose Activities dialog, the added library is removed from the Activities tab and remains visible (but unchecked) in the Choose Activities dialog.

Show the activity library in the Activities tab for all users who log on to the computer. If a user clicks Reset in the Tools > Choose Activities dialog, the added library remains in the Activities tab.

Hide the activity library from the Activities tab, but include it in the Choose Activities dialog (with each activity unselected). Alternatively, hide the activity library from the Activities tab and the Choose Activities dialog.

The following exercise shows how set those policies. 1. Open the Choose Activities dialog so you can reference it during this exercise: a. In Workflow Studio, select any workflow and click Edit to open the Workflow Studio Designer. b. In the Designer window, choose Tools > Choose Activities. 2. Install an activity library in the GAC. The Microsoft Support site includes detailed instructions for this task. Activity libraries are available for download from the Citrix Developer Network. 3. In a PowerShell console, enter the following command to add the library to the Activities tree for all users who log in to your computer:

Add-ActivityLibraryToTree -AllUsers -ExcludedClass 'NetScalerActivityBase' -strongname 'Citrix.WorkflowS

G

The AllUsers parameter determines whether the activity library is added to user.config or WFS.config: If the AllUsers parameter is The activity library is added to

189

To add an activity library to the Activities tab Omitted C:\Documents and Settings\user\Local Settings\Application Data\Citrix\Workflow Studio\WorkflowStudio\version\user.config for the current user only If a different user logs on to the same computer, that activity library is hidden from that user. If the current user resets the Choose Activities dialog, the added library is removed from the Activities tab but remains in the Choose Activities dialog. Specified C:\Documents and Settings\All Users\Application Data\Citrix\Workflow Studio\WorkflowStudio\version\WFS.config All users who log on to that computer see the added activity library. If a user resets the Choose Activities dialog, the added library remains in the Activities tab. The Citrix activity library installers use the AllUsers parameter. The ExcludedClass parameter enables you to hide specified classes in your binary from the Activities tab and from the Choose Activities dialog. The StrongName parameter installs activity libraries that are in the Global Assembly Cache (GAC).

4. Close the Workflow Studio Designer window and reopen it to refresh the tree in the Activities tab. The activity library you added is now included in the Activities tab tree. In the Choose Activities dialog, each activity is selected. 5. To hide the activity library from the Activities tab, but include it in the Choose Activities dialog (with each activity unselected), enter this command: Add-ActivityLibraryToTree CustomLibrary.dll -HideClass 6. Close the Workflow Studio Designer window and reopen it to refresh the tree in the Activities tab. The activity library is now removed from the Activities tab. In the Choose Activities dialog, the libraries activities are listed but are unchecked. Related Information Adding/Removing Activity Libraries using an Installer

190

Versioning Activity Libraries

Before you add an activity library to Workflow Studio, we recommend that you install the activity library in the Global Assembly Cache (GAC) so that you can support multiple versions of the libraries. The GAC manages multiple versions of assemblies, which is essential when an activity library changes to the extent that workflows built on the previous version of the activity library will no longer run. All Citrix activity libraries are installed in the GAC. If you are building activity libraries for your own use (perhaps for testing) and know you will not need to manage versioning of the library, you can just add the activity library to Workflow Studio. In that case, you copy it to %PROGRAMFILES%\Citrix\Workflow Studio and then use the Add-ActivityLibraryToTree cmdlet, referencing the activity library by file name. Workflow Studio does not support multiple versions of an activity library that is deployed to the file system in this manner. The best practice is to install your activity libraries in the GAC so that the GAC can handle the versioning for you when an update requires a new assembly version. The type of updates to an activity library determines whether the update requires a new file version or a new assembly version, as follows.
G

Changes requiring a new file version (the assembly version does not need to be incremented):
G

Non-required properties added to existing activities. Activities added to a library.

Changes to the code or existing properties that do not modify the default behavior or data types of the activity. With such changes, users can seamlessly upgrade to the changed activity without modifying their existing workflows. Any workflows use that library will begin seamlessly using the new version after the activity library binary is overwritten and the runtime is restarted.
G G

Changes requiring a new assembly version: Changes to the existing properties or execution logic that will not allow existing workflows built on the activity to continue to run. For example: Changes to the data type of a property, changes to the required properties of an activity, or changes to the behavior of an activity. With these changes, a new version of the activity needs to be deployed and workflows will need to be updated to explicitly use this new activity. To deploy this type of activity, you increment the assembly version, install it in the GAC, and add it to Workflow Studio using the Add-ActivityLibraryToTree cmdlet with the StrongName parameter.
G

You can have multiple versions of an activity installed and available for use. To support that, you must modify the namespace used internally in the activity library to ensure that each version can co-exist in the same workflow. The GAC manages the multiple versions of your binary automatically based on changes to the assembly version.

191

Versioning Activity Libraries Related Information Adding/Removing Activity Libraries using an Installer

192