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:


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

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:


CSS PropertyDescription
backgroundThe background colour of an element is specified by the background property and accepts a hexadecimal (Hex) code or HTML Color Name.

The Hex code #f7f7f7 is off white, creating a subtle contrast between the background and the background of the body text. To change this, specify a new Hex code or use a Color Name, as referenced in the HTML Color Names Solution Article.

Example
To create a black background, use:
background: #000000;
 or
background: black;
font-familyThe type of font used in the email body is specified by the font-family property.

Multiple font names are supported and Outlook will fall back to the next font in the list if the first is not installed on the recipient's system. Two types of font names are supported:
  • Family Name: A specific font name, like Arial, Times, or Courier.
  • Generic Name: A collection of font types, such as serif, sans-serif, and monospace.


MigrationStudio recommends that font lists start with the family name and finish with a generic type.  For example, the default CSS provided in the email module starts with Arial and concludes with sans-serif:

font-family: Arial, sans-serif; 


To extend this list to include additional fonts, add the font name(s) to the list:

font-family: Arial, Verdana, sans-serif;
colorThe default CSS sets the font colour to #495055, which is similar to dark slate grey. This value can be replaced with an alternative Hex code or a colour name, as documented in the HTML Color Names Solution Article. Alternatively, deleting the line will cause the colour to revert to the system default, black.

Examples

1. To set the font colour to royal blue using the Hex code, use:

color: #002366;


2. To set the font colour to dark blue using the colour name use: 

color: darkblue;


Note: The property uses the American spelling of color, the English spelling will cause an error.

font-sizeThe size of the text is controlled by the font-size property. Font sizes are commonly specified in points (pt) and pixels (px), the latter providing more consistent sizing across browsers. Since the majority of messages sent from the email tool will be read in Microsoft Outlook clients, the default CSS uses a point size.

To change the value, replace the font size, and specify the size unit.

Examples

1. To specify the font size in points, use: 

font-size: 12pt;

2. To specify the font size in pixels, use: 

font-size: 10px;

Removing the property from the default CSS will force Outlook to specify the font size.
line-heightThe height of a line of text is typically 20% larger than the font size in use.  For example, if a font is 12px tall, the line height is 13.2px.  Organisations that require a different line-height should specify the size using the line-height property.

Example
To set the line-height to 20px, use:
line-height: 20px;

Removing the property from the default CSS will reset the line-height property to normal.
text-alignThe text-alignproperty controls the horizontal alignment of the text.  There are four values supported by the email plugin:
  • Left: Align the text to the left
  • Right: Align the text to the right
  • Center: Centre the text (note the American spelling)
  • Justify: Lines have equal width


This value will apply to all text in the email and is set to left by default.


Example

To justify the text:

text-align: justify;
vertical-alignThe vertical position of an element is controlled by the vertical-align property.  The MigrationStudio email tool defaults to top-text to ensure all text is positioned at the top of the element.

Changing this value may negatively affect the formatting of the email. If a particular element requires different formatting, for example, a table cell may need to be vertically centered, this should be catered for by a new entry in the CSS.
marginThe CSS margin property is used to create space outside of an element.  For example, the orange shape below uses the default margin settings, whereas the blue shape has a margin of 20 pixels from the edge of this table cell.
Shape 1
Shape 2

Margins can be specified by using individual properties:
margin-top: 10px;
margin-right: 20px;
margin-bottom: 10px;
margin-left: 40px;


or through shorthand:

margin: 10px 20px 10px 40px;


When using the shorthand form of the property, the values represent the top, right, bottom and left margin sizes respectively.


The default style uses the shorthand form to specify a 15-pixel margin on all sides to create space between the body text and the email background.


Examples

1. Add only a left margin of 50 pixels (all other margin values are 0):


margin-left: 50px;

or:

margin: 0px 0px 0px 50px;

2. Add left and right margins of 20 pixels, no top margin, and a bottom margin of 10 pixels:

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

or:

