Customization of vRealize Automation 6.2.x Email Notifications

User Experience ("UX") focuses on the intimate understanding of your users. What is it that they need or desire, what do they value, what are their abilities, as well as their limitations?

As you embark upon the journey to the software-defined data center (SDDC), think and architect in terms of the user experience in addition to "boxes and arrows."

• What are the desired UX outcomes for those consuming the service(s)?

• Have you considered the UX in terms of its usefulness, usability, desirability, accessibility, credibility, and its value?

In addition to fundamental tenant and business group designs, entitlements and service catalogue designs, one such area for UX consideration is the messages provided to those consuming services of the software-defined data center.

For a moment, imagine you are providing automated infrastructure delivery to multiple business segments of a large media and entertainment organization, each with their own distinct brand. The segments are built upon their individual brand and identity.

• Do you centrally brand the service that you offer or do you tailor the service to each tenant business segment?

• How would this change if instead the services were used to provide automated infrastructure delivery only to your IT Operations team and not direct end users?

The messages that appear in the inbox of the user are part of the experience. VMware vRealize Automation can send automatic notifications for several types of events, such as, the successful completion of a catalogue request or a required approval workflow. System Administrators can configure global email servers, senders and recipients that process email notifications.

Tenant Administrators can override those defaults, or add their own servers, senders and recipients if no global attributes are specified. They may even select which events will cause notifications to be sent to their users. Each component, such as the service catalog or infrastructure-as-a-service, can define events that can trigger notifications.

Additionally, each user can choose if they wish to receive notifications. Users either receive all notifications configured by the Tenant Administrator or no notifications.

Notification may also have links that allow the user to perform interactively. For example, a notification about a request that requires approval can have one link for approving the request and one for rejecting it. When a user clicks one of the links, a new email opens with content that is automatically generated. The user can send the email to complete the approval.

Messages can be easily and beautifully customized using a simple, powerful template engine. These may be customized per-locale, per-tenant, and per-notification scenario. You have the ability to define and craft the desired user experience for any notification.

Getting Started with Message Templates

vRealize Automation uses a folder structure to determine the appropriate template to user based on the context of the tenant. Templates files are written in Apache Velocity, an easy to use Java-based template engine. Learn more about the simple directives used in the .vm template files in the Apache Velocity User Guide.

Deploy the Sample Templates

To use message templates in vRealize Automation, you must first obtain the sample templates, customize those templates that you need, and save the templates in the file system of your vRealize Automation appliance(s).

These templates are provided in VMware KB 2088805. Download and copy the vrealize_automation.tar.gz to root "/" the vRealize Automation appliance file system.

• From Windows, SCP the file to the vRealize Automation appliance with a utility like WinSCP.

• From Mac or Linux, open and terminal and run the following commands.

  scp vcac.tar.gz root@<vRA-VA-FQDN>:/
  

​From either Windows, Mac or Linux, SSH to the vRealize Automation appliance(s) and run the following commands to extract the contents to the root of the file system and set the appropriate permissions on the templates.

ssh root@<vRA-VA-FQDN>
cd /
tar -xvzf vcac.tar.gz
find /vcac -type d -exec chmod o+rx {} \;
find /vcac -type f -exec chmod o+r {} \;

Restart the VMware vRealize Automation appliance services by running this command:

service vcac-server restart

Before we start crafting the custom messages that for the user experience, let's examine the structure and contents of these loaded sample templates.

There are three main folders in sample templates:

1. /vcac/templates/email/html/core/ contains core templates for messages.
2. /vcac/templates/email/html/forms/​ contains templates for form layouts.
3. /vcac/templates/email/html/extensions/​ contains templates, which are used to display fields in IaaS forms.

Below is the file structure:

/vcac/
/vcac/vcac/templates/
/vcac/templates/email/
/vcac/templates/email/html/core/
/vcac/templates/email/html/core/defaults/
/vcac/templates/email/html/core/tenants/
/vcac/templates/email/html/extensions/
/vcac/templates/email/html/extensions/defaults/
/vcac/templates/email/html/extensions/tenants/
/vcac/templates/email/html/forms/
/vcac/templates/email/html/forms/defaults/
/vcac/templates/email/html/forms/tenants/
/vcac/templates/email/i18n.vm

In the core, extensions, and forms subfolders, there is a folder called defaults. The templates, represented as .vm files, in this folder are used by vRealize Automation when tenant specific templates are not specified.

Understanding Contents of /core/defaults/

Inside the /vcac/templates/email/html/core/defaults/ folder the there are five (5) template files that defined the default message structure.

• ​main.vm: Required. This is the main message and is defined by including / parsing additional template files.
• styles.vm: Optional. Included in the samples to define the CSS </style> element consumed by main.vm.
• header.vm: Optional.Included in the samples to define the HTML </header> element consumed by main.vm.
• links.vm: Optional. Included in the samples to define a set of URLs presented in main.vm.
• footer.vm: Optional. Included in the samples to define a footer message presented in main.vm.

