Workflow Studio 2.

5
Citrix eDocs

© 2011 Citrix Systems, Inc. All rights reserved. Terms of Use | Trademarks | Privacy Statement
Contents

Workflow Studio 2.5 6

About This Release 7
Introduction 9
About Citrix Workflow Studio 10
Source Components of Workflow Studio 12
About Activity Libraries 13
To access the Citrix Developer Network 14
About Workflows and Jobs 15
Management Interface for Workflows and Jobs 16
General Steps for Using Imported Workflows 17
Workflow Source Files 18
About the Database 19
About the Security Role Store 20
Known Issues 21
System Requirements 26
Supported Systems and Products 27
Install and Set Up 28
To install Workflow Studio 29
To configure Workflow Studio 32
To install activity libraries 34
To add a workflow runtime 35
To uninstall Workflow Studio or activity libraries 36
To start Workflow Studio 37
Get Started with Workflow Studio 38
Starting Workflow Studio 39
Importing the Sample Workflow 40
Testing the ExportServices Workflow 42
Creating and Scheduling a Job 43
Get Started with Workflow Studio Designer 45

2
 About the Sample Workflow 46
Starting Workflow Studio Designer 48
Creating a Category and Workflow 49
Adding Activities to a Workflow 51
Renaming Activities 54
Creating a Global Property 56
Configuring Activity Properties 57
Binding to a Global Property 59
Testing the Workflow 62
Manage 63
To create a workflow category 64
To manage categories 65
To view and filter workflow projects 66
To import a workflow 67
To export a workflow 68
To test a workflow 69
To specify a server for running jobs 70
To create a job 71
To view job details and event history 73
To view workflow details for a job instance 74
To change job properties 75
To manage jobs 76
To clear job history for a runtime 77
Customize 78
Planning and Starting a Workflow 80
Editing and Deleting Workflows 81
Changing Your View of the Designer Window 82
Working with Activities 86
Customizing the Activities Tab 87
Adding Activities to a Workflow 89
Adding a Branch to a Parallel Activity 91
Creating a Global Property 92
Binding Activity Properties 93
Starting a Workflow from Another Workflow 94
Creating and Working with Snippets 95
Creating an Activity without Writing Code 97
Using the Delay Activity to Persist a Workflow 98

3
 Adding Custom Code to a Workflow 99
Adding a Missing Component 100
Securing Workflows that Contain Password Values 101
Working with Fault Handlers 103
Secure 104
About Security Roles 105
About Security Permissions 108
Working with Security Roles 115
Securing Workflow Categories and Jobs 117
Workflow Studio Development 118
Developing Activity Libraries 119
Preparing for Activity Library Development 120
Activity Library Development Overview 121
Citrix Tools and Templates 123
Activity Library Design Considerations 124
Installation and Setup 126
To add assembly references 127
To install the converter and templates 128
To uninstall the DLL and templates 129
Converting PowerShell Snap-ins to Activity Libraries 130
To create an activity library project and convert an activity 131
Reviewing and Editing the Generated Code 133
To add references to the snap-in binary 134
To review activity attributes 135
To edit the input/output base classes 137
To edit the dependency properties 138
To review the project properties 139
To test the activity in Workflow Studio 140
To test an activity library that changed after installation 142
Creating Activities from Citrix Templates 143
To create an activity library project from a template 144
To add an activity to the project 145
Editing the Code Generated from a Template 146
To change the activity attributes 147
To define the default value for the delay activity 148
To correct the dependency properties 149
To add to the exception handling 150

4
 To edit validation logic 151
