A couple of weeks ago one of my customers had a requirement to provision and manage identities into xMatters. The xMatters API Documentation looked straight-forward and I figured it would be pretty quick to knock up an PowerShell xMatters Management Agent.
The identification of users (People) in xMatters was indeed pretty quick. I was quickly able to enumerate all users (that had initially been seeded independent of FIM/MIM) and join them to corresponding users in the MetaVerse.
It was then as I started digging deeper that the relationship between Sites (Locations) and Email/Mobile (Devices) attributes became apparent. This post details how I approached it and a base xMatters MA that should get you started if you need to do something similar.
A key concept to keep in mind is that at the simplest level there are 3 key Object Types in xMatters;
Associated with each is an id which can be either dynamically created on provisioning (by xMatters) or specified. For People there is also targetName which is the equivalent of UID/sAMAccountName. When using the API (for people) you can use either their ID or their targetName. For all other entities you need to use the ID.
For each entity as you’d expect there are different API URI’s. They are;
Finally to retrieve devices for a person use;
Other key points to consider that I uncovered are;
With all that introduction, here is a base xMatters PowerShell MA (implemented using the Granfeldt PowerShell MA) to get you started. You’ll need to tailor for your environment and trigger Provisioning, Deletes and Flow Rules for your environment and look to handle the xMatters API for your integration.
I’ve created two Object Classes. User and Site. User incorporates User Devices. Site is the locations (Sites) from xMatters.
Credentials for the Import script to connect to xMatters are flowed in from the Management Agent Username and Password attributes. This isn’t using Paged Imports. If you have a large number of users you may want to consider that. After retrieving all of the People entities each is queried to obtain their Devices. I’m only bringing through SMS and Email Devices. You’ll need to modify for additional Devices.
Ensure that you flow into the MetaVerse (onto custom attributes) the IDs associated with your Devices (e.g MobileID and EmailID). That will allow you to use the ID when updating those attributes.
For Sites, I created a custom ObjectClass (Site) in the MV and used objectID of the SiteID and displayName for the Site Name (as shown below).
This is where it gets a little more complicated. As PowerShell is not good at reporting webrequest responses we have to deal with the return from each API call and determine if we were successful or not. Then let FIM/MIM know so it can report that via the UI.
The Export script below deals with Adding, Deleting and Updating users. Update line 31 for your API URI for xMatters.
The detail above will get you started and give you a working Management Agent to import Users and Sites. You’ll need to do the usual steps (Set, Workflow, Sync Rule and MPR) to trigger Provisioning on the MA along with how you handle deletes.
A few weeks back the Microsoft AI Tour was in Sydney Australia. There was a…
If you're anything like me you always have PowerShell open, and often both PowerShell and…
Decentralised Identity is a technology I'm passionate about and have written many posts and tools…
Over two years ago I authored a PowerShell Module that enabled the automation of 1Password.…
Buried in my PowerShell Snippets Vol 4 post from 2021 is the PowerShell script and…
Short post on how to recovery from "The Windows Subsystem for Linux instance has terminated"…
This website uses cookies.
View Comments