ManagementStudio can monitor a mailbox for replies to emails sent from the system or for new emails sent directly to ManagementStudio for actioning.

These emails can be triaged as they are read and either ignored, raised as a defect, or attached to existing records. For example, emails containing Out Of Office replies to surveys can be ignored, or attached to the User's record so that a migration engineer can adjust a user's migration time using the info in the OOO email. Users can be encouraged to email questions they have to the project mailbox and those emails are automatically raised as defects for a migration engineer to action.

Reading a Mailbox

Config

The appSettings.json entry EmailTasks:ReceiveEveryXMin controls how frequently mailboxes are checked for emails. The lowest value this can be is 2 minutes and the recommended value is 10 minutes. 

Administration\Project Settings: Email Settings

1. Email From Address
   1. The email address users will see emails sent from MS will come from
2. Email From Display Name
   1. The name users will see emails sent from MS will come from
3. Enable Tracking
   1. MS adds a tracking token to each email that is sent, this allows the mailbox reader to recognise emails that are replies to emails sent from MS and have the reply get attached to the associated app/user/device, etc
4. Monitor a Mailbox
5. Monitor a Mailbox Enabled
   1. Tick to turn on mailbox monitoring
6. Create Defects for emails...
   1. Tick to have MScreate a Defect for emails that could not be associated with an app, user, device, etc
7. Pre-Processor Script
   1. The script Id of the script with any custom logic to triage emails.
   2. There can only be one pre-processor script. Any and all rules must go in the same script
8. Shared Mailbox Alias
   1. If a shared mailbox is being used enter the name here so that only emails in that mailbox are processed
9. Mail Server Details
   1. The mail server address and port
   2. SSL Options are best left as Auto but can be set manually if there are problems connecting.
10. Mail Authentication
    1. The User/Pass to authenticate with the mail server
11. Troubleshooting
    1. Last Error - Error generated when reading from the SMTP server
    2. Last Message Id: The email Id as found in email data. 
    3. Last Message Date: The received date of the most recently processed email.
    4. Note: To reprocess emails in the mailbox, clear the last message Id and Date

Email Received Event

Fires after an email have been processed by the system and either added to an associated record or raised as a defect. Emails that were ignored by the system are not passed to this event. 

This allows for additional actions to be taken such as moving newly created defects to a specific process or assigning them to a specific user.

Pre-Processor

The pre-processor script is run after the system reads an email but before it saves the results. This allows the system's interpretation of the email to be overridden. Create the script as normal in the "Administration\PS Scripts, Emails, Buttons" section and take note of the ScriptId. Enter the ScriptId into the  Pre-Processor Script Id field i.e. Num 7 on the Email Settings screenshot above.

Email Data Send to Pre-Processor PowerShell Script

# Email Object passed to PowerShell in ScriptArgs.EventData (as an array)

EmailId         = 1;		# int, Id to use when returning updates to  MS
Ignore          = $false;	# bool, Tell MS to stop any futher processing of email
IsNewDefect     = $false;	# bool, Tell MS to create a defect and attach email
ProjectId       = 2;		# int, ProjectId that is currently processing the email
ModuleId        = 8;		# int, ModuleId the email will be added too. *
InstanceId      = 0;		# int, InstanceId the email will be added too. *
MessageId       = "ABCXYZ....";		# MessageId from Email Sever 
To              = "info@xyz.com";	# To email addresses
From            = "noreply@xyz.com";	# From email address
Subject         = "Email Subject";	# Email subject 
ContentAsText   = "Email content";	# Email content as text, all html tags removed
ContentAsHtml   = ""			# Email content as full html. **

* ManagementStudio checks incoming emails to see if they are replies to emails sent by the system and if so will attach them to the originating record. 

 e.g. If a User is sent a Survey request email and replies to the email asking for help, then the email will be added to that user's record.

** Email Html is not included by default but can be added by adding the value "HtmlContent" to Args1

Update hash to send back to ManagementStudio to action on Emails

$updates += @{ 
	EmailId		= 1; 		#int, Req. Id from EventData to. *
	Ignore		= $false;	#bool, Continue/stop processing email 
	IsNewDefect	= $false; 	#bool, Create as defect and attach email
	ModuleId	= 2		#int, ModuleId to link email too. **
	InstanceId	= 1000;		#int, InstanceId to link email too. **
}

* The email Id is the only required field when returning updates back to MS  

** MS checks incoming emails to see if they are replies to emails sent by the system and if so will populate the ModuleId and InstanceId of the record it intends to link the email to. 

It is possible to set your own ModuleId/InstanceId. For example, the 'from' address can be looked up in MS and the found user's Id used to link the email to them.

Ex 1. Basic Out Of Office ignore email rule

## Convert the incoming EventData into a hash of updates that we can fill in later
$updatesHash = @{}
foreach($email in $ScriptArgs.EventData) {
    $updatesHash.Add($email.EmailId, @{ EmailId = $email.EmailId; Ignore = $email.Ignore; IsNewDefect = $email.IsNewDefect;  InstanceId = $email.InstanceId;  ModuleId = $email.ModuleId; })
}


## Out Of Office Rule
foreach($email in $ScriptArgs.EventData)
{
    ## If the Email contains text similar to "I am out of the Office" 
    ## Then flag that email to be ignored by the Email processor
    if($email.ContentAsText -match "I.*out.*of.*office/ig")  { 
        $updatesHash[$email.EmailId].Ignore = $true        
    } 
}

## Return Email Updates to MS to continue processing
$updatesHash.Values

Ex 2. Look for an AppId in the Subject and attach the email to the matching App

## Convert the incoming EventData into a hash of updates that we can fill in later
$updatesHash = @{}
foreach($email in $ScriptArgs.EventData) {
    $updatesHash.Add($email.EmailId, @{ EmailId = $email.EmailId; Ignore = $email.Ignore; IsNewDefect = $email.IsNewDefect;  InstanceId = $email.InstanceId;  ModuleId = $email.ModuleId; })
}

## Loop over every email found
foreach($email in $ScriptArgs.EventData)
{
    ## Does the email have 'AppId:1234' in the Subject?
    $subject = $email.Subject
    $subject = $subject.Replace(' ', '').ToLower() ## remove all spaces to push everything together 'appid:1234someothertext'
    if($subject -match "appid:")  
    { 
        ## Trim off all chars up to and including the :
        $idStartsAtIdx = $subject.IndexOf("appid:") + 6
        $subject = $subject.Substring($idStartsAtIdx)
        
        ## Get the first number found in the remaining subject and assume that's the AppId
        if($subject -match "\d+")
        {            
            ## Tell MS which App to add this Email too
            $appId = $Matches[0]
            $updatesHash[$email.EmailId].Ignore = $false
            $updatesHash[$email.EmailId].IsNewDefect = $false
            $updatesHash[$email.EmailId].InstanceId = $appId
            $updatesHash[$email.EmailId].ModuleId = 1
        }
        else 
        {
            ## Raise as a Defect that can be looked at sperately
            $updatesHash[$email.EmailId].Ignore = $false
            $updatesHash[$email.EmailId].IsNewDefect = $true
            $updatesHash[$email.EmailId].InstanceId = 0
            $updatesHash[$email.EmailId].ModuleId = 0
        }
    } 
}
## Return Email Updates to MS to continue processing
$updatesHash.Values

Further Support

If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket.