Part 4.1.3 – Receiving Comments – Runbook Design – SMMail_ProcInboundComments

Navigation:

Introduction

Alright! We’re ready to actually process the inbound comment emails. This will be a fairly long runbook.

Overview

We want a runbook that does the following:

  1. Accepts one parameter: emailID
  2. Gets the email by ID.
  3. Enters the email’s body text into the appropriate ticket.
  4. Generates and sends an email to the support team.

Branch Overview

We will need two branches, one for incidents, and one for service requests (big surprise).

  • Main
    • Branch 1 – Incidents
    • Branch 2 – Service Requests

Global Variables

  1. SCSM Scripts Account Username
    1. Username of AD account which can run SCSM SMLets on your SCSM server. It should have local admin rights on the SCSM server.
  2. SCSM Scripts Account Password
    1. Password to the account username given in the global variable ‘SCSM Scripts Account Username’.
    2. Make sure to check the ‘Encrypted Variable’ checkbox.
  3. SCSM Email Notification BCC Addresses
    1. semi-colon delimited list of email address to bcc all messages to.
  4. Email Scratch File Folder
    1. Folder to store a temp files for processing the email body text.

Activities Overview

Main Branch

  1. Initialize Data
    Type: Initialize Data
    Parameter 1 Name: emailID
  2. Get Email
    Type: Exchange User -> Get Items
    Configuration: helpdesk mailbox
    Filter: ID equals {emailID from “Initialize Data”}
  3. Smart Link
    Include: Subject from Get Email matches pattern “.*SR[0-9]+.*”
    Include: Subject from Get Email matches pattern “.*IR[0-9]+.*”
    Exclude: Get Email returns Warning,Failed
  4. Sanitize Subject
    Type: Data Manipulation -> Replace Text
    Input String: {Subject from Get Email}
    Pattern: ” (double-quotes)
    Replacement Text: (nothing)
    Use Regular Expression: True

Branch 1 – Incidents

  1. Smart Link from Sanitize Subject
    Include: Subject from Get Emails matches pattern “.*IR[0-9]+.*”
  2. (IR) Get ID from Email Subject
    Type: Data Manipulation -> Match Pattern
    Input String: {Subject from Get Email}
    Pattern: “IR[0-9]+”
    Case Sensitive: False
    Return Match Number: 0
  3. Get Incident
    Type: SC 2012 Service Manager -> Get Object
    Class: Incident
    Filters: ID equals {Match String from (IR) Get ID from Email Subject}
  4. (IR) Generate Comment GUID
    Type: Runbook Control -> Invoke Runbook
    Runbook: Generate GUID
    Invoke by path: True (checked)
    Wait for completion: True (checked)
  5. (IR) Write Email Body to Temp Folder
    Type: Text File Management -> Append Line
    File: {Email Scratch File Folder}scratch-{GUID from “(IR) Generate Comment GUID”}.txt
    File encoding: Auto
    Text: {Body from “Get-Email”}
  6. (IR) Parse HTML Email Body Content
    Type: System -> Run .Net Script
    Language: Powershell
    Script: See script section below “(IR) Parse HTML Email Body Content”.
    Published Data 1 Name: Plain Text Output
    Published Data 1 Variable: retval
  7. (IR) Replace Text
    Input String: {Plain Text Output from “(IR) Parse HTML Email Body Content”}
    Pattern: ” (double-quotes)
    Replacement Text: (nothing)
    Use Regular Expression: True
  8. (IR) Compile Comment
    Type: System -> Run .Net Script
    Language: Powershell
    Script: See script section below “(IR) Compile Comment”.
    Published Data 1 Name: Final Comment Text
    Published Data 1 Variable: comment
  9. (IR) Write Analyst Comments to Work Item
    Type: SC 2012 Service Manager -> Create Related Object
    Source Class: Incident
    Target Class: Trouble Ticket Analyst Comments
    Relationship Type: Has Analyst Comment
    Source Object Guid: {SC Object Guid from “Get Incident”}
    Comment: {Final Comment Text from “(IR) Compile Comment”}
    Entered by: {Sender from “Get-Email”}
    Entered date: {Date/Time Received from “Get Email”}
    ID: {GUID from “(IR) Generate Comment GUID”}
    Is private: True
    Display Name: {GUID from “(IR) Generate Comment GUID”}
  10. (IR) Forward to Admins
    Type: Exchange User -> Forward Item
    Body Prefix: The following message was processed and added to work item {Match String from “(IR) Get ID from Email Subject”} with title “{Title from “Get Incident”}.
    ID: {ID from “Get Email”}
    To: {SCSM Email Notification BCC Addresses}
  11. (IR) Move to Completed
    Type: Exchange User -> Move Item
    Configuration: helpdesk connector
    ID: {ID from “Get Email”}
    Copy: False
    Destination Folder: processing-complete

