Software Product Docs

User Guide

Introduction

PowerShell Tasks for SCSM allow you to easily create tasks in the SCSM console that trigger PowerShell scripts that are stored within the CMDB. With this extension you don’t need Visual Studio anymore for creating tasks that interact with the console context. This allows you to create tasks for things such as setting default values in a form, applying business rules to attributes, and bulk-modifying attributes, to name a few. Below you can find the comparison with standard console tasks:

Feature Standard SCSM Console Task Operaio PowerShell Console Task
Create\update console task In SCSM Console In SCSM Console
Storing of PS Script In ps1 (must be delivered to all computers with SCSM Consoles) In SCSM Management Pack
Execution context Current user Current user
Access to console API No Yes
Access to form context No Yes (Two-way)
Debug Outside of SCSM console Inside SCSM console (not step-by-step)
Output Yes Yes
Execution method Powershell.exe Inside console’s process
Open object’s form No Yes

Main Features * Create simple and complex Powershell-based tasks * Tasks scripts are stored in the Service Manager CMDB * Use variables to easily access data from the form and view context * No more need for Visual Studio

Installation

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 Tasks for SCSM:

  1. Log on to SCSM using an account with administrative privileges in SCSM.
  2. For SCSM 2012, import the itnetX.PowerShellTasks.2012.mpb management pack
    For SCSM 2015, import the itnetX.PowerShellTasks.2016.mpb management pack
  3. Import the itnetX.SCSM.Licensing.Library.mpb Management Pack into your SCSM environment.
  4. Import the itnetX.SCSM.PowerShellTasksv1.LicenseInfo.mp or the itnetX.SCSM.scsmProdPackv1.LicenseInfo (Bundle license for Productivity Pack) Management Pack into your SCSM environment.
  5. Restart the SCSM Console.

How it works

In the following we’re going to describe how to use Operaio PowerShell Tasks.

Views

You can find all Operaio PowerShell Tasks in one view in the console, located in Library -> PowerShell Tasks

In this view you can add, change or remove PowerShell Task:

Create a new PowerShell Task

To create a new PowerShell Task you can follow the steps below:

  1. Navigate to the PowerShell Tasks View: Library -> PowerShell Tasks
  2. Click Create PS Task in the Task pane:
  3. Enter a Display Name for the Task
  4. You have the possibility to use a custom ID for the Task if needed. To do that just check the box Use custom name
  5. Add an optional Description and use the Select Image button to specify an image for your task. You can select Images from the available Management Packs. You can change the image also after the creation.
  6. You can specify some additional settings for the behavior of the PS Task:

    We’re going to describe these settings in detail here
  7. Use the Browse button to select the target for the PS Task. The following targets are available:
    • Class
      If you select a class as a target (for example Incident) then the console task will be available in the Action Pane when an object of this class is selected or when the object form is opened.
    • Another Console Task
      If you select another console task as a target, then the task will be added to the target task as a child task. It looks like the following example for Change Incident Status:
    • View or Folder
      If you select a view or a folder as the target the console task will be available in the Action Pane when the given view or folder is selected. This can be helpful if you need to create a console task that is always available in some area but not related to any selected object.
  8. As a next step you can select the categories, where you want to make your task available.
  9. In the script section you insert your script content, which you want to use for this PowerShell Task. You can find information about sample scripts here.
  10. Save your PowerShell Task

Change a PowerShell Task

To change an existing PowerShell Task, follow the steps below:

  1. Navigate to the PowerShell Tasks View: Library -> PowerShell Tasks
  2. Select the Task you want to change and click on Edit PS Task in the Task section on the right site:
  3. Change the properties and save the changes

Disabled fields

You will not be able to change the Internal Name and Management Pack

Remove a PowerShell Task

To remove an existing PowerShell Task, follow the steps below:

  1. Navigate to the PowerShell Tasks View: Library -> PowerShell Tasks
  2. Select the Task you want to delete and click on Remove in the Task section on the right side:
  3. The Task will be deleted now

Configuration

Operaio PowerShell Tasks for SCSM is ready to use after the installation completes, however you can configure additional options

Properties

In the following we’re going to describe the properties you can specify for a PowerShell Task:

Display Name

The Display Name is the name of the task in the Action Pane. You can use any characters.

ID

The ID is the internal name used in the Management Pack. You can use an auto generated ID or create a custom, by checking Use custom name.

Description

Description for the task.

Behaviors

In this section you can enable or disable options for console tasks.

  • Require Output
    If enabled the Output Window will be displayed when the task is called and all output from PowerShell will be redirected to that window:
  • Multi Selection
    If this option is enabled, the task will be available if more than one items are selected in the view.
  • Run for each item
    This option is only available if Multi Selection is enabled. With this option a separate instance of the console task will be executed for each selected item. This means you will not have to loop through the $nodes array variable.
  • Do not show in views
    The task will not be available if the object is selected in a view. Works only if the target of the task is a class.
  • Do not show in forms The task will not be available on the object form. Works only if the target of the task is a class.
  • Show Debug window
    The script will not be executed and a Debug Window is displayed instead. You can use this to run a script and check the output.
  • Is group holder
    Use this option, if you want to add other tasks as “Children” to this task.

Categories

By defining categories, you can make the console task available in several different areas at the same time. Most categories have a description that explains where the task will be available if given criteria is selected. Most categories are very similar to View or Folder as a target.

Script

The script is the main part of the entire solution. The script will be stored in the management pack together with the console task and executed in the user’s context when the console task is called. You can use any cmdlets, modules, methods and techniques, but please keep in mind that cmdlets must be available on client.

Code samples

You can find samples for Operaio PowerShell Tasks in the following management pack:
itnetX.PowerShellTasks.Examples.xml.

Just import the management pack to your environment. The sample tasks are all available in 3 task groups and are targeted at the Incident class:

API Reference

PowerShell Tasks are executed in the same application domain as the Service Manager console, so you can use any API of the console in your script. The only limitations are the PowerShell language itself and the threading model.

We plan to add more helper methods in feature releases, so please make sure that you always read the latest available documentation.
You can get a list of available methods using the Debug Window and Get-Member cmdlet, for instance:
$pstaskhelper | Get-Member

Threading model

Service Manager uses WPF (Windows Presentation Foundation) as its UI engine. All UI components in WPF (TextBoxes, Lists, Buttons etc.) can be accessed only from the same thread where they were created. In opposite, the PowerShell Tasks are executed in a separate thread, so you can’t interact with any WPF components directly. This is not very important when you are using your PowerShell Tasks in views, but extremely important for PowerShell Task used from forms, because in this case you have to interact with the form context to update attributes.

Helper objects

To remove some limitations of the PowerShell language (like native support of delegates and generic types), and to avoid additional code to access WPF components from different threads, we have added several useful helper objects.

$nodes

The $nodes variable is an array of selected items for a given task.

$pstaskhelper

The $pstaskhelper is the main helper object and contains methods that you will use very rarely. All methods of this helper object are thread safe (this means what you don’t need to worry about whether you are accessing WPF components or regular variables).

AddActionLogEntry()

Description: creates a new action log entry

Definition:

Microsoft.EnterpriseManagement.UI.DataModel.IDataItem AddActionLogEntry(string actionLogTitle, string actionLogComment, string enteredBy, Microsoft.EnterpriseManagement.UI.DataModel.IDataItem actionLogEnum)

Parameters:
actionLogTitle – title for Action Log entry
actionLogComment – text of Acton Log entry
enteredBy – author of comment
actionLogEnum – object representing enumeration for Action Log type.

Example:

# Adding an Action Log Entry
# Description: This adds an action log entry to a work item. You can use a helper:
$nodes | %{
    $node = $_

    if($pstaskhelper.IsNodeWithinForm($node)){
        $formContext = $pstaskhelper.GetFormDataContext($node)
        write-host ("Current title:" + $formContext["Title"])
        $formContext["ActionLogs"] = $pstaskhelper.AddActionLogEntry("AL usign helper", "Some description", "TEST\user", $pstaskhelper.ConsoleContextHelper.GetEnumeration([guid]"d3a676ea-8251-cb74-f301-fa4a0697d21c" <#TaskExecuted#> ))
    }
}
CloneStream()

Description: clone existing stream. Useful if you need to add attachment from \save attachment to file.

Definition:

System.IO.Stream CloneStream(System.IO.Stream input)
CopyAttachment()

Description: copy attachment object. Useful is you have to copy attachment form one element to an another.

Definition:

Microsoft.EnterpriseManagement.UI.DataModel.IDataItem CopyAttachment(Microsoft.EnterpriseManagement.UI.DataModel.IDataItem curAttachment)
CreateAttachemntObject()

Description: create new attachment object from existing stream of existing file.

Definition:

Microsoft.EnterpriseManagement.UI.DataModel.IDataItem CreateAttachemntObject(System.IO.Stream fileStream, string fileName), Microsoft.EnterpriseManagement.UI.DataModel.IDataItem CreateAttachemntObject(string fileFullPath)
GetFormDataContext()

Description: get form data context. This is most important method to work with form’s data.

Definition:

Microsoft.EnterpriseManagement.UI.DataModel.IDataItem GetFormDataContext(Microsoft.EnterpriseManagement.ConsoleFramework.NavigationModelNodeBase node)

GetInstances()

Description: get class instances by simple criteria

Definition:

System.Collections.Generic.IList[Microsoft.EnterpriseManagement.UI.DataModel.IDataItem] GetInstances(string criteria, System.Guid classId)
GetProjectionInstances()

Description: get type projection instances by XML criteria

Definition:

System.Collections.Generic.IList[Microsoft.EnterpriseManagement.UI.DataModel.IDataItem] GetProjectionInstances(string criteria, System.Guid projectionId)
IsFormInTemplateMode()

Description: return true if current form is in template mode

Definition:

bool IsFormInTemplateMode(Microsoft.EnterpriseManagement.ConsoleFramework.NavigationModelNodeBase node)
IsNodeWithinForm()

Description: return true if currently selected object is in form

Definition:

bool IsNodeWithinForm(Microsoft.EnterpriseManagement.ConsoleFramework.NavigationModelNodeBase node)
RefreshView()

Description: refresh current view. Works only if object select in the view.

Definition:

System.Void RefreshView()
ConsoleContextHelper

instance of the Microsoft.EnterpriseManagement.UI.Extensions.Shared.ConsoleContextHelper class. Provides a lot of useful methods from Service Manager Console API.

ConsoleUIDispatcher

instance of the System.Windows.Threading.Dispatcher class with current form’s dispatcher. Please refer to WPF documentation for more info about dispatcher. This field is null if node called from view.

FormHelper

instance of the Microsoft.EnterpriseManagement.GenericForm.FormUtilities class. Provides useful methods to work with console UI. Methods in this field are not thread safe.

$task

The $task variable is an instance of the currently executing task. This can be useful to get the task configuration.

$parameters

The $parameters variable is an array of parameters which are defined for a given console task. PowerShell Tasks created from the console UI cannot have parameters. So usually this is an empty array.