Tag Archives: MimbolovePowershell

ConfigMgr OMS Connector

Written by Tao Yang

Earlier this week, Microsoft has release a new feature  in System Center Configuration Manager 1606 called OMS Connector:

image

As we all know, OMS supports computer groups. We can either manually create computer groups in OMS using OMS search queries, or import AD and WSUS groups. With the ConfigMgr OMS Connector, we can now import ConfigMgr device collections into OMS as computer groups.

Instead of using the OMS workspace ID and keys to access OMS, the ConfigMgr OMS connector requires an Azure AD Application and Service Principal. My friend and fellow Cloud and Data Center Management MVP Steve Beaumont has blogged his setup experience few days ago. You can read Steve’s post here: http://www.poweronplatforms.com/configmgr-1606-oms-connector/.  As you can see from Steve’s post, provisioning the Azure AD application for the connector can be pretty complex if you are doing it manually – it contains too many steps and you have to use both the old Azure portal (https://manage.windowsazure.com) and the new Azure Portal (https://portal.azure.com).

To simplify the process, I have created a PowerShell script to create the Azure AD application for the ConfigMgr OMS Connector. The script is located in my GitHub repository: https://github.com/tyconsulting/BlogPosts/tree/master/OMS

In order to run this script, you will need the following:

  • The latest version of the AzureRM.Profile and AzureRM.Resources PowerShell module
  • An Azure subscription admin account from the Azure Active Directory that your Azure Subscription is associated to (the UPN must match the AAD directory name)

When you launch the script, you will firstly be prompted to login to Azure:

image

Once you have logged in, you will be prompted to select the Azure Subscription and then specify a display name for the Azure AD application. If you don’t assign a name, the script will try to create the Azure AD application under the name “ConfigMgr-OMS-Connector”:

SNAGHTMLc560723

This script creates the AAD application and assign it Contributor role to your subscription:

image

At the end of the script, you will see the 3 pieces of information you need to create the OMS connector:

  • Tenant
  • Client ID
  • Client Secret Key

You can simply copy and paste these to the OMS connector configuration.

Once you have configured the connector in ConfigMgr and enabled SCCM as a group source, you will soon start seeing the collection memberships being populated in OMS. You can search them in OMS using a search query such as “Type=ComputerGroup GroupSource=SCCM”:

image

Based on what I see, the connector runs every 6 hours and any membership additions or deletions will be updated when the connector runs.

i.e. If I search for a particular collection based on the last 6 hours, I can see this particular collection has 9 members:

image

During my testing, I deleted 2 computers from this collection few days ago. If I specify a custom range targeting a 6-hour time window from few days ago, I can see this collection had 11 members back then:

image

This could be useful sometimes when you need to track down if certain computers have been placed into a collection in the past.

This is all I have to share today. Until next time, enjoy OMS Smile.

SharePointSDK PowerShell Module Updated to Version 2.1.0

Written by Tao Yang

OK, this blog has been very quiet recently. Due to some work related requirements, I had to pass few Microsoft exams. so I have spent most of my time over the last couple of months on study. Firstly, I passed the MCSE Private Cloud Re-Certification exam, then I passed the 2 Azure exams: 70-532 Developing Microsoft Azure Solutions and 70-533 Implementing Microsoft Azure Infrastructure Solutions. Other than studying and taking exams, I have also been working on a new version of the SharePointSDK PowerShell module during my spare time. I have finished everything on my to-do list for this release last night, and I’ve just published version 2.1.0 on PowerShell Gallery and GitHub:

This new release includes the following updates:

01. Fixed the “format-default : The collection has not been initialized.” error when retrieving various SharePoint objects.

i.e. When retrieving the SharePoint list in previous versions using Get-SPList function, you will get this error:

image

This error is fixed in version 2.1.0. now you will get a default view defined in the module:

image

02. SharePoint client SDK DLLs are now automatically loaded with the module.

I have configured the module manifest to load the SharePoint Client SDK DLLs that are included in the module folder. As the result of this change, the Import-SPClientSDK function is no longer required and has been removed from the module completely.

In the past, the Import-SPClientSDK function will firstly try to load required DLLs from the Global Assembly Cache (GAC) and will only fall back to the DLLs located in the module folder if they don’t exist in GAC. Since the Import-SPClientSDK function has been removed, this behaviour is changed in this release. Starting from this release, the module will not try to load the DLLs from GAC, but ALWAYS use the copies in the module folder.

03. New-SPListLookupField function now supports adding additional lookup columns.

When adding a lookup field in a SharePoint list, you can specify including one or more additional columns. i.e.:

image

The previous versions of this module did not support adding additional columns when creating a lookup field. In this version, you are able to add additional columns using the “-AdditionalSourceFields” parameter to achieve this goal.

04. Various minor bug fixes

Other than above mentioned updates, this version also included various minor bug fixes.

Special Thanks

I’d like to thank my friend and fellow CDM MVP Jakob Gottlieb Svendsen (@JakobGSvendsen) for his feedback. Most of the items updated in this release were results of Jakob’s feedbacks.

HybridWorkerToolkit PowerShell Module Updated to Version 1.0.3

Written by Tao Yang

Few days ago, I published a PowerShell Module to be used on Azure Automation Hybrid Workers called HybridWorkerToolkit. You can find my blog article HERE.

Yesterday, my good friend and fellow CDM MVP Daniele Grandini (@DanieleGrandini) gave me some feedback, so I’ve updated the module again and incorporated Daniele’s suggestions.

This is the list of updates in this release:

  • A new array parameter for New-HybridWorkerEventEntry called “-AdditionalParameters”. This parameter allows users to insert an array of additional parameters to be added in the event data:

SNAGHTMLb6e7547

  • A new Boolean parameter for New-HybridWorkerEventEntry called “-LogMinimum”. This is an optional parameter with the default value of $false. When this parameter is set to true, other than the user specified messages and additional parameters, only the Azure Automation Job Id will be logged as event data:

image

As we all know, we pay for the amount of data gets injected into our OMS workspace, this parameter allows you to minimise the size of your events (thus saves money on your OMS spending).

I have published this new release to both GitHub and PowerShell Gallery.

New PowerShell Module HybridWorkerToolkit

Written by Tao Yang

HybridWorkerToolkit23/04/2016 Update: released version 1.0.3 to GitHub and PowerShell gallery. New additions documented in this blog post.

21/04/2016 Update: updated GitHub and PowerShell gallery and released version 1.0.2 with minor bug fix and updated help file.

Introduction

Over the last few days, I have been working on a PowerShell module for Azure Automation Hybrid Workers. I named this module HybridWorkerToolkit.

This module is designed to run within either a PowerShell runbook or a PowerShell workflow runbook on Azure Automation Hybrid Workers. It provides few functions that can be called within the runbook. These activities can assist gathering information about Hybrid Workers and the runbook runtime environment. It also provides a function to log structured events to the Hybrid Workers Windows Event Logs.

My good friend and fellow MVP Pete Zerger posted a method he developed to use Windows event logs and OMS as a centralised logging solution for Azure Automation runbooks when executed on Hybrid Workers. Pete was using the PowerShell cmdlet Write-EventLog to log runbook related activities to Windows event log and then these events will be picked up by OMS. Log Analytics. This is a very innovative way of using Windows event logs and OMS. However, the event log entries written by Write-EventLog are not structured are lacking basic information about your environment and the job runtime.  Couple of weeks ago, another friend of mine, Mr. Kevin Holman from Microsoft also published a PS script that he used to write to Windows event logs with additional parameters.

So I combined Pete’s idea with Kevin’s script, as well as some code I’ve written in the past for Hybrid Workers, and developed this module.

Why do we want to use Windows Event logs combined with OMS for logging runbook activities on Hybrid workers? As Pete explained on this post, it provides a centralised solution where you can query and retrieve these activity logs for all your runbooks from a single location. Additionally, based on my experience (and also confirmed with few other friends), is that when you use Write-Verbose or Write-Output in your runbook and enabled verbose logging, the runbook execution time can increase significantly, especially when loading a module with a lot of activities. Based on my own experience, I’ve seen a runbook that would normally takes a minute or two to run with verbose logging turned off ended up ran over half an hour after I enabled verbose logging. This is another reason I’ve developed this module so it gives you an alternative option to log verbose, error, process and output messages.

Functions

This module provides the following 3 functions:

  • Get-HybridWorkerConfiguration
  • Get-HybridWorkerJobRuntimeInfo
  • New-HybridWorkerRunbookLogEntry

Note: Although the job runtime are different between PowerShell runbooks and PowerShell Workflow runbooks, I have spent a lot of time together with Pete making sure we can use these activities exactly the same ways between PowerShell and PowerShell workflow runbooks.

Get-HybridWorkerConfiguration

This function can be used to get the Hybrid Worker and Microsoft Monitoring Agent configuration. A hash table is returned the following configuration properties retrieved from Hybrid Worker and MMA agent:

  • Hybrid Worker Group name
  • Automation Account Id
  • Machine Id
  • Computer Name
  • MMA install root
  • PowerShell version
  • Hybrid Worker version
  • System-wide Proxy server address
  • MMA version
  • MMA Proxy URL
  • MMA Proxy user name
  • MMA connected OMS workspace Id

Get-HybridWorkerJobRuntimeInfo

This function retrieves the following information about the Azure Automation runbook and the job run time. They are returned in a hashtable:

  • Runbook job ID
  • Sandbox Id
  • Process Id
  • Automation Asset End Point
  • PSModulePath environment variable
  • Current User name
  • Log Activity Trace
  • Current Working Directory
  • Runbook type
  • Runbook name
  • Azure Automation account name
  • Azure Resource Group name
  • Azure subscription Id
  • Time taken to start runbook in seconds

New-HybridWorkerRunbookLogEntry

