One of the most common request you probably get when working with vRealize Automation 8.1 or vRealize Automation Cloud is, Can you customize email notifications?, could that be done with Action Based eXtensibility (ABX)? The short answer to both is “Yes”.
In this blog, I will show you how to take advantage of the Event Broker Service (EBS), Action Based eXtensibility (ABX) and vRealize Automation’s APIs for sending customized email notifications for a different variety of deployments (single or multiple resources, Private, Hybrid or Public Cloud based, Custom Resources, Kubernetes resources (e.g. Namespaces ), etc.
This is not a definitive implementation, but instead of, I would like to provide you with a functional / operational implementation that you could use as a base from which you could modify further, e.g. you may want to introduce your own email template, add/remove fields or bring your own secrets engine.
I will walk you through the steps to install, configure these resource and review the main code blocks.
You can download all the artifacts from this repository VMware TMM Hermes
System Pre-Requisites:
- vRealize Automation Version 8.1 with ABX On-Prem (Internet connectivity directly or via Proxy) or vRealize Automation Cloud with AWS (ABX On-Prem also possible).
- vRealize Suite LifeCycle Manager (vRSLCM) 8.1 ( If trying vRealize Automation Cloud you can use local properties instead of).
- SMTP Server supporting TLS (e.g. office365.com or mailtrap.io).
- Of Course, since we want to send email notifications on deployments events, make sure to have your vRealize Automation system configured (Cloud Account, Zone, Projects, Profiles, Images, Blueprints, etc.). In the case of this blog I have tested vRealize Automation Cloud with AWS Resources with Lambda permissions.
- Please note that the end user needs to have a valid email address, you could review that a valid email address exists for your test user by going to vRealize Automation Version’s “User Settings”, then “My Account”.
And before we begin, let’s go over some key concepts:
Event Broker Service (EBS): The service that dispatches messages published by a producer to the subscribed consumers.
Action Based eXtensibility (ABX): provides a lightweight and flexible run-time engine interface where you can define small scriptable actions and configure them to initiate when events specified in extensibility subscriptions occur.
Extensibility Action: A streamlined script of code that can run after an event is triggered in a subscription. Extensibility actions are similar to workflows, but are more lightweight. Extensibility actions can customized from within vRealize Automation Cloud Assembly. You can create these extensibility action scripts of code within vRealize Automation and assign them to subscriptions.
Subscriptions: Indicates that a subscriber is interested in being notified about an event by subscribing to an event topic and defining the criteria that triggers the notification. Subscriptions link either extensibility actions or workflows to triggering events used to automate parts of the applications life cycle.
Event Topic Describes a set of events that have the same logical intent and the same structure. Every event is an instance of an event topic.
Ok, so having that out of the way, let’s draft the steps that need to happen.
Configure our vRealize Suite LifeCycle Manager to store our vRealize Automation’s Refresh Token & Email Server Login credentials.
vRealize Suite LifeCycle Manager’s Locker feature, allows you secure and manage passwords, certificates, and licenses for vRealize Suite product solutions and integrations.
Since vRealize Automation 8. 1 deployments contains vRealize Suite LifeCycle Manager it is an easy integration and logical choice for password store.
Most likely when using vRealize Automation Cloud you won’t have a vRealize Suite LifeCycle Manager, in this case, we can disable and use local variables (more later at this post).
Login to vRealize Suite LifeCycle Manager with Admin rights (e.g. admin@local), Go to “Locker Section”, “Passwords” , then add 2 entries as follows:
smtpPassword ( your email server Password )
vraRefreshToken ( vRealize Automation Refresh Token for a service account with enough permissions to execute ABX actions, for simplicity any Administrator role will be more than enough* )
* HINT ! at the vmware / terraform-provider-vra you can find a Shell and Powershell scripts ( get_token.sh or get_token.ps1) to easily collect your vRealize Automation Refresh Token from vRealize Automation 8.1
These credentials are needed to access your Email Server and for making vRealize Automation API calls, make sure the username is the same for both secrets
Create an Extensibility Action (Python Based).
Clone or Download the artifacts from VMware TMM Hermes in your local system
Login to vRealize Automation (or Cloud) with Administrator role, Go to “Cloud Assembly”, “Extensibility”, “Actions”, and “Import”, locate the folder where you downloaded the artifacts from the repository and select “vRA-EmailNotification-003.zip” then the Project you would like to use it.
Please note that vRealize Automation 8.1 can run ABX Actions only in one specific Project, however in vRealize Automation 8.2 you could share actions across Projects, vRealize Automation Cloud already supports it.
Select IMPORT, then you will get a confirmation that the action was successfully imported and becomes available as “Email-Notification”.
Select OPEN to access the newly imported “Email-Notification” ABX Action.
A few things to highlight,
Dependency: This section is equivalent to having “pip install -r requirements” ,where the requirements are defined as: “request” and “json2html” Python libraries,
meaning that vRealize Automation should be able to reach the Python PIP repository at Internet.
( Please note that you can pre-install any dependencies into a zip bundle in case your vRA cannot reach the Internet, this is however out of the scope of this blog, more information at Create a ZIP package for Python runtime extensibility actions )
FaaS provider: Make sure to select “On Prem” when using vRealize Automation 8.1 or “Amazon Web Services” for vRealize Automation Cloud (it is very possible to use “On Prem” or “Azure FaaS” but it requires further testing and validation).
Default Inputs: This is useful for testing manually, however since we actually make calls to vRealize Automation API, make sure to replace those values with existing ones if you want to test manually.
At the “WRITE SCRIPT” locate the following sections and update the properties accordingly to meet your local environment :
######## LCM Variables #####################
lcm_url = “cava-r-96-020.eng.vmware.com” # vRSLCM URL
lcm_email_PasswordIdentifier = “smtpPassword” # vRSLCM Locker Alias for SMTP Password
lcm_refreshToken_PasswordIdentifier = “vraRefreshToken” # vRSLCM Locker Alias for vRA Token
lcm_pass = “XXXXXX” # Password to access vRSLCM
lcm_user = “admin@local” # Login to access vRSLCM
lcm_on = “on” # Set “on” to enable using vRSLCM or “off” to use local variables and replacing by “localsmtpPassword” & “localvraRefreshToken“, if Using vRealize Automation Cloud set it off.
localsmtpPassword = “XXXXXXXXX” # paste your password , if Using vRealize Automation Cloud provide this input.
localvraRefreshToken = “XXXXXXXX” # paste your vRA Token , if Using vRealize Automation Cloud provide this input.
######## SMTP Configuration START #####################
smtp_port = 587
smtp_server = “smtp.mailtrap.io” # FQDN for SMTP
smtp_login = “665e51d3948d03” # Login to access SMTP Server
sender_email = “[email protected]” # Email Address for Sender
######## vRA Configuration START #####################
vraUrl = ‘cava-n-81-246.eng.vmware.com’ # vRA on-prem URL
vraAlias = ‘vRA Wexford’ # vRA or vRAC Alias
vraCloud = “off” # “on” for using vRAC Cloud | “off” for using vRA 8.1 on-prem
######## VARIABLE ENDS #####################
Please note that only Administrators roles can access this section, even during execution and end users won’t be able to see this information at any moment.
then SAVE & CLOSE your changes, also it is a good practice to Create Version.
Now let me walk you through the main APIs and Functions.
I will start with vRealize Automation API calls, (vRealize Suite LifeCycle Manager API requires a Blog of its own but you can inspect the whole code at main.py).
First, we need to “Generate Bearer Token” to access vRealize Automation, for that, we can use the “/iaas/api/login?apiVersion=2019-01-15” API.
Please note that I include the apiVersion, that way, I can prevent my code to stop working whenever there is a new API definition, say after a vRealize Automation new release, you can always verify the API version available with “/iaas/api/about”.
After we are successfully authenticated, let’s query vRealize Automation to discover the information about the Deployment, for that we call “/deployment/api/deployments/{depId}” API.
Please note the use of the following parameters:
“?expandProject=true” -> The expanded details of the requested comma separated objects. Ex. blueprint, project.
“&expandResources=true” -> The ‘resources’ field of the deployment will be retrieved.
With his information we are ready to start crafting our Email’s Subject and Body template as needed.
For simplicity I collect only a few main attributes (name, createdAt, etc.) and format the entirety of JSON output into HTML then append it into a pre-defined template, that way I provide all available information for different deployment types. Please note that I am also able to include custom properties and other metadata provided by vRealize Automation.
however you can extract specific attributes to include in your template, as in the following example, I inspect all the available resources and collect only a few properties from them by exploring the JSON tree.
Please exercise caution, different kind of resources provide different kind of properties you could access, e.g. a “Cloud.Machine” could provide information that is not necessarily available in the case of a “Cloud.AWS.EC2.Instance” or a “Custom.Resource”, plan accordingly when defining your template.
Of course, we also need to collect the subscriber’s email information, for that we will use the “/csp/gateway/am/api/users/{acct}/orgs/{orgId}/info?apiVersion=2019-01-15” API.
Please note that this specific API, even though is found at vRealize Automation On-Prem, it is part of the Cloud Services Platform API Documentation. with an altogether different endpoint URL for the case of vRealize Automation Cloud (console.cloud.vmware.com), hence the importance of configuring correctly the vraCloud = “off” | “on”
At this point we got everything we require for sending a meaningful notification email.
Once again, you can inspect the whole code in the ABX Action’s “WRITE SCRIPT” or here main.py.
Let’s go back and resume the vRealize Automation configuration.
Create Event Broker Service (EBS)’s Subscription for a Deployment completed Event
A Deployment Completed Event (deployment.request.post) is fired after a deployment create, update or delete for both blueprint and catalog requests is generated.
We will subscribe to this event to trigger our ABX Action and receive an email notification for any of those events.
Login back to vRealize Automation, Go to “Cloud Assembly”, “Extensibility”, “Subscriptions” , then “New Subscriptions”.
Provide a “Name”, a “Description” of your preference,
for “Event Topic”, “+ ADD” from the list and select “Deployment completed” .
For “Action/workflow “, “+ ADD” and select the recently imported ABX Action “Email-Notification”.
Enable “Blocking” and adjust default settings if needed be, finally allow “Any project” for “Subscription scope” then “SAVE”.
And we’re ready to use this new ABX Action.
Testing & Validating
In order to test and validate the correct operation of our set up, request a brand new deployment of any resource, e.g. a simple VM Blueprint in the Project where our ABX action was configured.
Once the request is complete,
We will receive an email notification for this deployment:
And more information:
Let’s go ahead and update this existing deployment by going from small to large.
We will get an updated notification,
which includes the updated information for the newly added resources:
with an Administration role, you can validate and find more details about the ABX Action execution by going to “Extensibility”, “Activity” , then “Action Runs”
So VMs deployments are fine, but how about a Custom Resource Deployment? or if we’re trying a Kubernetes namespace Blueprint? may be a deployment request fails , how about that?
All those scenarios will be captured since we trigger our ABX Action at the “Deployment completed” for “Event Topic” as explained above.
In fact, you could imagine that testing & validating multiple scenarios could be time consuming, however we should and must automate this process, and in order to do that, you could take advantage of “vRealize Automation’s Code Stream” to create a “Pipeline” that runs multiple email notification scenarios with one single click.
I created an Email-Notification CodeStream Pipeline:
This CodeStream Pipeline has multiple “Blueprint tasks” ( to create, update, delete, etc. ) defined for streamlining our email notification testing.
This is an example for a Blueprint Task:
Please note that the “Deployment Name” is constructed with a environment variable “Email_Notification-CR-${executionId}”, so I could perform several and independent Pipeline executions for every change I do “Email_Notification-CR-${executionId}”.
Conclusion
Combining vRealize Automation capabilities or “building blocks”, like the ones described here : ABX , EBS, APIs & CodeStream will allow you to implement multiple use cases required today but also the ones you might face in the near future with a methodological and repeatable way.
Feel free to explore the code, change the template to your like, add or remove fields, enhance it, it is all about collaboration !
For more information feel free to check these blogs:
vRealize Automation Action Based Extensibility (ABX) now supports PowerShell
vRealize Automation Cloud (fka Cloud Automation Services) – API First!
Integrations Available For VMware Code Stream