Branch 2 – Service Requests

I’m only going to detail the items in this section that are significantly different.

  1. Smart Link from Sanitize Subject
    Include: Subject from Get Emails matches pattern “.*SR[0-9]+.*”
  2. (SR) Get ID from Email Subject
  3. Get SR
  4. (SR) Generate Comment GUID
  5. (SR) Write Email Body to Temp Folder
  6. (SR) Parse HTML Email Body Content
  7. (SR) Replace Text
  8. (SR) Compile Comment
  9. (SR) Write Analyst Comments to Work Item
    Type: SC 2012 Service Manager -> Create Related Object
    Source Class: Service Request
    Target Class: Trouble Ticket Analyst Comments
    Relationship Type: Work Item Has Comment Log
    Source Object Guid: {SC Object Guid from “Get SR”}
    Comment: {Final Comment Text from “(SR) Compile Comment”}
    Entered by: {Sender from “Get-Email”}
    Entered date: {Date/Time Received from “Get Email”}
    ID: {GUID from “(SR) Generate Comment GUID”}
    Is private: True
    Display Name: {GUID from “(SR) Generate Comment GUID”}
  10. (SR) Forward to Admins
  11. (SR) Move to Completed

Error Notifications

Alright, great. But what if something goes wrong? We need to add some error logging. For this, we’ll need to create several sub-branches.

Create the following branches:

Error Branch 1 (IR)

  1. Smart Link from ‘Get Incident’
    Include: Number of Objects from Get Incident equals 0
    Include: Get Incident returns warning or failed
  2. (IR) Generate Missing WI Msg Properties
    Type: System -> Run .Net Script
    Language: Powershell
    Script:

    $message = "The subject line of this email contains the Work Item ID {Match String from "(SR) Get ID from Email Subject"}. However, this work item could not be found in SCSM. The email's ID is {ID from "Get Email"} and has been moved to 'processing-failed' folder."

    Published Data 1 Name: message
    Published Data 1 Variable: message

  3. (IR) Forward to Admins 1
    Type: Exchange User -> Forward Item
    ID: {ID from “Get Email”}
    To: {SCSM Email Notification BCC Addresses}
    Body Prefix: {message from “(IR) Generate Missing WI Msg Properties”}
  4. Move to Failed
    Type: Exchange User -> Move Item
    Configuration: helpdesk connector
    ID: {ID from “Get Email”}
    Copy: False
    Destination Folder: processing-failed

