Automating Service Manager Service Request Catalog Deployment through PowerShell and CSV files

Goals

The purpose of this post is to provide users of System Center 2012 – Service Manager with the ability to deploy a service catalog of any size to their Service Manager environment through automation.

The portal is laid out in a way that an end user first identifies a category related to the problem they are experiencing. Once a category is identified, the end user can begin narrowing down their issue by choosing the next level of taxonomy, the “service offering”. After choosing a service offering, the next page prompts the user to narrow their issue down even further by choosing a “request offering”, and finally, the end user is presented with a form that contains a number of questions. This form is stored on the request offering itself, and by answering the questions, an end user is able to submit a service request or incident.

To give you an idea of what the end result will look like, below is an example of our production environment.

The initial loading of the portal allows the end user to choose an applicable category, highlighted in yellow in the above screenshot.

Once the end user identifies a category, they then choose one of the service offerings located immediately below each category, highlighted in green above.

After clicking on a service offering, the end user is then presented with a list of request offerings to choose from, highlighted in yellow above. Optionally, they can view the related help articles on the same page.

Lastly, the end user is presented with a form to complete, answering questions that will help the support analysts better understand and resolve the end user’s issue.

Background

We are an operations team within Microsoft that provides monitoring services for a number of different business units that support a variety of internal sites and services, including some of Microsoft’s largest customer-facing websites. We run Service Manager for these teams and have a service catalog where every employee in Microsoft can submit a ticket for support.

Because we support so many business units with a very large customer base, initial planning of our service catalog offered on the System Center 2012 – Service Manager portal showed that we would have more than 200 service offerings with more than 1000 request offerings.

We initially began creating these request offerings in the Service Manager console. The console offers a comprehensive UI to create each request offering, consisting of 8 steps per request offering. Soon after we started creating the request offerings, we decided that this was too much to accomplish without some automation. Furthermore, we were creating these in our pre-production environment, and there is no way to move the service offerings and request offerings from one Service Manager environment to another without having to recreate all the relationships in the system. This means there would be even more work to get the service catalog moved to production after initially creating it in a pre-production environment.

In partnership with the System Center 2012 – Service Manager product group, we were able to create a solution that utilizes CSV files and PowerShell scripts to create our categories, service offerings, and request offerings in bulk.

Benefits of Service Catalog Deployment Through PowerShell

The benefit of using CSV files and PowerShell to deploy your service catalog are numerous:

• Speed of deployment.
  • Easily create a new service offering and request offering by filling out a few rows and columns in a CSV file and import.
  • Request offerings with similar questions can be recreated in a few seconds.
    • E.g., if you have both a Service Manager investigation and Operations Manager investigation request offering with similar questions, you can copy and paste the questions from one request offering to the other
• The ability to easily recover from a disaster recovery scenario.
  • Either redeploy from the CSV files, or restore a backup of your service catalog management pack(s) into a new System Center 2012 – Service Manager environment and run the link-soro.ps1 PowerShell script to recreate the relationships from the request offerings to the service offerings.
    • When creating service catalogs through the console, relationships between request offerings and service offerings are lost during disaster recovery scenarios when a new Service Manager environment is deployed.
• Ability to easily deploy to a preproduction environment before moving to production.
  • No need to recreate all the work after creating the service catalogs in pre-production.
• Ability to easily make widespread changes to existing service catalogs without having to start from scratch.
  • Simply update the CSV file with the changes that are needed and re-import, overwriting your old management pack.

Deployment Steps

Gathering Information

Before being able to populate the CSV file with service catalog data and import it into Service Manager through PowerShell, information is needed from the business units that are asking the questions of the end users. This is the case whether you are deploying the service catalog through PowerShell or through the Service Manager console.

1. Maximum number of questions that will be asked on any request offering.

   Each question asked in the request offerings needs to be mapped back to a field in the service request. Service Manager has a few fields that can be utilized for this out-of-box, such as title, description, and priority. If there are any more questions that are asked of the end users, the Service Request class will need to be extended to add more fields.

2. Response data types being presented to the end user.

   The portal has the ability to present end users with a variety of different response types. These include date-pickers, drop-down lists, text boxes, attachments, etc. Knowing the response types that will be presented to end users will help to know what types of properties to create when extending the service request class.

   Note: While each question can map back to a string field regardless of the data type in the portal, it is generally recommended that the data type of the service request property being recorded to matches the data type presented to the end user on the portal. This is for ease-of-use if modifying the fields in the service request after the ticket has been submitted.

   For example, by mapping a date picker data type on the portal to a date picker property on the service request, support analysts can easily change the date if an incorrect entry was made by the end user. If it maps back to a string field, the support analyst would need to manually type in a date instead of being presented with a user-friendly calendar picker.

3. Property mapping and data warehouse requirements

   Because each question on every request offering needs to be mapped back to a property on the service request, if a business unit asking the portal questions has the same question on multiple request offerings that they would like to report on, display in a view, or set as criteria in a workflow, knowing this ahead of time can save time in the future. These similar questions on each request offering should be mapped to the same property on the service request.

   For example, we have a question that is “What team do you belong to?” on each request offering. Each of these question answers map back to the same field on the SR (i.e., SRString1) so that we can add the answer to our views, reports, and automated e-mails.

Extending the service request class

Once we have information from the business units utilizing the portal, we can create additional properties on the service request class by extending it. This requires the System Center 2012 Service Pack 1 – Service Manager Authoring Tool. The Authoring Tool can be downloaded from https://www.microsoft.com/en-us/download/details.aspx?id=36214.

After launching the authoring tool, create a new management pack that the extensions will be saved in. This is done by clicking ‘File’, then ‘New’, naming the management pack, and clicking ‘Save’.

In the Class Browser pane (if you don’t see the pane, go to the View menu to display it), in the drop-down choose the “System Work Item Service Request Library” management pack. Right-click the resulting “Service Request” class and choose View.

In the Management Pack Explorer (again, go to the View menu if you don’t see it), right-click the Service Request class and click ‘Extend class’.

In the resulting Target Management Pack window, click OK on the prompt to save the extension in your custom management pack.

Note: We are prompted with this because the extensions can’t be saved into a sealed management pack.

Creating Properties

In the new “Extension of Service Request” class that you’ve created, click ‘Create Property’. After giving the new property a name, click ‘Create’.

Note: We prefer to generalize the names so they can be used to map back multiple questions.

For example, instead of naming the new field “RequestedCompletionDate”, we may call the field “SRDate1”. This way we can use the same date picker to store an end user’s requested completion date, as well as a question of “When did this issue begin?” or any other question where a customer chooses a date from a date picker.

Note: As a best practice, name the property something that will help identify the type of field it is since these will be generalized.

For example, if you are creating a string, you may choose to call the property “SRString1”, “SRString2”, “SRString3”, etc.

Click the new property you’ve created, then go to the Details pane.

Change the Data Type field to the data type that the new property should be.

1. Textboxes should be “String”
2. Date pickers should be “Date Time”
3. True/False should be “Bool
4. Attachments should be “Binary”
5. Lists should be “List”

Note: If creating a list, what we’ve just done is created the property that the list will be stored in once a value is selected by the end user. We are automatically prompted to choose an existing list (or create a new list) that the actual list items are stored in.

Note: Unlike other properties, lists contain very specific data. Therefore, lists do not need to follow the “generalizing” guidelines noted above.

Create as many properties as necessary. Once all the required fields are created (dictated by the information gathered in the “Gathering Information” stage), go to the Management Pack Explorer view, right-click your custom management pack, and click Seal Management Pack.

Note: Sealing makes it so nobody can edit the management pack you’ve created (unless you have the original XML). It is also necessary because your new portal questions are going to reference this management pack. One management pack cannot reference another management pack unless the management pack being referenced is sealed.

In the resulting window, specify an output directory, select your Key File, and type in the name of your company, then click Seal.

Note: Information about key files can be found halfway down the article at https://technet.microsoft.com/en-us/library/hh457550 , and how to create them can be found at https://msdn.microsoft.com/en-us/library/6f05ezxy(v=VS.80).aspx.

Import the resulting .MP file into your Service Manager environment.

An example management pack that we have created (called “ServiceRequestExtensions”) is found in the TechNet Gallery at the link provided at the end of the post. This can be used in conjunction with an example CSV file found under the topic “Populating the CSV file”.

