Tag Archives: MimbolovePowershell

Automating OpsMgr Part 4: Create New Empty Groups

Written by Tao Yang

OpsMgrExntededIntroduction

This is the 4th instalment of the Automating OpsMgr series. Previously on this series:

When developing management packs, it is very common to define various groups that contain objects discovered by the management pack. The groups can be used for overrides, maintenance modes, reports, scoping user access, etc.

Generally speaking, there are 2 types of groups in OpsMgr: instance groups and computer groups. As the names suggested, instance groups can contain any types of instances in OpsMgr, and computer groups can only contain computer objects.

In the OpsMgr console, the easiest way to identify the group type is by the icon. i.e.

image

As you can see, the computer group has an additional computer in the icon.

There are 2 steps when creating a group:

1. Class definition – A singleton, unhosted group class representing the group itself. i.e.

image

2. A discovery workflow which uses A Data Source module type called “Microsoft.SystemCenter.GroupPopulator” to populate the group membership. i.e.

image

The class definition and the discovery can be defined in the same management pack, or different packs (i.e. Class definition in a sealed MP, and discovery MP can reference the sealed class definition MP). As you can see, the class definition for groups are really simple, but the discovery can sometimes get very complicated – all depending on your requirements.

When I was developing the OpsMgrExtended module, I have created 2 functions for group creations:

  • New-OMInstanceGroup
  • New-OMComputerGroup

As the names suggest, these 2 functions create new instance groups and computer groups respectively. But because the group populations can sometimes be tricky and complicated, after careful consideration, I have decided to code these 2 functions to only create empty groups and users will have to either manually populate the groups via the operations console, or developing their own runbooks to update the group discovery workflow.

So what does an empty group mean?

I simply coded the group populator data source to always return nothing by using a simple expression where True equals False (which would never happen):

image

Since populating groups can get complicated, and I think it will be very useful for people to use the OpsMgrExtended module to create and manage groups, I will dedicate this post and the next few posts in this blog series on creating and managing groups. So, please consider this as the first episode of the “sub series”. In this post, I will demonstrate a simple runbook that you can use to create instance groups and computer groups.

Runbook: New-Group

Executing Runbook

Creating Instance Group:

image

Creating Computer Group:

image

Results:

In Operations Console:

image

Management Pack – Class Definition:

image

Management Pack – Instance Group Discovery:

image

Management Pack – Computer Group Discovery:

image

Management Pack – Language Pack:

image

Additional Readings

Over the years I’ve been working with OpsMgr, I’ve booked mark the following great blog articles on creating groups in OpsMgr. You might find some of them useful:

Also, few previous posts from this blog:

Conclusion

In this post, I have demonstrated how to create computer groups and instance groups without any members. In the next post, I will demonstrate a runbook to add an explicit member to a computer group.

Automating OpsMgr Part 3: New Management Pack Runbook via SMA and Azure Automation

Written by Tao Yang

OpsMgrExntededIntroduction

This is the 3rd instalment of the Automating OpsMgr series. Previously on this series:

Today, I will demonstrate a rather simple runbook to create a blank management pack in the OpsMgr management group. Additional, I will also demonstrate executing this runbook not only on your On-Premise Service Management Automation (SMA) infrastructure, but also from an Azure Automation account via Hybrid Workers.

Since the Hybrid Worker is a very new component in Azure Automation, I will firstly give a brief introduction before diving into the runbook.

Azure Automation Hybrid Worker

Ever since Azure Automation was introduced, it was great solution for automating around your assets and fabric on Azure, but there was lack of capabilities of reaching out to your on-prem data centres. Last month during Microsoft Ignite in Chicago, Microsoft has announced an additional component: Hybrid Workers, which is a Azure Automation runbook worker that you can setup on a on-prem server computer. To find out more, you can watch this Ignite session recording: Automating Operational and management Tasks Using Azure Automation. and my buddy and fellow SCCDM MVP Stanislav Zhelyazkov has also written a good post on this topic: https://cloudadministrator.wordpress.com/2015/05/04/azure-automation-hybrid-worker-setup/

I am not going to go through the steps of setting up hybrid workers as Stan has already covered in his post. As Stan pointed out in his post, currently, any Integration Modules that you imported into your Azure Automation account does not get pushed out Hybrid Workers. Therefore in order to execute the New-OpsMgrMP runbook on your hybrid workers, after you’ve imported the OpsMgrExtended module in your Azure Automation account,  you must also need to manually copy the module to all your hybrid worker servers. To do so:

1. log on to the hybrid worker, and look up the PSModulePath environment variable. You can do so in PowerShell using $env:PSModulePath

image

2. Copy the OpsMgrExtended module to a folder that is on the PSModulePath list. Please do not copy it to any folders that are part of your user profile. I have copied it to “C:\Program Files\WindowsPowerShell\Modules” folder.

Operations Manager SDK Connection

The “Operations Manager SDK” connection must be created in the Azure Automation account, the same way as your On-Prem SMA environment:

SNAGHTML1aa0036a

The server  name I used is the FQDN of one of my OpsMgr management server. The user name is a service account I created in my on-prem Active Directory (I believe it’s called Legacy AD or LAD now Smile). i.e. Domain\ServicecAccount.  This is connection is created exactly the same as the one I created in my On-Prem SMA environment.

New-OpsMgrMP Runbook

The runbook in Azure Automation and SMA is exactly identical. Please note I have configured the Operations Manager SDK connection name to be identical on Azure Automation and SMA. you will need to update Line 11 of this runbook to the name of the connection you’ve created:

image

Executing the runbook on SMA:

Fill out the required parameters. the parameter “Version” is configured as optional in the runbook (with default value of “1.0.0.0”), so I did not enter a version number in that field:

image

Result:

image

And you can then see the management pack in OpsMgr operational console:

image

Executing Runbook on Azure Automation via Hybrid Worker:

Fill out the input parameters and select “Hybrid Worker”. As you can see, the default value for “Version” parameter has already been prepopulated in the Azure portal:

SNAGHTML1aab8ac4

Result:

image

And then the management pack appeared in OpsMgr operational console:

image

Conclusion

This is a rather simple runbook sample, the key to this runbook is the “New-OMManagementPack” activity from the OpsMgrExtended module.

For those who do not have SMA in their environment, I have just demonstrated how to leverage Azure Automation and Hybrid Workers to perform the same activities. As shown in Stan’s blog post, it’s rather easy to setup a Hybrid Worker in your environment, all you need is a Windows server with Internet connection. Unlike SMA, you do not need any database servers for Hybrid Workers.

I’d also like to point out, even if you have not opened an Azure Automation account yet, I strongly recommend you to do so and give it a try. You can go on a free tier, which gives you 500 job minutes a month. For testing and up skilling purposes, this is more than enough!

Lastly, if you would also like to see the ability to automatically push out custom modules to Hybrid workers in the future, Please help me and vote this idea in Azure  user voice:

http://feedback.azure.com/forums/246290-azure-automation/suggestions/8591839-allow-custom-integration-modules-to-be-automatical

Automating OpsMgr Part 2: SMA Runbook for Creating ConfigMgr Log Collection Rules

Written by Tao Yang

OpsMgrExntededIntroduction

This is the 2nd instalment of the Automating OpsMgr series. Previously on this series:

Few weeks ago, I have also published a post: Collecting ConfigMgr Logs To Microsoft Operation Management Suite – The NiCE Way, which demonstrated how to use an OpInsights integrated OpsMgr management group and NiCE Log File MP to collect ConfigMgr client and server logs into Microsoft Operation Management Suite.

The solution I provided in that post included few sealed management packs and a demo management pack which includes few actual event collection rules for ConfigMgr log files. However, it requires some manual XML editing outside of whatever MP authoring tool that you might be using, which could be a bit complicated for IT Pros and non management pack developers. The manual XML editing is necessary because the log collection rules use a Write Action module called “Microsoft.SystemCenter.CollectCloudGenericEvent” to send the event data to the OpInsights workspace. This write action module is located in the “Microsoft.IntelligencePacks.Types” sealed management pack. This management pack is automatically pushed to your OpsMgr management group once you’ve configured the OpInsights connection.

