Definitive Service Manager Powershell Part 3
How did you do on the homework assignment? Did you get different Objects of different Classes out of your environment like Review Activities or Hardware Assets? Here’s to hoping you did because now it’s time to build on those get/read operations and set/write properties on them!
Change a Few Incident Properties
We’re working with IR1234 again and no less starting with the identical 2 lines from the previous post. Plus, we’ll introduce another one of our definitive commands in the process.
$irClass = Get-SCSMClass –name "System.WorkItem.Incident" -computername "mgmtServer01"
$incident = Get-SCSMObject –class $irClass –filter "Name -eq 'IR1234'" -computername "mgmtServer01"
This time however, we’re going to throw the Incident we get back from Service Manager into a variable. Once it’s in a variable, we have that Incident in memory for as long as we have our PowerShell window open. We also don’t need to use | select-object * here, because $incident does in fact contain the entire Incident. PowerShell previously showed us just a summary. Emphasis on – PowerShell showed us a summary. The whole Incident was there all along and now we’re going to temporarily store it in the appropriately named $incident variable. Shall we change the Incident title? We shall!
$irClass = Get-SCSMClass –name "System.WorkItem.Incident" -computername "mgmtServer01"
$incident = Get-SCSMObject –class $irClass –filter "Name -eq 'IR1234'" -computername "mgmtServer01"
Set-SCSMObject –smobject $incident –property "Title" -value "Updated Title from PowerShell" -computername "mgmtServer01"
Done! Seriously that was it.
We declare the Class we want to work with, we retrieve an Object of that Class, we then use that Object in Set-SCSMObject to change a property by the name of “Title.” This whole process should feel pretty familiar if you’re using the SCSM Console or the Cireson SCSM portal. You look up an item you want to work with and then you set one or more properties. Speaking of which – what if you wanted to change more than just a single property on an Incident through PowerShell?
$propertiesToChange = @{
"Title" = "Updated Title from PowerShell";
"Description" = "This is the new Description of the Incident that I updated from PowerShell";}
Set-SCSMObject –smobject $incident –PropertyHashtable $propertiesToChange -computername "mgmtServer01"
It’s a slightly larger script, but we can now define multiple property/value pairs that we want to change in with a single PowerShell command. Why do this instead of several independent Set-SCSMObjects you ask? It’s not just about efficiency, it’s also that with every Set-SCSMObject we’re automatically adding a new entry into the History tab of the Object in question. Which means you can either have several History events back to back or a single one entered by whoever runs the above PowerShell. Auditing trail preserved!
Change a Few Manual Activity Properties
For our next example, let’s work with a Manual Activity. Here we’ll not only Complete a Manual Activity, but we’ll also leave some comments in the Notes field.
$maClass = Get-SCSMClass -name "System.WorkItem.Activity.ManualActivity$"
$ma = Get-SCSMObject -filter "name -eq 'MA5342'"
Set-SCSMObject –smobject $ma –propertyhashtable @{"Status" = "9de908a1-d8f1-477e-c6a2-62697042b8d9"; "Notes" = "This task has been completed and I did it with PowerShell!"; "ActualEndDate" = (get-date).ToUniversalTime()} -computername "mgmtServer01"
The pattern once again repeats itself. We define the Class we want to work with, we retrieve an Object from that Class, and finally we take action on it. Although here you’ll notice that instead of creating a variable to hold the properties and then changing them. I set them directly following the –PropertyHashtable parameter. Either way works, it just comes down to how you prefer to execute the command and what you find easier to read. Second, when we mark a Manual Activity as Complete we also set its Actual End Date property. We technically do not have to do this, but come reporting time we’d then have a “shape” or subset of Manual Activities that were Completed but missing an Actual End Date. In which case, we set it here because it’s just simply the right thing to do. Next, we set the Notes field to a value we want. Finally, we set the Status of the Manual Activity.
But the Status property probably wasn’t what you were thinking it was going to be. We didn’t use the word “Completed”. We used something else entirely. Just where did that value come from?
Enumerations (otherwise commonly known as Lists)
For our last example, we’re going to talk about another one of our definitive commands in practice. Get-SCSMEnumeration and Get-SCSMChildEnumeration. Commands that are worth emphasizing once more are wholly unique to SMLets. It’s not to say we can’t use the stock Microsoft commands, but it will require a little more PowerShell to achieve the same end result.
Unlike the Title or Description on an Incident or Manual Activity which are simple text fields. Things such as Impact, Urgency, or even Status are defined in the SCSM Console in the Library -> Lists view. Which means they are something else entirely than just text.
First is the general concept of a List. Things like:
- Incident Tier Queue
- Change Area
- Service Offering Category
- Incident Classification
- Activity Status
are examples of Lists. But items such as Hardware, Printing, Error Message, Completed, Level 2, etc. are examples of List Values. So long as you understand the hair being split here, then you understand the nature of Lists in Service Manager. It also means you now understand the difference between Get-SCSMEnumeration and Get-SCSMChildEnumeration. Let’s try it out:
$incidentClassificationList = Get-SCSMEnumeration –name "IncidentClassificationEnum$" -computername "mgmtServer01"
Get-SCSMChildEnumeration –enumeration $incidentClassificationList -computername "mgmtServer01"
In the above example we first retrieve the List we’re interested and then we retrieve that list’s values. Using the PowerShell pipeline, you can actually accomplish the above in a single line. You get the List which acts as the input to the item on the right of the pipeline.
Get-SCSMEnumeration –name "IncidentClassificationEnum$" -computername "mgmtServer01" | Get-SCSMChildEnumeration -computername "mgmtServer01"
But to use one of these list values in a Set-SCSMObject command, we need a unique identifier for the List Value we’re interested in. The above one liner gets us close to that objective, but falls just a bit short. Let’s perform one small change to our PowerShell one liner:
Get-SCSMEnumeration –name "IncidentClassificationEnum$" -computername "mgmtServer01" | Get-SCSMChildEnumeration -computername "mgmtServer01" | select-object displayname, id
Now we can see our plain text List Values next to our unique List Identifiers.
The reason for explaining this all comes back to our previous example. We want to set a Manual Activities Status to Complete. With the unique identifier for “Complete” we can now set it. But if you’re thinking:
How do you know what enum/list names are?
Just like Get-SCSMClass in the previous lesson, Get-SCSMEnumeration works as an implicit wildcard. Which means we can again guess as to what it may be called:
Get-SCSMEnumeration –name "ActivityStatus" -computername "mgmtServer01" | select-object displayname, id
And voila! The unique identifier for Completed has revealed itself! Not to mention, we didn’t even need to use Get-SCSMChildEnumeration because of the naming that exists behind the scenes for Activity Status. With our new found knowledge, we can now change properties of text fields or list values on Work Items or Configuration Items.
Tip: Full disclosure. You can use a plain text value to set a list value. But before you raise the pitchforks or decide to never look back at Get-SCSMEnumeration and Get-SCSMChildEnumeration let’s talk about why in my opinion you should not entertain this. Any Administrator or Advanced Operator role in Service Manager has the permission to update a List. Which means they have the ability to potentially rename an item in the list. Should they do this your script breaks as the value is now technically missing. But the Unique Identifier behind the scenes of it will never change. Which means a List Value can be renamed as often as you want but the actual behind the scenes unique value will always be there. It’s not just best practice, but it’s the safest practice and habit you can form!
Alright it’s almost time to wrap this post up. Think you’re getting the hang of things? Could you see yourself possibly using the above ideas to go one step further and…
- Skip a Manual Activity?
- Change the Support Group (Tier Queue) on an Incident?
- Retire a Hardware Asset?
I hope so because it’s time for…
Homework Assignment #2
Using a combination of Get-SCSMClass, Get-SCSMObject, Get-SCSMEnumeration, Get-SCSMChildEnumaration, and finally Set-SCSMObject:
- Change the Classification on a single Incident
- Change the Price or Maximum Available Level (max inventory stock) of a single Consumable
- This will require Cireson Asset Management
- Change the Area of a single Manual Activity and its Scheduled Start/End Dates
- Resolve a single Incident by setting the Incident’s Status, Resolved Date, Resolution Category, and Resolution Description
- Update the Asset Status, Description, and Managed By on an Active Directory Printer
NOTE: When building PowerShell that modifies data it is strongly advised to work against a development environment so you can TEST. TEST. TEST. PowerShell nor Service Manager have an “undo” command so once you’ve changed/committed something that action is immediately performed. Remember that with Great PowerShell Comes Great Responsibility.
In closing – once you know the unique ID of a list value you can re-use it as much as you’d like because it never changes. If you have questions don’t forget that our community has answers! But if you’re looking for bragging rights, feel free to post your own ideas of how to use this in the following community thread. See everyone next week for Part 4!
Definitive Service Manager PowerShell Blog Series: Part 1 / Part 2
