Objective
You have a working FlexDeploy Release/Pipeline. The goal of the tutorial is to send mail notification using Office365 as smtp server. The tutorial will include:
Enable HTTPS in FlexDeploy server
Configure credentials in Azure
Configure FlexDeploy Email Setting properties
Configure email content
Configuration steps
We would need to perform 4 primary activities,
FlexDeploy Server must be SSL(HTTPS) enabled, if not already done.
One valid regular Azure user without MFA enabled. Preferably create a dedicated user account for the same.
A Service Principal(Azure Application), which will send email notifications on behalf of the user.
Provide all relevant access to the Service Principal so that it can send email notifications. User Consent/Admin Consent is essential as well.
Enable HTTPS in FlexDeploy server
Please review below link to enable SSL(HTTPS) in FlexDeploy server.
In the above link the steps are shown using self-signed certificate. However, it is always recommended to use an SSL certificate issued by a CA.
Once the SSL is configured and server is restarted, please make sure to update the Server Base URL.
Above steps are essentials and the reason is explain in Why enabling HTTPS and configuring correct Redirect URI is important
Configure credentials in Azure
Please refer to below link on how to configure Service Principal(Azure Application) and provide relevant permissions.
While configuring the Redirect URI(as mentioned in above link) - it should be your FlexDeploy server url appended with the following path /flexdeploy/rest/v2/oauth .
In our case the FlexDeploy Server url is https://fdtlt86.flexagon.azure.com:8443 so effectively the Redirect URL will be https://fdtlt86.flexagon.azure.com:8443/flexdeploy/rest/v2/oauth.
Why enabling HTTPS and configuring correct Redirect URI is important
Lets first understand Redirect URI: This is the URI where Azure will redirect(basically FlexDeploy Server) after successfully authorizing the Azure application.
As part of Azure Application(Service Principal) setup in previous step, we have configured the Redirect URI as https://fdtlt86.flexagon.azure.com:8443/flexdeploy/rest/v2/oauth
The Redirect URL generated by FlexDeploy server using the Server Base URL is
$Server_Base_Url/flexdeploy/rest/v2/oauth
This must match the Redirect URL that was configured in the Azure Redirect URL. Else will get below error.
You can’t have an http url configured in Azure Application Redirect URI. Restriction at Azure end as shown below. This is why you need to enable SSL(HTTPS) in FlexDeploy Server.
Configure FlexDeploy Email Setting properties
Navigate to system-settings and configure the Email Setting with relevant details,
Use the ClientId/Client Secret of Azure Application(Service Principal) for OAuth Client Id/Secret and the Azure user credentials should be added under SMTP User/Password.
After providng the necessary details, select either the Authorize(first time) or Re-Authorize buttons.
Or
At this point you will be re-directed to Microsoft to authorize FlexDeploy. This is the step where user is providing the consent to Azure Application.
If everything is successful you should be redirected back to this page with below success message.
In certain organizations, user may not have right to give consent. In that it can request for Admin Approval as shown below.
In such scenario, it’s advisable to provide Admin Consent to the Azure Application(Service Principal) directly from Azure App Registration page as shown below. Post which no popup should appear during Authorization.
Once authorization is complete, you can test the configuration by clicking on the Test Email Configuration button.
It may happen that the Azure account setup is completed properly. We even got the green Authorized acknowledgment. Still while doing Test Email Configuration it may fail.
You may face below error popup after around 10secs.
Important thing to understand here is even though its thrown as AuthenticationFailedException, there may be nothing wrong with userId/password. If we check closely, we can find, it’s getting timeout while connecting to smtp server. Could be Firewall related issue. Check the FlexDeploy Server log as well.
Tips :You can try telnet to smtp server host/port from the FlexDeploy server to check once.
Similar issue: https://stackoverflow.com/questions/56802175/smtp-send-mail-is-not-working-for-office365
If everything is successfully configured, Test Email Configuration will reflect success response.
Test email shall also be sent to user who initiated
Configure email content
Add a Notification Step in pipeline. The Pipeline should have a Role defined(any name) with the mail recipients as part of the same Role.
The Role should be mapped to Pipeline Roles of Notification step as shown below.
Provide correct Subject and Message details. In case the Message has dynamic values make sure to use f(x) option so that it can parse the dynamic values accordingly.
Sample groovy script to send mail notification body with dynamic content.
def builder = new StringBuilder();
// Creating variables and capturing relevant details
def envCode= stgexec.getEnvironmentCode()
def submittedUser= snapshot.getCreatedBy()
def releaseName= stgexec.getReleaseName()
// Setting the Header of the mail
builder.append("<h1 style=\"padding: 10px 0\">Pipeline stage execution completed.</h1>");
// Sending the Stage execution details in Table format
// Below section is to form the HTML table format
builder.append("<table border=1>");
builder.append("<tr>"+
"<th style=\"padding: 0 10px 5px 0\">Environment Name</th>"+
"<th style=\"padding: 0 10px 5px 0\">Release Name</th>"+
"<th style=\"padding: 0 10px 5px 0\">Pipeline Name</th>"+
"<th style=\"padding: 0 10px 5px 0\">Submitted User</th>"+
"</tr>");
builder.append("<tr>"+
"<td style=\"padding-right: 10px\">${envCode}</td>"+
"<td style=\"padding-right: 10px\">${releaseName}</td>"+
"<td style=\"padding-right: 10px\">${PipelineName}</td>"+
"<td style=\"padding-right: 10px\">${submittedUser}</td>"+
"</tr>");
builder.append("</table>");
Apparently it looks fairly simple only, indeed it is. Lets go through it.
It’ simply retrieving some information using FlexDeploy API and assigning it to 3 variables.
Then creating a simple HTML table(basically String) with above details for better clarity (not mandatory, clear text also acceptable ).
That’s it, FlexDeploy will use the same content to send mail notification.
In case you are wondering from where we derived
stgexecoperations or we directly usedPipelineNamevariable, please refer to below page to have a detailed understanding of FlexDeploy Groovy variable and methods:
Pipeline Groovy Variables and Methods
Below given is the result notification mail. It will contain some pre-configured information along with the content we added as part of Notification message.
In the Notification step itself FlexDeploy provides an excellent feature to verify/retrieve the operation/method names as shown below using Variable Lookup.
Next we will try something slightly more complex. Lets assume our Release has multiple projects associated to it, we want to add Project and Package details as well as part of the mail.
If we refer to Pipeline Groovy Variables and Methods , we can get the Project objects through stgexec.getSnapshotProjects() method. This method will basically return ReleaseProjectVersion objects.
ReleaseProjectVersion object has multiple methods to retrieve relavant details we are looking for. Above link contains all details.
So if we refactor our previous code a bit, below code will give us our desired result.
def builder = new StringBuilder();
def envCode=stgexec.getEnvironmentCode()
def releaseName=stgexec.getReleaseName()
//stgexec.getSnapshotProjects() --returns list of ReleaseProjectVersion objects.
def releaseProjects=stgexec.getSnapshotProjects()
// Setting the Header of the mail
builder.append("<h1 style=\"padding: 10px 0\">Pipeline stage execution completed.</h1>");
// Sending the Stage execution details in Table format
// Below section is to form the HTML table format
builder.append("<table border=1>");
builder.append("<tr>"+
"<th style=\"padding: 0 10px 5px 0\">Environment Name</th>"+
"<th style=\"padding: 0 10px 5px 0\">Release Name</th>"+
"<th style=\"padding: 0 10px 5px 0\">Project Name</th>"+
"<th style=\"padding: 0 10px 5px 0\">Project Version</th>"+
"<th style=\"padding: 0 10px 5px 0\">Package Name</th>"+
"</tr>");
//Looping through all ReleaseProjectVersion objects(Projects)
for (project in releaseProjects) {
def projectName = project.getProjectName();
def projectVersion = project.getProjectVersionName();
def packageName = project.getPackageName();
builder.append("<tr>"+
"<td style=\"padding-right: 10px\">${envCode}</td>"+
"<td style=\"padding-right: 10px\">${releaseName}</td>"+
"<td style=\"padding-right: 10px\">${projectName}</td>"+
"<td style=\"padding-right: 10px\">${projectVersion}</td>"+
"<td style=\"padding-right: 10px\">${packageName}</td>"+
"</tr>");
}
builder.append("</table>");
Now output mail will appear as given below.
Congratulations! You have successfully completed the email Notification Integration from FlexDeploy Pipeline.
Now that you have configured email setting successfully in FlexDeploy, the same can be reused for all other mail notifications as well. Simply refer to Pipeline Groovy Variables and Methods and configure your mail content similar way as mentioned above.