cloudportal services manager -...
TRANSCRIPT
CloudPortal Services Manager
Developer’s Guide to the Services Manager SDK
www.citrix.com
2
©2012 Citrix Systems, Inc. All rights reserved. Citrix®, NetScaler®, Access Gateway™, Branch
Repeater™, XenApp™, XenDesktop®, XenServer®, and HDX™ are trademarks or registered
trademarks of Citrix Systems, Inc. and/or one or more of its subsidiaries, and may be registered in
the U.S. Patent and Trademark Office and in other countries. Xen® is a trademark of Citrix Systems,
Inc. managed on behalf of Xen.org, and may be registered in the U.S. Patent and Trademark Office
and in other countries. All other trademarks and registered trademarks are property of their
respective owners.
This document is furnished "AS IS." Citrix Systems, Inc. disclaims all warranties regarding the
contents of this document, including, but not limited to, implied warranties of merchantability and
fitness for any particular purpose. This document may contain technical or other inaccuracies or
typographical errors. Citrix Systems, Inc. reserves the right to revise the information in this
document at any time without notice. This document and the software described in this document
constitute confidential information of Citrix Systems, Inc. and its licensors, and are furnished under a
license from Citrix Systems, Inc.
3
Contents Introduction ............................................................................................................................................ 5
Components ............................................................................................................................................ 5
Components Overview........................................................................................................................ 5
Locations ......................................................................................................................................... 5
Web Server ...................................................................................................................................... 6
Database ......................................................................................................................................... 6
Provisioning Engine ......................................................................................................................... 6
Service Web Services ...................................................................................................................... 6
Services ................................................................................................................................................... 7
Service Overview ................................................................................................................................. 7
Service Properties ............................................................................................................................... 7
Customer Only Services ...................................................................................................................... 7
Multiple Service Instance .................................................................................................................... 8
Customer Plans ................................................................................................................................... 9
User Plans............................................................................................................................................ 9
Single User Plans ............................................................................................................................. 9
Multiple User Plans ......................................................................................................................... 9
Adding User Plan Properties ........................................................................................................... 9
User Plans and the Active Directory ............................................................................................... 9
Provisioning ........................................................................................................................................... 11
Provisioning Requests ....................................................................................................................... 12
Provisioning Server ........................................................................................................................... 12
Provisioning Engine ........................................................................................................................... 12
Queues .............................................................................................................................................. 12
Primary queue ............................................................................................................................... 13
Bulk request queue ....................................................................................................................... 13
Usage data queue ......................................................................................................................... 13
Response queue ............................................................................................................................ 13
Worker queues .............................................................................................................................. 13
Provisioning request sequence ......................................................................................................... 13
1. Create a Provisioning Request and add properties .............................................................. 14
2. Pre-process the request ........................................................................................................ 16
3. Send the request ................................................................................................................... 16
4
4. Process the request with the rules ....................................................................................... 18
5. Post-process the request ...................................................................................................... 19
Bulk requests ..................................................................................................................................... 19
Rules .................................................................................................................................................. 20
Condition ....................................................................................................................................... 20
Action ............................................................................................................................................ 20
Events Rules ...................................................................................................................................... 20
Event Types ................................................................................................................................... 20
Event Objects ................................................................................................................................ 20
Logging .............................................................................................................................................. 21
Service Development ............................................................................................................................ 21
Creating, Enabling and Provisioning a New Service .......................................................................... 22
Overview ....................................................................................................................................... 22
Service Hierarchy .......................................................................................................................... 22
Access the service management screen ....................................................................................... 22
Create a service ............................................................................................................................. 22
Enabling the Service for a Location ............................................................................................... 24
Enabling the Service for a Reseller customer ............................................................................... 25
Provision a customer with a service ............................................................................................. 26
Provision a user with a service ...................................................................................................... 29
Custom Provisioning Actions ............................................................................................................ 30
Properties Context ........................................................................................................................ 30
Parameter Expansion .................................................................................................................... 30
Errors ............................................................................................................................................. 31
Sample Actions .............................................................................................................................. 31
Provisioning Manager ....................................................................................................................... 32
Rules .............................................................................................................................................. 32
Actions .......................................................................................................................................... 46
Queues .......................................................................................................................................... 49
Conclusion ............................................................................................................................................. 52
5
Introduction This document provides details of the terminology and topology of the Citrix CloudPortal Services
Manager (SM) version 10.0. It is a general guide targeted at developers with experience with
Microsoft’s .NET. Companion videos are available that provide walkthrough tutorials extending the
SM.
Components
Components Overview The CloudPortal Services Manager (SM) consists of a Web Server, a Database, a Provisioning Engine
and a number of Web Services. The Web Server provides a user interface and API access. The
Database contains the configuration of all Customers, Users and Services. And the Provisioning
Engine performs the actual configuration process.
Location
Web User
API UserWeb Server
Database
DomainController
ProvisioningEngine
DirectoryWeb Service
ServiceWeb Services
Service InfrastructureServers
Locations
A location represents an Active Directory Forest. All of the infrastructure required to provide a
service is in the location. The SM supports more than one location.
There is always a primary location which is in the same environment as the Web Server.
6
Web Server
The Web Server manages Customers, Users and Services entities that are stored in the Database. It
provides both a UI and an API. When a change is made to one of these entities a provisioning
request is sent to the Provisioning Engine. The Web Server can also query a service’s state using web
services specific to each service.
Users interact with the Web Server UI with a web browser using HTML over HTTP/HTTPS. The Web
Server API is accessed using XML over HTTP/HTTPS.
Database
The Database contains all configuration information. Changes to services done outside of the SM will
be overridden by the Database configuration. As well as service configuration it contains Customer
and User details. User passwords are not stored in the Database.
The Database should not be accessed directly. The Application Objects and Data Access Layer should
be used to query and make changes to the Database.
Provisioning Engine
The Provisioning Engine processes requests by executing a series of rules that determine how the
provisioning request is performed. The rules are a recipe for the provisioning process and are a
series of “if condition then do action” statements. There are a large number of built-in actions and
each service can have their own specific actions.
The Web Server sends requests to the Provisioning Engine using Microsoft’s Message Queue
(MSMQ). The request is a binary serialized Hashtable.
Service Web Services
Services can have their own web service that is used both by the Web Server to query service
specific status information and by service specific provisioning actions. The methods available for
these web services depend on the requirements of that service. However, normally there is a ping
method that the Web Server uses to check connectivity.
7
Services
Service Overview Service properties describe a service. Services are configured in a layered way. At the top level are
“Top Environment Services”. Properties set here are defaults values for the service system wide.
Then for each location there are “Active Directory Location Services”. These property values are the
defaults for each location. Next down are each of the “Customer Reseller Services” where Resellers
can override values specific to their on-sold services. And at the bottom is the Customer and User
Service properties.
They can be set at various levels with the higher levels forming a default. The same set of services
properties are at all levels. However the property value may not be set.
Services have several settings that affect how the service is used. The Customer Only Service setting
stops users from being able to provision the service. The Multiple Service Instance setting allows
more than one service of this type to be provisioned at the same time.
Plans are groups of properties that are selected by name when configuring a service. They are used
to define a level of service, for example Bronze, Silver and Gold by. They can also simplify the billing
process since they represent sets of billable features described by the properties.
When a Provisioning Request is sent to the Provisioning Engine the service properties are resolved.
Service Properties Service Properties are named values in a hierarchy of inherited properties. To retrieve a property
value the hierarchy is traversed from the bottom level up. If there is no value at the current level a
default value from the level above is found.
The hierarchy is:
Top Environment Services
Active Directory Location Services
Customer Reseller Services
Customer Services
User Services
Customer Only Services The concept of a customer specific service denotes that the service only applies to a customer and is
not applicable to users. For example, the DNS service only applies to a customer. When the DNS
service is provisioned to the customer, we provision Zones and DNS records for the customer. We
cannot assign or provision the DNS service to a user, because DNS Zones and records do not apply
on a user-to-user basis. Instead, we use the concept of administrator roles, which means a user can
be granted access to the "DNS Service Administrator" role providing the user with privileges to
manage DNS records for the customer.
Customer specific services can be defined on the "Service Schema" screen as seen in the UI:
8
Multiple Service Instance Most services are single instance based. For example, a user can only have one Hosted Exchange
mailbox. When Hosted Exchange is provisioned to the user, we add a mailbox to the user's Active
Directory account.
There are also services that are hosted where it is possible for the customer to have more than one
instance of. Examples are SharePoint sites, Web Hosting, SQL Server Databases. For these services
the customer can create Instances. Effectively, a user can belong to one or many SharePoint sites.
In the interface you can see which services have instances and which do not, as seen in the UI:
9
The SharePoint Service is an example of a service that can be instanced. The star before the Service
name indicates that this is a service that can be instanced.
For both the service instances and the other services the gum ball icons represent the provisioning
status.
Customer Plans A Customer Plan was previously called a Package Template.
User Plans A User Plan was previously called a Service Access Level (SAL).
Single User Plans
A regular setup does not allow multiple User Plans. Only one User Plan can be assigned to a user for
the service.
For example, a mailbox service can have multiple service access levels such as Gold, Silver and
Bronze. Each User Plan can also contain a set of properties such as an inbox limit, whether anti-
spam is enabled and a list of protocols such as MAPI, IMAP and POP. In the example, the Gold User
Plan could be configured with an inbox limit of 2GB with anti-spam enabled and MAPI access. The
Bronze User Plan could be configured with an inbox limit of 500MB with anti-spam disabled and only
POP access.
In this sort of service it makes sense that the user can only have one User Plan for the service. For
example, the user cannot have the Gold User Plan with anti-spam enabled and the Bronze User Plan
where anti-spam is disabled.
Multiple User Plans
Less common is a service that allows multiple User Plans to be assigned to a user.
One example may be a fictitious Application Server service could make use of User Plans to define
application access. One User Plan could be called "Office Applications" and another "Graphic Design
Tools". Therefore, a user can be assigned to both User Plans in order to gain access to both
application groups.
A service can be configured to use multiple User Plans on the "Service Deployment" screen. Once
the service is expanded, click on "Service Settings", change the Category drop-down-list to "Schema
Settings" and enable the "Multiple User Access Levels" property.
Adding User Plan Properties
User Plan properties can only be managed on the "Configuration->System Manager->Services
Schema" screen. Once your service is expanded, the service management frame will appear as
displayed in the image below click on the "Property Definitions.
User Plans and the Active Directory
Each User Plan also creates a back-end AD group that can be used for granting AD privileges. An
extra “None” group is created for users who aren’t in an assigned User Plan.
10
For example, consider the File Sharing Service (FSS). The FSS may have User Plans such as Full, List,
and Read. After the service is provisioned, the User Plan groups will automatically appear in AD as
seen in Active Directory Users and Computers:
When a customer is provisioned with the File Sharing Service, each User Plan assigned to the
customer will be added to the customer's OU. The pattern is "ServiceName CustomerShortCode
SAL". As displayed in the image below for a customer with the short code of "CRC" provisioned with
the File Sharing Service. The group "FSS CRC READ" represent the customer's group for the File
Share Service (FSS) with READ access.
Each of the customer's group User Plans are automatically member of the root service's User Plan
Groups. Take the "FSS READ" group for example. This allows us to assign unique permission to the
"FSS READ" group which would apply to all members of the group. And hence all the associated
users that have that that User Plan assigned.
11
When a user is provisioned the FSS "READ" User Plan, they will become a member of the customer's
FSS READ group as seen in Active Directory Users and Computers:
Provisioning The Web UI allows management of customers, users and service related configuration in the
Database. To actually update the real customers, users and services it sends a Provisioning Request.
The Provisioning Request is queued for processing on the Provisioning Server. The Provisioning
Engine that run on the Provisioning Server retrieves requests from the Provisioning Queue and
executes a series of Provisioning Rules to satisfy the request. Once the Provisioning Rules have
completed it updates the customer, user or service to a successful or failed status.
Provisioning is the process of making the real world configuration match the desired configuration
stored in the Database.
To provide separation of the management system from the service system Provisioning is handled by
sending a Provisioning Request message to a MSMQ Queue. The Provisioning Engine on the
Provisioning Server listens to the queue and performs rules when a new request arrives.
Rather than fix the configuration process in compiled code and provide a limited set of options, a set
of Rules are performed at various stages of the Provisioning Sequence.
These Rules are optionally logged for both success and failed actions.
12
Provisioning Requests A Provisioning Request contains a collection of properties (named values) stored in a hashtable. This
is the context required to perform the Provisioning Rules with properties such as the Customer's
name and the Service properties. The request properties are different depending on the request
type. There’s a variety of provisioning request types, for example...
Customer requests:
• Provision a Customer
• De-provision a Customer
• Provisioning a Service to a Customer
• De-provision a Service from a Customer
User requests:
• Provision a User
• De-provision a User
• Provisioning a Service to a User
• De-provision a Service from a User
Provisioning Server The Provisioning Server performs the provisioning process. It has a multiple Queues and runs the Provisioning Engine service.
Provisioning Engine
The Provisioning Engine is a rules system. It retrieves requests from the Queue and processes a sequence of rules. The Rules are processed in order until either a rule fails or all the rules are complete.
Queues The Provisioning Request is serialized and sent using Microsoft Messaging Queue to the Provisioning
Server. The Message label is the Request type and the body contains the Request properties.
The queues are defined each location, as viewed in the UI:
13
Primary queue
Most requests get sent to the primary queue
Bulk request queue
Slower requests may be sent to the bulk request queue
Usage data queue
Usage data is collected through the usage queue path.
Requests should not be sent directly to this queue as it for internal use only.
Response queue
If the Provisioning Engine has connectivity to the database then this can be blank. If not then this is
queue is used internally used to send back database update for such things as Logging, Auditing, and
Status updates.
Requests should not be sent directly to this queue as it for internal use only.
Worker queues
Each of the queues may have one or more associated worker queues. There will be one worker for
each thread assigned to the queue.
Requests should not be sent directly to these queues as it for internal use only.
Provisioning request sequence These following steps are performed when requested by the Web Server UI or API:
14
1) Create a provisioning Request and add properties
2) Pre-process the request
3) Send the request
4) Process the request
5) Post-process the request
Step Runs where? Performed by?
1 Web Server Code
2 Web Server Rules
3 Web Server Rules
4 Location’s Provisioning Engine Rules
5 Primary Provisioning Engine Rules
Rules in running in the Locations Provisioning Engine assume they have no access to the database
and all the context they require is in the provisioning request.
1. Create a Provisioning Request and add properties
Create a provisioning Request object. It has properties that will be used by the Provisioning Engine
to perform whatever task is required. The information needed for a particular provisioning Request
depends on the entity that is being provisioned and (particularly for the different services) the
Properties that have been configured.
For example if you’re creating a user then the user’s name, password and email address are
properties that are set in the request, as viewed in the UI:
15
Which would generate a message like this, as viewed in the Provisioning Manager:
16
2. Pre-process the request
The Request’s Send method does send the request directly. It hands the request off to the Pre-
Request rules.
Before the provisioning Request is sent to the Provisioning Engine, the Pre-Request rules are run.
This happens on the Web Server (in the context of the IIS Service on this server).
The Provisioning Rules are loaded (from the Database) when the Web Server is started and are kept
in the IIS Application Cache.
The intention of these rules is to allow for any configuration of the provisioning Request that needs
to be done before the provisioning Request is sent to the Provisioning Engine where the Provisioning
Actions are run. These Pre-Request Rules are run on the Web Server so that they have access to the
Database and also all the SM Application Objects and Data Access Layer.
3. Send the request
At the end of the Pre-Request rules the request is binary serialized and sent using MSMQ to the
Provisioning Engine queue in the target Location.
The Web Server sends the request to the Microsoft Message Queue (MSMQ) on the Provisioning
Engine specified in the Request. The path to the MSMQ that it will send the Provisioning Request
can be seen in the RequestQueue property define in the Location, as viewed in the UI:
17
The connection method depends on the value of the name:
If the Path is something like:
FormatName:DIRECT=http://ProvisioningServer/msmq/.. Or
FormatName:DIRECT=https:// ProvisioningServer/msmq/.. then the message will be sent via IIS.
Otherwise if the Path is something like:
FormatName:DIRECT=OS:lab1dc01\private$\cortexrequest then the direct method of using direct
MSMQ access. This requires that the Provisioning Engine that you are sending the message to is in
the same Active Directory domain as the Web Server.
The way that MSMQ sends messages means that the MSMQ service on the Web Server is given the
Provisioning Request. It is the job of the MSMQ service on the Web Server to attempt to send the
message to MSMQ on the Provisioning Server. This means that the MSMQ service on the Web
Server will create the connection to the receiving MSMQ. This can be useful in diagnosing
connection faults. To see the MSMQ connections simply open Computer Management on the Web
Server. Then expand the "Services and Applications" section and then under this the "Message
Queuing" section and finally the "Outgoing Queues" section, as seen in Computer Management:
18
You would hope to see no messages in the Queue and the Connected State as shown in this
screenshot. Otherwise you need to check the connectivity to the Provisioning Server MSMQ.
4. Process the request with the rules
MSMQ will handle the delivery of the Provisioning Request to the Provisioning Engine. The
Provisioning Engine is a service called CortexQueueMonitor. This service monitors the
CortexRequest private message queue for new messages. It then runs the rules associated with the
queue.
The CortexQueueMonitor service loads the Provisioning Rules from the Database when the service
starts. This service runs in the context of a privileged user and therefore has the appropriate access
to perform all the provisioning actions required.
For example the set of Request Rules that are run to create a user, as seen in the Provisioning
Manager:
19
5. Post-process the request
Sometimes there is some information that needs to be retrieved which can only be done once the
object has been provisioned or there are processes that you want to run only once you know
something has been successfully provisioned. An example is that SM stores the users mail box GUID.
But this information can only be found after the user has been given a mailbox. The Post-Request
rules are the opportunity to do anything that needs to happen after the provisioning has finished.
These Rules always run on the Provisioning Engine of the Primary Location regardless of which
Location the provisioning occurred in. This is done so that the Post-Request Rules have access to the
Database server if needed.
Bulk requests Bulk requests are used where a change may generate a large number of requests. Rather than slow
down the Web Server generating and sending lots of requests, a Bulk request is used instead. The
rules that process a Bulk request expand it into all the required requests.
An example might be changing the default email name pattern for a Customer. In this case all users
must be re-provisioned to pick up the new name. A single bulk request would be sent. It would
process on the Primary Provisioning Engine where it has access to all Database details. It would then
generate all the individual user update requests to be process in the normal way.
20
Bulk requests are a special case where regardless of the service’s Location the request is sent to the
Primary Provisioning Engine.
Rules The Rules are generally loaded from the Database. The rules are a list of Conditions and Actions. If
the condition is true then the action is performed.
If the action is successful then a success action is also performed otherwise an error action is
performed. Typically the success and error actions simply log the action details.
Condition
The condition can refer to any of the properties in the Provisioning Request. It can be omitted in
which case the action is always performed. The condition is a boolean expression with full VB.NET
syntax.
Action
The Action can perform any task required. There are a large number of pre-built actions. For
example there are actions to run commands, vbscript and SQL commands. Each action has
parameters that provide data to the action. The parameters can be fixed or refer to properties of the
Provisioning Request.
Events Rules In order to enable customization of the Rules, a number of Events have been created. It is
recommended that as much as possible any customized rules are added to these events. This is
because any rules added to these events will not be overwritten by SM releases however changes to
the default provisioning actions will probably be overwritten by new releases.
The Events that are available are called when an Event Type has occurred for the configured Event
Object.
Event Types
Event Types specify when the rules associated with the Event will run. There are four standard Event Types that are available. These are:
1. After Deprovision This event type will run after the standard rules to deprovision the Event Object have run.
2. After Provision This event type will run after the standard rules to provision the Event Object have run.
3. Before Deprovision This event type will run before the standard rules to deprovision the Event Object have run.
4. Before Provision This event type will run before the standard rules to provision the Event Object have run.
Event Objects
The standard Event Objects are:
21
1. Customer 2. Customer Service 3. User 4. User Service
Logging For each Rule that has been configured to log information the results of the Rule will be logged to
the Database.
Sometimes the Request Rules are run against a server that does not have direct access to the
Database. If this is the case then a MSMQ message is created with the appropriate information and
this is sent to the MSMQ specified in the Location’s Response Queue setting.
If however the Provisioning Engine has direct access to the Database then this variable can be left
blank and the Provisioning Engine will use the Location’s Connection String setting to log the result
of the Rule directly, as seen in the UI:
Service Development There are several ways that SM can be extended. There is an accompanying video that walks
through the steps of developing a new service from a simple service to a fully-fledged one.
Here’s some ways to create and extend service:
22
Create a New Service in SM and then configure the actual service to use the AD group that
the SM automatically manages. When a user is given the service they are made a member of
the service group and hence have access to the service.
Add User Plans. Configure the actual service to use group membership to determine what
features of the actual service are enabled.
Add some Rules to the Event rules for the service to customize what is performed when the
service is provisioned or de-provisioned.
Add some Properties to the Service and Rules to work with those properties.
Add a user control to the WebUI for the service to display the service Properties in a custom
way.
Add a new page to the WebUI for the service to manage custom configuration and
management.
Creating, Enabling and Provisioning a New Service
Overview
The following section describes the minimum steps to create a service using the SM user interface.
We will create a sample service and enable it in the service hierarchy by starting with an Active
Directory location, assign it to a reseller and provision the service to a customer and user.
Service Hierarchy
Services are defined against the “Top Location” using the System Manager. Note that in a standard
hosted environment there is only likely to be a single Active Directory location.
All service information is inherited in the following hierarchy:
Active Directory location services inherit from top environment services
Reseller services inherit from Active Directory location services
Customer services inherit from a customer reseller service
User services inherit from a customer service
Access the service management screen
To create a new service, login to the Web UI with a user assigned with the "Service Provider
Administrator" role. This is typically the top level service provider account.
Create a service
On the main menu, click on the Configuration->System manager->Service Schema to get to the
service management screen.
Create a service by specifying a service name and click on "Create a new service". In this example we
will create a service called "Sample Service".
23
Our new "Sample Service" will now show up in the list of “top environment services” in “Service
Deployment”. New services are not enabled by default. Open the service and press Save to enable
the service.
24
Enabling the Service for a Location
SM allows multiple Active Directory location services. Enabled top environment services can be
enabled at a location level. We have already created a top level service name "Sample Service". We
need to enable our service for the location before we continue. We can enable our service at a
location by going to “Service Deployment” and selecting the "Active Directory Location Services"
service filter option. The location filter drop-down-list will be displayed when multiple locations are
configured. This will allow the service provide to configure the services for each location.
25
In the list of location services, find and click on our "Sample Service". The location service
configuration screen should be displayed. Click on "Save" to enable the service for the selected
location. The service cannot be disabled while it is assigned to a reseller customer.
Enabling the Service for a Reseller customer
Now that our service is enabled at the location level, we need to assign the service to a reseller
customer. Once our service is assigned to a reseller customer, the reseller will be able to provision
our service to their customers.
To enable our service for the reseller, click on the "Customers->Customer Services" menu item to
display the list of services available to the reseller customer.
Select the reseller service. Note that in a multi-location environment, a separate reseller service will
be displayed for each location. This provides the flexibility to specify the services a reseller can
provision per location.
Our "Sample Service" option will appear in the list of available reseller services for the customer.
Make sure the checkbox next to the name of our service is checked and click "Provision". Once the
service is enabled for the reseller customer, our "Sample Service" will show up in the list of available
services that can be provisioned to the reseller's sub-customers.
26
For the top service provider customer, refresh the screen to see the "Sample Service" in the list of
available services. The top service provider’s customer is their own reseller.
Provision a customer with a service
Select the "Sample Service" from the list of services and click "Provision" to allocate the service to
the customer. When the provisioning status light for the service turns green, the "Sample Service"
entry will show up on the user services screen.
27
When a new service is provisioned to a customer, an Organizational Unit (OU) will be created for the
service. The default OU for the service can be located under the root domain > "CortexSystem" >
"Services" > "Service Name". A security group will be created for each plan. By default, a DEFAULT
and NONE service access level is created for a service. The group format is "ServiceName Plan".
In the screenshot below we can see that the "Sample Service" OU was created for our "Sample
Service". A security group was created for the DEFAULT "Sample Service DEFAULT ", and NONE
"Sample Service NONE" plans.
28
Plan security groups will be created for the customer under their OU. To ensure the plan group
names are unique for each customer provisioned with the service, a "ServiceName
CustomerShortName Plan" pattern is used.
In the screenshot below we can see that the FULL "Sample Service CRC DEFAULT" and NONE
"SampleService CRC NONE" security groups are created under the customer's OU "Cortex Root
Customer (CRC)" for customer "Cortex Root Customer" with a customer short name "CRC". Note
that the customer's OU format is using the default name pattern.
29
Provision a user with a service
On the Users screen, which can be accessed by clicking on the Users icon from the main menu, find
and click on a user that we want to provision with a service. On the list of user functions, click on
Services. Note that the Services option is not available to de-provisioned users.
Click on the "Sample Service" row in the list of available services to view the service options. Click on
provision to assign the user to the service.
Provisioning a user with the service will add the user to the customer's service access level security
group.
In the screenshot below we can see that user Standard User "Standard_CRC" is a member of the
"Sample Service CRC DEFAULT " customer security group.
30
The idea behind using security groups is to assign rights and permissions to members assigned to
these groups. The DEFAULT security group membership denotes that the user is provisioned with
the service and the NONE security denotes that the user is not provisioned with the service.
Removing the user from the service by "deprovisioning" the user from the "SampleService" will
remove the user's membership from the "Sample Service CRC DEFAULT" security group. The user will
then become a member of the " Sample Service CRC NONE" security group.
Custom Provisioning Actions Provisioning Actions are an instance of Microsoft .NET class that support the IAction interface. The
action parameters are defined by the constructors of the class. To create a custom action simply
inherit from the abstract base class ActionBase. Then override the OnDo method to perform
whatever task is required.
Properties Context
There is a properties context passed into the action's OnDo method. In the Provisioning Engine this
is the Provisioning Request properties. The action is free to change any of the properties which will
then be available to the next action. The SetProperty method of the ActionBase class sets property
values and also handles rolling back property changes should the action fail. See "Set" action sample.
Parameter Expansion
Most actions allow parameters that have {name} values in them. The name values are replaced with
the value of the property with that name, when the action is executed. This is called expanding. To
get the expanded value of a parameter use the Expand method of the ActionBase class. See "Set"
action sample.
31
Errors
When an action fails, the OnDo method can either return -1 or throw an exception. See "Sleep"
action sample.
Sample Actions
Here is an action that does nothing. It's the actual implementation of the standard action "No
Action".
Public Class None
Inherits ActionBase
Public Sub New()
End Sub
' ignore constructor parameters
Public Sub New(ByVal ParamArray Parms() As Object)
End Sub
' ignore action
Protected Overrides Function OnDo(ByVal Properties As Hashtable) As
Integer
Return 0
End Function
End Class
More usefully here's the code that implements the standard action "Set". It expands all the
properties with {} in the Value parameter then sets the property called Property with the result.
Public Class [Set]
Inherits ActionBase
Private _Property As String
Private _Value As String
Public Sub New(ByVal [Property] As String, ByVal Value As String)
_Property = [Property]
_Value = Value
End Sub
Protected Overrides Function OnDo(ByVal Properties As Hashtable) As
Integer
SetProperty(Properties, _Property, Expand(Properties, _Value))
Return 0
End Function
End Class
And finally here's the code that implements the standard action "Sleep". Notice that if there is a
problem it simply raises an exception.
32
Public Class Sleep
Inherits ActionBase
Private _MilliSeconds As String
Public Sub New(ByVal MilliSeconds As String)
_MilliSeconds = MilliSeconds
End Sub
Protected Overrides Function OnDo(ByVal Properties As Hashtable) As
Integer
Dim MilliSeconds As Integer = Val(Expand(Properties,
_MilliSeconds))
If MilliSeconds <= 0 Then Throw New Exception("Sleep time is in
milliseconds and must be a number greater than zero.")
Threading.Thread.Sleep(MilliSeconds)
Return 0
End Function
End Class
Provisioning Manager The Provisioning Manager allows both editing of the Provisioning Rules and Actions as well as
viewing of the Provisioning Requests on the Provisioning Queues.
Rules
Viewing Rules
There are two places where rules are managed, Rules and Events.
Rules are the core set of rules and are only visible in “Advanced” mode. These should not generally
be changed.
Events are sets of rules called when various events occur.
33
Custom rules should be added to the “Before” or “After” rule sets for the event that needs
customization.
Select the desired rule, right click and select Properties to view the rule details:
34
Rule logic
Each Provisioning Rule in the set is performed in order one after the other (unless there is an error in
a Provisioning Rule that has Stop On Error set).
A Provisioning Rule follows this logic:
1. Provisioning Rule Enabled.
If the Provisioning Rule is enabled then Evaluate Condition.
Otherwise move to the next Provisioning Rule in the set.
2. Evaluate Condition
If a Condition is not configured OR if the Condition evaluates to True then Perform the Rule
Action.
Otherwise move to the next Provisioning Rule in the set.
The Condition is any boolean expression in VB.Net syntax
3. Perform the Rule Action
The Action can perform any defined Action. Common examples are to perform a provisioning
task or to gather information into the Provisioning Request so that a later Rule has the
information needed to perform a provisioning task.
35
4. Logging the Result.
A Success Action and an Error Action can be configured for each Provisioning Rule. These are
generally used to log the results of the Rule's Condition evaluation and Rule's Action.
Referencing Properties
When you need the value of a property in a Provisioning Rule you signify this by using curly braces {
and }. This syntax is used by the Provisioning Engine to find the value of the specified property so
that it can be passed to the Condition evaluation or the Provisioning Action.
Referencing different property types
The usual property type is stored as a textual value.
Basic Property
Eg. {CustomerFullName} equates to the name of a customer
Hashtable Property (A collection of name/value parameters)
Eg. {UserDBProperties}(“ExternalEmailAddress”)
This would return the value of a user’s “ExternalEmailAddress” attribute from the
“UserDBProperties” hashtable.
Array Property (A multi-value property)
Eg. {EmailAddresses}(0) would return a users first email address
{EmailAddresses}(1) would return the second email address in the array.
Useful Customer Request Properties
These properties will exist when provisioning customers, customer services, users or user services:
Property Name Description
{CustomerID} Unique numeric Cortex identifier for the customer
{CustomerLongName} Full name of the customer
{CustomerShortName} Abbreviated customer name
{PrimaryDomain} Name of the customers primary domain
{CustomerDomains}(n) Array containing domains associated with a customer
Useful User Request Properties
These properties will exist when provisioning users or user services:
Property Name Description
{SpecificProperties}(“password”) Users password. (password is only available when the password has been changed or a new user created)
{SpecificProperties}(“CPAL”) Change password at next logon
{UserFullName} Full name of user
{UserName} sAMAccountName for user
{UserID} Numeric cortex unique identifier for user
{UserProperties}(“userPrincipalName”) uPN for user
36
Useful Service Request properties
The {ServiceName} request property is used to determine which service is being provisioned or
deprovisioned.
The {ServiceProperties} hashtable will contain a name value pair for each property defined for the
service.
Request Type
{MessageLabel} is the Request Type. There are many different request types, here are some
examples:
Request Type Description
Customer Create Provision Customer
Customer Update Update provisioned customer
Customer Deprovision Deprovision Customer
Customer Service Add Provision service to customer
Customer Service Remove Deprovision service from customer
User Create Provision User
User Service Add Provisioning service to user
General Tab
The General Tab of a Provisioning Rule looks like:
37
Rule Enabled
If this is not checked then this Provisioning Rule will be ignored. Any Rules which are not enabled
appear in Green when viewed in the Provisioning Rules Editor:
Stop on error
If this is enabled then if either the Evaluate Condition step or the Rule Action step fails the
processing of the Provisioning Rule set stops otherwise the processing will continue with the
processing of the next Rule in the Provisioning Rule set.
Condition Tab
The Rule Condition looks like:
38
Condition
The Condition is a VB.NET boolean expression. The {FoundPath} syntax in the expression advises the
evaluator to look for a Property called FoundPath
Description
The description will appear in the Rule. In the case of the example the Rule will read "If not found
then <action description>". Where <action description> is the description of the Action.
Action Tab
The Rule Action looks like:
39
Action
You choose from the drop down list the Action that will do what you want to do. The drop down list
contains a list of all the actions that are currently supported by the rules:
40
The particular action that you choose will determine which parameters and options are shown.
Description
The description will appear in the Rule. In the case of the example Rule. The interface will read "If
Condition description> then Create user". Where <condition description> is the description of the
condition.
Optional parameters
Some actions have optional parameters that can be specified. This will be enabled if the Action does
have optional parameters and then you choose how many of the available optional parameters you
want to set.
Other parameters
In the example Rule the Directory Create User Action has the parameters of Path (for the
distinguished name path of the user to be created) and name for the sAMAccountname AD attribute
of the user. However each different action will have its own set of parameters.
Rollback on failure
This feature has not been implemented.
41
Debugging Rules
Provisioning Requests can be debugged through the Rules using the Provisioning Manager. The rules
are run using the currently selected Request in the Message Park as a context.
Requests can be copied from existing queues and put into the Message Park. The requests here are
stored in the Database.
NOTE: The rules run on the desktop as the current user, NOT actually in the Provisioning Engine
service as the service user.
For example:
First we will send a request through using the Web UI. Select a Customer Service and click Provision.
Then go to the Provisioning Server and start Provisioning Manager. Go to Message Queues->Private
Queues->cortexrequest->Journal messages and right click Copy the LAST “Customer Service Update”
request with CustomerLongName of Customer X and ServiceLabel of Hosted Exchange:
42
Go to Rule Stores->Default Rule Store->Message Park, right click and Paste. Right click the newly
copied message in the Message Park and click Select:
43
A blue triangle shows the currently selected Request.
Go to Rule Stores->Default Rule Store->Events->Customer Service->HE->Provision and right click a
node selecting Breakpoint:
44
Click the main menus Debug->Start. Wait, maybe some time, while the rules run down to the
selected breakpoint. The current rules is highlighted in Yellow and the current request properties are
displayed on the right hand pane.
45
Values in the Request that have changed since the last display are hightlighted in Red.
46
Actions
Viewing Actions
Actions are .NET assemblies. They need to be imported into the SM before they can be used in
Rules.
47
The red X means that the Action DLL cannot be found or loaded.
Importing Actions
Actions need to be imported to add new Actions or update existing actions. Right click on the
Actions and select Import:
Browse to the assembly that contains the Actions to be imported and click Open. Check the Actions
that you would like to import:
48
If the number of parameters to an Action has changed and that action is in use by a Rule, you will be
warned to update the Rule as required.
Testing Actions
While you can test actions by creating rules that use them you can also test the action outside of the
rules system.
For example in the “Standard Actions” there is one called “Run Command” that will run an
application. Right click and select Test. Enter “notepad.exe” for the Filename and press Test.
Notepad should start.
49
Queues
While Provisioning Requests can be viewed in Windows Server Manager under Message Queuing,
there is limited management of the messages and you can only view the messages contents as a hex
dump. Provisioning Manager allows viewing, copy, paste, delete and purging of messages.
By default the queues only show pending requests. To view historic requests you must enable
journaling on the queue.
Enabling Journaling
In MSMQ each queue has a corresponding Journal Queue. Requests that been completed are moved
to the Journal. By default the Journal is disabled but can be enabled with a one-time only setting. Go
to the Server Manager->Features->Message Queuing->Private Queues.
Open the properties of the required queue, typically “cortexrequest”. Under Journal select Enabled
and optionally a maximum size. NOTE: when the journal is full newer messages are lost so it must be
purged manually if it is full.
50
Viewing requests
Navigate to the appropriate queue, for example the “cortexrequest” journal queue.
51
The request types are labelled, and the properties contain the context for the request. Each
provisioning request is made up of a number of properties (named values). This is the source of
information for all Provisioning Rules. The request above is adding a service to Customer “Storage
Customer 01”.
As the Provisioning Rules are processed it is common for additional information to be gathered and
stored in new properties in the Provisioning Request.
There are three types of properties:
1. Basic property
2. Hashtable container
3. Array container
Basic property
This is a basic name value pair where the value is most often a textual value. The
CustomerLongName property in the diagram above is an example of this.
Hashtable container
This is a property that in turn contains a collection of name value pairs.
In the above request there is a property called ServiceProperties.
52
You can tell that this is a Hashtable container by the + expand symbol and the (a) in front of the
property name. The property's name value pairs can be seen in the in the Provisioning Rules Editor
by expanding the property:
Array Container
This is a property that contains an array of values.
In the above requests there is a property called CustomerRoles.
You can tell that this is an Array container by the + expand symbol and the (x) in front of the
property name. The number of elements in the array can be seen in the in the Provisioning Rules
Editor by expanding the property:
Conclusion The CloudPortal Services Manager SDK provides an extensible way to integrate almost any third-
party service into Services Manager. Please refer to CitrixTV for additional samples on how to
develop extensions to Services Manager.