To test the standard activity in a workflow 152
Best Practices 153
Reference the snap-in binary 154
To add references to the snap-in binary 155
Change optional integer properties 156
Use strong names for activity libraries 158
To review the project properties 159
Add custom activity icons and reference them 160
To add and reference icons 161
Determine if any overrides are needed 162
Review validation logic 163
Other Considerations 164
Activity Attribute Reference 166
General Activity Attributes 167
PowerShell-Specific Activity Attributes 170
Dependency Property Attributes 172
PowerShell-Specific Property Attribute 175
Automating Workflow Studio with PowerShell 176
Getting Started 177
About Workflow Studio Automation 178
About Workflow Studio Snap-Ins 179
To add Workflow Studio snap-ins to a PowerShell console 180
Deploying, Running, and Managing Workflows 182
To download a workflow to your computer 183
To import a workflow into your Workflow Studio data store 184
To deploy a workflow (create a job) 186
To run a workflow and view its deployment history 187
Adding/Removing Activity Libraries using an Installer 188
To add an activity library to the Activities tab 189
Versioning Activity Libraries 191

5
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 Review conceptual information about Workflow Studio

About Workflow Studio Release Read about new features
2.5
System Requirements Read about system requirements and supported
systems
Known Issues for Workflow Get information about known issues
Studio 2.5
Installing and Configuring Install, configure, and run Workflow Studio
Workflow Studio
Getting Started with Workflow Follow this guided tutorial to learn the basics about
Studio importing, testing, and scheduling workflows
Getting Started with Workflow Follow this guided tutorial to learn the basics about
Studio Designer creating a workflow.
Creating and Managing Jobs Create, manage, and view Workflow Studio categories,
projects, and jobs
Creating and Editing Workflows Create and edit workflows
Securing Operations and Data Secure runtimes, workflows, and jobs
Workflow Studio Development Learn about creating custom activity librarires and
using PowerShell for automation

6
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

● 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

● 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

7
About This Release

● 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

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

8
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 Read about the types of automation provided by
Workflow Studio
Source Components of Read about the components on which Workflow Studio
Workflow Studio is built and extends
About Activity Libraries Read about activity libraries, the building blocks of
workflows
To access the Citrix Developer Access a wealth of information and tools on the Citrix
Network Developer Network
About Workflows and Jobs Get conceptual information on workflows and jobs
About the Database 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.

9
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:

● 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:

● 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

● 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:

● 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:

● 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:

● 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:

● Change a job’s 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:

● 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
● 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

● 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:

● 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

● 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:

● 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.

● 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.

● 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:

● 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:

● 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:

● 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:

● 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:

● 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:

● 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 Install Workflow Studio or a runtime

To configure Workflow Studio Configure Workflow Studio
To install activity libraries Install activity libraries
To add a workflow runtime Add a workflow runtime
To uninstall Workflow Studio or Uninstall components
activity libraries
To start Workflow Studio 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.

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

● 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

● 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:

● 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:

● 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 Description
Workflow After you enter the Server and Database and click Connect, the
Database 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.)
TCP Port Sharing If you do not enable TCP Port Sharing, you cannot create
workflow runtimes.
Workflow This page is available only if TCP port sharing is enabled.
Runtimes
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.

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.
Firewall 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.

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:

● 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:

● 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:

● 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.

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:

● 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:

● 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.

● 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:

● 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.

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:

● 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 Create categories to contain related workflows

To manage categories Move a workflow between categories; delete a
workflow or category
To view and filter workflow Change your view of workflow projects
projects
To import a workflow Import a workflow
To export a workflow Export a workflow to share it with others
To test a workflow Test a workflow in Workflow Studio Designer
To specify a server for running Add the servers to which you will deploy jobs
jobs
To create a job Create a job to deploy and/or schedule a workflow
To view job details and event View jobs and their history
history
To view workflow details for a View workflow details in the Job Inspection window
job instance
To manage jobs Enable/disable jobs, change your view of the jobs
table, delete a job, and view deleted jobs
To change job properties Change a job's schedule, runtime, or parameters
To clear job history for a Remove all job history for a runtime
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

● 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

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

To group the workflow projects table

● 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:

● 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:

● 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:

● 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.

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:

● 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.

● 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.

● 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 window’s 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:

● For deployed jobs:

● 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:

● 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:

● 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:

● 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

● 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 Plan and begin creating a workflow.

