Introduction

End-user communications should form a central part of any migration strategy: users feel informed and part of the process, it creates opportunities for the project to collect and validate information, and it helps migrations to be delivered more smoothly.

MigrationStudio contains an enhanced email module that provides the project with a simple way of creating and maintaining rich content without the need to know advanced mark-up language.  Messages created in the tool can be sent manually by the administrator, or automatically through MigrationStudio's Evergreen Servicing Module (ESM).

This document forms part of a series of solution articles that have been created to get project administrators started with end-user communications in MigrationStudio.  This article will cover the one-time setup activities, creating custom emails, and how to personalise the emails using information from MigrationStudio:

• Installation
• Configuration
• Global Settings
  • Global Graphic
  • Global Style
    • Updating the Default Style
  • Global Greeting
  • Global SignOff
  • Global MetaData
  • Emails Per Minute
  • Last Run Log
• Local Email Settings
  • Email Subject
  • Email Graphic
  • Email Greeting
  • Email Content
  • Email SignOff
  • Email MetaData
  • Email Validation
  • Email Notes
• First Run
• Enabling New Custom Emails in the UI

For more examples, please refer to the 'End User Communications' section in the Knowledge Base.

Installation

MigrationStudio's enhanced email capability is provided by a new plugin.  All installations post-October 2020 should have this installed but to verify that it's available:

• Login to MigrationStudio with an administrator account,
• Switch to the User Migration module (1),
• Click Plugins (2) from the toolbar and look for Custom Emails menu option (3). If the Custom Emails menu option is missing, please contact the Service Desk to request the installation.

Configuration

There are two areas within the tool that need to be configured before emails can be sent from MigrationStudio:

• Global Settings: common values that are used across all emails to define the default look and feel of messages
• Local Email Settings: values that are specific to each email, like content and where there's a need to override global settings

To access the configuration panel:

• Login to MigrationStudio with an account that has administrator privileges
• Switch to the Admin view (1) and click Custom Settings (2) from the vertical menu on the left
• Choose Custom Email Settings (3) from the sub-menu tabs.

Global Settings

Custom emails will often share similar formatting, branding, and sender details to ensure that messages from the project team are consistent.  These are considered to be default values and are found in Global Settings:

• Global Graphic
• Global Style
• Global Greeting
• Gloabl Meta Data
• Emails Per Minute
• Last Run Log

Global Graphic

Header images are included at the top of the email to reinforce corporate branding and to create a visually appealing experience for the reader.  For example:

This will be used only if an image isn't specified in the local email settings.

Step 1 - Create an Image

Create a new header image with the following properties:

• Width: 600px wide
• Height: As required
• Format: JPG or PNG

Step 2 - Upload the Image

Copy the image to [MigrationStudio Install Path]\Portal\Customisation\EmailTemplates\Images on the MigrationStudio IIS server.

For most installations, this will be c:\Inetput\wwwroot\MigrationStudio\Portal\Customisation\EmailTemplates\Images

Step 3 - Reference the Image in MigrationStudio

In MigrationStudio, add the filename (not the full path) to the Global Graphic field.  For example:

Click the Save Custom Settings button at the top of the screen to save the changes.

Key Points

• 600px width
• JPG or PNG format
• Will be replaced by contents of local email settings

Global Style

The main look and feel of the email are governed by the HTML component responsible for style: Cascading Style Sheets (CSS).  CSS controls a wide range of formatting, including the colours on the page, the type of font and size, and spacing.  The email module contains a default style, which can be updated by administrators to match the corporate branding guidelines.  

The code below is an example of the default style that ships with the custom email module:

body {
background: #f7f7f7;
font-family: Arial, sans-serif; 
color: #495055; 
font-size: 11.5pt;
line-height:23px; 
text-align: Left; 
vertical-align: text-top;
margin: 15px 15px 15px 15px; 
padding: 10px;
}

CSS support in Microsoft Outlook is not as mature as in modern browsers and changes to the default should be fully tested in Outlook.  

Updating the Default Style

