Monday, March 30, 2015

Getting Other Types of "Things" from a Custom PowerShell Exchange Connector

9:35 PM Posted by Adam Dzak No comments


You know what seems like a reasonable thing to do? Call a phone number, leave a voicemail, and create an incident for the user that called; to the shell!

Scenario: Your company makes use of a non-Microsoft phone system and you've setup a phone number to leave voicemails in the Service Manager Workflow account's inbox so as to take advantage of the Exchange Connector with the purpose of converting the email with voicemail attachment to a Work Item (Incident or Service Request) within SCSM.

Issue: The Exchange Connector (v3 and 3.1) both only parse a specific type of message class. That message class is "IPM.Note". It's by design and crazily useful because it means only emails will get converted into Work Items. Things that won't get converted are things like Out of Office replies (IPM.Note.Rules.Oof.Template.Microsoft) or in this case your phone system's more than likely proprietary voicemail message class. For example, the message class for Interactive Intelligence is IPM.Note.i3Vox.

Resolution v1: So maybe it isn't just voicemails, may you want other message classes converted to work items. Regardless, this can be done using...
  1. PowerShell
  2. Active Directory cmdlets (available with an RSAT installation)
  3. The community developed SMLets for Service Manager (an absolute MUST for anyone wanting to play with SCSM via PowerShell)
  4. OPTIONAL: A virtual/physical machine running Outlook

The fourth step is certainly optional, because you could just as easily install Outlook on one of the Service Manager management servers. But if you have a VM infrastructure I generally avoid putting any additional kind of load on the core SCSM infrastructure. Granted, this is a pretty small trick to execute but to each their own.

Getting Started...
We'll be making use of the following script located here on my TechNet page. This script runs as your SCSM Workflow account via Task Scheduler to rip through the locally available Outlook client every 5 minutes to check for a different type of message class (in this case voicemails) and create Work Items in SCSM with the voicemail file as an attached item. If you're looking really close, it may ring a bell with this script from 2011 with just a few modifications. Since this script is scrubbing for a different type of message class you'll never jeopardize your primary SCSM functions!

You'll also need to configure Outlook to allow programmatic access to itself. Out of the box this is turned off (for obvious reasons of security) but in this case you'll need to either disable it entirely or scope access to it. Once you're done with this you'll also need to create a folder on the machine where this is running (then again, you could easily use a network share if you prefer - just modify the script to point to the new location) so you can temporarily save off the voicemail attachments. I say temporarily as once the Work Item is created the script also does cleanup and deletes the attachments it pulled from the email. This way you can ensure you don't eventually have this script be the cause of an "Out of Disk Space" error.

The other thing this script does is attempt to identify who left the voicemail. Presumably your phone system may leave voicemails with either the called as the sender, subject, etc. This too can be targeted by programmatic means with PowerShell/Outlook. Once id-ed a quick sanity test validates the caller by passing them into a simple "Get-ADuser" check.

FAQ...
  • Isn't this just a hackneyed version of the Exchange Connector? Yes, it absolutely is!
  • Can't I just do this with Orchestrator? You could try, until you realize much like the Exchange Connector within SCSM that the Integration Packs for Exchange in SCO also fundamentally make use of the IPM.Note class.
  • Why can't you just make a management pack for SCSM to allow some of this customization via a Settings pane or something? Hrrmmm. Good point...

Sunday, March 22, 2015

I'd Love to Use a "Direct Reports" style Service Request but...

10:01 AM Posted by Adam Dzak 2 comments


Perhaps you're an IT department who...well maybe needs some work when it comes to Active Directory management (titles aren't right, manager/direct report relationships are incorrect, etc) OR maybe your structure and maintenance is flawless! In either scenario - you'll recognize the importance of it when it comes to Service Manager queries (or Office 365, because SharePoint will showcase these things as well).

As I recall (and no less found around the internet) was something to the tune of "I want to build a Service Request for a new hire workflow and I need to be able to select managers." or in my case I wanted to build some Service Requests that were available only to managers and other select AD groups and within those requests only show My Direct Reports. Because if I were to use such a query, it opens up a lot of really interesting Active Directory automation possibilities such as, but not limited too...
  • Change one of my employee's titles
  • Change one of my employee's names
  • Terminate one of my employee's
  • Order hardware for one of my direct reports
  • etc.
There are certainly a lot of really basic requests you can do, but if you're like me keeping the end user in mind (in this case a manager) - you've just made a select group of requests SUPER friendly and easy to use on the Service Manager portal. So you get to building, you start building the request and then you run into your first problem.


Wait, how do I show only my direct reports?


SCSM does offer a way to do this, but I ran into the identical problem as described here (https://shaunlaughton.wordpress.com/2014/01/10/working-with-managers-and-direct-reports-within-service-manager-2012-service-requests/) with fortunately a solution! Consider that post absolutely mandatory to start building these types of requests. Suffice it to say, there is a way to build the query natively in SCSM, but it comes with significant performance issues. As Shaun resolves, he built a custom management pack for the specific purpose of targeting just this AD relationship. It results in a significant performance boost for the query and more importantly - never fails! Way to go Shaun!

Alright, so you start building the request/query, you publish it, you start testing with your own AD account with some dummy AD accounts that report to you to test this and it works. Great! Well, almost. Because while I wouldn't fault you for deeming completion, there is something you wouldn't have thought of...because it's a bug in SCSM.

I published a request that shows a manager's direct reports, but managers are calling in complaining that they see people that were let go/left the company. I even checked Active Directory, they don't report to them anymore! How the hell is this relationship known?!


Ugh, so close yet so far right? As I said, this turns out to be a known bug in SCSM (See here). Despite the AD relationship not existing (i.e. being NULL) the relationship is kept in SCSM. This comes down to the AD Connector while being very aware of the change, not updating this particular relationship in SCSM. But SCSM is infinitely customizable right? Of course it is! We can build ourselves a management pack out of this! Because if you haven't started customizing SCSM, you're going to want to now.

As Travis Wright points out how to import additional AD properties in 2009 while at Microsoft you can get any other property you want in his example the web page attribute of AD - http://blogs.technet.com/b/servicemanager/archive/2009/12/21/creating-an-ad-connector-using-powershell-and-csv-import.aspx. But great, the website...that's neat I suppose and I thought you said we were going to build a management pack to get out of this? Correct! What you'll need to do is follow Travis' post exactly but you'll want to include an additional property and that's the "Enabled" property (a Boolean true/false value). Now you'll be able to query all direct reports who are Enabled in AD, thus truly showing all of your active Direct Reports! (If you want to go the extra mile for other potential uses, go ahead and sync some password properties like PasswordLastSet, PasswordNeverExpires, etc. If I were you, when naming this custom Management pack of yours...call it something like "UserCustomizations" or "AdditionalADProperties")

So once you've imported the Direct Report management pack and are syncing the additional properties...NOW you are ready to build your queries.


Scenario 1: I want a service request to show all of my direct reports
    1. Select the first "Manages User"
    2. Scroll down and select username
      1. Set it equal to the Token: Portal Username
        1. By setting this, you are saying whoever is logged into the portal... use their username (i.e. a manager goes to the portal, this query would obtain any employee who reports to them)
    3. Then select "User (Manager and Direct Report)
    4. Now find and add the "Enabled" property
      1. This allows you to target Direct Reports that are Enabled (i.e. You won't see disabled employees)
    5. On "Display Columns" tab select "User (Manager and Direct Report)"
      1. Pick any fields you want to display for the Direct Report such as "Display Name" (Which is their first and last name), Job Title, etc.

Scenario 2: I want to see all Managers (AD users that have direct reports)
    1. Select the second "Manages User"
    2. Scroll down and select username
      1. Set it to is not empty
    1. Select User (Manager and Direct Report)
      1. Find the "Enabled" property and set it equal to True

Scenario 3: I want to see my supervisor as a selection in a Service Request (seems weird, it would only be one selection)
    1. Select the second "Manages User"
    2. Scroll down and select username
    3. Set it equal to the Token: Portal Username
      1. In setting the Username property above, you are settings yourself or whoever is logged into the portal as the token


That's all for now, hope I've managed to help someone through this slightly bizarre setup!

Monday, March 2, 2015

Management Pack Source Control (slightly more intelligent backups)

6:46 PM Posted by Adam Dzak , No comments


I've seen a lot of posts and PowerShell scripts online talk about how to backup your management packs, how to make them regularly scheduled jobs using Task Scheduler (or Orchestrator), and while they all generally work as advertised - I found one thing missing from them (at least that I want!) and it's Source Control.

Team Foundation Server (TFS), Visual Studio, hell even SharePoint to a degree care about what versions of things are "checked out" or updated, etc. Regardless of the size environment you are in, sooner or later someone new is going to join your Service Manager crew and you'll have to arguably just trust they are making good management pack decisions. Which hey - with good training and experience maybe it isn't a concern...or maybe you really just want to know what is going on with those management packs. Specifically, your unsealed management packs that are probably always changing because you're always updating them with new templates, new service requests, etc. If only there was someway to keep track of all the changes going on...

I've recently uploaded a PowerShell script to TechNet which I can only say "GET TO DOWNLOADING!" The script is really simple and does backups of Management Packs only if changes have been made to them. How does it know if changes have been made? It continually updates a local/network path to include new folders for each change in version!

https://gallery.technet.microsoft.com/Unsealed-Management-Pack-59199413