Workflow
Editing and Deleting Workflows Access a list of workflow projects from which you can
delete a workflow or open the Workflow Studio
Designer to edit a workflow
Changing Your View of the Close and open panes, change the view of the design
Designer Window 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
Customizing the Activities Tab 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
Adding Activities to a Workflow Add activities to the design surface, review items to
verify after adding an activity, review notes related to
using parallel and sequence activities
Adding a Branch to a Parallel Add a branch to a parallel activity and reorder parallel
Activity activity branches
Creating a Global Property Create a global property that can be used in muliple
activities
Binding Activity Properties Read about the concept of activity binding and how
Workflow Studio handles binding
Starting a Workflow from Use the Start-Workflow activity to start another
Another Workflow workflow from the current one
Creating and Working with Save an activity as a snippet, add a snippet to a
Snippets workflow, and delete, share, and import snippets
Creating an Activity without Expand the activity library by creating an activity
Writing Code based on another activity such as PowerShell Script,
Windows Script, Command Script, and SNMP activities.
Using the Delay Activity to Add a persistence checkpoint to a workflow.
Persist a Workflow
Adding Custom Code to a Edit the automatically generated source code (the
Workflow code-beside file)
Adding a Missing Component Add a reference to a missing component
Securing Workflows that Read about the supported encryption methods, obtain
Contain Password Values and install certificates, choose a certificate for a
workflow, and view the certificate associated with a
workflow

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:

● 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.

● 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

● 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.

● 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:

●

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:

● 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.

● 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.

● 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
Developer’s Guide.

To customize the Activities tab

● 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

● 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

● 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:

● 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.

● 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.

● 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:

● 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

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

To reorder parallel activity branches

● 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

● Drag the snippet from the Activities tab to the workflow.

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

95
Creating and Working with Snippets

To share snippets
● 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
● 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.

● 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:

● 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

● 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:

● 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 Read about the security roles that apply to servers and
runtimes
About Security Permissions Read about the security permissions that apply to
workflow categories and jobs
Working with Security Roles View, assign, and remove security roles
Securing Workflow Categories Change security permissions on categories or jobs
and 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 Description
Perform all job This role provides access to all workflow and security operations on
and security a runtime (that is, all operations listed for the other roles). Only the
operations person who installed Workflow Studio is automatically added to this
role.
Deploy, schedule, This role provides access to the following operations on a runtime:
and start jobs
● Deploy workflows

● Start workflows

● View workflows, deployed jobs, and their history

● View runtimes

● Get and clear workflow output

● Update runtime logs

Resume job This role provides access to the following operations on a runtime:
instances
● 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:

● View workflows

● View runtimes

● Stop workflows

● Update runtime logs

Suspend job This role provides access to the following operations on a runtime:
instances
● View workflows

● View runtimes

● Suspend workflows

● Update runtime logs

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

● View workflows, deployed jobs, and their history

● View runtimes

● Access the running workflow count

● Update runtime logs

View security role This role provides access to the following operations on a runtime:
memberships
● View security roles and security role assignments

● View runtimes

● Update runtime logs

Modify security This role provides access to the following operations on a runtime:
role memberships
● 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:

● Deploy workflows

● View deployed jobs and their history

● View runtimes

● Remove workflows

● Update runtime logs

view the currently deployed jobs

Start deployed This role provides access to the following operations on a runtime:
jobs
● 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 This role provides access to the following operations on a runtime:
deployed jobs
through Task ● View runtimes
Scheduler
● 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:

● 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 job’s 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 Description
Full Control Contains the following summary permissions:

● 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 Contains the following summary permissions:
Admin
● Workflow Admin

● Jobs Admin

108
About Security Permissions

Jobs Admin Contains the following summary and explicit permissions:

● Start Workflow

● Pause Jobs

● Resume Jobs

● Stop Jobs

● View Jobs
Workflow Admin Contains the following explicit permissions:

● View Workflow

● Create Workflow

● Edit Workflow

● Delete Workflow

● Test Workflow

● Edit Category
Start Workflow Contains the following explicit permissions:

● View Workflow

● Test Workflow

● Deploy Workflow

● Schedule Workflow
Permissions Admin Contains the following explicit permissions:

● Move Workflow

