Automatically Adding the Customer Company CI When an Incident is Created – Workflow Authoring – Part 1 Constructing the PowerShell Script

Automatically Adding the Customer Company CI When an Incident is Created – Workflow Authoring – Part 1 Constructing the PowerShell Script

Automatically Adding the Customer Company CI When an Incident is Created – Workflow Authoring – Part 2 Authoring the Workflow

** Update ** I’ve also added the code to use if you are incorporating the Organisation Class from Cireson Asset Management.

Almost every deployment of Service Manager that I’ve designed or worked on has required a custom class to represent a customer organisation.  When an analyst is examining an Incident or Service Request form it is immediately obvious which organisation they belong to, and any important facts about that organisation, such as whether their support contract has expired, and key contacts.

So, this is an easy customisation to implement, however the analyst then has an extra manual step to figure out which customer organisation to use when creating or triaging an Incident.  We can easily automate this with a simple PowerShell script.

This is a two part series that describes the PowerShell script, and the authored workflow that will automate it.  Part 1 explains the construction of the PowerShell script.  Part 2 explains the construction of the workflow.

Prerequisites

Prerequisite: User Company Property

This automation process relies on the “Company” property being populated on your user CIs, and that the company name matches the Customer Organisation name for the relevant Customer.

Prerequisite: Customer Class

The first prerequisite is the Customer Company class.  I’ve seen this implemented in many different ways, in many different companies, and there are a couple of blogs out there on the subject. (Here’s a great one by Marcel Zehner).  A quick rundown is that out of the box SCSM is not ‘customer aware’.  That is to say that the customer or client is a company, that you want to store various bits of information about such as, primary contact, contract information, billing, business type, number of employees, etc, and this class doesn’t exist by default.

For this post I’ve created a CI Class called CustomerOrganisation, located in a management pack called Dev.CustomerOrganisation.Classes

If/when you create this class I’d recommend calling it something like Customer Organisation, or Customer Company rather than just Customer.  Like almost every Service Desk I’ve interacted with the term Customer is used to refer to an individual user as well as a company.  There is also a relationship in the IR class called ‘Customer’ that relates the IR back to an AD User.  You’ll confuse terminologies by introducing another entity with the same name.

Prerequisite: IR to Customer Relationship

Obviously you’ll need to have a relationship between the Incident Class and your new Customer organisation class.  I’ve called mine “RelatedCustomerOrganisation” and stored it in the CustomerOrganisation class.

Optional Prerequisite: Show the Customer Org in the Incident Form

You don’t need to do this for the purpose of this workflow, however it makes sense to extend the Incident form to show a Single Instance Picker that is bound to your “RelatedCustomerOrganisation” relationship.

The PowerShell Script

The first thing we need to do is load the PowerShell module.

Import-Module 'C:\Program Files\Microsoft System Center 2012 R2\Service Manager\Powershell\System.Center.Service.Manager.psd1'

Next we need to obtain the relationships for the Customer Organisation and Affected User.

#Store the relationship types as a variables
$CORel = Get-SCSMRelationship -Name "RelatedCustomerOrganisation"
$AURel = Get-SCSMRelationship -Name "System.WorkItemAffectedUser"

It is important here that you specify the system name of your Customer Organisatoin class, and not the friendly display name.

Now we need to obtain the Incident.

# Get the Incident
$IR = Get-SCSMClassInstance -Class (Get-SCSMClass -Name System.WorkItem.Incident) | ? {$_.ID -eq "$GUID"}

I know I’ve used a variable here for the Incident ID.  We will populate that by configuring the variable in the workflow properties (see part 2).

Now we have the Incident, we can obtain the Affected User relationship that exists between the Incident and the User.

# Use the method to return the related Affected User object GUID and save it to a variable
$AffectedUserGUID = $IR.GetRelatedObjectsWhereSource($AURel.ID).EnterpriseManagementObject.id.GUID

Now I’ve enclosed the remainder of the script in an if statement.  This is to ensure the script doesn’t attempt to run and possibly throw an error, if the Affected User relationship doesn’t exist.

# If related Affected User is returned then process the remainder of the script
if ($AffectedUserGUID -ne $null)

{

Now we need to obtain the CI info about the Affected user so we can obtain the value of the Company property.

# Obtain CI info about the Affected User
$AU = Get-SCSMClassInstance -ID $AffectedUserGUID

And then obtain the Customer Organisation CI where the value of the DisplayName property matches the value of the users Company property.

# Obtain the Customer Organisation where the name matches the users Company property
$CO = Get-SCSMClassInstance -Class (Get-SCSMClass -Name CustomerOrganisation) | ? {$_.DisplayName -eq $AU.Company}
[/code</pre>
Finally, we create the relationship.
<pre>
# If a match between the user and the Customer Organisation is found then create the relationship
if ($CO -ne $null)

{

#Create the relationship between the Incident and the Customer Organisation CI
New-SCRelationshipInstance -RelationshipClass $COREL -Source $CO -Target $IR

}

}

Now onto part 2 to plug the script into a workflow!