When using management pack authoring tools such as VSAE, if you need to reference a sealed management pack (or management pack bundle), you must have the sealed MP or MP bundle files (.mp or .mpb) handy and add these files as references in your MP project. But since the sealed MP “Microsoft.IntelligencePacks.Types” is automatically pushed to your management group as part of the OpInsights integration, and Microsoft does not provide a downloadable .mp file for this MP (yes,I have asked the OpInsights product group). There was no alternatives but manually editing the XML outside of the authoring tool in order to create these rules.

Our goal is to create potentially a large number of event collection rules for all the ConfigMgr event logs that ConfigMgr administrators are interested in. In my opinion, this is a perfect automation candidate because you will need to create multiple near-identical rules, and it is very time consuming if you use MP authoring tools and text editors to create these rules (as I explained above).

Pre-requisites

I am going to demonstrate how to create these event collection rules using a SMA runbook which uses The OpsMgrExtended PowerShell module. In order to implement this solution, you will need the following:

  • An OpsMgr 2012 SP1 or R2 management group that has been connected to Azure Operational Insights (OMS)
  • A SMA infrastructure in your environment
  • Microsoft ConfigMgr 2012 management pack version 5.0.7804.1000 imported and configured in your OpsMgr management group
  • The ConfigMgr components of which you need to collect the logs from must be monitored by the OpsMgr (including ConfigMgr servers and clients). These computers must be agent monitored. Agentless monitoring is not going to work in this scenario.
  • NiCE Log File MP imported in your OpsMgr management group
  • OpsMgrExtended module imported into SMA and an “Operations Manager SDK” SMA connection object is created for your OpsMgr management group – Please refer to Part 1 of this series for details
  • The “ConfigMgr Logs Collection Library Management Pack” must also be imported into your OpsMgr management group – Download link provided in my previous post.

 

Runbook: New-ConfigMgrLogCollectionRule

When executing this runbook, the user must specify the following parameters:

  • RuleName: the internal name of the OpsMgr rule
  • RuleDisplayName: the display name of the OpsMgr rule
  • ManagementPackName: The internal name of the management pack (must be an existing MP in your OpsMgr management group)
  • ClassName: The target class of the rule. It must be one of the following values:
    • “Microsoft.SystemCenter2012.ConfigurationManager.DistributionPoint”
    • “Microsoft.SystemCenter2012.ConfigurationManager.ManagementPoint”
    • “Microsoft.SystemCenter2012.ConfigurationManager.SiteServer”
    • “Microsoft.SystemCenter2012.ConfigurationManager.Client”
  • LogDirectory: The directory where the log is located (i.e. “C:\Windows\CCM\Logs”)
  • LogFileName: The name of the log file (i.e. “UpdatesStore.Log”)
  • EventID: The Event ID that you wish to use when converting log file entries to Windows events
  • EventLevel: Windows event level. Must be one of the following values:
    • ‘Success’
    • ‘Error’
    • ‘Warning’
    • ‘Information’
    • ‘Audit Failure’
    • ‘Audit Success’
  • IntervalSeconds: How often does the rule run

On line 16 of the runbook, I’ve coded the runbook to retrieve a SMA connection object called “OpsMgrSDK_TYANG”:

image

This is because my SMA connection object for my OpsMgr management group is named “OpsMgrSDK_TYANG”. You will need to change this line according to how you’ve created your SMA connection:

SNAGHTML10a57cfa

 

You can also further simplify the runbook in the following possible areas:

  • Hardcoding the destination management pack in the runbook
  • Hardcoding the interval seconds (i.e. to 120 seconds)
  • Create a switch statement for the target class, so instead entering “Microsoft.SystemCenter2012.ConfigurationManager.Client”, users can simply enter “Client” for example.
  • Create a switch statement for the LogDirectory parameter. for example, when the target class of “Client” is specified, set LogDirectory variable to “C:\Windows\CCM\Logs”.
  • Automatically populate Rule name and display name based on the target class and the log file name.
  • Build a user’s request portal using System Center Service Manager or SharePoint List (This would be a separate topic for another day, but Please refer to my previous MVP Community Camp presentation recording for some samples I’ve created in the past using SharePoint Lists).

Lastly, needless to say, you can also execute this PowerShell workflow in a standalone PowerShell environment (or convert this PowerShell workflow into a regular PowerShell script). When running it outside of SMA, you will need to use another Parameter Set for the “New-OMManagementPackReference” and “New-OMRule” activities. So instead of using –SDKConnection Parameter, you will have to use –SDK (and optionally –Username and –Password) to connect to your OpsMgr management group. To Change it, please modify the following lines:

Change Line 16 to $SDK = “<Your OpsMgr management server>”

Change Line 47 to:

image

$NewMPRef = New-OMManagementPackReference -SDK $SDK -ReferenceMPName “Microsoft.Windows.Library” -Alias “Windows” -UnsealedMPName $ManagementPackName

Change Line 117 to:

image

New-OMRule -SDK $USING:SDK -MPName $USING:ManagementPackName -RuleName $USING:RuleName -RuleDisplayName $USING:RuleDisplayName -Category “EventCollection” -ClassName $USING:ClassName -DataSourceModules $USING:arrDataSourceModules -WriteActionModules $USING:arrWriteActionModules -Remotable $false

Result:

After I filled out all the parameters:

image

image

image

And executed the runbook:

image

The rule was successfully created:

image

And shortly after it, you should start seeing the log entries in your OMS workspace:

image

 

Conclusion

I have demonstrated how to use the OpsMgrExtended module in a SMA runbook to enable users creating large number of similar OpsMgr management pack workflows.

Given this is only part 2 of the series, and the first example I have released, maybe I should have started with something easier. The reason I’ve chosen this example as Part 2 is because I am going to present in the next Melbourne System Center, Security, & Infrastructure user group meeting next Tuesday 7th July among with 3 other MVPs (David O’Brien, James Bannan and Orin Thomas). I am going to demonstrate this very same scenario – using OpInsights to collect SCCM log files. So I thought I’ll make this the 2nd instalment of the series, so people who attended the user group meeting have something to refer to. In this sample runbook, I’ve used a relatively more complicated activity called New-OMRule to create these event collection rules. This activity is designed as a generic method to create any types of OpsMgr rules. I will dedicate another blog post just for this one in the future.

Lastly, if you are based in Melbourne and would like to see this in action, please come to the user group meeting in the evening of 7th July. It is going to be held at Microsoft Melbourne office in South Bank. the registration details is available on the website: http://mscsig.azurewebsites.net/.

Automating OpsMgr Part 1: Introducing OpsMgrExtended PowerShell / SMA Module

Written by Tao Yang

OpsMgrExntededBackground

The OpsMgrExtended PowerShell and SMA module is a project that I have been working on since August last year. I am very glad that it is now ready to be released to the community.

This module is designed to fill some gaps in the current OpsMgr automation solutions provided natively in System Center 2012 suite. This module can be used as a System Center Service Management Automation (SMA) Integration Module, as well as a standalone PowerShell module.

Currently, the following products are available when comes to creating automation solutions for OpsMgr:

  • OpsMgr native PowerShell module
  • OpsMgr Integration Pack for System Center Orchestrator
  • OpsMgr portable Integration Module for System Center Service Management Automation

In my opinion, each of above listed serves their purpose, but also have some limitations.

OpsMgr PowerShell Module
An OpsMgr native component that can be installed on any computers running PowerShell. With the System Center 2012 R2 release, this module offers 173 cmdlets. However, most of them are designed for administrative tasks, it is lacking features such as creating management pack components (i.e. rules, monitors, etc.).

OpsMgr Integration Pack for System Center Orchestrator

Microsoft has released a version of this IP for every release of OpsMgr 2012. However, the functionalities this IP provides is very limited.

image