● Read Permissions

● Change Permissions
View Workflow Grants access to the following functions:

● List of workflows in the Workflows tab.

● Display of the workflow in the Designer.

Grants access to the following cmdlet:

● Export-Project

109
About Security Permissions

Create Workflow Grants access to the following functions:

● 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:

● 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:

● 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:

● Copy-Project

● Set-ProjectStatus (granted by Create Workflow or Edit

Workflow)
Delete Workflow Grants access to the following functions:

● 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:

● Remove-Project (This cmdlet returns partial results based

on permissions.)

110
About Security Permissions

Edit Category Grants access to the following functions:

● 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:

● 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:

● The Start command in the Designer.

Deploy Workflow Grants access to the following functions:

● 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:

● 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:

● 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:

● 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:

● The Pause command in the Jobs tab.

Grants access to the following cmdlet:

● Suspend-Workflow
Resume Jobs Grants access to the following function:

● The Resume command in the Jobs tab.

Grants access to the following cmdlet:

● Resume-Workflow
Stop Jobs Grants access to the following function:

● The Stop command in the Jobs tab.

Grants access to the following cmdlet:

● Stop-Workflow

112
About Security Permissions

View Jobs Grants access to the following functions:

● The display of a job in the Jobs tab.

● The Open command in the Jobs tab.

Grants access to the following cmdlet:

● Get-DeployedWorkflow

● Get-ScheduledWorkflow

● Get-Workflow

Each of those cmdlets return partial results based on

permissions.
Move Workflow Grants access to the following function:

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

Grants access to the following cmdlet:

● 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:

● The View Security command in the Workflows tab.

● The View Security command in the Jobs tab.

Change Permissions Grants access to the following functions:

● The Edit Security command in the Workflows tab.

● The Edit Security command in the Jobs tab.

Grants access to the following cmdlet:

● 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

● 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:

● 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)

● Permissions on the ITDev group: Workflow Admin

● Permissions on the HR group: Jobs Admin

● 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:

● 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.

● 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 Create custom activity libraries using Citrix tools and
templates which simplify the development process
Automating Workflow Studio Use PowerShell snap-ins to automate the functionality
with PowerShell 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 Learn about activity library uses and development,
Development activity library design considerations, and how to
install tools and templates
Converting PowerShell Snap-ins Develop an activity library from a PowerShell snap-in
to Activity Libraries by using the Citrix PowerShell Converter
Creating Activities from Citrix Develop an activity library by using the Citrix Standard
Templates Activity template for Visual Studio
Best Practices Review best practices for developing activity libraries
Activity Attribute Reference 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:

● 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.

● 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.

● 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:

● 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:

● ItemTemplates\Visual C#\Citrix Workflow Studio\

● 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 Provides
Common
● 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.
CustomActivityDesigner
● Support for the customized theme in the Workflow
Studio Designer.
CustomActivityPropertyEditor
● Custom file browser, folder browser, text editor,
and custom binding dialog support.
CustomActivitySerializers
● Helper objects to make PowerShell serializable.
User
● Base classes you can derive from when building
activities to simplify access to PowerShell and WMI.

● Native tools to support development of UI

activities.

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 Description

Designer 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.
DisplayNameAttribute The name that appears for the activity in the Workflow
Studio Designer.
Description Help text that appears in the Workflow Studio Designer
under the Activity list when this activity is selected.
ActivityTreePath Specifies where the activity appears in the Activity list in
Workflow Studio Designer.
ActivityValidator Defines the class responsible for the activity’s validation
logic. That validator class appears at the end of generated
code.
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

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

General Activity Attributes

PowerShell-Specific Activity Attributes

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 Description
DisplayName Specifies the name to appear for the property in the
property grid.
Description Contains the help text that appears below the property
grid when the property is selected.
Category Determines under which group in the property grid the
property will appear.
Browsable Specifies whether the property will appear in the property
grid or in the MS binding dialog box.
Specifies which part of a property should be serialized by
DesignerSerializationVisibility
the Workflow Studio Designer.
EditorAttribute Specifies which property editors, if any, are associated
with this property.
CTXPSParameterInfo Allows you to map activity properties to PowerShell
parameters.
Related Information