This function can be used to log event log entries. By default, other than the event message itself, the following information is also logged as part of the event (placed under the <EventData> XML tag:

  • Azure Automation Account Name
  • Hybrid Worker Group Name
  • Azure Automation Account Resource Group Name
  • Azure Subscription Id
  • Azure Automation Job Id
  • Sandbox Id
  • Process Id
  • Current Working Directory ($PWD)
  • Runbook Type
  • Runbook Name
  • Time Taken To Start Running in Seconds

This function also has an optional Boolean parameter called ‘-LogHybridWorkerConfig’ When this parameter is set to $true, the event created by this function will also contain the following information about the Hybrid Worker and MMA:

  • Hybrid Worker Version
  • Microsoft Monitoring Agent Version
  • Microsoft Monitoring Agent Install Path
  • Microsoft Monitoring Agent Proxy URL
  • Hybrid Worker server System-wide Proxy server address
  • Microsoft OMS Workspace ID

Sample Runbooks

Sample PowerShell Runbook:

Sample PowerShell Workflow Runbook

As you can see, the way to call these functions between PowerShell and PowerShell Workflow runbooks are exactly the same.

Hybrid Worker Configuration output:

SNAGHTML40e35ad

Hybrid Worker Job Runtime Info output:

SNAGHTML40f4d28

Event generated (with basic information / without setting –LogHybridWorkerConfig to $true):

SNAGHTML4159a60[4]

Event generated (whensetting –LogHybridWorkerConfig to $true):

SNAGHTML4150515

Consuming collected events in OMS

Once you have collected these events in OMS, you can use search queries to find them, and you can also create OMS alerts to notify you using your preferred methods.

Searching Events in OMS

i.e. I can use this query to get all events logged by a particular runbook:

Type=Event “RunbookName: Test-HybridWorkerOutput-PSW”

image

or use this query to get all events for a particular job:

Type=Event “JobId: 73A3827D-73F8-4ECC-9DE1-B9340FB90744”

image

OMS Alerts

i.e. if I want to create an OMS alert for any Error events logged by New-HybridWorkerRunbookLogEntry, I can use a query like this one:

Type=Event Source=AzureAutomation?Job* EventLevelName=Error

image

image

Download / Deploy this module

I have published this module on Github as well as PowerShell Gallery:

GitHub Repository: https://github.com/tyconsulting/HybridWorkerToolkit

PowerShell Gallery:  http://www.powershellgallery.com/packages/HybridWorkerToolkit/1.0.3

Credit

I’d like to thank Pete and Kevin for the ideas in the first place, also I’d like to thank Pete, Jakob Svendsen, Daniele Grandini and Kieran Jacobsen for the testing and feedback!

A Major Update for the SharePointSDK PS Module

Written by Tao Yang

Sharepoint-2013-LogoIntroduction

This blog has been a bit quiet over the last few weeks. This is because I have been really really busy. I have spent a lot of time working on an updated version of the SharePointSDK PS module. Just in case you have not played with this module, here’s some background info:

Just over a year ago, I posted a PowerShell / SMA / Azure Automation module on this blog called SharePointSDK. Few months ago, I have also published this module on Github and PowerShell Gallery. This module was designed to help automate operations around SharePoint lists (i.e. CRUD operations for SharePoint list items). Coupling SharePoint (both On-prem version or SharePoint Online) with Azure Automation (or even SMA) is becoming more and more common in the community when designing automation solutions. This module provides ways for your automation runbooks to interact with SharePoint list items.

However, I believe the original 1.0 release was really basic, and there are still a lot I’d like to cover in this module. Now I’m pleased to announce the new major release (version 2.0.1) is now available on both Github and PowerShell Gallery.

What’s New?

I’ve included the following updates in version 2.0.1:

  • 26 additional functions!
  • Updated the SharePoint CSOM (Client Component SDK) DLLs to the latest version in the module.
  • Created a separate help file for the module. Get-Help is now fully working
  • Various bug fixes

The table below lists all the functions that are shipped in the current release (version 2.0.1):

Function Description Released on Version
Import-SPClientSDK Load SharePoint Client SDK DLLs 1.0
New-SPCredential Create a SharePoint credential that can be used authenticating to a SharePoint (online or On-Premise) site. 1.0
Get-SPServerVersion Get SharePoint server version. 1.0
Get-SPListFields Get all fields from a list on a SharePoint site. 1.0
Add-SPListItem Add a list item to the SharePoint site. 1.0
Get-SPListItem Get all items from a list on a SharePoint site or a specific item by specifying the List Item ID. 1.0
Remove-SPListItem Delete a list item to the SharePoint site. 1.0
Update-SPListItem Update a list item to the SharePoint site. 1.0
Get-SPListItemAttachments Download all attachments from a SharePoint list item. 1.0
Add-SPListItemAttachment Upload a file as a SharePoint list item attachment. 1.0
Remove-SPListItemAttachment Remove a SharePoint list item attachment. 1.0
New-SPList Create a new list on the SharePoint site. 2.1
Remove-SPList Remove a list from the SharePoint site. 2.1
Get-SPList Get a list from the SharePoint site. 2.1
New-SPListLookupField Create a new lookup Field for a SharePoint list. 2.1
New-SPListCheckboxField Create a new checkbox Field for a SharePoint list. 2.1
New-SPListSingleLineTextField Create a new single line text Field for a SharePoint list. 2.1
New-SPListMultiLineTextField Create a new Multi-line text Field for a SharePoint list. 2.1
New-SPListNumberField Create a new number Field for a SharePoint list. 2.1
New-SPListChoiceField Create a new choice Field for a SharePoint list. 2.1
New-SPListDateTimeField Create a new date time Field for a SharePoint list. 2.1
New-SPListHyperLinkField Create a new Hyperlink or Picture Field for a SharePoint list. 2.1
New-SPListPersonField Create a new Person or Group Field for a SharePoint list. 2.1
Remove-SPListField Remove a Field from a SharePoint list. 2.1
Update-SPListField Update a SharePoint list field. 2.1
Set-SPListFieldVisibility Set the visibility of a SharePoint list field. 2.1
Get-SPGroup Get a single group or all groups from the SharePoint site. 2.1
New-SPGroup Create a new SharePoint group. 2.1
New-SPGroupMember Add an user to a SharePoint group. 2.1
Remove-SPGroupMember Remove an user from a SharePoint group. 2.1
Clear-SPSiteRecycleBin Empty the SharePoint site recycle bin. 2.1
Get-SPSiteTemplate Get avaialble Site Template(s) from the SharePoint site. 2.1
New-SPSubSite Create a new SharePoint sub site. 2.1
Get-SPSubSite Get all SharePoint sub sites from a root site. 2.1
Remove-SPSubSite Delete a SharePoint sub site. 2.1
Add-SPListFieldToDefaultView Add a SharePoint list field to the list default view. 2.1
Remove-SPListFieldFromDefaultView Remove a SharePoint list field to the list default view. 2.1

As you can see, the previous version has shipped 11 functions, and 26 additional functions have been added to the current release (2.0.1). With this release, other than the SharePoint list items, we are also able to manage SharePoint lists, list fields, groups, group members, and even subsites. I have included functions to create what I believe the most common list fields (as highlighted below):

image

Future Plans

At this stage, there are still few things I’d like to cover in this module but I simply do not have time. Since I think I have reached another milestone at this stage, I have decided to release this version now and roll other ideas into the future release.

In the second week of March, I will be presenting at SCU APAC (Kuala Lumpur, Malaysia) and Australia (Melbourne).  I am presenting 2 identical sessions at both locations:

  • Be a hero and save the day with OMS and Power BI (Co-present with CDM MVP Alex Verkinderen)
  • Automation for IT Ops with OMS and Azure Automation (Co-present with CDM MVP Pete Zerger)

As part of the demos I have prepared for the Azure Automation session with Pete, I will cover how I’m using this module as part of my automation solutions.

After SCU, I am planning to write another blog post for my Automating OpsMgr series which will cover one of the our SCU demos (I know, it has been a long time since my last post for that series). I will also cover this module in more details in this upcoming blog post.

Download the Module

So for now, if you’d like to give this module a try, you can find it from both GitHub and PowerShell Gallery. All functions are fully documented in the help file. You can access the help document as well as code examples using Get-Help with –Full switch.

Lastly, if you have any feedback, or suggestions for future releases, please feel free to drop me an email.

This is all I have to share for today, until next time, happy automating Smile.

Automating OpsLogix Oracle MP Configuration

Written by Tao Yang

Introduction

One of the flagship management packs from OpsLogix is the Oracle Database MP. This MP provides several GUI driven wizard to help you creating your own monitoring solutions for Oracle by leveraging the OpsMgr management pack templates (https://technet.microsoft.com/en-au/library/hh457614.aspx). At this stage, the OpsLogix Oracle MP provides the following templates:

01. Oracle Alert Rule template

This template allows you to create a rule that checks a value from your oracle environment and generate alerts in the event that the value is detected or missing, depending on the configuration you have specified.

02. Oracle Performance Collection Rule template

This template allows you to create a rule that will collect performance data from your Oracle environment in order to visualize data on the performance view and reports.

03. Oracle Two-State Monitor Template

This template allows you to create a monitor that will check the health of an element according to the configuration that you have specified in the wizard. It will generate alerts when the monitor becomes unhealthy.

Like any other OpsMgr management pack templates, the above mentioned templates can be found in the Authoring pane of the OpsMgr console, under “Management Pack Templates”:

image

Some Background on Management Pack Templates

The MP templates provide great ways for users to create complex monitoring scenarios without having to use MP authoring tools such as VSAE or Silect MPAuthor. The MP templates are designed to satisfy specific monitoring needs (i.e. Windows service monitoring, TCP Port monitoring etc.). From an OpsMgr admin and operator point of view, they are great, because each template provides a user friendly GUI driven wizard for you to create your monitoring solutions.

From a MP developer point of view, these templates are not easy to create – not only because you need to define the templates in the MP, but most of time, you also need to design the UI pages to be used in the wizard, which is very time consuming (not to mention these UI pages are written in C#). I have done it several times, and believe me, they are not easy! So every time when I see a MP offers management pack templates, I really appreciate the effort put in by the developers.

Although I think the management pack templates provides a user friendly GUI driven wizard for users to create their monitoring solutions, in my opinion, the biggest drawback is also the GUI wizard. It means you HAVE TO use the GUI wizard – it may become an issue when you have a lot of stuff to configure.

Let me give you an example based on my own experience. A few months ago, I was away attending a conference overseas and a customer needed to create hundreds of instances for the Windows Service monitoring template. Because they didn’t want to wait for my return, I was told someone spent a few days clicking through the wizard many, many times.

So what other options do we have? Fortunately, the management pack template instances can be created via OpsMgr SDK.

Automating MP Template Instance Creation

If you have been following my blog series “Automating OpsMgr”, you may have already read Part 17 of this series: Creating Windows Service Management Pack Template Instance, where I demonstrated a runbook leveraging the OpsMgrExtended PowerShell module and enabled people to create a management pack template instance (in this case, the Windows Service template) using one line of PowerShell script. This was a great example on how to create the template instances in mass scales.

OK, let’s go back to the OpsLogix Oracle MP… Just to put it out there, my experience with Oracle DB is very limited. Throughout the years I spent in IT, I’ve only been dealing with Microsoft’s SQL servers. Based on my experience with SQL, I know that every DBA will have a set of queries they regularly use to monitor their SQL environments. I assume this is also the case for Oracle. So, one of the first concerns I had when I started playing with this MP is, creating user defined monitoring scenarios could be very time consuming when using the management pack template wizards. Therefore, I spent few hours today, and produced 3 separate PowerShell functions that people can use to create instances for the 3 templates mentioned above. These functions are:

  1. New-OpsLogixOracleAlertTemplateInstance
  2. New-OpsLogixOraclePerfTemplateInstance
  3. New-OpsLogixOracle2StateMonitorTemplateInstance

Pre-requisites:

These functions requires the OpsMgrExtended Module on the computer where you are running the script. Please follow the instruction and setup this module first.

Download Link:

I have uploaded the code for above mentioned PowerShell functions to Github. You can download them from https://github.com/tyconsulting/OpsMgr-SDK-Scripts/tree/master/OpsLogix%20Oracle%20MP%20Scripts

Now, let’s test them, I will use the –verbose switch when calling these functions so you can see the verbose messages.

01. Creating a test MP

Firstly, I’ll create a test MP using the New-OMManagementPack command from the OpsMgrExtended module:

image

02. Create an instance for the alert rule template (using PowerShell Splatting)

Calling the New-OpsLogixOracleAlertTemplateInstance function:

image

SNAGHTML7af883b

03. Create an instance for the performance collection template

Calling the New-OpsLogixOraclePerfTemplateInstance function:

image

SNAGHTML7b050da

04. Create an instance for the Two-State Monitor template

Calling the New-OpsLogixOracle2StateMonitorTemplateInstance function:

image

SNAGHTML7b1236d

Note: There is also a test.ps1 script in this Github repository. It contains the test parameters used as shown in the screenshots above.

Conclusion

As you may have noticed, these functions also have a parameter set to support the SMA / Azure Automation connection object (defined in the OpsMgrExtended Module). If you are planning to make this part of your automation solution, you can simply change this from a PowerShell function to a runbook and use the –SDKConnection parameter to establish connection to the management group. this should be very straightforward; you can refer to my previous post on the Automating OpsMgr blog series for more details.

I hope these functions will help customers who are deploying Oracle monitoring solutions using OpsLogix Oracle MP. For example, if you need to create a lot of these instances, you can create a CSV file with all the required parameters and values, and then create a very simple PowerShell script to read the CSV file and then call the appropriate functions. I’ve done the hard work for you, the rest should be pretty easy  Smile.

Lastly, if anyone would like to evaluate the OpsLogix Oracle MP, they can be contacted via email sales@opslogix.com

Azure Automation Runbook: New-FakeVirus

Written by Tao Yang

Often when you are playing with security related products, you would need to create dummy/fake viruses on your computers. The most common way to do this is to create a EICAR test file (https://en.wikipedia.org/wiki/EICAR_test_file).

I have used this method in the past when testing the Microsoft Forefront Endpoint Protection management pack in OpsMgr. Today I needed to use it again when I was preparing a demo for the OMS Malware Assessment. I thought, why not make an Azure Automation runbook that automatically create the EICAR test file for me on remote computers, so I can trigger it manually or schedule it to run on a regular basis? So here’s what I came up with.

CAUTION: Use it at your own risk! And obviously, this runbook is designed to run on hybrid workers Smile.

Runbook: New-FakeVirus

You will need to specify 3 optional input parameters:

image

  • Credential: The name of the credential asset saved in your Azure Automation account – If you need to use an alternative credential to connect to the target computer (via WMI)
  • ComputerName: The target computer of where the fake virus is going to be created, if not specified, it will be created on the runbook worker itself.
  • Folder: the folder of where the file is going to be created on the target computer. If not specified, the runbook will use the System environment variable %TEMP%.

Runbook Output:

image

If your Windows Defender or System Center Endpoint Protection (SCEP) is working correctly, you will see this on your target computer straightaway:

image

If the target computer is monitored by OpsMgr and you have imported the Forefront Endpoint Protection (FEP) 2010 MP, you’ll get an alert:

image

And you will also see in the OMS Malware Assessment dashboard shortly:

image

image

SharePointSDK and SendEmail PS Modules Published in GitHub and PowerShell Gallery

Written by Tao Yang

I have recently published 2 PowerShell modules that I’ve written around a year ago on GitHub and PowerShell Gallery:

SharePointSDK:

Original Post: http://blog.tyang.org/2014/12/23/sma-integration-module-sharepoint-list-operations/

Github Repository: https://github.com/tyconsulting/SharePointSDK_PowerShellModule

PowerShell Gallery: https://www.powershellgallery.com/packages/SharePointSDK/

SendEmail:

Original Post: http://blog.tyang.org/2014/10/31/simplified-way-send-emails-mobile-push-notifications-sma/

Github Repository: https://github.com/tyconsulting/SendEmail_PowerShellModule

PowerShell Gallery: https://www.powershellgallery.com/packages/SendEmail/

Please note the versions I published on Github and PowerShell Gallery are newer than the versions from my original blog posts. Originally, both modules take clear text user name and passwords as input parameters. This behaviour was flagged by the PowerShell Gallery administrators after they examined my modules using PowerShell Script Analyzer. I have just updated both modules today and replaced clear text user name and password parameters with PSCredential parameter. So if you are currently using old versions without using SMA / Azure Automation connection objects, you may need to update your scripts and runbooks after you upgrade.

Automating OpsMgr Part 19: Creating Any Types of Generic Rules

Written by Tao Yang

OpsMgrExntededIntroduction

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

Although I have written number of functions in the current version of the OpsMgrExtended module that allows you to  create some popular types of rules in OpsMgr (i.e. perf collection rules and event collection rules). Sometimes, you still need to create other types of rules, such as WMI event collection rules, or rules based on module types written by yourself. In this post, I will demonstrate how to create any types of rules using the New-OMRule function.

Additionally, since the OpsMgrExtended module can be used on both your on-prem SMA infrastructure as well as on your Azure Automation account (with the help of Hybrid Workers), and pretty much all the previous runbooks and posts are based on SMA, I will use Azure Automation in this post (and maybe in the future posts too). I will demonstrate 2 sample runbooks in this post. Since Azure Automation now supports PowerShell runbooks on both Azure runbook workers as well as on hybrid workers, with the 2 sample runbooks I’m going to demonstrate, one is based on PowerShell workflow and the other one is a PowerShell runbook.

What Components are OpsMgr Rules Made Up?

Before we diving into the sample runbooks, please let me explain how are the OpsMgr rules made up. In OpsMgr, a rule is essentially a workflow that contains the following components:

  1. One or more Data Source modules
  2. Zero or one Condition Detection Modules
  3. One or more Write Action modules

To explain in plain English, a rule can have multiple data source modules and write action modules, but condition detection module is optional, and you can only use up to 1 condition detection module in your rule. The order of execution is Data Source Modules –> Condition Detection Module –> Write Action Modules. Additionally, some modules requires mandatory and/or optional configuration parameters (i.e. System.SimpleScheduler), some modules do not require any configuration parameters (i.e. Microsoft.SystemCenter.CollectPerformanceData).

OM-Rule Design Consideration

When I was writing the New-OMRule function, I have realised in order to capture all required information for each member module, the following information is required:

  • Module Type Name (Mandatory)
  • Configuration (Optional)
  • Member Module Name (Mandatory)
  • RunAs Profile Name (Optional)

i.e. in the example below, I have high lighted the information required in a member module of a rule.

image

Other than the information listed above, if we are writing an alert-generating rule, we would also need the following information for the alert configuration:

  • String Resource
  • Language Pack ID
  • Alert Name
  • Alert Description

I needed to figure out a way to enforce users to supply all required information listed above. In order to do that, I think the best way is to define a class for member module configurations and another class for alert configurations. However, since class definition is a new concept only been introduced in PowerShell version 5 (which still in preview other than Windows 10 machines at the time of this writing), I could not do this natively in PowerShell. In order to work around this limitation, I have defined these two classes in OpsMgrExtended.Types.dll using C#. This DLL is shipped as part of the OpsMgrExtended module.

image

The OM-Rule is expecting instances of these classes defined in OpsMgrExtended.Types.dll as input parameters. You will see how I used these classes in the sample runbooks.

Sample PowerShell Runbook: New-WMIPerfCollectionRule

OK, let’s start with a “simpler” one first. The New-WMIPerfCollectionRule runbook is a PowerShell runbook that can be used to create perf collection rules based on WMI queries. I think it’s simpler than the other one because it’s a PowerShell runbook (as opposed to PowerShell workflow) and we don’t have to worry about configuring alerts for the rules created by this runbook. The source code for this runbook is listed below:

As you can see, this runbook requires the following input parameters:

  • RuleName – the internal name of the rule
  • RuleDisplayName – the display name of the rule. this is what people will see in OpsMgr console
  • ClassName – The internal name of the target class (i.e. “Microsoft.Windows.OperatingSystem”)
  • WMINameSpace – the WMI name space of where the WMI class you are going to query resides. This is optional. if not specified, the default value of “Root\CIMV2” will be used
  • WMIQuery – the WMI query to retrieve the performance counter value
  • IntervalSeconds – the rule execution interval in seconds. this is optional, if not specified, the default value of 900 (15 minutes) will be used.
  • ObjectName – The object name for the performance data (i.e. Process, or LogicalDisk)
  • CounterName – the counter name for the performance data (i.e. ProcessCount, or FreeSpaceMB)
  • InstanceNameWMIProperty – the property returned from the WMI query which represent the performance data instance value (i.e. if you are collecting logical disk counters, the result of WMI query may contain a property that represent the drive letter, which can be used to identify the instance in perf data). This is optional, if not specified, the perf data instance name would be “_Total”.
  • ValueWMIProperty – the property returned from the WMI query that represent the perf value.

The first step of this runbook is to retrieve a connection object named “OpsMgrSDK_Home” from my Azure Automation account (or SMA). This connection object is pre-configured, which contains the computer name of one of my OpsMgr management servers, and the credential of a service account which has OpsMgr admin privilege in my management group.

SNAGHTMLddea7c

The runbook also needs to explicitly import the OpsMgrExtended module. During the test, I found for this PowerShell runbook, I must manually import the module using Import-Module cmdlet in order to load the assemblies defined in the OpsMgrExtended.Types.dll. Since we are going to be using hybrid workers, you must manually deploy this module to your hybrid workers because at the time of this writing, Azure Automation is not able to automatically deploy required modules to hybrid workers.

Next, we must define the module configurations for each member module used by the WMI perf collection rules that this runbook creates. I have determined this type of rules should be configured using the following modules

  • One Data Source Module
    • Microsoft.Windows.WmiProvider
  • One Condition Detection Module
    • System.Performance.DataGenericMapper
  • Three Write Action Modules
    • Microsoft.SystemCenter.CollectPerformanceData
    • Microsoft.SystemCenter.DataWarehouse.PUblishPerformanceData
    • Microsoft.SystemCenter.CollectCloudPerformanceData

To explain in English, the rules created by this runbook would periodically execute a WMI query (Data source module), then map the result from WMI query to OpsMgr performance data (Condition detection module), finally store the performance data in OpsMgr operational DB, data warehouse DB and also OMS workspace (3 write action modules).

So we will need to use the New-OMModuleConfiguration function from the OpsMgrExtended PS module to create an instance of the “OpsMgrExtended.ModuleConfiguration” class. As explained earlier, the “OpsMgrExtended.ModuleConfiguration” class is defined in the OpsMgrExtended.Types.dll. Take the data source member module as an example:

I have placed the module type name, module configuration and the member module name into separate variables and passed them to the New-OMModuleConfiguration function and created a module configuration object for the data source module.

Note:

You can use Get-Help New-OMModuleConfiguration to access the help file for this function. If you need to use an alternative OpsMgr RunAs profile to for any member modules, you can also specify the name of the RunAs profile you are going to use with the –RunAsMPName and the –RunAsName parameter. The RunAsMPName parameter is used to specify the internal name of the management pack that defined the RunAs profile, and the RunAsName parameter is used to specify the internal name of the RunAs profile (i.e. if you are creating rules for SQL related classes, you might need to use the default SQL RunAs Profile, in this case, the –RunAsMPName would be “Microsoft.SQLServer.Library” and –RunAsName would be “Microsoft.SQLServer.SQLDefaultAccount”.)

Since a rule can have multiple data source modules and multiple write action modules, the New-OMRule function is expecting the array type of input for data source modules and write action modules. This is why even there is only going to be one data source member module or write action member module, we still need to place them into separate arrays before passing into the OM-Rule function:

image

image

On the other hand, since the condition detection member module is optional, and you can only have maximum one condition detection member module, you do not need to place the module configuration object for the condition detection module into an array.

Lastly, I have hardcoded the management pack name to be “Test.OpsMgrExtended” in this sample runbook. this MP must be created prior to running this runbook otherwise it would fail. However, if you have a look at the sample runbooks in previous posts, you can easily figure out a way to firstly detect the existence of this MP and use this runbook to create the MP if it does not exist in your management group.

Now, it’s time to take this runbook for a test run. I’m using the following parameters during the test run:

  • RuleName: “Test.WMIPerfCollection.Process.Count.WMI.Performance.Collection.Rule”
  • RuleDisplayName: “Windows Server Process Count Performance Collection Rule”
  • ClassName: “Microsoft.Windows.OperatingSystem”
  • WMIQuery: “select Processes from Win32_PerfRawData_PerfOS_Objects”
  • ObjectName: “Process”
  • CounterName: “ProcessCount”
  • ValueWMIProperty: “Processes” –verbose

And I have specified to run on a hybrid worker group:

SNAGHTMLd3df42

The hybrid worker will pick up this job very soon, and during this test run, the job was completed around 2 minutes. after the job finishes, I’m able to find this rule in OpsMgr console:

image

image

Sample PowerShell Workflow Runbook: New-WindowsEventAlertRule

Now, let’s take a look at the second sample runbook. This runbook is designed to create rules that detects certain event log entries and generates alerts upon detection. I think it’s more complicated than the first sample because this is a traditional PowerShell workflow runbook (which works on both SMA and Azure Automation), and we also need to configure alert settings for this rule. The source code for this runbook is listed below:

This runbook takes the following input parameters:

  • RuleName – the internal name of the rule that you are creating
  • RuleDisplayName – the display name of the rule
  • ClassName – The internal name of the target class (i.e. “Microsoft.Windows.OperatingSystem”)
  • EventLog – the name of the event log (i.e. “System”)
  • EventID – the ID of the event that you are detecting
  • EventSource – is what you see as “source” in Windows event log
  • EventLevel – can be one of the following value:
    • Success
    • Error
    • Warning
    • Information
    • Audit Failure
    • Audit Success
  • AlertName – the alert name / title
  • AlertSeverity – can be one of the following value:
    • Critical
    • Warning
    • Information
  • AlertProirity – can be one of the following value:
    • Low
    • Medium
    • High

As you can see, firstly, other than the standard process of retrieving the connection object for my OpsMgr management group, I have used several “Switch” statements with inline scripts to translate the event level, alert priority and alert severity from English words (string) to numbers (integer), because when configuring member modules for OpsMgr rules, we must use the number (instead of names). Note I’ve also used “ValidateSet” to validate the input of these parameters, so only valid inputs are allowed.

I am not going to explain the member module configurations again, because I’ve already covered it in the first sample. But please note because the rules created by this runbook will be generating alerts, we must configure alert settings. In OpsMgr, when a workflow is configured to generate alerts (either rules or monitors), other than the rule / monitor itself, we must also define a String Resource for the alert message ID, as well as defining the alert name and description in a preferred language pack (by default, ENU). Therefore, we are going to use another class defined in OpsMgrExtended.Types.dll for alert configuration. The class for alert configuration is called OpsMgrExtended.AlertConfiguration, and you can use New-OMAlertConfiguration function to create an instance of this class. Same as all other functions in the OpsMgrExtended PS module, you can use Get-Help cmdlet to access the help file for New-OMAlertConfiguration. You will need to specify the following input parameters for New-OMAlertConfiguration:

  • AlertName – the name / title of the alert
  • AlertDescription – the alert description / detail
  • LanguagePackID – the 3-letter language pack code for the language pack that you wish to create the alert message under. this is an optional parameter, if not specified, the default value of “ENU’’ will be used.
  • StringResource – the ID for the alert string resource

As you can see, since the write action member module for the rules created by this runbook would be “System.Health.GenerateAlert”, and we are defining <AlertMessageId> and <AlertParameters> in the write action member module configuration:

image

The String Resource must match the AlertMessageId:

image

And if you have previously authored OpsMgr management packs, you’d probably already know how to define the <AlertParameters> section for the alert description. Basically, any variables you are using in the alert description must be defined in the <AlertParameters> section, then in the alert description, you’d reference them using “{}” and a number inside. <AlertParameter1> becomes {0}, <AlertParameter2> becomes {1}, and so on. You can up to define 10 alert parameters:

image

Since you can define multiple alert messages (for multiple language packs), when you are creating alert generating rules, the New-OMRule function would expect you to pass in an array that contains OpsMgrExtended.AlertConfiguration objects. So, even if you are only defining the alert in one language pack, please still place it into an array before passing to the New-OMRule function:

image

OK, now, let’s give this runbook a test run with the following parameters:

  • RuleName: “Test.Disk.Controller.Event.Alert.Rule”
  • RuleDisplayName: “Disk Controller Error Event Alert Rule”
  • ClassName: “Microsoft.Windows.OperatingSystem”
  • EventLog: “System”
  • EventID: 11
  • EventSource: “Disk”
  • EventLevel: Error
  • AlertName: “Windows Disk Controller Error”
  • AlertSeverity: Critical
  • AlertPriority: High

SNAGHTML1055790

After the hybrid worker in my lab executed the runbook, I am able to see the rule created in OpsMgr console:

image

image

and the raw XML (once I’ve exported the MP):

image

Hybrid Worker Configuration

Since the samples in this post are all based on Azure Automation and Hybrid worker, I just want to point out this article if you need help setting it up: https://azure.microsoft.com/en-us/documentation/articles/automation-hybrid-runbook-worker/

Also as I mentioned earlier, you will need to deploy OpsMgrExtended module manually on to the hybrid workers by yourself. When copying the OpsMgrExtended module to your hybrid workers, make sure you copy to a folder that’s listed in the PSModulePath environment variable. During my testing with a PowerShell runbook, I initially placed it under “C:\Program Files\WindowsPowerShell\Modules” folder, as it was listed in the PSModulePath environment variable when I checked in a PowerShell console on the hybrid worker. However, I got error messages telling me the runbook could not find commands defined in the OpsMgrExtended module. To troubleshoot, I wrote a simple PowerShell runbook:

image

and based on the output, the folder in “C:\Program Files” is not listed!

image

Therefore, I had to move the module to another location (C:\Windows\System32\WindowsPowerShell\v1.0\Modules). after the move, the runbook started working.

Summary

In this post, I have demonstrated how to use the New-OMRule function from OpsMgrExtended PS module to create any types of rules in OpsMgr. Although OpsMgrExtended module has already shipped two other functions to create event collection and performance collection rules, the New-OMRule fills the gap that allows users to specify each individual member module and its configurations. This is probably the most technically in-depth post in the Automating OpsMgr series. I have tried my best to explain and demonstrate how to use the New-OMRule function. But if you are still unclear, have questions or issues, please feel free to contact me.

I haven’t figured out what I will cover in the next post, but I still have a lot to cover in this series. Since I am attending few conferences in the coming weeks in November, I probably won’t have time to work on part 20 until end of November. Until next time, happy automating!

Automating OpsMgr Part 18: Second Update to the OpsMgrExtended Module (v1.2)

Written by Tao Yang

OpsMgrExntededIntroduction

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

Before I diving into the topic of creating generic rules using the New-OMRule function from the OpsMgrExtended module, I have updated this module again. It is now on version 1.2.

I was working on another project and I needed to use the New-OMRule function to create rules and I realised this function did not support specifying optional RunAs accounts for member modules. As I needed to create rules that use a RunAs account in the data source module, I had to update this function to accommodate it.

Additionally, as I mentioned in the previous post (Part 17), there is a bug in the New-WindowsServiceTemplateInstance function, where the description field is not populated. I have also fixed it in this release.

What’s New?

So, in summary, here’s what’s changed:

  • Updated OM-Rule function to allow specifying optional RunAs profile for each member module.
  • Fixed the issue in New-WindowsServiceTemplateInstance function where the description field is not populated.

Where to Download V1.2?

I have updated the original link, so you can download this updated version at TY Consulting’s web site: http://www.tyconsulting.com.au/portfolio/opsmgrextended-powershell-and-sma-module/

Conclusion

Now that I’ve updated and enhanced the New-OMRule function I will demonstrate how to create rules using this function as planned in the next module.