As a reminder, these files are built using an Apache Velocity template engine. Learn about the directives used and available that may be used in the Apache Velocity User Guide.

Let's take a look at the structure of the ​main.vm.

In the main.vm you can see the basic standard building blocks of an HTML document similar to:

<html>
     <header></header>
     <head>
         <title></title>
         <style></style>
     </head>
     <body>
     </body>
</html>

Inside the code blocks, Apache Velocity #parse directives call additional.vm template files, for example:

<head>
     #parse( 'core/styles.vm' )
</head>

Pretty simple, right? Plus, there is tons of room to get creative, as you will see later in this post.

If you can follow standard HTML and basic Apache Velocity directives you are already well on your way. When you create your own .vm files and place them into the defaults folder remember to include the core/ before the template name in the #parse directive.

You will also notice there is a call within the </body> element for $body. This directive is calling content for the message based on the notification scenario. Content layouts for the $body element is provided in the /vcac/templates/email/html/forms/​ directory contents.​

Now, let's move forward and explain how to provide per-tenant, per-locale and scenario based directory structures.

Customizing Per-tenant Templates

As mentioned prior, tenant specific templates can be loaded in the tenants/<tenantName> folder in parallel to the defaults folder.

For example, if your tenant was named "CloudOperations" you would add a /CloudOperations/ folder under the tenants folder.

/vcac/
/vcac/templates/
/vcac/templates/email/
/vcac/templates/email/html/core/
/vcac/templates/email/html/core/defaults/
/vcac/templates/email/html/core/tenants/
/vcac/templates/email/html/core/tenants/CloudOperations/
/vcac/templates/email/html/extensions/
/vcac/templates/email/html/extensions/defaults/
/vcac/templates/email/html/extensions/tenants/
/vcac/templates/email/html/extensions/tenants/CloudOperations/
/vcac/templates/email/html/forms/
/vcac/templates/email/html/forms/defaults/
/vcac/templates/email/html/forms/tenants/
/vcac/templates/email/html/forms/tenants/CloudOperations/
/vcac/templates/email/i18n.vm

When a new folder/file is added for customization, you must ensure it has right permissions by executing commands on the vRealize Automation appliance(s).

find /vcac -type d -exec chmod o+rx {} \;
find /vcac -type f -exec chmod o+r {} \;

You need to wait for 120 seconds to see new customizations reloaded and reflected in messages.

Customizing Per-locale Templates

Locale specific templates can be specified in defaults or tenants/<tenantName> folders. These folders can contain further sub-folders for locale specific templates.

When searching for locale-specific template, vRealize Automation searches by country, then language, and on the defaults. ​For example:

1. /vcac/templates/email/html/core/defaults/fr/CA/<template>.vm
2. /vcac/templates/email/html/core/defaults/fr/<template>.vm
3. /vcac/templates/email/html/core/defaults/<template>.vm<

When searching for a tenant-specific template, vRealize Automation searches through the tenants folders before searching the defaults folder. A search through these tenant-oriented folders simultaneously inspects for locale. When no tenant information is defined, search is confined to the defaults folder alone.

For example, when searching for a <template.vm> in the locale fr_CA (French Canada) under the CloudOperations tenant the following sequence of paths would be checked in this order:

1. /vcac/templates/email/html/core/tenants/CloudOperations/fr/CA/<template>.vm
2. /vcac/templates/email/html/core/tenants/CloudOperations/fr/<template>.vm
3. /vcac/templates/email/html/core/tenants/CloudOperations/<template>.vm
4. /vcac/templates/email/html/core/defaults/fr/CA/<template>.vm
5. /vcac/templates/email/html/core/defaults/fr/<template>.vm
6. /vcac/templates/email/html/core/defaults/<template>.vm

Customizing Scenario Based Templates

vRealize Automation 6.1 allows a scenario ID to be used to customize template content.

For example, in a .vm template you could specify a scenario such as:

if ($scenario == "csp.catalog.notifications.resource.activated")
     <p>Lorem ipsum dolor amet, consectetur adipiscing elit.</p>
end

In vRealize Automation 6.2 we introduced a new, scalable, and recommended approach to scenario based notifications.

Note

6.2 still supports the 6.1 customization method, but it is not recommended.

To customize a template file for a specific scenario, create a file named in the following format: <template.vm>-<scenarioId>.

To create a separate main.vm for the above Resource Activated scenario, create a template file with this name: main.vm-csp.catalog.notifications.resource.activated

A list of scenarios can be found in KB 2088805​ or in Administration > Notifications > Scenarios when logged into vRealize Automation as a Tenant Administrator.

Add Custom Properties