Populating the CSV File

After we have extended the Service Request class with our custom properties, we are ready to fill out our CSV file in preparation for importing our Service Catalogs.

The CSV file is used to define all components of the service and request offerings, aside from any related knowledge articles. A CSV file can create as many service or request offerings as needed. The following columns specify the values used to create the catalogs:

• Category
  • Used to specify the name of the category you are creating
• Service Offering
  • Used to specify the name of the service offering you are creating
• SO Description
  • A short description of the service offering, located on the main page of the portal
• SO Overview
  • A longer description of the service offering, located once you drill into the service offering
• Request Offering
  • Used to specify the name of the request offering you are creating
• RO Description
  • A longer description of the request offering, located once you drill into the request offering
• Questions
  • Used to create questions on the request offering
• Answers
  • The list of answers displayed to end users when using a list (either simple or enum)
• Required
  • Used to specify whether an answer to a question is required
• Question type - specifies what type of question it is
  • Text
  • Simple List (list values in the answer column, one for each row)
  • Date
  • MP ENUM List (Answer column contains the name of a SCSM List)
  • True False
• Map
  • Defines the Service Request property that the answer will be stored in
  • Each request offering must map to a unique property on the Service Request

A blank CSV file ready to be filled out (called “BlankServiceOffering.csv”) is included in the package that can be downloaded from the TechNet Gallery linked at the end of this post.

An example of a pre-populated CSV file (called “CustomServiceCatalog.csv”) which can be used in conjunction with the example ServiceRequestExtensions.MP referenced above is included in the package that can be downloaded from the TechNet Gallery linked at the end of this post.

Breakdown of the example pre-populated CSV file

The first step is to define your category and your first service offering. In our below screenshot we have a category called “Test Category”, and a Service Offering called “Report a Problem”. From there we added an SO overview and description.

A couple of things to note:

• You only need to define the category once
• The overview, description, RO Owner, and Icon fields are all optional

Once this is defined, you can begin filling out your request offerings that fall under the service offering as well as the questions/answers and question types.

Items to note about request offerings and the questions/answers:

• The request offering is defined on each row. This is so the PowerShell scripts know which request offering to associate each question/answer with.
• You will generally have one question per row. The only exception is when you have a simple list that you are populating.
• The only time the Answer field is used is for lists (both simple lists and enum lists).
  • When using enum lists, the answer is the actual list that all the list items are stored in.
  • When using simple lists, you can list out each answer on a separate line.
• An example of a simple list is starting at row 3, column H – question “Issue classification” in the screenshot below.
  • Notice the 3 list items in the Answer column.
• Required is simply “Yes”, or else leave the field blank if not required.
• Questions should map to fields found in either the service request extension or the base service request class.
• Question types can be found in the table below:

Property Type	Script looks for
String	“Text”
DateTime	“Date”
list	“MP Enum List”
inlinelist	“Simple List”
integer	“integer”
Boolean	“True False”
Boolean	“Check Box”
FileAttachment	“Attachement”
FileAttachment	“Attachment”
integer	“number”

Once the CSV file is filled out, we are ready to import the data into Service Manager through PowerShell.

Note: We recommend creating one category per CSV file. This separates each category into a separate management pack, which is useful if you need to update one category/service offering/request offering without risking other category/service offering/request offering data.

Running the PowerShell scripts

There are three PowerShell scripts that need to be run to import the CSV data into Service Manager.

After launching PowerShell change directories to the folder that the three scripts are located in before running them. You will need to have a “CSV” folder within the directory the PowerShell scripts are located in, as well as a “Portal Images” folder. The images need to have the same name as what you referenced in the CSV file, and can be a maximum of 32x32 pixels.

The PowerShell scripts utilize custom CMDLets called SMLets developed by members of the product team. These need installed on your management server before continuing and can be found at https://smlets.codeplex.com/.

The PowerShell scripts are detailed below and need run in the order laid out:

Convert-SO

• Creates a new management pack
• Stores the catalog defined in your CSV file in the management pack
• Stores the service offering data (including descriptions) in the management pack
• Imports the management pack into Service Manager

Usage: .\convert-so.ps1 csvfilename managementpackname

Where
csvfilename is the name of the CSV file
managementpackname is the name of the new management pack being created to store the service catalog in

Example: .\convert-so.ps1 CustomServiceCatalog.csv CustomServiceCatalogMP

Convert-RO

• Creates a template and stores it in the specified management pack
• Stores the request offering data (including descriptions) in the management pack
• Stores the category and service offering each request offering should be related to in the notes field on the request offering
• Imports the management pack into Service Manager

Usage: .\convert-ro.ps1 csvfilename managementpackname templatename classname

Where

csvfilename is the name of the CSV file
managementpackname is the name of the managementpack the request offerings are being stored in (same name as the convert-so powershell script used)
templatename is the name of a new template to be created
classname is the internal name of the class extension you created (found in either the MP xml or details pane in the authoring tool)

Example: .\convert-ro.ps1 CustomServiceCatalog.csv CustomServiceCatalogMP CustomServiceCatalogTemplate ClassExtension_b2be6fe1_e230_4964_a402_f411b

Link-SORO

• Looks-up all request offerings in Service Manager and creates a relationship to their corresponding service offerings (based on the notes field of the request offering)

Usage: .\Link-SORO

Example: .\link-soro.ps1

In the case of our example CSV file that references our example ServiceRequestExtensionsMP, we would run the following:

PS C:\> cd '.\Service Catalog Scripts'
PS C:\Service Catalog Scripts> .\convert-SO.ps1 CustomServiceCatalog.csv CustomServiceCatalogMP
PS C:\Service Catalog Scripts> .\convert-RO.ps1 CustomServiceCatalog.csv CustomServiceCatalogMP CustomServiceCatalogTemplate ClassExtension_b2be6fe1_e230_4964_a402_f411b
PS C:\Service Catalog Scripts> .\Link-SORO.ps1

Note: The “Skipping” results in the output are the request offerings that the PowerShell script skips since there is not a valid category and service offering entry on the request offering notes.

Viewing the Final Results

Once the above steps have been complete, you can view the final results by navigating to your portal. Notice the new Category, Service Offering, and Request Offerings that are displayed.

Restoring Service Catalog Management Packs

Restoring the service catalog management packs isn’t as straight forward as exporting from one system and importing into another. This is due to the categories (created when importing the CSV files) being saved directly in the same management pack that we defined the service offerings and request offerings in. Because each service offering references a category, that referenced category needs to be in Service Manager before the management pack containing the service offerings can be imported.

If you import your service catalog into a new Service Manager environment as-is, you will be presented with the following error:

The solution is simple. Since the category that each service offering references needs to already exist in Service Manager, we can change the category to point to one that already exists. This will allow us to import the management pack. The only category that ships with Service Manager is called “General”.

The first thing we will need to do is export the management pack that we created through PowerShell (in this case, called “CustomServiceCatalogMP”). We will then create a copy of this management pack, as we are going to modify the management pack but we still need to keep an original. Open the management pack in your favorite XML editor, and near the bottom there is an area where the Service Offerings are stored (indicated by “ServiceOffering ID”). To the right we can see where the category is referenced (indicated by “Category=”). In the below example the category is set to “Category="Test.Category"”.

We then need to update this with the built-in category. We actually need to know the internal name (enum value) of the General category instead of the friendly name. The internal name of the general category is “System.ServiceOffering.CategoryEnum.General”. Your end result will look like:

“Category="System.ServiceOffering.CategoryEnum.General"” as indicated in the below screenshot.

Once this is complete, you can save the management pack and import it into Service Manager.

Once this is complete we have imported the management pack that contains your new category. This means that if we were to import the original copy of this management pack, it would not fail since the category now exists. The final step is to import the original copy (the one without the changes to the category).

Best Practices

Use Built-in Icons

When navigating to the portal, Service Manager loads all the icons for each service offering and request offering on the initial loading of the portal. When using custom icons, this means that every icon is downloaded by the end user, and can cause a long delay in the loading of the portal. The icons are not cached either. They are retrieved every time the user accesses the home page of the service catalog.

The solution to this is to use as few custom icons as possible. We don’t actually use any custom icons and let the portal load the default icon, which is a set of keys. This can drastically reduce the loading time for the portal, depending on the number of icons you have.

Have a Required Title

