Keywords

Keywords are a way of dropping special words into email templates that ManagementStudio will substitute the real value for when the email is getting sent. e.g. starting an email with "Hi [UserMigration-FirstName]" will be converted to "Hi John" when the email is processed. 


For a raw list of keywords see this article.


TABLE OF CONTENTS


Keyword Tester: http://migrationstudio.ddns.net:5000/1/d/keywords


Basic Structure

Keywords are at minimum formed of two square brackets [ ] with a target module (Apps, Users, Devices, etc) and a property to parse (e.g. AppVendor). Keywords support a long and short form, where the target module can be shortened to A for Applications, U for UserMigrations, etc.


Details Keywords

The list of available keywords for a given App, User Device, etc can be taken from the Admin -> [Module] -> Details Config panel. All of the property e.g. AppName, AppVendor, AppVersion are available as keywords to be be used. 


Label Keywords

A label modifier is also available that will get the name of the property as it appears in the UI. e.g. [Applications-Label-AppVendor] == 'Vendor' or more usefully [Applications-Label-Custproperty1] == 'Service Now #Id'


Custom Form Keywords

Custom Form fields can be used as keywords using their internal Field Id. They are structured as [Module-CustomForm or CF-XXX] where XXX is the field Id.  


Deployment Unit Keywords

When creating an email for e.g. a User, it is useful to be able to reference information from that user's Deployment Unit. Even though the email might be targeting a UserMigration module all of the Deployment Unit keywords are also available to you. 

e.g. "Hi [UM-FirstName], your laptop can be picked from [DU-ShortLocation]"


Examples


Example KeywordOutput
Details
[Applications-Label-AppVendor]Vendor
[Applications-AppVendor]Adobe
[A-AppVendor]Adobe


Custom Forms
[Applications-CustomForm-Label-142]Favorite color
[Applications-CustomForm-142]Blue
[A-CF-142]Blue


Putting it all together
Hi [UM-FirstName]. Your laptop is in [DU-ShortLocation] and your [A-CF-Label-142] is [A-CF-142]
Hi John. Your laptop can be picked from room 42b and your Favorite color is Blue

Date Formats

When working with dates the -Format{} modifiers can be used to format the date. These use the full .Net suite of formatting options Date Format Cheat Sheet


Example KeywordOutput
[DeploymentUnit-StartDate]18/04/2020 23:50:55
[DeploymentUnit-StartDate-Format{dd/MMM/yyyy HH:mm}]18/Apr/2020 23:50
[DeploymentUnit-StartDate-Format{dd/MMM/yyyy}]18/Apr/2020



T +/- Date Modifier

Using the T modifier days can be added or subtracted from a date. This can be useful when working with expiry dates.


Example KeywordOutput
[DeploymentUnit-StartDate]8/04/2020 00:00:00
[DeploymentUnit-StartDate-t{-4}]4/04/2020 00:00:00
[DeploymentUnit-StartDate-Format{dd/MMM/yyyy}-t{-4}]4/Apr/2020
[DeploymentUnit-StartDate-Format{dd/MMM/yyyy}-t{+4}]12/Apr/2020



Images

When sending emails it is usual to include images in your email templates. ManagementStudio offers four different ways to include these images but for all ways, the first step is to upload the image as a 'Project Resouce' in the Admin section. 


Linked images will add a URL to the email that links back to the ManagementStudio server. This lowers the size of the overall emails but the User might need to right-click on the image to download it if there isn't a client/server trust in place. When linking an image the filename or resource Id can be used.


Embed Images directly

Embedded images have the advantage that they do not need to link back to the server, this means the user will not need access to the server (Necessary for sending emails externally). However, it increases the overall size of the email. When embedded an image the filename or resource Id can be used.



For Email we recommned using Embedded images in email templates, specifcally via its ID. 
e.g. <img src="[Img-123]" alt="Welcome to Win 10" width="600" height="130" />


For web pages such as the surveys / test sign-offs you must use Linking via a Url.
e.g. <img src="[Project-Url-Resource-123]" alt="Welcome to Win 10" width="600" height="130" />



Example KeywordNote


<img src="[Project-Url-Resource-Email_Header.png]" />
Link to the image via its filename on the Project Recourses screen.
<img src="[Project-Url-Resource-X]" />
Link to the image via its Id on the Project Resources screen.


<img src="[Img-Email_Header.png]" />
Embed image via its filename on the Project Recourses screen.
<img src="[Img-X]" />
Recommend Approach.  Embed image via its Id on the Project Resources screen.



Project Static Keywords

Project keywords are a setlist of five keywords ([Project-Keyword-1..5]) whose value is fixed and set in the Project Settings panel 'Admin -> Project Admin -> General Settings'. These can be used for values that are popular but rarely change. For example, if there is a URL to the project help site or a project mailbox that you need to include in a number of emails.

Keyword List:

[Project-Keyword-1][Project-Keyword-2][Project-Keyword-3][Project-Keyword-4][Project-Keyword-5]



Project Resource Keywords

Resource keywords create a URL to download a project resource. This can be used to allow users to download files such as test plans, project help docs, etc. They can also be used in Html IMG tags to allow project image resources to be referenced in emails and surveys. 


KeywordNote
[Project-Url-Resource-X]

[P-Url-R-X]

Resolves to the raw URL to the Project Resource where X is the Survey Id
[Project-Url-Resource-Win-10-Logo.png]

[P-Url-R-Win-10-Logo.png]

Resolves to the raw URL to the Project Resource where the name of the file is used


Putting it all together
Html:
<img src="[Project-Url-Resource-Win-10-Logo.jpg]" alt="Windows 10 Logo">
Markdown:
![alt text]([Project-Url-Resource-7] "Windows 10 Project Logo")
Click <a href="[Project-Url-Resource-1]">here</a> to download your Win10 guide.
Click here to download your Win10 guide.



Survey Keywords

Surveys have a Sign-Off URL that can be accessed from the keyword [Module-Url-Survey-x] where X is the SurveyId. As there can be multiple surveys per module the Survey Id must be included in the keyword to tell ManagementStudio which link to generate. 

For example, the User Migration module might have a 'Win 10 Readiness Survey', 'User Data Validation Survey', and 'How was your experience' survey. Each of those surveys would have their own SurveyId to include in the keyword.


KeywordNote
[Applications-Url-Survey-X]
[A-Url-S-X]
Resolves to the raw URL to the App Survey where X is the Survey Id
[UserMigrations-UrlButton-Survey-X-Button Label]
[UM-UrlButton-S-X]
Creates a HTML block that renders as a button that can be used in email templates
[UserMigrations-UrlButton-Survey-5-Complete Survey]


Putting it all together
Click <a href="[UserMigrations-Url-Survey-2]">here<a/> to complete your survey.
Click here to complete your survey.



Self-Schedule Keywords

As a user can only be in one Deployment Unit at a time, there is no need for an extra Id to be added to the Self-Schedule URL keyword. A link expiry keyword is also available. 


KeywordNote
[UserMigrations-Url-SelfSchedule]
[U-Url-SS]
Resolves to the raw URL to the SelfSchedule of the User
[UserMigrations-Url-SelfSchedule-LinkExpiryDate]
[UM-Url-SS-LED]
The expiry date of the link. Supports date modifiers
[UserMigrations-UrlButton-SelfSchedule-Button Label]
[U-UrlButton-SS-Button Label]
Creates a HTML block that renders as a button that can be used in email templates
[UserMigrations-UrlButton-SelfSchedule-Book Self-Schedule Slot]
Putting it all together

Click <a href="[UserMigrations-Url-Survey-2]">here<a/> to book your migration slot. This link will expire on [UM-Url-SS-LED-DF{MMMM dd}].
Click here to book your migration slot, This link will expire on May 26.



Advanced Keywords


A table of links to a User's Apps, Devices, or other module items can be generated using 'Links' keywords. Link keywords support defining a list of columns and also allows the list to be filtered. For a more detailed explication of defining columns and filters see this help page.


Example:

This keyword will get a list of Apps for a User with the columns, App Vendor, App Name, App Version, Process, and will filter the list to only Apps in the '1. Identified' or '2. Discovery process.


[UserMigrations-Links-Applications-Args{Columns:AppVendor, AppName, AppVersion, Process; Filter: x.Process == '1. Identified' || x.Process == '2. Discovery';}]
Note: This is one big keyword surrounded by a single pair of [ ]


Output:

App VendorApp NameApp VersionProcess
AdobeAcrobat Reader15.17.20050.1921521. Identified
AdobeAcrobat Standard15.16.20039.1852681. Identified
AdobeEULA15.16.20039.1852681. Identified
AdobeReader11.0.17.91. Identified


History Support

An advanced feature of keywords is the ability to get the previous value of a property, the date it was updated, and the name of the account that updated it. This is not generally used in email templates but can be very useful with conditional logic via the API. 


Long Form:

Example KeywordOutputNote
[Applications-AppVendor]AdobeCurrent Value
[Applications-History-AppVendor-LastModifiedValue]Adobe Inc.Previous Value
[Applications-History-AppVendor-LastModifiedDate-Format{dd/MMM/yy HH:mm}]14/May/20 13:15Date of Change
[Applications-History-AppVendor-LastModifiedBy]John Joe [jjdoe]Changed By


Short Form:

Example KeywordOutputNote
[A-AppVendor]AdobeCurrent Value
[A-H-AppVendor-LMV]Adobe Inc.Previous Value
[A-H-AppVendor-LMD-f{dd/MMM/yy HH:mm}]14/May/20 13:15Date of Change
[A-H-AppVendor-LMB]John Joe [jjdoe]Changed By




Further Support

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