What’s this?
Butler can send two kinds of alert messages via Teams:
- When an app fails during reload.
See the Concepts section for additional details.
A complete reference to the config file format is found here.
Basic vs formatted Teams alerts
Teams alerts come in two forms:
- Customizable formatting using a template concept. A standard template that will fit most use cases is included with Butler. With this option the first and last parts of the script log can be included in the message, allowing you to tell from the Teams message what caused the reload to fail.
You can also add buttons to the message that can be used to open any URL you want, or open the app that failed reloading. - A fixed, more basic format that is built into Butler. No template file needed, but also less detailed.
Which option to go for depends on whether you want just a notification that something went wrong, or if you want as much detail as possible in the Teams message. In most cases the customizable formatting is the best option.
Sample message with custom formatting
An “app reload failed” Teams message using the custom formatting option could look like this:
Here’s how to set it up:
-
Create a workflow in Teams, take note of its URL (you will need it in step 2 below). More information on how to create a Teams workflow in the Concepts section.
-
Edit the Teams section of the config file, i.e. the settings in
Butler.qlikSenseCloud.event.mqtt.tenant.alert.teamsNotification.reloadAppFailure.The
messageTypeproperty should be set toformatted.
ThebasicMsgTemplateproperty is not used with formatted messages and can thus be left empty, -
Edit the template file if/as needed, the file is specified in
Butler.qlikSenseCloud.event.mqtt.tenant.alert.teamsNotification.reloadAppFailure.templateFile.It uses the Handlebars templating engine, to which Butler provides template fields with actual values.The available template fields are described here.
Sample template files are included in the release Zip file, and are also available in the GitHub repository’s src/config/teams_templates directory.
-
Restart Butler if it’s already running.
Sample message with basic formatting
A “reload task failed” Teams message with basic formatting could look like this:
To set it up:
-
Create a workflow in Teams if you don’t already have one, take note of its URL (you will need it in step 2 below).
-
Edit the Teams section of the config file i.e.
Butler.qlikSenseCloud.event.mqtt.tenant.alert.teamsNotification.reloadAppFailure.The
messageTypeproperty should be set tobasic.
ThebasicMsgTemplateproperty is the message that will be sent via Teams. Template fields can be used. -
Restart Butler if it’s already running.
Customizing Teams messages
When using the formatted Teams alerts you have full freedom to create the alert you need.
Behind the scenes Teams messages are constructed as “Adaptive Cards”, which is standardised JSON format that Teams understands.
More information on Adaptive Cards can be found here, here and here.
When it comes to Butler, it uses the Handlebars templating engine to render a template file into an adaptive card JSON object that is then sent to the workflow webhook.
A few things to keep in mind when creating custom Teams messages:
- The handlebars syntax itself must be correct. If incorrect no Teams JSON object will be created. And no Teams message sent.
- The handlebars template must result in a JSON object that adheres to Teams’s specifications for JSON payloads.
If the JSON syntax is somehow invaid the Teams API will return errors and no messages sent. JSON can be pretty sensitive to details, there should for example not be any trailing commas in properly formatted JSON objects.
Using custom links in templates
It is also possible to define custom links in the config file, and use them in Teams templates.
This is described here: Custom links in alerts.
How it works
The concept is the same for all alert types, see the this page for details.
Settings in config file
---
Butler:
...
...
mqttConfig:
enable: false # Should Qlik Sense events be forwarded as MQTT messages?
...
...
qlikSenseCloud: # MQTT settings for Qlik Sense Cloud integration
event:
mqttForward: # QS Cloud events forwarded to MQTT topics, which Butler will subscribe to
enable: false
broker: # Settings for MQTT broker to which QS Cloud events are forwarded
host: mqttbroker.company.com
port: <port>
username: <username>
password: <password>
topic:
subscriptionRoot: qscloud/# # Topic that Butler will subscribe to
appReload: qscloud/app/reload
...
...
qlikSenseCloud: # Settings for Qlik Sense Cloud integration
enable: false
event:
mqtt: # Which QS Cloud tenant should Butler receive events from, in the form of MQTT messages?
tenant:
id: tenant.region.qlikcloud.com
tenantUrl: https://tenant.region.qlikcloud.com
authType: jwt # Authentication type used to connect to the tenant. Valid options are "jwt"
auth:
jwt:
token: <JWT token> # JWT token used to authenticate Butler when connecting to the tenant
# Qlik Sense Cloud related links used in notification messages
qlikSenseUrls:
qmc: <URL to QMC in Qlik Sense Cloud>
hub: <URL to Hub in Qlik Sense Cloud>
comment: This is a comment describing the tenant and its settings # Informational only
alert:
# Settings for notifications and messages sent to MS Teams
teamsNotification:
reloadAppFailure:
enable: false
alertEnableByTag:
enable: false
tag: Butler - Send Teams alert if app reload fails
basicContentOnly: false
webhookURL: <URL to MS Teams webhook>
messageType: formatted # formatted / basic
basicMsgTemplate: 'Qlik Sense Cloud app reload failed: "{{appName}}"' # Only needed if message type = basic
rateLimit: 15 # Min seconds between emails for a given appId. Defaults to 5 minutes.
headScriptLogLines: 15
tailScriptLogLines: 15
templateFile: /path/to/teams_templates/failed-reload-qscloud-workflow.handlebars
...
...