In order to generate email based notifications from a user defined Powershell step the following data items need to be set up within emdash.
- Channel- the channel defines how messages are sent e.g. email or Slack. Each channel has a defiend set of properties which must be set before the channel cann be used.
- Distribution list - this defines a set of recipients for a notification message
- Template - this defines the content of the message
- Rule - rules define which notifications result in actual messages being sent to recipients. The rule links the message to the template, channel abd distribution list.
The basc sequence of events when sending a message is as follows.
Setting up a channel
A channel defines how a message is sent e.g. via email. A channel is assigned to a channel type e.g. email, Slack etc which define which properties must be set for the channel e.g. SMTP server, from email address, slack channel etc.
To create an email channel:
1) Go to the Channels page under Admin Tools -> Notifications.
2) Click Create channel
3) Enter a name, a description and a Channel type of "Text based email"
4) Choosing a channel type of "Text based emil" then enables other properties specific to this type of channel.
Enter the details for the additional fields.
- From email address - this is the email address that the email will apear to be sent from.
- From email address display name - this is the display name that the email will apear to be sent from.
- SMTP Server - the name of the email server
- Email subject - the subject that will be incuded in emails sent on this channel.
- Use default credential for email - determines whenther the default credential are sent with the email. In general this should be set to false.
- Email server user name - the user name to authenticate with the email server. This field is optional.
- Email server password- the password to authenticate with the email server. This field is optional.
- SMTP port - the port to use for the SMTP server. Usually port 25.
- SMTP enable SSL - whether to enable SSL when sending the email to the SMTPP server.
- Enabled - whether the channel is enabled or not. If the channel is not enabled then any messages sent on it will be discarded.
5) Press Save.
Setting up a distribution list
A distribution defines the recipients of a notification. In the case of email this will be a list of email addresses.
To create an email distribution list:
1) Go to the Distribution lists page under Admin Tools -> Notifications.
2) Click Create distribution list
3) Enter a description and a Channel type of "Text based email"
4) Click the Add entry button to add an email address.
5) To remove an email address from the list click the Delete button alongside the address.
6) Click Save.
Setting up a template
A message template defines the content of the message that is sent as a result of the notification. The template supports the following text substitutions.
- Environment wide settings. Standard functionality based on environment wide setting options and overrides at the environment level based on environment wide settings.
- Environment values. The following stings will be replaced with the appropriate environment field if included in the message template.
- {ENVIRONMENT_NAME} – substituted with target environment name
- {ENVIRONMENT_OWNER} – substituted with target environment Owner
- {ENVIRONMENT_FILESHARE} – substituted with target environment Fileshare
- {ENVIRONMENT_PLATFORM} – substituted with target environment PlatformName
- {ENVIRONMENT_AUTHENTICATIONTYPE} – substituted with target environment AuthenticationType
- {ENVIRONMENT_DESCRIPTION} – substituted with target environment Description
- {ENVIRONMENT_NOTES} – substituted with target environment Notes
- {ENVIRONMENT_HIDEFROMENVREFRESHLIST} – substituted with target environment HideFromEnvRefreshList
- {ENVIRONMENT_ENVTYPE} – substituted with target environment EnvType
- {ENVIRONMENT_OWNERALLOCATEDFROM} – substituted with target environment OwnerAllocatedFrom
- {ENVIRONMENT_OWNERALLOCATEDTO} – substituted with target environment OwnerAllocatedTo
- Additional info strings. When creating the notification message if the user includes an additional info field it will be substituted into the message template text. This allows the user to create dynamic message content in a workflow step and have it included in the message that is actually sent by the notification service. emdash currently supports the following additional info types:
- AddInfo1
- AddInfo2
An example template with the three types of substituion would look something like:
Sample email text for environment {ENVIRONMENT_NAME}
Environment wide setting TEST123 for this environment is set to TEMPLATE_TEST123
Some additional info has been included - AddInfo1
If the environment name is set to TEST01, environment wide setting TEST123 has a value of xyz and AddInfo 1 is supplied as value abcd then the resulting email text will be:
Sample email text for environment TEST01
Environment wide setting TEST123 for this environment is set to xyz
Some additional info has been included - abcd
Setting up a rule
Rules are the heart of the notification system. Any notification messages created using the Notify function are matched against the rules and are only processed if a match is found.
The following fields can bet set on a rule:
These fields are used for matching notifications:
Mandatory
- NotificationTypeId – notification type to match messages on
Optional
- ApplicationId – application to match messages on
- DeploymentWorkflowId – workflow to match messages on
- DeploymentWorkflowStepId – workflow step to match messages on
- DeploymentStepId – deployment step to match messages on
- EnvironmentId - environment to match messages on
- EnvironmentTypeId – environment type to match messages on
These fields used for sending messages
- NotificationChannelId – defines the channel on which to send messages matching the rule
- NotificationMessageTemplateId – defines the template to messages matching the rule
- NotificationDistributionListId – defines the distribution list to send messages matching the rule
To create a rule:
1) Go to the main rules page under Admin Tools -> Notifications.
2) Click Create rule
3) Enter the mandatory fields Description, Notification type, Channel, Template and Distribution list. Channel, Template and Distribution list will be the entries you set up earlier in the process.
Optionally you can enter Application,, Workflow, Workflow step, Deployment step, Environment and Environment Type to further refine whether the rule will match a notificaiton created by emdash or a user step.
Creating and sending a message
In order to send a notification, call the Notify message on the PowerShell content. The below code shows some smale code.
[CmdletBinding()]
Param(
[Parameter(Mandatory=$True)]
[emDash.Workflow.Step.Interface.PowershellContext]$ctx
)
try
{
# The following two variables must be included as these define the name of th estep and its current version in emdash
$emdashStepName="NotifyStep"
$emdashStepVersion="3"
$baseDirectory = $ctx.GetBaseDirectory()
$ctx.LogProgress("Base directory is $baseDirectory")
Add-Type -Path ("$baseDirectory\emDash.Workflow.Steps.Common.dll")
Add-Type -Path ("$baseDirectory\emDash.Workflow.Model.dll")
$notification = New-Object emDash.Workflow.Model.Notification.Notification
$notification.JobId = $ctx.JobId
$notification.StepId = $ctx.JobStepId
$notification.AdditionalInfo = @{}
$notification.AdditionalInfo.Add([emDash.Workflow.Model.Notification.NotificationAdditionalInfoType]::AddInfo1,'some additional info for the notification message')
$notification.NotificationType = [emDash.Workflow.Model.Notification.NotificationType]::SystemMessage
$ctx.ServiceClient.Notify($ctx.ClientId,$notification)
# returning True will set the step status to Succeeded
Return $True
}
catch [Exception]
{
Write-Error ("Error: {0} {1}" -f $_.Exception.Message, $_.Exception.StackTrace)
# returning False will set the step status to Failed
Return $False
}
0 Comments