By default, all text within the email will follow the same format and style.  In the CSS example above, body refers to the HTML element that the formatting applies to (in case, the body or entire content of the email), while the style that will be applied to the text is enclosed in braces {}.  The braces can contain one or multiple style properties, like background or font-family; each property is terminated with a semi-colon.

The table below details the default CSS in further detail:

background: #000000;

background: black;

font-family: Arial, sans-serif; 

font-family: Arial, Verdana, sans-serif;

color: #002366;

color: darkblue;

font-size: 12pt;

font-size: 10px;

line-height: 20px;

text-align: justify;

margin-top: 10px;
margin-right: 20px;
margin-bottom: 10px;
margin-left: 40px;

margin: 10px 20px 10px 40px;

margin-left: 50px;

margin: 0px 0px 0px 50px;

margin-left: 30px;
margin-right: 20px;
margin-bottom: 10px;

margin: 0px 20px 10px 30px;

padding: 10px 20px;

margin: 15px 25px 15px 25px;

margin-top: 15px;
margin-right: 25px;
margin-bottom: 15px;
margin-left: 25px;

margin: 10px;

margin: 10px 10px 10px 10px;

margin-top: 10px;
margin-right: 10px;
margin-bottom: 10px;
margin-left: 10px;

padding-top: 10px;
padding-right: 15px;
padding-bottom: 20px;
padding-left: 15px;

padding: 10px 15px 20px 15px;

padding-left: 20px;

padding: 0px 0px 0px 20px;

padding: 15px 25px;

padding: 15px 25px 15px 25px;

padding-top: 15px;
padding-right: 25px;
padding-bottom: 15px;
padding-left: 25px;

padding: 10px;

padding: 10px 10px 10px 10px;

padding-top: 10px;
padding-right: 10px;
padding-bottom: 10px;
padding-left: 10px;

Notes:

• CSS support in Outlook isn't as advanced as browsers
• Color Names are an easy way to add colour without learning hexadecimal codes

Global Greeting

The Global Greeting variable contains the primary salutation to be used by default in all emails, although email-specific greetings can also be specified in Local Email.  The field supports HTML and Markdown, and information that is held in MigrationStudio about the recipient can be included by using the appropriate keywords.

For example, an email is sent to Russell Robertson.  To include Russell's first name in the greeting, use [%FirstName%]:

A full list of email keywords can be found in the Email Keywords Solution Article.

Global SignOff

Similar to the Global Greeting above, Global SignOff provides a default sign-off option for all emails.  This could be in the form of a simple text-based sign-off, or additional formatting and links can be applied by using common HTML tags (e.g. this is <b>bold</b> text) and Markdown (this is **bold** text).  Information that is held about the recipient in MigrationStudio is integrated through keywords.

The following example adds formatting to text and provides a link to further information.

Global MetaData

By default, email sent via MigrationStudio will use the details provided during setup.  As this is used by all modules within MigrationStudio (e.g. emailing Connector logs to administrators), it may be necessary to specify new Sender and Reply-To information for end-user communications.  The Global MetaData field allows administrators to specify alternative Sender and Reply-To details, in addition to attachments:

For example:

The Global MetaData properties are optional but SendFrom and ReplyTo must always be specified in pairs.  For example:

Emails Per Minute

Microsoft Exchange Online limits the number of emails sent from a specific account to 30 messages per minute, which can cause an issue when sending a large volume of emails to the end-user estate.  If it is not possible to implement a workaround to this limitation, MigrationStudio can limit the number of messages sent by the value specified in Emails Per Minute.

Unlike Exchange Online that drops messages when the limit is reached, MigrationStudio will queue email in batches that are processed every minute.  For example, Emails Per Minute is set to 20 and 500 users are selected to receive an email.

The first 20 will be processed before MigrationStudio waits one minute and process the next 20. In this example, it would take 25 minutes to deliver all messages.

Notes: 

• To send unlimited emails, specify 0 (zero).
• Although this functionality provides a convenient way of managing the limits enforced by Exchange Online, it does not circumvent them.  MigrationStudio recommends that Emails Per Minute is not set to the maximum of 30 to avoid Exchange Online rejecting other email sent from MigrationStudio during the same time frame (e.g. log files or UAT) that will count towards the total.

