TABLE OF CONTENTS
- Keywords
- Advanced Keywords
- Article Links
- Further Support
Keywords
Keywords are a way of adding special words or images into email templates that ManagementStudio will substitute the real value for when the email is 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.
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 properties, e.g. AppName, AppVendor, AppVersion, are available as keywords to 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 Keyword | Output |
---|---|
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 Keyword | Output |
---|---|
[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 Keyword | Output |
---|---|
[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 |
Contact Email Keywords
This keyword resolves to a list of email addresses for a type of Contact of an App, User, etc. e.g. if an App has 3 UAT Contacts this keyword will resolve to "user1@email.com; user2@email.com; user3@email.com". This is specifically for emailing multiple contacts of an App (User etc.) in a single email.
The example below uses App Contacts but all standard modules are supported.
Internal Name | Output |
---|---|
[App-ContactType-Emails-External Support] | List of emails whose contact type is 'External Support' |
[App-ContactType-Emails-UAT Tester] | List of emails whose contact type is 'UAT Tester' |
[App-ContactType-Emails-<All>] | List of emails from ALL contacts regardless of the type |
The example below uses User Contacts
Internal Name | Output |
[UM-ContactType-Emails-App Owner] | List of emails whose contact type is 'App Owner' |
[UM-ContactType-Emails-<All>] | List of emails from all contacts regardless of the type |
[UM-ContactType-Emails-UAT Tester] | List of emails whose contact type is 'UAT Tester' |
The example below uses Device Contacts
Internal Name | Output |
[Devices-ContactType-Emails-<All>] | List of emails from all contacts regardless of the type |
[Devices-ContactType-Emails-App Owner] | List of emails whose contact type is 'App Owner' |
Team Member Keywords
The Team member keywords (CreatedBy, AssignedTo, OwnedBy, DelegateTo1, DelegateTo2, PacakgedBy) can be extended to pick out parts of the User Account contained within.
The example below uses AssignedTo but all of the six Team Member keywords work the same.
Internal Name | Output |
---|---|
[UM-AssignedTo-UserName] | johndoe |
[UM-AssignedTo-FullName] | John Doe |
[UM-AssignedTo-FirstName] | John |
[UM-AssignedTo-LastName] | Doe |
[UM-AssignedTo-Email] | johndoe@email.com |
[UM-AssignedTo-DisplayName] | John Doe[johndoe] |
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.
Link images via a Url
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, the image filename or resource ID can be used.
For Email we recommend 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 or test sign-offs, the image must be linked via a Url.
e.g. <img src="[Project-Url-Resource-123]" alt="Welcome to Win 10" width="600" height="130" />
Example Keyword | Note |
<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.
Keyword | Note |
---|---|
[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 |
[Project-Today] [P-Today] | Gets the current date without the time component |
[P-Today-Format{dd/MMM/yyyy}] [P-Today-Format{dd/MMM/yyyy}-T{+10}] | Format the date Add 10 days and then format the date See the Date Format section above for more info |
[Project-Timestamp] [P-Timestamp] | Gets the current date with the time component. E.g. 10/5/2022 12:30:45 |
[P-Timestamp-Format{dd/MMM/yyyy}] [P-Timestamp-Format{dd/MMM/yyyy}-T{+10}] | Format the date & time Add 10 days and then format the date See the Date Format section above for more info |
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 its own SurveyId to include in the keyword.
Keyword | Note |
---|---|
[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.
Keyword | Note |
---|---|
[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. |
Script Button Keywords
Buttons can be added to emails that will execute a script in ManagementStudio. Common use cases are emailing User voting buttons or allowing a manager to unlock a survey of one of their staff.
Keyword | Note |
---|---|
[{Module}-Url-Script-{ScriptId}-{Button Text}-{arg1}-{arg2}-{arg3}] | Resolves to the raw URL to the SelfSchedule of the User |
[{Module}-UrlButton-Script-{ScriptId}-{Button Text}-{arg1}-{arg2}-{arg3}] | Creates a HTML block that renders as a button that can be used in email templates |
[{Module}-UrlButton-Script-{ScriptId}-{Button Text}-{arg1}-{arg2}-{arg3}] | |
Putting it all together | |
Advanced Keywords
Notes List
Resolves a list of the most recent notes for an App, User, Device, etc to the keyword.
[{Module}-Notes-{LastX|0}-{Public|Private}]
- Module - Name of the Module the keyword is resolving
- Applications, UserMigrations, etc
- LastX
- The number of notes to retrieve.
- Use 0 for all notes.
[A-Notes-0-Public] - All Public Notes
[A-Notes-5-Public] - Last 5 Public Notes
[A-Notes-10-Private] - Last 10 Public and Private Notes
Blueprint Keyword
Resolves a list of Blueprints for an App, User, Device, etc to the keyword.
[{Module}-Blueprints-{FolderId|0}-{FullPath|ShortPath|Name}-NoneLabel]
- Module - Name of the Module the keyword is resolving
- Applications, UserMigrations, etc
- Folder Filter
- FolderId- Limit the Blueprints to only Blueprints under this Folder Id
- Use 0 for no folder filter
- Display Format
- FullPath - Blueprint Path from the root, filtered to the specified FolderId
- RelativePath - Blueprint Path, starting from the specified FolderId
- ShortPath - Just the Folder\Blueprint part of the path
- Name - Just the Blueprint Name, no folder
- Index:XX - Pull out a part of the Blueprint path by its index, relative to the FolderId. Where XX is replaced by an index number
- None Label
- The text to show if no Blueprints were found
Blueprint Keyword Examples
For this example Blueprint Path, here are some example keywords are their output
Path:: Location[id:10]\Ireland[id:15]\Galway[id:20]\City Center[id:5]
Keyword | Output |
[UM-BP-15-FullPath] | Location\Ireland\Galway\City Center |
[UM-BP-15-RelativePath] | Ireland\Galway\City Center |
[UM-BP-15-ShortPath] | Galway\City Center |
[UM-BP-15-Name] | City Center |
[UM-BP-15-Index:0] | Ireland |
[UM-BP-15-Index:1] | Galway |
[UM-BP-15-Index:9-Bad Blueprint] | Bad Blueprint (No BP was at index 9, the fall back value was used) |
Datamining Report
Resolves a Datamining Report as HTML to the keyword.
[{module}-DMR-{Id|Name}-{ScopeAll|ScopeDmr|ScopeOne}-{AsTable|AsAttachment}-Args{Columns:Col1,Col2,Col3}]
- Module - Name of the Module the keyword is resolving
- Applications, UserMigrations, etc
- Source
- Name: The public name of the DMR
- Id: The Id of the DMR
- Scope
- "ScopeAll" - Set the Data Source to all Items
- "ScopeOne" - Set the Data Source to the one item this keyword is being parsed against
- "ScopeDmr" - Set the Data Source to that of the one the DMR has been saved as
- As
- "AsTable" - renders the DMR has html
- "AsAttachment" - If used in an email template, the DMR will be attached as an Excel file
- Args - An optional list of modifiers to send to the DMR
- Columns
- Display only the selected columns rather than the whole DMR
- The column names are the 'Internal Names' of the DMR. To see these names click the 'Show Internal Column Names' button in the ribbon menu of the DMR UI.
- ExcelTemplateResourceName
- Name of the Excel file to inject this report into.
- The Excel file must be imported as a Project Resouce
- ExcelTemplateResourceId
- Project Resource Id of the Excel file to inject this report into.
- The Excel file must be imported as a Project Resouce
- IncludeColumnHeaders
- SheetName
- Sheet Name to inject the report into
- StartRow
- Top Left cell of the report
- StartColumn
- Top Left cell of the report
- Columns
As Table
[UM-DMR-15-ScopeOne-AsTable]
[UM-DMR-My Report-ScopeDmr-AsTable-Args{Columns:UserMigrations_Title,Applications_Total,Applications_ReadyCount}]
As Attachment
[UM-DMR-10-ScopeDmr-AsAttachment-Args{ Columns:UserMigrations_Title,Applications_Total,Applications_ReadyCount; ExcelTemplateResourceName:My Report Template.xlsx; SheetName:Report }]
[UM-DMR-10-ScopeDmr-AsAttachment-Args{ ExcelTemplateResourceId:99; IncludeColumnHeaders:false; SheetName:Report }]
[UM-DMR-10-ScopeDmr-AsAttachment-Args{ StartRow:5; StartColumn:10; SheetName:My Report }]
Links Tables Support
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 allow the list to be filtered. For a more detailed explanation 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 Vendor | App Name | App Version | Process |
---|---|---|---|
Adobe | Acrobat Reader | 15.17.20050.192152 | 1. Identified |
Adobe | Acrobat Standard | 15.16.20039.185268 | 1. Identified |
Adobe | EULA | 15.16.20039.185268 | 1. Identified |
Adobe | Reader | 11.0.17.9 | 1. 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 Keyword | Output | Note |
---|---|---|
[Applications-AppVendor] | Adobe | Current Value |
[Applications-History-AppVendor-LastModifiedValue] | Adobe Inc. | Previous Value |
[Applications-History-AppVendor-LastModifiedDate-Format{dd/MMM/yy HH:mm}] | 14/May/20 13:15 | Date of Change |
[Applications-History-AppVendor-LastModifiedBy] | John Joe [jjdoe] | Changed By |
Short Form:
Example Keyword | Output | Note |
---|---|---|
[A-AppVendor] | Adobe | Current Value |
[A-H-AppVendor-LMV] | Adobe Inc. | Previous Value |
[A-H-AppVendor-LMD-f{dd/MMM/yy HH:mm}] | 14/May/20 13:15 | Date of Change |
[A-H-AppVendor-LMB] | John Joe [jjdoe] | Changed By |
Article Links
- ManagementStudio Keywords - Full List
- Date Format Cheat Sheet (external resource)
- Surveys - Display Fields: Link Tables
Further Support
If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket.