;)
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 a previous post we looked at how to display relationships information using the Service Manager PowerShell cmdlets. In this post we will cover how to create, update, and remove relationships using these cmdlets.
Creating Relationships
Every time you create a relationship in Service Manager, a relationship instance is created. You can think of the relationship instance as the object that joins the two items together. The diagram below shows an example of this. It shows the relationship between an incident and the person assigned to it.
Each box, in the diagram above, represents an object in Service Manager, and has its own unique GUID. Therefore to relate two object together a relationship instance must be created. In order to do this you will need to use the New-SCRelationshipInstance cmdlet.
*PowerShell Tip – As we noted in this Get Work Items post, PowerShell often uses aliases. In this case you may have noticed that the cmdlet is New-SCRelationshipInstance and not New-SCSMRelationshipInstance. This is because many of the Service Manager cmdlets simply use the SC and have an alias to the SCSM name. From what I have witnesses this is the case with many of the cmdlets that are universal between Service Manager and Operations Manager. In this case, you can actually run either version of the cmdlet and get the same results.
For the first example, I am going to use one of the most common tasks associated with creating new relationship instances, setting the assigned to user of incident. In order to do this you will need three things. First, you will need the work item, in this case the incident. Then you will need the user object you want to set as the assigned to user. And finally, you will need the relationship you want to create. As shown in previous posts, you can get the incident and the user object with the Get-SCSMClassInstance cmdlet, and you can get the relationship using the Get-SCSMRelationship cmdlet. Then you simply need to put the three items together using the New-SCRelationshipInstance cmdlet.
| 1234567891011 | # Get the Incident$IR = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.Incident) | ?{$_.Id -eq “IR1820”}# Get User Object$User = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.User) | ?{$_.UserName -eq “adamb”}# Get the Relationship$AssignedToUser = Get-SCSMRelationship -name System.WorkItemAssignedToUser | FL# Create Relationship InstanceNew-SCRelationshipInstance -RelationshipClass $AssignedToUser -Source $IR -Target $User |
Just like in the Get Realtionships post, you will need to examine the output of the Get-SCSMRelationship to determine the appropriate source and target objects. In this case you may noticed that the source class for the “Assigned To User” relationship is System.Workitem, and we used an incident for the source. This works because the Incident class is a subclass of Work Item, and therefore inherits all of its properties and relationships.
Updating Relationships
If you look at the Service Manager PowerShell cmdlets you will notice there is not an Update-SCRelationshipInstance cmdlet. This is because you do not update relationships in the same way that you update objects. Depending on how the relationship is created in Service Manager, you can have 1, or as many as 2,147,483,647 instances of a relationship. In the previous example we added an “Assigned To User” relationship to an incident. Since you can only have 1 person assigned to an incident at a time, if there was a previous relationship, the new one would override it. However, if we added the user to the relationship, that allows more than one instance, for example “Is Related to Configuration Item”, then it would add the new relationship to the list of existing relationships. In order to determine the total number of allowed relationship instances you can use the Get-SCSMRelationship cmdlet. The total number of relationship instances is listed the MaxCardinality of the Target property. The example below shows you how to output this information for a couple of relationship types.
| 12345 | # Display the number of relationship instances for Assigned To UserGet-SCSMRelationship -name System.WorkItemAssignedToUser | %{Write-Host $_.Name “-” $_.Target.MaxCardinality}# Display the number of relationship instances for Is Related to Configuration ItemGet-SCSMRelationship -name System.WorkItemRelatesToConfigItem | %{Write-Host $_.Name “-” $_.Target.MaxCardinality} |
If you run the commands above you will see “Assigned To User” can have 1 instance, and “Is Related to Configuration Item” can have over 2.1 billion. Remember if you add a new instance and it exceeded the number allowed, then the previous instances will be overwritten. So in the case of updating the “Assigned To User”, or any other relationship that has only 1 instance, you just need to run the New- SCRelationshipInstance cmdlet again, and you will overwrite any previous relationships with your new one. However, if you want to change a relationship where there are multiple instances allowed, then you will need to remove the old instances and then add the new ones.
Removing Relationships
The Remove-SCRelationshipInstance cmdlet is used when removing a relationship instance in Service Manager. Just like with the Update-SCSMClassInstance cmdlet, the easiest way to use the Remove-SCRelationshipInstance cmdlet is by piping it into another command that returns the instance you want to remove. To do this, you need to use the Get-SCRelationshipInstance cmdlet. Personally, I’m not a big fan of this cmdlet, since the parameters do not work like you would expect them to. For example, it has a parameter for the Source instance and a parameter for Target instance. So you would think that if you entered an object for the source and an object for the target, it would tell you the relationship instances between the two, but it does not. I will display all of the relationship for the source and all of the relationship for the target into one big list. Therefore, when using this cmdlet it is best to only list a source or a target, then use a where clause to narrow down to the specific relationship type. In the example below you can see how it is used to return all instances of the “Is Related to Configuration Item” relationship class for a specific incident, then it removes them all.
| 12345678 | # Get the Incident$IR = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.Incident) | ?{$_.Id -eq “IR1820”}# Get the relationship$rel = Get-SCSMRelationship -Name “System.WorkItemRelatesToConfigItem”# Return and remove the relationship instancesGet-SCRelationshipInstance -Source $IR | ?{$_.RelationshipId -eq $rel.Id} | Remove-SCRelationshipInstance |
Review Activity Relationships
One of the most confusing tasks in Service Manager automation can be working with Reviewers in a Review Activity. This is because the user listed as the reviewer does not have a direct relationship to the review activity. There is a class named Reviewer that gets created and related to the review activity as the Reviewers relationship. Then a user or group can be related to that Reviewer as the “Is User” or “Voted By User”. The “Is User” is the person who is assigned as the reviewer and the “Voted By User” is the person who actually approved or rejected the request. So remember, when dealing with Review Activities there are three different relationships to take into consideration. I have listed them in the table below for your reference.
| Display | Internal Name | Source Class | Target Class |
|---|---|---|---|
| Reviewers | System.ReviewActivityHasReviewer | System.WorkItem.Activity | System.Reviewer |
| Is User | System.ReviewerIsUser | System.Reviewer | System.User |
| Voted By User | System.ReviewerVotedByUser | System.Reviewer | System.User |
In order to add a reviewer to a review activity you must first create the Reviewer, then relate the Reviewer to the Review Activity, then relate the user to the Reviewer as the Is User. The diagram below shows a visual representation of this, with the rectangles being Service Manager objects and the ovals being relationships.
Now there is one more thing to mention about adding a reviewer to a Review Activity. You cannot add an existing Reviewer to a Review Activity. If you try you will receive a message stating, “A discovery data item was rejected because the item is already bound to another Membership relationship.” In order to avoid this you need to create the Reviewer object at the same time you create the Reviewers relationship instance to the Review Activity. As shown in the example below, you do this by using the TargetClass and TargetProperty parameters in the New-SCRelationshipInstance cmdlet.
| 12345678910111213141516171819202122232425262728 | # Get the Review Activity$RAId = “RA1873″$RA = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem) | ?{$_.ID -eq $RAId}# Get the Reviewers relationship$ReviewerRel = Get-SCRelationship -name System.ReviewActivityHasReviewer# Set the properties for the Reviewer object (Set MustVote and Veto according to your needs)$reviewer = @{Decision = “Not Yet Voted”MustVote = $FalseVeto = $False}# Create the Reviewer and Relate it to the Review Activity$ReviewerRelInstance = New-SCRelationshipInstance -RelationshipClass $ReviewerRel -Source $RA -TargetClass (Get-SCSMClass -name System.Reviewer ) -TargetProperty $reviewer -PassThru# Get the Reviewer object that was just created$ReviewerInstance = Get-SCSMClassInstance -Id $ReviewerRelInstance.TargetObject.Id.Guid# Get User Object to relate to the Reviewer$Approver = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.User) | ?{$_.UserName -eq “adamb”}# Get the Is User Relationship$ReviewerIsUser = Get-SCRelationship -name System.ReviewerIsUser# Create the Is User relationship between the Reviewer and the UserNew-SCRelationshipInstance -RelationshipClass $ReviewerIsUser -Source $ReviewerInstance -Target $Approver |
There are a few things you will want to make note of in the script above. First, when setting the properties of the Reviewer object, we created a hash table. This allows you to set the all of the values required for the object and pass them as one variable in the command. You will also what to note the settings in this hash table. The decision should always be set to “Not Yet Voted”, but the MustVote and Veto can be set to True or False depending on your needs. Finally, you may have noticed that we used the PassThru parameter when creating the Reviewers relationship. The PassThru parameter allows you to save the newly created object to a variable, in this case the $ReviewerRelInstance variable. We then used this variable to get the unique GUID of the Reviewer object that was created. This is then used that to save the Reviewer object to the variable $ReviewerInstance, which is used to related the User to the Reviewer.
In this post you have seen how to create, update, and remove Service Manager relationships. Be sure to check the Overview post for more content in this series.