As you can see, it only offer 8 activities. It also requires the corresponding version of the OpsMgr operational console to be manually installed on each Orchestrator runbook server and runbook designer computer before you can executing runbooks which utilise these activities. The requirement for the operations console introduces some limitations:

  • You cannot install multiple versions of OpsMgr operations console on a same computer. – This means if you have multiple versions of OpsMgr (i.e. 2012 and 2007), you MUST use separate Orchestrator runbook servers and runbook designer computers for runbooks targeting these systems.
  • If you also need to install OpsMgr agents on these runbook servers, you can ONLY install the agent that is the same version of the operations console. – This means if you do have both OpsMgr 2007 and 2012 in your environment, the runbook servers for your OpsMgr 2007 management groups cannot be monitored by OpsMgr 2012 (unless you implement less efficient agentless monitoring for these runbook servers).

OpsMgr SMA Portable Integration Module

When SMA was released as part of System Center 2012 R2, it was shipped with an OperationsManager portable module built-in to the product.

SNAGHTMLa03ddea

The portable modules are not real modules. They are like the middle man between your runbooks and the “real” Integration Modules. It takes your input parameters and call the activities from the real module for you. i.e.

image

In order to use the OperationsManager-Portable module in SMA, you must firstly manually install the “real” OpsMgr 2012 PowerShell module on all the SMA runbook servers. One of the great feature that SMA offers is being able to automatically deploy Integration Modules to all runbook servers once been imported into SMA. But for the portable modules, this is not the case, as you must manually install the “real” modules by yourself. The other limitation is, it still only just offers whatever is available in the native OpsMgr 2012 PowerShell module.

With all these limitations in mind, I have developed a brand new custom OpsMgr PowerShell / SMA Module OpsMgrExtended to fill some of these gaps.

 

OpsMgrExtended Introduction

Back in January 2015, I have presented a work-in-progress version of this module in the Melbourne MVP Community Camp. At that time, I said it was going to be released in few weeks time. Unfortunately, I just couldn’t dedicate enough time on this project and I wanted to add few additional functions in this module, I only managed to finalise it now (5 months later). My presentation has been recorded, you can watch it and download the slide deck from my previous post: http://blog.tyang.org/2015/01/23/microsoft-mvp-community-camp-2015-session-sma-integration-module-opsmgrextended/

OpsMgr SDK Assemblies

The core component of all above mentioned native solutions is the OpsMgr SDK. All of them requires OpsMgr SDK assemblies to be installed onto the computer running the scripts and runbooks separately. This is done via the install of the OpsMgr Operations console and the PowerShell console. When you install the Operations Console or the PowerShell console onto a computer, the OpsMgr SDK assemblies are installed into the Global Assembly Cache (GAC) on this computer.

To make OpsMgrExtended module TRULLY portable and independent, I have placed the 3 OpsMgr 2012 R2 SDK DLLs into the module base folder. The PowerShell code in the OpsMgrExtended module would try to load the SDK assemblies from the GAC, but if the assemblies are not located in the GAC, it would leverage the 3 SDK DLLs that are located in the module base folder. By doing so, there is NO requirement for installing ANY OpsMgr components before you can start using this module.

Why Using OpsMgrExtended?

“If you think you will do a task twice – automate it!

When comes to automation, this is my favourite quote, from Joe Levy, a program manager in the System Center Orchestrator team. I have been managing large OpsMgr environments for many years. At my last job, I was pretty much the single point of contact for OpsMgr. Based on my own personal experience, there are a lot of repetitive tasks when managing OpsMgr infrastructures. This is why few years ago I spent few months of my spare time and developed the OpsMgr Self Maintenance MP. This MP was targeting the administrative workflows which normally carried out by OpsMgr admins.

Other than the day-to-day tasks the Self Maintenance MP has already covered, I still find a lot of repetitive tasks that do not fall into that category. for example, management packs development. I have been writing management packs for few years. Based on my own experience and the feedbacks I got from the community, I believe a lot of OpsMgr customers, or the broader community are facing the following challenges:

MP development can get very hard, and there are not many good MP developers out there.

Most of the SCOM administrators in your organisation would fall into the “IT Pro” category. MP development can get very complicated and definitely a skillset more suitable for developers  rather than IT Pro’s. There are simply not many MP developers out there. I’ve been heavily involved in the OpsMgr community for few years now, I can confidently state that if I don’t know ALL the good MP developers in the OpsMgr community, I think I know most of them. So trust me when I say there are not many around. Sometimes, I would imagine, world would be a better place if MP Development skills are as popular as ConfigMgr OSD skills (which pretty much every System Center specialist I know has got that written down on their CV’s).

It is hard to learn MP development

I’m not saying this skill is very hard to learn. But I don’t believe there are enough good & structured materials for people who wants to pick up this skill. When I started writing management packs, I was really struggling in the beginning. My friend and fellow Melbourne based MVP Orin Thomas once said to me, that he believes if you want people to start using your products, you need to make sure you invest heavily in developing trainings. I think what Orin said was spot on. I believe this is one of the main reasons that there are not many good MP developers around.

Too many toolsets

For beginners, you can use the OpsMgr operational console to write some really basic management pack elements. Most of the OpsMgr specialist who claims they can write management packs probably would use either the OpsMgr 2007 R2 Authoring Console, or the 3rd party product Silect MPAuthor. They are user-friendly, GUI based authoring tools and there are relatively easy to learn. Then for seasoned MP developers, they would normally use Visual Studio Authoring Extension (VSAE) – which is just a extension in Visual Studio, no GUI, you need to REALLY understand the management pack XML schema to be able to use this tool. not to mention Visual Studio is not free (Using it to author MPs for commercial purpose or for large organisations does not qualify you for using the free Community edition). It is hard to explain when someone completely new in this area ask me “what tool do people use to write management packs?”

How about PowerShell?

Most IT Pros should by now already very familiar with Windows PowerShell. Wouldn’t it be nice if I can use PowerShell to create OpsMgr monitors and rules? For example, if I need to monitor a Windows service, how about use a cmdlet like “New-ServiceMonitor” to create this service monitor in my OpsMgr management group?

Well, this is one of the areas I’m trying to cover in the OpsMgrExtended module.

When I was managing a large OpsMgr environment in my previous job, as much as I like developing management packs, sometimes, I still consider it as repetitive tasks. Every now and then, people would come to me and asked me to monitor service X, monitor perf counter Y, collect events Z, etc. I’ve done it once, I’ve learnt how to do it, I don’t want to do it over and over again, simply because I’m not a robot and I HATE repetitive tasks! Not to mention all the ITIL overhead that you have to put up with (i.e. testing, managing Dev, Test, Production environments, change management, release management, etc.). When there is a monitoring requirement, why can’t my customer simply fill out a request and whatever he / she needs to create gets automatically created? – Same way a normal end user would request for a piece of software to be installed on his / her PC? I don’t have to be involved (neither do I want to) when every time someone needs to get something created in OpsMgr. I’d rather spend my time working on some more complicated solutions Smile.

Another good example would be, over a year ago, I was helping a colleague from another team setting up a brand new OpsMgr 2012 environment to monitor couple of thousand servers within our organisation. My colleague has spent a lot of time, back and forth with the Windows server support team to identify their requirements. In the end, after I waited a long period of time, they finally gave me a spreadsheet which consists of 20-30 services they need to monitor. Imagine for most of the OpsMgr administrators who has never used VSAE before, this would take a lot of time and maybe a lot of copy-paste to accomplish when using Authoring Console, MPAuthor or even NotePad++. For me, although I used VSAE and I knew how to develop custom snippet templates in VSAE, still took me like 20-30 minutes to develop such snippet template, then generated MP fragment, built MP, testing, pushing to Production etc. And since our customers has already identified their requirements, I shouldn’t need to be involved at all if we have an automation solution in place.

As I demonstrated in my 2015 Melbourne MVP Community Camp presentation (demo 2, start from 28:05, link provided above), I have designed a set of tasks for customers to request new monitors:

  1. New New blank unsealed MP
  2. Create a unit monitor in a “Test” management group
  3. Created a SMA runbook that runs daily and populates the MP list of my Test MG onto a SharePoint List
  4. When customers have tested the newly created monitor and happy with it, he / she can go to the SharePoint List, locate the specific MP where the monitor is stored, and use a drop-down box to copy the MP to the production environment.

This process has covered the entire process of creating, testing and implementing the new SCOM monitoring requirements without getting OpsMgr administrators involved at all!

What functions / activities are included in this release of OpsMgrExtended

In the first release of this module, I have included 34 PowerShell functions (if you watched the presentation recording, there were 29 back in January, I’ve added few more since). These functions can be grouped into 3 categories:

SDK Connection Functions

  • Import-OpsMgrSDk
    • Load the SDK assemblies. It will firstly try to load them from GAC, if the assemblies are not in GAC, it will load them from the SDK DLLs from the module base folder.
  • Install-OpsMgrSDK
    • Install the OpsMgr SDK DLLs from the module base folder to the GAC
  • Connect-OMManagementGroup
    • Establish connection to the OpsMgr management group by specifying a management server name (and optional alternative username and password).

Administrative Tasks

  • Approve-OMManualAgents
    • Approve manually installed OpsMgr agents that meet the naming convention.
  • Backup-OMManagementPacks
    • Backup OpsMgr management packs (unsealed and sealed).
  • Add-OMManagementGroupToAgent
    • Configure an OpsMgr agent to report to a specific management group using WinRM.
  • Remove-OMManagementGroupFromAgent
    • Remove a management group configuration from an OpsMgr agent using WinRM.
  • Get-OMManagementGroupDefaultSettings
    • Get OpsMgr management group default settings via OpsMgr SDK. A System.Collections.ArrayList is returned containing all management group default settings. Each setting in the arraylist is presented in a hashtable format.
  • Set-OMManagementGroupDefaultSetting
    • Set OpsMgr management group default settings.

Basic Authoring Tasks

  • Get-OMManagementPack
    • Get a particular management pack by providing the management pack name or get all management pack in an OpsMgr management group using OpsMgr SDK.
  • New-OMManagementPack
    • Create a new unsealed management pack in an OpsMgr management group.
  • Remove-OMManagementPack
    • Remove a management pack from an OpsMgr management group.
  • Copy-OMManagementPack
    • Copy an unsealed management pack from a source OpsMgr management group to the destination. management group.
  • New-OMManagementPackReference
    • Add a management pack reference to an unsealed management pack.
  • New-OM2StateEventMonitor
    • Create a 2-state event monitor in OpsMgr.
  • New-OM2StatePerformanceMonitor
    • Create a 2-state performance monitor in OpsMgr.
  • New-OMPerformanceCollectionRule
    • Create a performance collection rule in OpsMgr.
  • New-OMEventCollectionRule
    • Create an event collection rule in OpsMgr.
  • New-OMServiceMonitor
    • Create a Windows service monitor in OpsMgr.
  • New-OMInstanceGroup
    • Create an empty instance group in OpsMgr using OpsMgr SDK. The group membership must be populated manually or via another script.
  • New-OMComputerGroup
    • Create an empty computer group in OpsMgr using OpsMgr SDK. The group membership must be populated manually or via another script.
  • New-OMConfigurationOverride
    • Create a configuration (parameter) override in OpsMgr using OpsMgr SDK.
  • New-OMPropertyOverride
    • Create a property override in OpsMgr using OpsMgr SDK.
  • New-OMOverride
    • Create an override in OpsMgr using OpsMgr SDK. This function would detect whether it’s a property override or configuration override and call New-OMPropertyOverride or new-OMConfigurationOverride accordingly.
  • Remove-OMGroup
    • Remove an instance group or computer group in OpsMgr using OpsMgr SDK.
  • Remove-OMOverride
    • Remove an override in OpsMgr.
  • Get-OMDAMembers
    • Get monitoring objects that are members of a Distributed Application in OpsMgr using OpsMgr SDK. By default, this function only retrieves objects one level down. Users can use -Recursive parameter to retrieve all objects within the DA hierarchy.
  • New-OMAlertConfiguration
    • Create a new OpsMgrExtended.AlertConfiguration object that can be passed to the New-OMRule function as an input. This object is required for the New-OMRule function when creating an alert generating rule.
  • New-OMModuleConfiguration
    • Create a new OpsMgrExtended.ModuleConfiguration object that can be passed to the New-OMRule function as an input.
  • New-OMRule
    • Create a rule in OpsMgr by specifying data source modules, optional condition detection module, write action modules and also alert configuration when creating an alert generating rule. This function can be used to create any types of rules in OpsMgr.
  • New-OMWindowsServiceTemplateInstance
    • Create a Windows Service monitoring template instance in OpsMgr.

Advanced Authoring Tasks

  • New-OMTCPPortCheckDataSourceModuleType
  • New-OMTCPPortCheckMonitorType
  • New-OMTCPPortMonitoring

Last year, when I asked few OpsMgr focused MVPs for advice and feedbacks, my buddy Dieter Wijckmans suggested me to create a function that creates a TCP Port monitoring template instance. When I had a look, I did not like the MP elements created by this template. As I explained in my MVP Community Camp presentation (Demo 3, starts at 47:13 in the recording), I didn’t like the module type and monitor types created by the TCP Port monitoring template because many values have been hard coded in the modules and the monitor types did not enable On-Demand detections. Therefore, instead of creating an instance of this template using SDK, I’ve taken the hard route, spent a week, written 1,200 lines of PowerShell code, recreated all the MP elements the way I wanted.

When you use New-OMTCPPortMonitoring function from this module, it creates the following items:

  • Class Definition for TCP Port Watcher and various groups
  • Class Relationships
  • Class and Relationship Discoveries
  • Data Source Module Type
  • Monitor Type
  • Performance Collection Rule
  • 4 Unit Monitors and a dependency monitor
  • Discovery Overrides

The monitors created by New-OMTCPPortMonitoring supports On-Demand detection (which can be triggered by clicking the “Recalculate Health” button in Health Explorer), and I have variablised the data source module type and monitor type, so they can be reused for other workflows.

Establishing Connections to OpsMgr Management Groups

Configuring SMA Integration Module

When using this module in SMA, you may create a connection object to your OpsMgr management group.

image

image

  • Connection Type: Operations Manager SDK
  • Name: Name of this SMA connection object
  • Description: Description of this SMA connection
  • ComputerName: One of the OpsMgr management servers
  • UserName: A Service Account that has OpsMgr administrator access
  • Password: Password for the service account

 

Connecting in Normal PowerShell Scripts

When this module is used as a normal PowerShell module, all the functions that require OpsMgr management group connections support the following 3 parameters:

  • SDK: One of the OpsMgr management servers
  • -Username (optional): Alternative account to connect to OpsMgr management group.
  • -Password (optional): the password for the alternative account.

 

Getting Help and More Information

I have included help information for every function in this module. You can access if using Get-Help cmdlet.

i.e. Get-help New-OMRule –Full

SNAGHTMLeaa1c1f

Once imported in SMA, you can also see the description for each function in the WAP Admin portal:

SNAGHTMLeaf2cd0

SNAGHTMLeb0d60c

Getting Started

I have written many sample runbooks for this module. Initially, my plan was to release these sample runbooks together with the module. Then I had a second thought, I think instead of releasing these samples now, I will make this a blog series and continue writing posts explaining how to use this module for different scenarios. I believe by doing so, it will help readers better understand the capability this module brings. I will name this series “Automating OpsMgr” and consider this is Part 1 of this series.

System Requirements

The minimum PowerShell version required for this module is 3.0.

The entire module and sample runbooks were developed on Windows Server 2012 R2, Windows 8.1, OpsMgr 2012 R2 and PowerShell version 4.0.

I have not test this module on OpsMgr 2012 RTM and SP1. Although the SDK assembly version is the same between RTM, SP1 and R2, I cannot guarantee all functions and upcoming sample runbooks would work 100% on RTM and SP1 versions. If you have identified any issues, please let me know.

I have performed very limited testing on PowerShell 5.0 Preview. I cannot guarantee it will work with PowerShell 5.0 100%. But if you manage to find any issues on PowerShell 5.0, please let me know.

 

Where Can I Download this Module?

This module can be downloaded from TY Consulting’s web site from link below:

DOWNLOAD HERE.

I’m releasing this module under Apache License Version 2.0. If you do not agree with the term, please do not download or use this module.