Only available in vRealize Automation 6.2 and later, custom properties that are part of the request form can be added in the email template in this format: $formData.get("provider-<CustomPropertyName>”)

Customizing Scenario Subjects

Only available in vRealize Automation 6.2 and later, the subject line can be customized per notification scenario by creating a template with this naming convention: s​ubject.vm-<scenarioId>

To define a subject line for the Resource Activation scenario, create a template as: subject.vm-csp.catalog.notifications.resource.activated.

The content of this file must be only one line of text. For example:

[One Cloud] Your Resource Has Been Activated

Putting It All Together

Now you know how to:

• Load and Set Default Templates
• Template Directory Structure and Content
• Default Template Structure and Directives
• Customizing Per-Tenant Directory Structures
• Customizing Per-Locale Directory Structures
• Customizing Scenario Based Templates
• Customizing Scenario Based Emails

Let's take this take this to the next level with an example, and create a custom template for a tenant based on what you now know.

Requirement	Setting
Tenant	CloudOperations
Scenario	Resource Activated
Locale	Default
Template	Custom Design
Subject	Custom Subject

Let's Get Started

1. Obtain the sample templates from KB 2088805.

2. Open a terminal and run the following command:

   scp vcac.tar.gz root@<vRA-VA-FQDN>:/
   

3. SSH to the vRealize Automation appliance and run the following commands to extract the contents to the root of the file system and set the appropriate permissions on the sample templates.

   cd /
   tar -xvzf vcac.tar.gz
   find /vcac -type d -exec chmod o+rx {} \;
   find /vcac -type f -exec chmod o+r {} \;
   

4. Restart the VMware vRealize Automation appliance services by running this command:

   service vcac-server restart
   

5. Create a custom folder for the CloudOperations tenant in the directory structure: /vcac/templates/.

   /vcac/templates/email/
   /vcac/templates/email/html/core/
   /vcac/templates/email/html/core/defaults/
   /vcac/templates/email/html/core/tenants/
   /vcac/templates/email/html/core/tenants/CloudOperations/ # <-- My Tenant!
   /vcac/templates/email/html/extensions/
   /vcac/templates/email/html/extensions/defaults/          # <-- Will Use defaults.
   /vcac/templates/email/html/extensions/tenants/
   /vcac/templates/email/html/forms/
   /vcac/templates/email/html/forms/defaults/               # <-- Will Use defaults.
   /vcac/templates/email/html/forms/tenants/
   /vcac/templates/email/i18n.vm
   

6. Under /vcac/templates/email/html/core/tenants/CloudOperations/ create message and subject templates for the scenario csp.catalog.notifications.resource.activated to be called called when a new requested resource is activated.

   1. First, c​reate the file ​subject.vm-csp.catalog.notifications.resource.activated. The first line of the file is edited as seen below.

      

   2. Next, ​under /vcac/templates/email/html/core/tenants/CloudOperations/ create the file main.vm-csp.catalog.notifications.resource.activated. If you choose to use custom images, fonts, etc place those resources on an easily accessible web server that the users can access during the render.

   In your template, you may want to set some variables to call within the template, such as:

   ## --------------------------------
   ## Set variables...
   ## --------------------------------
   
   # set( $orgName = "VMware, Inc." )
   # set( $orgStaff = "Cloud Operations" )
   # set( $orgDate = "2015" )
   # set( $orgSignOff = "Party on,"      )
   # set( $orgPoweredBy = "Powered by VMware vRealize Automation and energy drinks." )
   # set( $orgURL = "<http://demo.vmware.com/>" )
   # set( $orgImages = "{$orgURL}images/" )
   # set( $orgFonts = "{$orgURL}fonts/" )
   # set( $orgLogo = "{$orgURL}{$orgImages}logo.png" )
   

   You can call these variables within your template at any time, like so:

   ## --------------------------------
   ##  Start the content close...
   ## --------------------------------
   
   $orgPoweredBy
   Copyright © $orgDate $orgName
   
   ## -------------------------------
   ## End the content close...
   ## -------------------------------
   

   Now, I know what you're thinking. "Can I set these as global variables in simply parse that file and call the variable when I need it?" Unfortunately, not at this time.

What you end up with looks similar to the following.

and...

Once again, remember that when a new folder/file is added for customization, you must ensure it has right permissions by executing commands on the vRealize Automation appliance(s).

find /vcac -type d -exec chmod o+rx {} \;
find /vcac -type f -exec chmod o+r {} \;

​You need to wait for 120 seconds to see new customizations reloaded and reflected in your messages.

Now, let's put it to work and see what happens when a user requests a new resource from the CloudOperations tenant.

Voila! Isn't that so much better?

Get creative! Define the user experience for messages from vRealize Automation in your software-defined data center and have fun while doing it.

Disclaimer

This is not an official VMware document. This is a personal blog post. The information is provided as-is with no warranties and confers no rights. It is not intended to replace official VMware documentation. Please, refer to official VMware documentation for the most up-to-date information.