;)
This post is part of a series on Service Manager PowerShell. Be sure to check out the Overview Page for all posts in this series.
In the previous posts, we looked at returning work item and configuration item information with the Get-SCSMClassInstance cmdlet. In one of the examples, we returned all of the properties related to an Incident. You may have noticed, when running this command, that certain items were not returned. Most notably are the assigned to user and the affected user. It also did not return any related configuration items, work items, or activities. The reason these were not returned, is because they are not properties. They are related items. In order to find this you must first find the relationship, then you can return the details of the object.
Determining the Relationship
Just like with class instances, if you want to return a related object, you need to know what the relationship is. As with most things in Service Manager, there are multiple ways that you can determine the relationship. The examples below use the Get-SCSMRelationship cmdlet to determine the relationship. Example 1 is using the Display Name of the relationship. In this case I knew the name of the relationship, and was able to return it in my command. If you are unsure of the relationship you can use a wildcard like in example 2. You can also search by using the Source of Target class. However, you need to be careful with this. If, for example, you ran this command against the Incident class (System.WorkItem.Incident), all that would be returned is the Primary Owner relationship. This is because it is the only one unique to the Incident class. To find the affect user you would need to search on the base System.WorkItem class. For this reason, I generally stick to searching by name.
# Example 1: Using the Display Name
Get-SCSMRelationship -DisplayName "Affected User"
# Example 2: Using a Wildcard
Get-SCSMRelationship -DisplayName "*User*"
# Example 3: Using the Source
Get-SCSMRelationship -Source (Get-SCSMClass -Name System.WorkItem)One way to determine the relationship name is to look at the history of an item in the console. If you look at the item history you will see all relationship changes. The display name of the relationship will be present under the relationship class column.
For more information in determining classes, I suggest checking out this post by Marcel Zehner. He created an excel sheet with all of the different relationship types in Service Manager.
There is one more thing to keep in mind with the Get-SCSMRelationship cmdlet. As with other things in SCSM, multiple relationships can have the same display name. So after finding the relationship using the methods above, it is best to use the Name parameter since this is a unique value. However, for some reason the Get-SCSMRelationship cmdlet does not output the name by default, so you should add “| FT DisplayName, Name” to the end of your command to determine the name.
# Step 1: Determine the relationship
Get-SCSMRelationship -DisplayName "Affected User"
# Step 2: Find the name
Get-SCSMRelationship -DisplayName "Affected User" | FT DisplayName, Name
# Step 3: Using the name parameter save the relationship to a variable
$rel = Get-SCSMRelationship -Name "System.WorkItemAffectedUser"Finding the Related Objects
After determining the relationship, you can use the methods in Get-SCSMClassInstance cmdlet to return the related objects. There are two different methods to find these, GetRelatedObjectsWhereSource and GetRelatedObjectsWhereTarget. You need to use the one where the class of the object you are returning from Get-SCSMClassInstance matches either the source or the target. The example below show how to find the affected user of the incident. Since Get-SCSMRelationship showed that the source is System.WorkItem, we’ll use the GetRelatedObjectsWhereSource method.
# Get the relationship
$rel = Get-SCSMRelationship -Name "System.WorkItemAffectedUser"
# Get the incident
$IR = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.Incident) | ? {$_.ID -eq "IR3570"}
# Use the methods to return the object
$IR.GetRelatedObjectsWhereSource($rel.ID)When you run the command above it will output the EnterpriseManagementObject, which is typically the display name of the object. In this case it would be the name of the Affected User. However, the EnterpriseManagementObject is not just a string value. It contains multiple sub properties of the related object. As with everything else, you never want to go strictly off the display name. So if you add “.EnterpriseManagementObject.id.GUID” to the end of the command it will return the unique GUID of the object. If you save that in a variable, you can then use it with the Get-SCSMClassInstance to return all of the information about the object.
# Get the relationship
$rel = Get-SCSMRelationship -Name "System.WorkItemAffectedUser"
# Get the incident
$IR = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.Incident) | ? {$_.ID -eq "IR3570"}
# Use the methods to return the object GUID and save it to a variable
$AffctUsr = $IR.GetRelatedObjectsWhereSource($rel.ID).EnterpriseManagementObject.id.GUID
# Return the details of the related object
Get-SCSMClassInstance -ID $AffctUsrThis same logic can be applied to the assigned to user, created by user, related work items, affected configuration items, etc. You just need to know the relationship you want to find.
Finding the Related Object by Target
Using the same logic as the previous example you can easily find the activities contained within a Change Request.
# Get the relationship
$rel = Get-SCSMRelationship -Name "System.WorkItemContainsActivity"
# Get the change request
$CR = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.ChangeRequest) | ? {$_.ID -eq "CR823"}
# Use the methods to return the object GUID and save it to a variable
$Act = $CR.GetRelatedObjectsWhereSource($rel.ID).EnterpriseManagementObject.id.GUID
# Return the details of the related object
Get-SCSMClassInstance -ID $ActThe example above returns the activities contained within the change request CR823. But what if you have the review activity, and you want to return the change request it belongs to? In that case all you would need to do is to change your script to use the GetRelatedObjectsWhereTarget method.
# Get the relationship
$rel = Get-SCSMRelationship -Name "System.WorkItemContainsActivity"
# Get the review activity
$RA = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.Activity.ReviewActivity) | ? {$_.ID -eq "RA825"}
# Use the methods to return the object GUID and save it to a variable
$WI = $RA.GetRelatedObjectsWhereTarget($rel.ID).EnterpriseManagementObject.id.GUID
# Return the details of the related object
Get-SCSMClassInstance -ID $WIThis same logic would apply if you wanted to find all of the work items a user is assigned to, or any other type of relationship.
This section showed how to find different related objects. The next few sections will cover how to update, create, and remove relationships and work items. And be sure to check the Overview Post for more content in this series.