Last Run Log

A summary of operations is recorded in Last Run Log each time the email tool is launched.

Local Email Settings

Out of the box, MigrationStudio provides 30 slots for administrators to create custom emails.  The Local Email Settings section of the tool is where an email message is found, with additional options to customise or override the values specified in Global Settings. 

Email Subject

Status: Mandatory

The email subject should be plain text and does not support formatting or keywords.  The email subject is also used to identify the email in the MigrationStudio UI.

Email Graphic

Status: Optional

If left unpopulated, Email Graphic will inherit the value specified in Global Graphic.  

To specify an image specific to this local email, copy the image file to [MigrationStudio Install Path]\Portal\Customisation\EmailTemplates\Imageson the MigrationStudio IIS server.  For most installations, this will be c:\Inetput\wwwroot\MigrationStudio\Portal\Customisation\EmailTemplates\Images

For example:

Files should be 600px wide and saved as either JPEG or PNG.

Email Greeting

Status: Optional

By default, the salutation defined in Global Greeting will be used in each email unless a local value is specified. Greetings can be formatted using HTML or Markdown and can include information held about the user in MigrationStudio.

The example below will add formatted text and the recipient's full name:

Email Content

Status: Mandatory

The main body of the email is defined in Email Content. This section was developed to enable an administrator to create rich-text messages that contain recipient information from Migration, formatted text, links to other resources, and additional images.

The example below uses Markdown to format heading, create unordered (bullet) lists, and provides two different methods of linking to other resources.

This will result in the following email:

Common Markdown commands can be found at https://support.migrationstudio.com/a/solutions/articles/14000105833

Email SignOff

Status: Optional

The local email will inherit the Global SignOff settings unless otherwise specified.  The Email SignOff setting supports plain and formatted text (via HTML and Markdown).  The example below uses Markdown to add formatting to the email signature and provide a link to the user's survey.

Email MetaData

Status: Optional

MigrationStudio has the ability to specify different Sender and ReplyTo settings for each email.  This could be useful, for example, if a different team will be dealing with responses for that stage of the project or multiple migration types (mobile, server, O365, and Windows) are being managed in MigrationStudio.

The following parameters are available and follow the same format as with Global MetaData:

• SenderName
• SenderEmail
• ReplyToName
• ReplyToEmail
• Attachment

The example below will inherit the Sender details from Global MetaData or the system defaults if not defined, and provides new ReplyTo information and an attachment specifically for this email.

Email Validation

Status: N/A

To ensure that users don't receive emails with key components missing, MigrationStudio will validate the email for errors (such as missing content or incorrectly specified image file) and provide guidance on how to resolve the issue.  For example:

Email Notes

Status: Optional

A notes field is available to include additional information about the email's purpose.  This will not be included in the email sent to the end-user and is for administrator reference only.

First Run

The first time the email tool is run, MigrationStudio will need to build a list of emails that are available to the administrator:

• Switch to the User Migration module (1)
• Click Plugins (2) on the toolbar
• Select Custom Emails (3) and Scan for Emails (4) to begin the scan

• MigrationStudio will display a notice at the bottom of the screen once the scan is complete
• Use the F5 key to refresh Internet Explorer
• Switch back to the User Migration module (1)
• Click Plugins (2) on the toolbar and select Custom Emails (3)
• Three new options will be available: Send, Preview, and Admin
• Choose Send (4) to view all the emails available (the entries here are based on the Email Subject)

Enabling New Custom Emails in the UI

To make a new custom email visible in the Custom Emails menu, the tool should scan for new emails:

• Switch to the User Migration module (1)
• Click the Plugins option (2) from the toolbar
• Select the Custom Emails option (3) and choose 3: Admin (4) > Scan For Emails (5)
• Refresh Internet Explorer and the new email will be visible.

Note: Changes to content in existing emails do not require a refresh.

Further Support

If you require further support, please visit MigrationStudio's Service Desk at https://support.migrationstudio.com/ to search the knowledge base or create a new support ticket.