Each service request that is created needs to have a title filled in before any modifications to the work item can be saved through the console. Because of this, it is recommended that you have a question on each request offering that maps back to the title. Alternatively if you don’t mind having the same title for all service requests, you can add a default title to the template that is applied by Service Manager when an end user submits their request.

One Category Per Management Pack

If you need to modify an entire category including its service and request offerings, it can be very useful to have only one category per management pack. This allows you to easily remove the entire category by simply deleting the management pack without worrying about other categories. It also allows you to make changes to one category by utilizing CSV files without worrying about causing other categories to go “offline” while making changes to the one category.

Periodically Backup MPs

As a best practice, periodically backup your custom management packs. This allows you to have up-to-date information in case you need to restore to a secondary environment during a disaster recovery scenario.

Name Changes

If you are going to change the name of any of your categories or service offerings, be sure to update the “notes” field on your request offerings as well. If you recall, the link-soro PowerShell script matches the data in this field to a category and service offering. If you change the name of your category and service offering, a match can no longer be made when running the link-soro PowerShell script if you need to restore your service catalog management packs to a secondary environment.

For this reason, make sure you update the notes field on your request offerings if changing the name of your categories and request offerings.

Downloads

All files and scripts mentioned in this posting can be found in the TechNet Gallery at https://gallery.technet.microsoft.com/Service-Catalog-script-eeb29fc1.

Comments

• Anonymous
  January 01, 2003
  Hi Tom, The service catalog is mainly used to create service request.  Service requests are customer-driven, whereas incidents are usually server driven.  There is one method to create incidents via the portal, however you aren't presented with the rich set of taxonomies and custom questions that you are when creating a service request. To create an incident request via the portal, in the lower right-hand side of the page there is text stating, "Can't find a solution?".  There is a button next to this labeled, "Create a request" that can be used to create an incident in Service Manager. Andrew

• Anonymous
  January 01, 2003
  Andrew, Just a side note - On my SCSM Management Server, Powershell 3 was installed. This prevented the convert-RO.ps1 script from completing correctly. I experienced the same kind of issues as the SQLPSX guys are (see social.technet.microsoft.com/.../be63367b-306e-4ab3-a48b-b0bb8be745ee ) - I dropped down to a powershell v2 session and it all worked as intended. Maybe something to caveat for now? Also, can I recommend that in the "map" CSV column you clarify whether the scripts are expecting the display name or the internal name (e.g. "Alternate contact method" vs "ContactMethod" or "Required by" vs "RequiredBy"). Love the scripts though. Thank you very much! Drew

• Anonymous
  January 01, 2003
  Thanks Aaron.  Regarding the RO's not creating if only one is defined, I have experienced this with some of my other PowerShell scripts.  It’s probably checking to see if there is any data in the variable.  If there is only one item, PowerShell treats it as a string and strings do not have the count property.  If more than one object it treats it as an array which has the count property. The solution for PowerShell v2 is to explicitly create the variable as an array (i.e., [array]$var) In PowerShell v3 this should be fixed. I’ll look at the code and see if I can fix it. As far as the special characters go, I would suggest avoiding using them.  PowerShell uses special characters for various things, so you'll run into problem if it happens to be used by PowerShell. Andrew

• Anonymous
  January 01, 2003
  Hi Casey, The SR template is applied when running the convert-ro.ps1 PowerShell script.  When running the script you supply the template name as a parameter.  If there is already a template with the name you’ve specified in Service Manager, it will apply that template.  Otherwise it will create a new, blank template with the name you specify. If you have an existing template that has approval activities, just supply the name of this template when running the script. Andrew

• Anonymous
  March 12, 2013
  Great solution!!  We are still in testing and only have a couple of Service Offerings right now so I'm considering scrapping them and going to your method.   One question I have is about Service Request templates.  One of our offerings is a purchase request.  The data capture part is straightforward enough but what about SR templates?  Our template has a number of approval activities and a runbook automation activity.  If you create SO/RO using your solution, what about the runbooks that might be needed behind the scenes or the activities?   Hope this makes sense! -Casey

• Anonymous
  March 27, 2013
  The comment has been removed

• Anonymous
  April 19, 2013
  Can this be used to create Incidents instead of Service requests?