TABLE OF CONTENTS

• Mailbox Monitoring and Email Processing
• Configuring Mailbox Monitoring
  • Polling Frequency
  • Email Settings Configuration
• Email Processing Workflow
  • Email Event Handling
  • Pre-Processor Script
    • Email Data Provided to Pre-Processor
    • Returning Updates to ManagementStudio
      • Example Email Module IDs
• Pre-Processor Script Examples
  • Example 1: Out-of-Office Auto-ignore
  • Example 2: Attach Email to App by AppId in Subject
• Troubleshooting
• Further Support

Mailbox Monitoring and Email Processing

ManagementStudio can monitor a mailbox for incoming emails. This capability supports both replies to system-generated emails and new emails sent directly to the system for further action.

Email messages can be triaged as they are processed. Actions include ignoring certain emails, raising defects, or attaching emails to existing records. For example, out-of-office replies can be ignored or linked to a user’s record for a migration engineer to reference.

Configuring Mailbox Monitoring

Polling Frequency

The frequency with which mailboxes are checked is controlled by the EmailTasks:ReceiveEveryXMin setting in the appSettings.json file.

• Minimum value: 2 minutes
• Recommended value: 10 minutes

Email Settings Configuration

Access the email monitoring configuration at:

Administration → Project Settings → Email & Keywords

Configure the following fields:

Email Processing Workflow

Email Event Handling

After an email is processed—either attached to a record or raised as a defect—the Email Received event is triggered. Emails ignored during processing are not included.

Use this event to automate further actions, such as moving new defects to a specific workflow or assigning them to designated users.

Pre-Processor Script

A PowerShell pre-processor script can be defined for advanced triage logic. The script is executed after the email is read but before actions are committed, allowing custom handling or routing.

• Define the script in:
  Administration → PS Scripts, Emails, Buttons
• Enter the script’s ID into the Pre-Processor Script field in Email Settings.

Email Data Provided to Pre-Processor

The PowerShell script receives an array of email objects in ScriptArgs.EventData. Fields available:

Note: ManagementStudio will try to match incoming replies to sent messages and attach them to the originating item (user, app, etc.).

Returning Updates to ManagementStudio

The script must return a hashtable of updates for each email. Only EmailId is required; all other fields are optional depending on the desired processing logic.

Example Email Module IDs

• Module and Instance IDs can be set by your script, or supplied by the system when matching a reply to a previous message.

Pre-Processor Script Examples

Example 1: Out-of-Office Auto-ignore

This script ignores emails which are likely out-of-office replies.

$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; })
}

foreach($email in $ScriptArgs.EventData) {
    if($email.ContentAsText -match "I.*out.*of.*office/ig")  { 
        $updatesHash[$email.EmailId].Ignore = $true        
    } 
}

$updatesHash.Values

Example 2: Attach Email to App by AppId in Subject

This script looks for an AppId:1234 pattern in the email subject and links the email accordingly.

$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; })
}

foreach($email in $ScriptArgs.EventData) {
    $subject = $email.Subject
    $subject = $subject.Replace(' ', '').ToLower()
    if($subject -match "appid:") { 
        $idStartsAtIdx = $subject.IndexOf("appid:") + 6
        $subject = $subject.Substring($idStartsAtIdx)
        if($subject -match "\d+") {            
            $appId = $Matches[0]
            $updatesHash[$email.EmailId].Ignore = $false
            $updatesHash[$email.EmailId].IsNewDefect = $false
            $updatesHash[$email.EmailId].InstanceId = $appId
            $updatesHash[$email.EmailId].ModuleId = 1
        } else {
            $updatesHash[$email.EmailId].Ignore = $false
            $updatesHash[$email.EmailId].IsNewDefect = $true
            $updatesHash[$email.EmailId].InstanceId = 0
            $updatesHash[$email.EmailId].ModuleId = 0
        }
    } 
}
$updatesHash.Values

Troubleshooting

• Last Error: Review in Email Settings for SMTP server errors.
• Last Message Id/Date: Indicates what message was last processed; clear these fields to force reprocessing.

Further Support

For additional assistance, visit the ManagementStudio Service Desk to search the knowledge base or create a new support ticket.