Because this module requires OpsMgr 2012 SDK DLLs, and I am not allowed to distribute these DLLs (refer to System Center 2012 R2 Operations Manager EULA Section 7 Scope of License, which can be located on the OpsMgr 2012 R2 DVD under Licenses folder).

image

Therefore, once you’ve downloaded this module, you will need to manually copy the following 3 DLLs into the module folder:

  • Microsoft.EnterpriseManagement.Core.dll
  • Microsoft.EnterpriseManagement.OperationsManager.dll
  • Microsoft.EnterpriseManagement.Runtime.dll

These DLLs can be found on your OpsMgr management server, under <OpsMgr Install Dir>\Server\SDK Binaries:

image

Copy them into the module folder:

image

If it’s intended to be used in SMA, you will need to zip the folder back after DLLs been copied to the folder, then import the module in SMA.

Looking back, this has has been a very long journey – I have written around 6,800 lines of code for this module alone, not including all the sample runbooks that I’m going to publish for this blog series. I hope the community would find it useful, and please feel free to contact me if you have any new ideas or suggestions.

This is all I have for the Part 1 of this new series. In the next couple of days, I will discuss how to use the OpsMgrExtended module to create ConfigMgr log collections rules for OMS (As I previously blogged here.)

Various Ways to Find the ID of a Monitoring Object in OpsMgr

Written by Tao Yang

Often when working in OpsMgr, we need to find the ID of a monitoring object. For example, in the recent Squared Up Dashboard  version 2.0 Customer Preview webinar (https://www.youtube.com/watch?v=233oTAefrRM), it was mentioned in the webinar that the monitoring object IDs must  be located when preparing the Visio diagram for the upcoming Visio plugin.

In this post, I’ll demonstrate 3 methods to retrieve the monitoring object ID from SCOM. These 3 methods are:

  • Using OpsMgr built-in PowerShell Module “OperationsManager”
  • Using OpsMgr SDK via Windows PowerShell
  • Using SCSM Entity Explorer

In the demonstrations, I will show how to retrieve the monitoring object ID for a particular SQL database:

  • Monitoring Class Display Name: SQL Database
  • DB name: master
  • DB Engine: MSSQLSERVER
  • SQL Server: SQLDB01.corp.tyang.org

image

Note: Before I start digging into this topic, if you are not very PowerShell savvy, and only want a simple GUI based solution, please go straight to the last method (using SCSM Entity Explorer).

 

Using OpsMgr PowerShell Module OperationsManager

01. Define variables and connect to the management server:

02. Get the monitoring class based on its display name:

However, in my management group, there are 2 classes with the same name “SQL Database”:

image

As you can see, the first item in the array $MonitoringClasses is the correct one in this case. We will reference it as $MonitoringClasses[0].

03. Get the monitoring object for the particular database:

The Get-SCOMClassInstance cmdlet does not take any criteria, therefore, the command above retrieves all instances of the SQL Database class, then filter the result based on the database name, SQL server name and SQL DB instance name to locate the particlar database that we are looking for.

image

The monitoring object ID is highlighted as above.

image

The type for the ID field is Guid. You can also convert it to a string as shown above.

 

Using OpsMgrSDK Via Windows PowerShell

In this example, I won’t spend too much time on how to load the SDK assemblies, in the script, I’m assuming the SDK DLLs are already loaded into the Global Assembly Cache (GAC). So, in order to use this script, you will need to run this on an OpsMgr management server or a web console server, or a computer that has operations console installed.

01. Define variables, load SDK assemblies and connect to OpsMgr management group:

02. Get the monitoring class based on the display name

image

As you can see, since the display name is not unique, 2 classes are returned from the search (this is same as the first method), except this time, the type for $MonitoringClass varible is a ReadOnlyCollection. However, we can still reference the correct monitoring class using $MonitoringClass[0]

image

03. Get the monitoring object for the particular database:

Please refer to this page for the properties that you can use to build the search criteria (MonitoringObjectGenericCriteria)

As you can see, unlike the first method using the built-in module, we can specify a more granular search criteria to locate the monitoring object (as result, the command execution should be much faster). However, please keep in mind although there is only one monitoring object returned from the search result, the $MonitoirngObject variable is still a ReadOnlyCollection:

image

And you can access the particular SQL Database (Monitoring Object) using $MonitoringObject[0]:

image

 

Using SCSM Entity Explorer

SCSM Entity Explorer is a free utility developed by Dieter Gasser. You can download it from TechNet Gallery: https://gallery.technet.microsoft.com/SCSM-Entity-Explorer-68b86bd2

Although as the name suggested, it was developed for SCSM, it also works with OpsMgr. Once you’ve downloaded it and placed on a computer, you can follow the instruction below to locate the particular monitoring object.

01. Connect to an OpsMgr management server and search the monitoring class using display name

image

As shown above, there are 2 classes returned when searching the display name “SQL Database”. You can find the correct one from the full name on the right.

02. Load objects for the monitoring class:

Go to the objects class and click on “Load Objects” button to load all instances.

image

Unfortunately, the we cannot modify what properties to be displayed on the objects list, and the display name does not contain the SQL server and DB instance name. In this scenario, the only way to find the correct instance is to open each one using the “View Details” button.

image

Once you’ve located the correct instance, the monitoring object ID is displayed on the objects list.

Having said that, if you are looking for a monitoring object from a singleton class (where there can only be 1 instance in the MG, such as a group), this method is probably the easiest out of all 3.

i.e. When I’m looking for a group I created for the Hyper-V servers and their health service watchers, there is only instance:

image

Also, for certain monitoring objects (such as Windows Server), you can easily locate the correct instance based on the display name:

image

Conclusion

based on your requirements (and the information available for search), you can choose one of these methods whichever you think it’s the best.

Lastly,  if you know other ways to locate monitoring object ID, please leave a note here or send me an email.

PowerShell Script to Extract CMDB Data From System Center Service Manager Using SDK

Written by Tao Yang

Background

In my previous post Writing PowerShell Module That Interact With Various SDK Assemblies, I’ve explained how to create a PowerShell module that embeds various SDK DLLs and I’ve used System Center Service Manager SDK as an example. Well, the reason that I created the module for Service Manager SDK is because I needed to write a script to extract CMDB data from Service Manager. In this post, I’ll go through what’ I’ve done and the script can also be downloaded at the end of the article.

So, I needed to write a script to export configuration items from Service Manager, I have the following requirements:

  • The script must be generic and extendable to be able to extract instances of any CI classes.
  • The properties (to be exported) of each class should also be configurable.
  • Supports delta export (Only export what’s changed since last execution).
  • Be able to also export CI Relationships
  • Be able to filter unwanted relationships (from being exported).

After evaluating different options, I have decided to directly interact with Service Manager SDK in the script instead of using the native Service Manager PowerShell module and the community based module SMLets.

Pre-requisite

As I just mentioned, this script requires the SMSDK module I have created previously (you will have to locate the SDK DLLs from your Service Manager management server and copy them to the module folder as I explained in the previous post).

Configuration

In order to make the script generic while being extendable, I’ve used a XML file to define various configurations for the script:

image

I have added a lot of comments in this XML file so it should be very self-explanatory. Just few notes here:

  • This XML configuration file must be placed in the same folder as the script.
  • For each property that you wish to be exported from Service manager, list them under <Properties><PropertyName> tag.
  • This script also exports the relationships associated with each CI object that is exported. However, only the relationships where the exported CI object is the source object are exported.
  • Both <PropertyName> and <CIClassName> are the internal names, Please do not use the display names.
  • You can use the SCSM Entity Explorer (Free download from TechNet Gallery) to identify what are the internal names for the class and property that you wish to export.

image

 

Script

Since I have written a lot of scripts using OpsMgr SDK in the past, I didn’t find Service Manager SDK too hard (although this is only the second time I’ve written scripts for Service Manager). The script itself is fairly simple and short:

 

To execute the script, simply pass the service management server name (user name and password are optional), and you can also use -verbose if you’d like to see verbose messages:

.\SMConfigItemExtract.ps1 -ManagementServer SCSMMS01 -verbose

Outputs

This script will create a separate CSV file for each CI class that’s configured in the XML. It will also create a single CSV file for ALL relationships export:

image

SNAGHTML1484a713

The script also writes the execution time stamp to the config.xml under <LastSyncFileDateUTC>. When the script runs next time, it will retrieve this value and only export the configuration items that have been changed after this time stamp. If you need to force a full sync, please manually remove the value in this tag:

image

Download

You can download the prerequisite SMSDK PowerShell module HERE.

You can download the script and the config.xml file HERE.

Writing PowerShell Modules That Interact With Various SDK Assemblies

Written by Tao Yang

Over the last few months, there have been few occasions that I needed to develop PowerShell scripts needed to leverage SDK DLLs from various products such as OpsMgr 2012 R2, SCSM 2012 R2 and SharePoint Client Component SDK.

In order to be able to leverage these SDK DLLs, it is obvious that prior to running the scripts, these DLLs must be installed on the computers where the scripts are going to be executed. However, this may not always be possible, for example:

  • Version Conflicts (i.e. OpsMgr): The OpsMgr SDK DLLs are installed into computer’s Global Assembly Cache (GAC) as part of the installation for the Management Server, Operations Console or the Web Console. However, you cannot install any components from multiple OpsMgr versions on the same computer (i.e. Operations console from OpsMgr 2012 and 2007).
  • Not being able to install or copy SDK DLLs (i.e. Azure Automation): If the script is a runbook in Azure Automation, you will not be able to pre-install the SDK assemblies on the runbook servers.

 

In order to be able to overcome these constraints, I have developed a little trick: developing a simple PowerShell module, placing the required DLLs in the PS module folder and use a function in the module to load the DLLs from the PS Module base folder. I’ll now explain how to develop such PS module. I’ll use the custom module I’ve created for the Service Manager 2012 R2 SDK last week as an example. In this example, I named my customised module “SMSDK”.

01. Firstly, create a module folder and then create a new PowerShell module manifest using “New-ModuleManifest” cmdlet.

02. Copy the  required SDK DLLs into the PowerShell Module Folder. The module folder would also contain the manifest file (.psd1) and a module script file (.psm1).

SNAGHTML12c34a9

03. Create a function to load the DLLs. In the “SMSDK” module that I’ve written, the function looks like this:

As you can see, In this function, I have hardcoded the DLL file names, assembly version and public key token. The script will try to load the assemblies (with the specific names, version and public key token) from the Global Assembly Cache first (line 32). If the assemblies are not located in the GAC, it will load the assemblies from the DLLs located in the PS Module folder (line 38).

The key to this PS function is, you must firstly identify the assemblies version and public key token. There are 2 ways to can do this:

  • Using the PowerShell GAC module on a machine where the assemblies have already been loaded into the Global Assembly Cache (i.e. in my example, the Service Manager management server):

image

  • Load the assemblies from the DLLs and then get the assemblies details from the current app domain:

image

Note: although you can load the assemblies from the GAC without specifying the version number, in this scenario, you MUST specify the version to ensure the correct version is loaded. It happened to me before when I developed a script that uses OpsMgr SDK, it worked on most of the computers but one computer. It took me a while to find out because the computer had both OpsMgr and Service Manager SDKs loaded in the GAC, the wrong assembly was loaded because I didn’t not specify the version number in the script.

Now, Once the Import SDK function is finalised, you may call it from scripts or other module functions. For example, in my “SMSDK” module, I’ve also created a function to establish connection to the Service Manager management group, called Connect-SMManagementGroup. This function calls the Import SDK (Import-SMSDK) function to load assemblies before connecting to the Service Manager management group:

For your reference, You can download the sample module (SMSDK) HERE. However, the SDK DLLs are not included in this zip file. For Service Manager, you can find these DLLs from the Service Manager 2012 R2 Management Server, in the <SCSM Management Server Install Dir>\SDK Binaries folder and manually copy them to the PS module folder:

image

Lastly, this blog is purely based on my recent experiences. Other than the Service Manager module that I’ve used in this post, I’ve also used this technique in few of my previous work, i.e. the “SharePointSDK” module and the upcoming “OpsMgrExtended” module that will soon be published (You can check out the preview from HERE and HERE). I’d like to hear your thoughts, so please feel free to email me if you’d like to discuss further.

A SMA Integration Module For SharePoint List Operations

Written by Tao Yang

Background

Many Microsoft System Center Orchestrator and Service Management Automation (SMA) users may agree with me, that these two automation platform does not have feature rich end user portals natively. Although System Center Service Manager can be used as a user portal for triggering SCORCH/SMA runbooks, Microsoft SharePoint is also a very good candidate for this purpose.

Integrating SharePoint with Orchestrator and SMA is not something new, many people have done this already. i.e.

System Center Universe America 2014 – Orchestrating Daily Tasks Like a Pro (by Pete Zerger and Anders Bengtsson)

Service Management Automation and SharePoint (by Christian Booth and Ryan Andorfer)

In my opinion, SharePoint (especially SharePoint lists) provides a quick and easy way to setup a web based end user portal for orchestration runbooks. I have also blogged my experiences in the past:

My Experience Manipulating MDT Database Using SMA, SCORCH and SharePoint

SMA Runbook: Update A SharePoint 2013 List Item

To me, not only I am using SharePoint 2013 in my lab; SharePoint Online from my Office 365 subscription, I also have no choice but using SharePoint 2010 in real life.

In my opinion, it is complicated to write SMA runbooks to interact with SharePoint (Using SharePoint web based APIs), not to mention the different versions of SharePoint also dictates how the runbook should be written. It is easier to use Orchestrator as a middle man in between SMA and SharePoint so we can use Orchestrator’s SharePoint integration pack.

Earlier this month, I was developing solutions to use SMA and Azure Automation to create OpsMgr Management Packs catalog on SharePoint 2013 / SharePoint Online sites. I have blogged the 2 solutions here:

On-Premise Solution (SMA + SharePoint 2013)

Cloud Based Solution (Azure Automation + SharePoint Online)

As I mentioned in the previous posts, I had to write a separate SMA module to be used in Azure Automation to interact with SharePoint Online because SharePoint Online sites require a different type of credential (SharePointOnlineCredential) that the PowerShell cmdlet Invoke-RESTMethod does not support. I called that module SharePointOnline back in the previous post and it utilises assemblies from the SharePoint Client Component SDK. I think the SharePoint people also refer to this SDK as Client-Side Object Model (CSOM)

After the MP catalogs posts were published, I have decided to spend a bit more time on the SharePoint Client Component SDK and see if it can help me simplify the activities between SMA and SharePoint. I was really happy to find out, the SharePoint Client Component SDK works for SharePoint 2013, SharePoint Online and SharePoint 2010 (limited). So I have decided to update and extend the original module, making it a generic module for all 3 flavours of SharePoint.

After couple of weeks of coding and testing, I’m pleased to announce the new module is now ready to be released. I have renamed this module to SharePointSDK (Sorry I’m not really creative with names Smile with tongue out).

 

SharePointSDK Module Introduction

The SharePointSDK module contains the following functions:

image

CRUD Operations for SharePoint List items:

Function Description Compatible SharePoint Version
Add-SPListItem Add an item to a SharePoint list 2010, 2013 and SP Online
Get-SPListFields Get all fields of a SharePoint list 2010, 2013 and SP Online
Get-SPListItem Get all list items of a SharePoint list or a specific item by specifying the List Item ID 2010, 2013 and SP Online
Remove-SPListItem Delete an item from a SharePoint list 2010, 2013 and SP Online
Update-SPListItem Update one or more field values of a SharePoint list item 2010, 2013 and SP Online

The functions listed above are the core functionalities this module provides. it provides simplified ways to manipulate SharePoint list items (Create, Read, Update, Delete).

Miscellaneous Functions

Function Description Compatible SharePoint Version
Import-SPClientSDK Load SharePoint Client Component SDK DLLs 2010, 2013 and SP Online
New-SPCredential Based on the type of SharePoint site (On-Prem vs SP Online), create an appropriate credential object to authenticate to the Sharepoint site. 2010, 2013 and SP Online
Get-SPServerVersion Get SharePoint server version 2010, 2013 and SP Online

These functions are called by other functions in the modules. It is unlikely that runbook authors will need to use them directly.

SharePoint List Attachments Operations

Function Description Compatible SharePoint Version
Add-SPListItemAttachment Add an attachment to a SharePoint list item 2013 and SP Online
Get-SPListItemAttachments Download all attached files from a SharePoint list item 2013 and SP Online
Remove-SPListItemAttachment Delete an attached file (based on file name) from a SharePoint list item 2013 and SP Online

As the names suggest, these functions can be used to manage attachments for SharePoint list items.

I’d like to point out  that the Add-SPListItemAttachment function not only support uploading an existing file to the SharePoint list item. it can also be used to create an attachment file directly using a byte array. This function can be used in 3 scenarios:

  • Uploading an existing file from the file system
  • Directly creating a text based file with some contents as a list item attachment.
  • Read the content of an existing binary (or text)  file, save it as a attachment with a different name

 

Configuration Requirements

Download and Prepare the module

The module zip file should consist the following 5 files:

image

  • Microsoft.SharePoint.Client.dll – One of required DLLs from the SDK
  • Microsoft.SharePoint.Client.Runtime.dll – One of required DLLs from the SDK
  • SharePointSDK.psd1 – Module Manifest file
  • SharePointSDK.psm1 – PowerShell module file
  • SharePointSDK-Automation.json – SMA Integration Module Meta File (where the connection asset is defined).

Download SharePointSDK Module

Note:

The zip file you’ve downloaded from the link above DOES NOT contain the 2 DLL files. I am not sure if Microsoft is OK with me distributing their software / intellectual properties. So, just to cover myself, you will need to download the SDK (64-bit version) from Microsoft directly (https://www.microsoft.com/en-us/download/details.aspx?id=35585), install it on a 64-bit computer, and copy above mentioned 2 DLLs into the SharePointOnline module folder.

Once the SDK is installed, you can find these 2 files in “C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI\” folder.

Once the DLLs are placed into the folder, zip the SharePointSDK folder to SharePointSDK.zip file again, and the integration module is ready.

image

Import Module

Once the DLLs are zipped into the module zip file, import the module into SMA by using the Import Module button under Assets tab

image

Create a Connection object to the SharePoint site

After the module has been successfully, a connection to SharePoint Site must be created. The Connection type is “SharePointSDK”

image

The following fields must be filled out:

  • Name: Name of the connection.
  • SharePointSiteURL: URL to your sharepoint site
  • UserName : a User who should be part of the site members role (members group have contribute access).
    • If the site is a SharePoint Onine site, this username MUST be in the email address format. (i.e. yourname@yourcompany.com). I believe this account must be an account created in the Office 365 subscription. I have tried using an outlook.com account (added as a SharePoint site member), it didn’t work.
    • When connecting to a On-Prem SharePoint site, you can use the Domain\UserName format (As shown in the screenshot below)
  • Password: Password for the username you’ve specified.
  • IsSharePointOnlineSite: Boolean field (TRUE or FALSE), specify if it is a SharePoint Online site.

i.e. the connection to a SharePoint site in my lab:

image

Sample Runbooks

In order to better demonstrate this module, I have also created 10 sample runbooks:

image

Download Sample runbooks

I’ll now go through each sample runbook.

Runbook: Sample-SPNewUserRequestList

This sample runbook creates a brand new dummy new users requests list on your SharePoint site. The list created by this runbook will then be used by other sample runbooks (for demonstration purposes).

This runbook is expecting 2 input parameters:

  • ListName: The Display Name that you’d like to name the new users requests list (i.e. New Users OnBoarding Requests).
  • SPConnection: The name of the SharePointSDK connection that you’ve created previously (i.e. Based on the connection I’ve created in my lab as shown previously, it is “RequestsSPSite”

image

This runbook creates a list with the following fields:

image

Runbook: Sample-SPGetListFields

This runbook demonstrates how to retrieve all the fields of a particular list.

image

Runbook: Sample-SPAddListItem

This runbook adds an item to the New Users Requests list the previous runbook created. It also demonstrates how to create a text file attachment directly to the list item (without having the need for an existing file on the file system).

It is expecting the following inputs:

  • Title (New users title, i.e. Mr. Dr. Ms, etc)
  • FirstName (New user’s first name)
  • LastName (New user’s last name)
  • Gender (New user’s Gender: Male / Female)
  • UserName (New user’s user vname)
  • AttachmentFileName (file name of the text based attachment)
  • TextAttachmentContent (content of the text file attachment)
  • NewUserListName (display name of the new users requests list. i.e. New Users OnBoarding Requests)
  • SPConnection (The name of the SharePointSDK connection that you’ve created previously (i.e. Based on the connection I’ve created in my lab as shown previously, it is “RequestsSPSite”)

i.e.

image

The list item is created on SharePoint:

SNAGHTML1d5a6df8

Attachment content:

image

Runbook: Sample-SPUpdateListItem

This runbook can be used to update fields of an existing list item on the New Users Requests list.

Runbook: Sample-SPGetAllListItems

This runbook can be used to retrieve ALL items from a list. Each list item are presented as a hash table.

image

Runbook: Sample-SPGetListItem

This runbook can be used to retrieve a single item from a list.

image

Runbook: Sample-SPDeleteListItem

This runbook deletes a single list item by specifying the List Item ID.

Runbook: Sample-SPAddListItemAttachment

This runbook demonstrates 2 scenarios:

  • Directly attaching a file to a list item
  • attach and rename a file to a list item

image

image

Runbook: Sample-SPDeleteListItemAttachments

This runbook demonstrates how to delete an attachment from a list item (by specifying the file name).

Runbook: Sample-SPDownloadListItemAttachments

This runbook demonstrates how to download all files attached to a list item:

image

Files downloaded to the destination folder:

image

Benefit of Using the SharePointSDK Module

Using as a Regular PowerShell Module

As we all know, SMA modules are simply PowerShell modules (sometimes with optional SMA module meta file .json for creating connections). Although this module is primarily written for SMA, it can also be used in other environments such as a regular PowerShell module or in Azure Automation. When using it as a normal PowerShell module, instead of passing the SMA connection name into the functions inside the module, you may provide each individual value separately (Username, password, SharePoint Site URL, IsSharePointOnlineSite).

Simplified scripts to interact with SharePoint

When using this module, most of the operations around the list item only takes very few lines of code.

i.e. Retrieving a list item:

Using PowerShell:

Using PowerShell Workflow (in SMA):

If you use SharePoint 2013’s REST API, the script will be much longer than what I’ve shown above.

Same Code for Different SharePoint Versions

The SharePoint REST API has been updated in SharePoint 2013. Therefore, if we are to use the REST API, the code for Share Point 2013 would look different than SharePoint 2010. Additionally, when throwing SharePoint Online into the mix, as I mentioned previously, it requires different type of credential for authentication, it further complicates the situation if we are to use the REST API. This makes our scripts and runbooks less generic.

By using this SharePointSDK module, I am able to use the same runbooks on SharePoint 2010, 2013 and SharePoint Online sites.

Limitations

During testing, I noticed the 3 attachments related functions in the SharePointSDK module would not work on SharePoint 2010 sites. These functions are:

  • Add-SPListItemAttachment
  • Remove-SPListItemAttachment
  • Get-SPListItemAttachments

After a bit of research, looks like it is a known issue. I didn’t think it too much a big deal because all the core functions (CRUD operations for the list items) work with SharePoint 2010. Therefore, in these 3 functions, I’ve coded a validation step to exit if the SharePoint Server version is below version 15 (SharePoint 2013):

image

Conclusion

If you are using SMA and SharePoint together, I strongly recommend you to download this module and the sample runbooks and give it a try. If you have a look at the sample runbooks, I’m sure you will realise how easy it is to write PowerShell code interacting with SharePoint.

In case you didn’t see the download links, you can download them here:

Download SharePointSDK Module

Download Sample Runbooks

Lastly, I’m not a SharePoint specialist. If you believe I’ve made any mistakes in my code, or there is room for improvement, I’d like to hear from you. Please feel free to drop me an email Smile.

Using Royal TS for PowerShell Remote Sessions

Written by Tao Yang

Background

I have used many Remote Desktop applications in the past. I have to say Royal TS is the one that I like the most! Recently, I showed it to one of my colleagues, after a bit of playing around, he purchased a license for himself too.

Today, my colleague asked me if I knew that Royal TS is also able to run external commands, and he thought it’s pretty cool that he’s able to launch PowerShell in the Royal TS window. Then I thought, if you can run PowerShell in Royal TS, we should be able to establish PS remote sessions in Royal TS too. Within 10 minutes, we managed to create few connections in Royal TS like these:

SNAGHTML1c209a8d

SNAGHTMLa497d178

image

SNAGHTML1c2e5543

In this post, I’ll go through the steps I took to set them up.

Connections to Individual Servers

To create a connection to an individual server,

01. Choose add->External Application:

image

02. Enter the following Details:

Display Name: The name of the server you want to connect to.

Command: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

Arguments: -NoExit -Command “Enter-PSSession $CustomField1$”

Working Directory: C:\Windows\System32\WindowsPowerShell\v1.0

On the icon button next to the display name, choose “Use Application Icon” if you want to.

image

image

03. Choose a Credential if you want to connect using an alternative credential

SNAGHTML1c5136c4

If you choose to use an alternative credential,  you must also tick “Use Credentials” box under Advanced tab:

image

04. Enter the remote server name in Custom Field 1:

image

Note: in the arguments field from step 01, I’ve used a Royal TS variable $CustomField1$ as the name of the computer in the Enter-PSSession command. It is more user friendly to use the Custom Field for the computer name, rather than modifying the argument string for each connection that you wish to create.

Create An Ad-Hoc Connection

You can also create a connection in Royal TS for Ad-Hoc connections. In this scenario, you will need to enter the remote computer that you wish to connect to:

image

After the the computer name has been entered, the connection is then established:

image

To create this connection in Royal TS, instead of using the Custom Field 1 for the computer name, I’ve added an additional PowerShell command in the Arguments:

Arguments: -NoExit -Command “$Computer = Read-Host ‘Please enter the Computer Name’; Enter-PSSession $Computer”

image

The Custom Field 1 is no longer required in this scenario. Everything else is the same as the previous sample (for individual computers).

Other Considerations

Maximised PowerShell Window

You may have noticed from the screenshots above, that the PowerShell windows are perfectly fitted in the Royal TS frame. this is because I am also using a customised PS Module that I’ve written in the past to resize the PoewerShell window. Without this module, the PowerShell console would not automatically fit into the Royal TS frame:

image VS image

If you like your console looks like the left one rather than one on the right, please follow the instruction below.

01. Download the PSConsole Module and place it under C:\windows\system32\WindowsPowerShell\v1.0\Modules

image

02. Modify the “All Users Current Host” profile from a normal PowerShell window (NOT within PowerShell ISE). If you are not sure if this profile has been created, run the command below:

image

After the profile is created, open it in notepad (in PowerShell window, type: Notepad $Profile.AllUsersCurrentHost) and add 2 lines of code:

image

After saving the changes, next time when you initiate a connection in Royal TS, the console will automatically maximise to use all the usable space.

Note: Because most likely you will be using an alternative (privileged credential) for these PS remote sessions. therefore the resize console commands cannot be placed into the default profile (current user current host). It must be placed into an All users profile. And also because the resize command only works in a normal PowerShell console (not in PowerShell ISE), therefore the only profile that you can use is the “All Users Current Host” profile from the normal PowerShell console.

Alternatively, if you do not wish to make changes to the All Users Current host profile, you can also add the above mentioned lines into the Royal TS connection arguments field:

i.e.

Arguments: -NoExit -Command “import-module psconsole; resize -max; Enter-PSSession $CustomField1$”

image

Duplicating Royal TS Connections

If you want to create multiple connections, all you need to do is to create the first one manually, and then duplicate it multiple times:

image

When duplicating connections, the only fields you need to change are the Display Name and CustomField1.

WinRM configuration

Needless to say, WinRM must be enabled and properly configured for PS remoting to work. this is a pre-requisite. I won’t go through how to configure WinRM here. Someone actually wrote a whole book on this topic.

Conclusion

I’d like to thank Stefan Koell (blog, twitter), the Royal TS developer (and also my fellow SCCDM MVP) for such an awesome tool. This is now probably THE most used application on all my computers Smile.

If you haven’t tried Royal TS out, please give it a try. Other than the obvious Windows version, there are also a Mac version, an iOS version and an Android version.

A Simplified Way to Send Emails and Mobile Push Notifications in SMA

Written by Tao Yang

Background

For those who knows me, I’m an OpsMgr guy. I spend a lot of time in OpsMgr and I am very used to the way OpsMgr sends notifications (using notification channels and subscribers).

In OpsMgr, I like the idea of saving the SMTP configuration and notification recipients’ contact details into the system so everyone who has got enough privilege can use these configurations (when configuring alert subscriptions).

Over the last few months, I have spent a lot of time on SMA (Service Management Automation). As I started building more and more runbooks and integration modules, I really miss the simple way of sending notifications in OpsMgr. Although there is a built-in PowerShell cmdlet for sending emails (Send-MailMessage), it requires a lot of input parameters, and the runbook author needs to have all the SMTP information available. I thought it would be nice if I could save SMTP settings as connection objects (similar to notification channels in OpsMgr), and recipients’ contact details (email and mobile device push notification services’ api keys) also as connection objects (similar to subscribers in OpsMgr).

To achieve my goals, I have created 2 SMA Integration modules:

Module Name Connection Type Name PowerShell Functions
SendEmail SMTPServerConnection Send-Email
SendPushNotification SMAAddressBook Send-MobilePushNotification

SendEmail Module

This module defines a connection type where can be used to save all SMTP related information:

  • SMTP Server address
  • Port
  • Authentication Method (Anonymous, Integrate or Credential)
  • User name
  • Password
  • Sender Name
  • Sender Address
  • UseSSL (Boolean)

SNAGHTML1ba0bfc7

image

SNAGHTML1ba1992f

This module also provides a PowerShell function called “Send-Email”. Since when retrieving an automation connection in SMA, a hash table is returned, Not only you can pass individual SMTP parameters into the Send-Email function, you can also simply pass the SMA connection object that you have retrieved using “Get-AutomationConnection” cmdlet. for more information, please refer to the help topic of this function, and the sample runbook below.

SendPushNotification Module

This module provides a connection type called SMAAddressBook. It can be used like an address book to store recipient’s contact details:

  • Display Name
  • Email Address (optional)
  • NotifiyMyAndroid API Key (optional, encrypted)
  • Prawl (iOS push notification) API Key (optional, encrypted)
  • NotifyMyWndowsPhone API Key (optional, encrypted)

image

SNAGHTML1bb2b9d4

This module also provides a PowerShell function called Send-MobilePushNotification. It can be used to send push notification to either Prawl, NotifyMyAndroid or NotifyMyWindowsPhone.

Sample Runbook

As you can see from this sample, the runbook author does not need to know the SMTP server information (including login credentials), nor the contact details of the recipient. The runbook can simply pass the SMTP connection object (PowerShell Hash Table) into the Send-Email function.

After I executed this runbook, I received the notification via both Email and Android push notification:

SNAGHTML1bb9521f

image

Download

Please download from the download link below. Once downloaded, please import the zip files below into SMA:

image

Download Link

Related Posts

OpsMgr Alerts Push Notification to iOS (And Android, And Windows Phone) Devices

Authoring Integration Modules for SMA

Conclusion

As shown in the sample above, once the SMTP details are saved in SMTP connection objects, and recipients’ contact details are saved as SMAAddressBook connections, it is really simple to utilise the functions provided by these 2 modules to send notifications.

Also, I’d like to point out I had to create 2 integration modules instead of 1 because I need to create 2 kinds of connections. Having said that, these 2 modules do not depend on each other and can be used separately too.

As many people referring to SMA modules and runbooks as Lego pieces, I will definitely to share more and more my Lego pieces as they’ve been developed. In the meantime, please feel free to contact me if you have questions or suggestions.