Software Product Docs

User Guide

Introduction

PowerShell Activity for SCSM allows you to automate tasks in a very easy way. By introducing an activity which runs custom PowerShell scripts, you can flexibly use your automation as a steps inside your business workflows. All automation scripts are stored in the CMDB and are triggered from PowerShell activities within your processes. You can use PowerShell Activities just like you use runbook activities and add them to your Service Request, Change Request, and Release Record templates.

Main Features:

  • Automate SCSM business processes or internal processes
  • New activity type to execute Powershell scripts
  • Scripts are stored in Service Manager CMDB

Installation

Prerequisites

We recommend to install the “SCSM PowerShell Cmdlets” (aka SMLets) module. This module provides cmdlets for Service Manager which can be used in your scripts. You can download the “SCSM PowerShell Cmdlets” from the link bellow. You can also find a documentation of how to install and a list of the available commands under this site:

https://smlets.codeplex.com/

Installation

The installation is performed using the management pack import functionality of SCSM. Please refer to the Microsoft TechNet Library for more information on how to import management packs:

http://technet.microsoft.com/en-us/library/hh524269.aspx

Follow these steps to install Operaio PowerShell Activity for SCSM:

  1. Log on to SCSM Workflow server using an account with administrative privileges in SCSM. The SCSM Workflow Server is by default the first SCSM Management Server installed.
  2. For SCSM 2012, copy the \2012\itnetX.PowerShellActivity.Workflows.dll, and for SCSM 2016, copy the \2016\itnetX.PowerShellActivity.Workflows.dll to the SCSM installation directory. By default, this is C:\Program Files\Microsoft System Center 2012\Service Manager\ for SCSM 2012 (including SP1), C:\Program Files\Microsoft System Center 2012 R2\Service Manager\ for SCSM 2012 R2, and C:\Program Files\Microsoft System Center\Service Manager\ for SCSM 2016.
  3. For SCSM 2012, import the itnetX.PowerShellActivity.2012.mpb management pack.
    For SCSM 2016, import the itnetX.PowerShellActivity.2016.mpb management pack
  4. Import the itnetX.SCSM.Licensing.Library.mpb Management Pack into your SCSM environment.
  5. Import the itnetX.SCSM.PowerShellActvityv1.LicenseInfo.mp or the itnetX.SCSM.scsmProdPackv1.LicenseInfo (Bundle license for Productivity Pack) Management Pack into your SCSM environment.
  6. Restart the SCSM Console.

Permissions for other user roles

Operaio PowerShell Activity for SCSM introduces a new class to the CMDB of SCSM. If you are using PowerShell Activities in Service Requests that you publish to your end users using Request Offerings, you need to grant the Enduser role permissions to create instances of this class.

Please follow these steps to grant the required permissions:

  1. Copy the Set-SCSMProfileOperation.ps1 and Set-itnetXPowerShellActivityPermissions.ps1 files to your SCSM management server (copy both files to the same folder).
  2. Open Set-itnetXPowerShellActivityPermissions.ps1 in a text editor of your choice.
  3. Find the line $scsmServerName = "localhost" and change the value localhost to the name of your SCSM management server if needed.
  4. Save and close the file.
  5. Run Set-itnetXPowerShellActivityPermissions.ps1 in PowerShell as an administrator.
  6. Import the itnetX.PowerShellActivity.Queues.xml Management pack
  7. In your SCSM Console, go to Administration/Security/User Roles, then open the desired User Role, go to "Catalog Item Groups" and provide access to All PowerShell Scripts (Catalog)

PowerShell Version

The PowerShell activity scripts are executed on your Workflow server and use the PowerShell version installed on that server. Please note that PowerShell versions up to 5.1 are supported. PowerShell core or version 7 are not supported.

How it works

In the following we’re going to describe how to use Operaio PowerShell Activity for Service Requests. The procedure for Change Requests and other work items is the same.

Create PowerShell Script in SCSM

The PowerShell scripts, which you can user for the PowerShell Activity, are placed in the console under Administration -> PowerShell Scripts -> All PowerShell Scripts. Here you can add and manage your PowerShell scripts:

To create a new PowerShell script, follow the steps below:

  1. Move to the All PowerShell Scripts view under Administration -> PowerShell Scripts
  2. Make a right click on All PowerShell Scripts or use Create PowerShell Script in the Action Pane
  3. Enter a Script name and optionally a Description
  4. In the PowerShell Script Text section enter the content of your script and save it:

You can use predefined variables in your script which allow you to interact easily with Service Manager. These are explained here

Now you can use the created script in your PowerShell Activity, as described in the next chapter.

Adding a PowerShell Activity

After you created a PowerShell script in SCSM, you can use this for a PowerShell Activity. We are going to describe how to add a PowerShell Activity to a Service Request. For Change Request and Release Record and other Work Items it is the same.

  1. Create a new Service Request from a template and fill out the required fields, or open an existing Service Request template.
  2. Go to the Activities tab and press the + button to add a new Activity
  3. Select the Default PowerShell Activity
  4. Enter a Title and optional a Description
  5. In the PowerShell Script section, use the … button to browse for your PowerShell script.
  6. Select the PowerShell script you want to use for this activity and select it:

    By pressing the … button you also have the possibility for an Advanced Search, where you can specify more filters with the available properties:
  7. After the selection of the PowerShell script you can save the activity.
  8. Add more activities if needed and then save the Service Request and the execution of the activities will start.

Configuration

Operaio Checklist Activity for SCSM is ready to use after the installation completes, however you can configure additional options.

Available variables

You can use these predefined variables:

  • $mg
    Contains the Service Manager Management Group.
  • $ActivityId
    Contains the Id of the Activity itself. If you are using SMLets, you can get the instance of the activity which triggered the script using: $Activity = Get-SCSMObject –Id $ActivityId
  • $ParentId
    Contains the Id of the parent Work Item. Normally, the parent work item is the request which includes the activity, such as the Service Request, however, it can also be another activity if you are using parallel activities or sequential activities.
  • $RootId
    Contains the Id of the root Service Request (or other Work Item) itself. If you are using SMLets, you can get the instance of the root work item using: $WI = Get-SCSMObject –Id $RootId

Samples

This chapter contains examples for PowerShell activity scripts.

Skipping an activity based on User Input

The following example assumes that you have a Service Request template which is used in a Request Offering. Inside this Request Offering, you have a user prompt which asks the user about the type of request. Possible values are “Trial”, “Quote”, or “Trial + Quote”. The user prompt is mapped to the property xtext01 of the Service Request class

The Service Request template contains 4 activities:

  • PowerShell Activity: Evaluate Conditions
  • Parallel Activity: Fulfil Request
  • Manual Activity: Send Trial
  • Manual Activity: Send Quote

Depending on the selection of the user in the user prompt, the two manual activities have to either be skipped or unskipped. This can be done using the following PowerShell Script in the “Evaluate Conditions” PowerShell Activity.

Import-Module SMLets

$objSR = Get-SCSMObject $rootId
$enquiry = $objSR.xtext01

$rcWIHasActivity = Get-SCSMRelationshipClass System.WorkItemContainsActivity$

$arrAllActs = Get-SCSMRelatedObject -SMObject $objSR -Depth Recursive -Relationship $rcWIHasActivity
$actT = $arrAllActs | ?{$_.Description -eq "<%TRIAL%>"}
$actQ = $arrAllActs | ?{$_.Description -eq "<%QUOTE%>"}

Write-Host "### Resetting all activities to 'skipped' in case this activity is rerun... ###"
Set-SCSMObject $actT -Property Skip -Value $true -Verbose
Set-SCSMObject $actQ -Property Skip -Value $true -Verbose

if ($enquiry -like "*Trial*")
{
    Set-SCSMObject $actT -Property Skip -Value $false -Verbose
}
if ($enquiry -like "*Quote*")
{
    Set-SCSMObject $actQ -Property Skip -Value $false -Verbose
}

Remove-Module SMLets