ERROR BRANCH 2 (IR)

  1. Smart Link from (IR) Parse HTML Email Body Content
    Include: Plain Text Output from (IR) Parse HTML Email Body Content equals failed
    Include: (IR) Parse HTML Email Body Content returns warning or failed
  2. (IR) Replace Text (failure)
    Input String: {Plain Text Output from “(IR) Parse HTML Email Body Content”}
    Pattern: ” (double-quotes)
    Replacement Text: (nothing)
    Use Regular Expression: True
  3. (IR) Generate Missing WI Msg Properties
    Type: System -> Run .Net Script
    Language: Powershell
    Script:

    $message = "There was a problem parsing the body contents of the email mesage. The Powershell parse script returned the following output "{Replacement Text from (IR) Replace Text (failure)"}."

    Published Data 1 Name: message
    Published Data 1 Variable: message

  4. (IR) Forward to Admins 2
    Type: Exchange User -> Forward Item
    ID: {ID from “Get Email”}
    To: {SCSM Email Notification BCC Addresses}
    Body Prefix: {message from “(IR) Generate Missing WI Msg Properties”}
  5. Move to Failed
    Type: Exchange User -> Move Item
    Configuration: helpdesk connector
    ID: {ID from “Get Email”}
    Copy: False
    Destination Folder: processing-failed

ERROR BRANCH 3 (IR)

  1. Smart Link from ‘(IR) Compile Comment’
    Include: Number of Objects from Get Incident equals 0
    Include: Get Incident returns warning or failed
  2. (IR) Generate Comment Compile Failed Msg
    Type: System -> Run .Net Script
    Language: Powershell
    Script:

    $message = "There was a problem compiling the comment for the email mesage. The Powershell parse script returned the following output {Error summary text from "(SR) Compile Comment"}."

    Published Data 1 Name: message
    Published Data 1 Variable: message

  3. (IR) Forward to Admins 3
    Type: Exchange User -> Forward Item
    ID: {ID from “Get Email”}
    To: {SCSM Email Notification BCC Addresses}
    Body Prefix: {message from “(IR) Generate Missing WI Msg Properties”}
  4. Move to Failed
    Type: Exchange User -> Move Item
    Configuration: helpdesk connector
    ID: {ID from “Get Email”}
    Copy: False
    Destination Folder: processing-failed

ERROR BRANCH 4 (IR)

  1. Smart Link from ‘(IR) Write Analyst Comments to Work Item’
    Include: Number of Objects from Get Incident equals 0
    Include: Get Incident returns warning or failed
  2. (IR) Generate Write Comment Failed Msg
    Type: System -> Run .Net Script
    Language: Powershell
    Script:

    $message = "There was a problem writing the comment the SR. The email has been moved to the 'processing-failed' folder. Email ID: {ID from "Get Email}. Work item ID: {ID from "(SR) Write Analyst Comments to WI}. Error message: {Error summary text from "(IR) Write Analyst Comments to Work Item}."

    Published Data 1 Name: message
    Published Data 1 Variable: message

  3. (IR) Forward to Admins 3
    Type: Exchange User -> Forward Item
    ID: {ID from “Get Email”}
    To: {SCSM Email Notification BCC Addresses}
    Body Prefix: {message from “(IR) Generate Missing WI Msg Properties”}
  4. Move to Failed
    Type: Exchange User -> Move Item
    Configuration: helpdesk connector
    ID: {ID from “Get Email”}
    Copy: False
    Destination Folder: processing-failed

I recommend that you duplicate these error branches for the ‘Service Request’ branch of this runbook as well.

Scripts

Note: The (SR) scripts are basically the same as these below, but with different SCSM variables linked in.

(IR) Parse HTML Email Body Content

$retval = Powershell {
$filename = "{File Path from "(IR) Write Email to Temp File"}"
If(test-path $filename) {
  $body = Get-Content "$filename" -Raw 
  $html = New-Object -ComObject "HTMLFile"
  $htmlBody = Get-Content "$filename" -Raw
  $html.IHTMLDocument2_write($htmlBody)
  $plainOutput = $html.body.innertext
}
Else{$plainOutput = $false}

#limit to 3750 characters, scsm can only handle 4k
If($plainOutput.Length -gt 3800) {$plainOutput = $plainOutput.Substring(0,3750)}
#remove non-xml char's since we're passing it back in
$plainOutput = [System.Text.RegularExpressions.Regex]::Replace($plainOutput,"[^1-9a-zA-Z_:.\\\/\-\!\@\#\$\%\^\&\*\(\)\+\=\,]"," ")
$plainOutput
}

(IR) Compile Comment

$From = "{From from "Get Email"}"
$sent = "{Date/Time Sent from "Get Email"}"
$to = "{To from "Get Email"}"
$Subject = "{Subject from "Get Email"}"

#$BodyFilePath = ""
#$Body = PowerShell { Get-Content "$BodyFilePath" -Raw }

$Body = "{Output String from "(IR) Replace Text"}"
$Comment = "From: " + $from + "`n"
$comment += "Sent: " + $sent + "`n"
$comment += "To: " + $to + "`n"
$comment += "Subject: " + $subject + "`n"
$comment += "`n"
$comment += $body

Conclusion

Here is an image of the final runbook!

413-1

Advertisements

One thought on “Part 4.1.3 – Receiving Comments – Runbook Design – SMMail_ProcInboundComments

  1. Pingback: How I Handle SCSM Email Integration – Navigation | windowsmasher

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s