What’s this?
Butler can send two kinds of alert emails:
- When a reload task fails during execution.
- When a running reload task is somehow stopped/aborted.
- When a reload task completes successfully.
Butler has a de-duplication feature that ensure each email address that has qualified for an alert email only gets ONE email per alert.
See the Concepts section for additional details and sample alert emails.
Basic vs formatted email alerts
If you want Butler to send email alerts you must provide an email template file.
For some other alert destinations (Slack and Teams) Butler offers a “basic” option. A fixed format alert is then sent by Butler.
The closest thing available for emails is to use the mail log appender described here, but if you set up a log appender AND have Butler running, you might as well use the formatted email option as it provides much more flexibility than log4net’s email appender.
Rate limiting
Butler has rate limiting feature to ensure alert recipients are not spammed with too many alert emails.
The rate limit is configured (in seconds) in the main config file and can be set independently for reload-failed and reload-aborted emails.
The corresponding config settings are Butler.emailNotification.reloadTaskFailure.rateLimit
, Butler.emailNotification.reloadTaskAborted.rateLimit
and Butler.emailNotification.reloadTaskSuccess.rateLimit
.
Rate limiting is done based on task ID + email address.
Sending test emails to verify correct settings
It can be tricky to find the correct settings to use Butler with email servers.
Butler itself uses a very generic email components to send emails, but corporate email servers may impose restrictions on from where/what servers emails will be accepted, encryption may be used together with non-standard network ports etc.
Butler offers a command line option that when used will send a simple test email to the specified email address.
This makes is very easy to test if the email settings in Butler’s config file are working or not.
When this command line option is used Butler will start normally, but also send a test email during startup.
The command line option is --test-email-address <address>
.
The sender of the test email can be specified with --test-email-from-address <address>
.
If the settings in the config file’s Butler.emailNotification.smtp
section are valid and correct a command like this can be used:
butler.exe -c ./config/production.yaml --test-email-address myname@somedomain.com
. Adapt config file location and email address as needed.
The resulting email looks like this:
Sending alert emails to app owners
Butler can optionally send alert emails to the owner of apps that failed reloading/were aborted.
Note
App owner notification email can only be sent to app owners that have an email stored in their Qlik Sense user profile.
This is typically the case if the Qlik Sense user directory has been synced from a Microsoft Active Directory - but there is no guarantee this is the case.
If there is no email available for an app owner, he/she will simply not receive a notification email.
This feature is controlled by the config file properties Butler.emailNotification.reloadTaskAborted.appOwnerAlert.enable
and Butler.emailNotification.reloadTaskFailure.appOwnerAlert.enable
.
If set to true
the app owner will be added to the send list of alert emails, in addition to the recipients specied in Butler.emailNotification.reloadTaskAborted.recipients
and Butler.emailNotification.reloadTaskFailure.recipients
.
The sections of the config file dealing with app owner notification emails looks like this:
It works like this:
- If
appOwnerAlert.enable
is set tofalse
no app owner emails will be sent. If it’s set totrue
the rules below apply. - If
appOwnerAlert.includeOwner.includeAll
is set totrue
all app owners will get notification emails when apps the own fail/are aborted…- … except those app owners listed in the
appOwnerAlert.excludeOwner.user
array. - That array thus provides a way to exclude some app owners (e.g. system accounts) to receive notifcation emails.
- … except those app owners listed in the
- If
appOwnerAlert.includeOwner.includeAll
is set tofalse
it’s still possible to add individual app owners to theappOwnerAlert.includeOwner.user
array.
Those users will then receive notification emails for apps they own.
Send alerts only for some reload tasks
Some reload tasks may be more important than others.
I.e. some tasks should generate alert emails when they fail/abort/succeed, but others not.
Butler controls which tasks to send alerts for by looking at a specific Qlik Sense custom property.
Note
The concept described below is the same for failed, aborted and successful reload tasks.
Each of these three types of tasks have their own settings in the config file.
- If the config file setting
Butler.emailNotification.reloadTaskFailure.alertEnableByCustomProperty.enable
is set tofalse
, all failed reload tasks will cause alert emails. - If that setting is
true
only some tasks will cause alert emails:- If a task has the value specified in
Butler.emailNotification.reloadTaskFailure.alertEnableByCustomProperty.enabledValue
set for the custom property named as specified inButler.emailNotification.reloadTaskFailure.alertEnableByCustomProperty.customPropertyName
, the alert will be sent. - If a task does not have that custom property set, no alert will be sent for that task.
- A task can still cause an alert to be sent if a specific email address is specified for the task, see below for details.
- If a task has the value specified in
Some configuration is needed to make this work:
- Make changes to the config file. Specifically the three settings mentioned above needs to be reviewed and updated as needed.
- Create a custom property in Sense.
- The name and value of the custom property must match the one in the config file,
Butler.emailNotification.reloadTaskFailure.alertEnableByCustomProperty.customPropertyName
andButler.emailNotification.reloadTaskFailure.alertEnableByCustomProperty.enabledValue
. - The custom property should be available on reload tasks.
- The name and value of the custom property must match the one in the config file,
- Set the custom property for reload tasks for which alert emails should be sent.
Aborted reload tasks (as compared to the failed reload tasks described above) are handled the same way, with their own settings in the config file.
In the QMC the custom property can look like this:
Send alerts to specific people, for some tasks
It’s possible to send alert emails to specific email addresses and control this on a per-task basis.
This is achieved by using a Sense custom property that contains the email addresses alerts should be sent to, for the task in question.
Note
The concept described below is the same for failed, aborted and successful reload tasks.
Each of these three types of tasks have their own settings in the config file.
These config setting Butler.emailNotification.reloadTaskFailure.alertEnableByEmailAddress.customPropertyName
controls which custom property is used to store email addresses for failed reload tasks.
Email specific alert recpients is independent from the feature where alerts can be switched on/off for individual tasks (see above).
In other words: If an email address has been designated as recipient of alert emails, that address will always receive alert emails for all failed reload tasks.
Having set two different (blurred out) recipients of alert emails for a reload task:
Settings in config file
Warning
Don’t forget to create the log appender .xml files on the Sense server(s).
This page describes how.
Those xml files are the foundation on top of which all Butler reload task alerts are built - without them the alerts described on this page won’t work.
Templates: Configuring email appearance
Alert emails use standard HTML formatting. Inline CSS can be used (if so desired) for fine tuning the visual look of the alert email.
Butler’s process for sending alert emails is
- Figure out which email body template file should be used. This is determine by two set of fields in the main config file:
- For reload failure emails these config file properties are used:
Butler.emailNotification.reladTaskFailure.bodyFileDirectory
andButler.emailNotification.reladTaskFailure.htmlTemplateFile
- For aborted reload emails these config file properties are used:
Butler.emailNotification.reloadTaskAborted.bodyFileDirectory
andButler.emailNotification.reloadTaskAborted.htmlTemplateFile
- For reload failure emails these config file properties are used:
- For email subjects, these config properties are used:
Butler.emailNotification.reladTaskFailure.subject
andButler.emailNotification.reloadTaskAborted.subject
- Process the body template, replacing template fields with actual values.
- Process the email subject template, replacing template fields with actual values.
- Send the email.
A couple of sample template files are found in the src/config/email_templates
directory of the GitHub repository.
Remember
You can use template fields in email subjects too!Template fields reference
A complete list of template fields - including descriptions - is available in the Reference section.