Dependency Property Attributes

Change optional integer properties

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:

● IntegerPropProperty to DelayTimePropProperty

● IntegerProp to DelayTimeProp
That code line should look like this:

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:

● 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:

● 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.

● 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:

● 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… Connect Visual Studio to this Which is the…

process…
Validation logic (which wfs.exe Workflow Studio
runs at design time, Designer process
such as when you
specify a property)
Execution logic (for a WorkflowExpressRuntime.exe Process used to run
workflow run when you workflows from the
click Start in the Designer
Workflow Studio
Designer)
Execution logic (for a WorkflowRuntimeHostService.exe Service that Workflow
deployed workflow or Studio uses to run jobs
job)

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.

● 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:

● 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 activity’s 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
designer determines the appearance of the activity on the desi
surface, such as its background color, selected glow, font, and
position. BaseActivityDesigner is the Citrix-provided des
which renders an activity as follows.

[DisplayNameAttribute(@"name")]
Specifies the name of an activity. This is the name that appear
Activities tree and on the activity when it is on the design surf
spaces in this name are replaced with underscore characters w
activity is dropped on the design surface.
[Description(@"text")]
Provides a brief text description of the activity. This text appe
below the Activities tree in the Workflow Studio Designer when
activity is selected in the tree. Typically, this text is a short, h
overview of 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
activity. Each activity typically has a dedicated validator class.
create an activity using the Citrix activity template, the valida
resides at 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
icon/image used with this attribute is the same as the one use
ToolboxBitmapAttribute. This image must be a 32x32 PNG
file.

ImageResourceName BackColor TextFontFam

ShineColor MaskColor TextFontSize
GlowColor TextForeColor Width
GlowIntensity ShapeRadius Height

[ToolboxBitmapAttribute(typeof(ActivityName), @"name.png")]
Specifies the 16x16 image file to use as the icon for the activit
Activities tree. The image must be a PNG file. Typically the ap
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
references an assembly, that referenced assembly will be adde
reference to the workflow project. However, sometimes an ass
not referenced to an activity and therefore needs to be specifi
this attribute. This informs the Workflow Studio Designer to ma
add the specified assembly as a reference to the workflow pro

ActivityReferenceAssembliesAttribute takes one par

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=ne
PublicKeyToken=3509c8c16f49bbe9" })]

In the process of handling this attribute to create a project ref

call to Assembly.ReflectionOnlyLoad() is made, assumi
the string is the assembly FullName. The ReflectionOnlyLo
call is very forgiving in that it will accept just the assembly na
assembly name and version, and so on. Therefore, if you provid
the 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
of the XenDotNetLibrary assembly in the future, that string mu
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
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 OpenFileEditor
DropDownList OpenFolderEditor
DSComputerPicker PasswordEditor
DSGroupPathPicker PropertyColumnEditor
DSObjectPathPicker TextEditor
DSOUPicker TrusteeEditor
NamedCollectionEditor
Following are the data types that can be used with other editors:

EditorHelper StringEdit
FileWithConstructor StringWithConstructor
FolderWithConstructor VariableEdit
Notes:

● 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)]

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:

● 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

● 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 Long String

BoolString NonEmptyString StringList
Dictionary Object Switch
Enumeration Password UInt
Guid PSCredential UInt32
Int PSObject ULong
Int32 PSObjectArray Unknown
IntList

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
Deploying, Running, and Deploy, run, and manage workflows using PowerShell
Managing Workflows
Adding/Removing Activity Add an activity library to the Workflow Studio
Libraries using an Installer Activities tab

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.

● 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:

● Microsoft .NET Framework 3.5

● Windows PowerShell 2.0

● Citrix Workflow Studio

Citrix provides the following snap-ins:

● 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:

● 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:

● 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

● The AllUsers parameter determines whether the activity library is added to

user.config or WFS.config:

If the AllUsers The activity library is added to…

parameter
is…

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.

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

● 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.

● 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.

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