margin: 0px 20px 10px 30px;

3. Add 10-pixel of margin to the top and the bottom, and 20-pixel margin to the left and right:
padding: 10px 20px;
 When only two values are specified, the first value refers to the top and bottom settings, the second value refers to the right and left settings. This is equivalent to:
margin: 15px 25px 15px 25px;
or:
margin-top: 15px;
margin-right: 25px;
margin-bottom: 15px;
margin-left: 25px;

4. Add a 10-pixel margin to all sides:
margin: 10px;
The example above only requires one value in the shorthand because all margin sizes are the same.  This is equivalent to:
margin: 10px 10px 10px 10px;
or:
margin-top: 10px;
margin-right: 10px;
margin-bottom: 10px;
margin-left: 10px;
paddingThe CSS padding property creates space around an element's content. For example, the text in the first shape below has no padding defined and snaps to the top left, whereas the text in the second has a padding of 15 pixels on all sides:
Shape 1
Shape 2

To illustrate how padding and margin properties can work together (and differ), a margin can also be applied to shape 2, as in the previous example:
Shape 2

The default CSS in the email tool adds 10 pixels around the main content. New values can be specified using the shorthand notation or long-form.

Examples
1. Add padding of 15 pixels to the left and right of the element, 20 pixels at the top and 10 pixels at the bottom:
padding-top: 10px;
padding-right: 15px;
padding-bottom: 20px;
padding-left: 15px;
or:
padding: 10px 15px 20px 15px;

2. Add 20px padding to the left of the element:
padding-left: 20px;
or:
padding: 0px 0px 0px 20px;

3. Add 15-pixel of padding to the top and the bottom, and 25-pixel padding to the left and right:
padding: 15px 25px;
When only two values are specified, the first value refers to the top and bottom settings, the second value refers to the right and left settings. This is equivalent to:
padding: 15px 25px 15px 25px;
or:
padding-top: 15px;
padding-right: 25px;
padding-bottom: 15px;
padding-left: 25px;

4. Add 10-pixel padding to all sides:
padding: 10px;
The example above only requires one value in the shorthand because all sizes are the same.  This is equivalent to:
padding: 10px 10px 10px 10px;
or:
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:


ParameterDescriptionExample
SendFromNameThe name the email is sent from.SendFromName: The Windows 10 Team
SendFromEmailThe email address the email is sent from.SendFromEmail: Windows10@jimmyjamesand.co
ReplyToNameThe name the email should reply to.ReplyToName: Windows 10 Help
ReplyToEmailThe email the address the email will reply to.ReplyToEmail: windows10help@jimmyjamesand.co
AttachmentAttach a file to all emails by specifying the filename.  The file should be placed in \Portal\Customisation\EmailTemplates\ under the MigrationStudio root folder.

For most installations, this will be c:\Inetpub\wwwroot\MigrationStudio\Portal\Customisation\EmailTemplates\.
Attachment: w10_faq.pdf


For example:


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

ExampleExplanation
SendFromName: The Windows 10 Team
SendFromEmail: Windows10@jimmyjamesand.co
Attachment: w10_faq.pdf
This is a valid configuration.  MigrationStudio will use the SendFromName and SendFromEmail specified in Global MetaData.

As ReplyToName and ReplyToEmail are not specified, these values are inherited from the system defaults specified in Admin > Initial Setup > Email Settings.
SendFromName: The Windows 10 Team
ReplyToName: Windows 10 Help
ReplyToEmail: windows10help@jimmyjamesand.co

This is not a valid configuration. SendFrom and ReplyTo information should be specified in pairs, in this case, SendFromName and SendFromEmail are both required. The correct format would be:
SendFromName: The Windows 10 Team
SendFromEmail: windows10@jimmyjamesand.co


ReplyToName and ReplyToEmail are specified correctly and will be used to override the system defaults.

Unlike the first example, an attachment is not specified.



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:

For further information on creating email content, please visit [LINK TBC]



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.