Documentation

Tip

Upgrading from an earlier version of Butler?

General guidance on how to do this is found here.

What’s new in version 8.3.3

Bug Fixes

  • API endpoint /v4/schedules/status now respects enable/disable in config file #509
  • Incorrect return value from base conversion API endpoint #508

Other

  • Migrate to Fastify 4 #510
  • Upgrade internal API docs to use OpenAPI 3.x #511

What’s new in version 8.3.2

Bug Fixes

  • Update template config file wrt sending data to multiple New Relic accounts #505

What’s new in version 8.3.1

Bug Fixes

  • Add missing API endpoint docs to HTML/YAML/JSON API documents #502
  • Fix broken macOS build

What’s new in version 8.3.0

NOTE: There is no macOS binary for this version.

Features

  • Send Butler metrics and failed/aborted reloads as New Relic events and/or logs to zero, one or more New Relic accounts #489

Other

  • Enforce code style across all files #497
  • Update dependencies

What’s new in version 8.2.0

Features

  • Add failed/aborted reload task and app tags as metadata for New Relic events and logs #479
  • Add optional “from” option when sending test email #486

Bug fixes

  • Add better debug logging around which email addresses are used when sending alert emails #487
  • Back slash in script log breaks Slack and Teams messages #485
  • Better debug logging when posting data to New Relic

Other

  • deps: Updated dependencies

What’s new in version 8.1.0

Features

  • API endpoint for sending events to New Relic #441

Bug fixes

  • Incorrect New Relic API url used when posting metrics via Butler’s REST API #468
  • No more errors when empty New Relic metrics attribute/header arrays in config file #467

What’s new in version 8.0.1

Bug fixes

  • Empty attribute arrays in New Relic config no longer cause errors #640

What’s new in version 8.0.0

⚠️ Breaking changes

  • Forward script logs for failed and aborted reloads to New Relic.
    This required a change in structure/format of Butler’s config file #460

Features

  • Command line option for sending test email #430

Bug fixes

  • Update dependencies to stay sharp and secure.

What’s new in version 7.5.1

Bug fixes

  • Disable sending alerts to New Relic in sample config file #452
  • Disable API-generate-doc setting in sample config file #455

What’s new in version 7.5

Features

  • Automatic cration of API docs as part of CI pipeline #444, #355

What’s new in version 7.4

Features

  • Enable/disable alert emails per reload task. #385, #355
  • Base alert email rate limits on taskId + email address combination instead of just taskId. #424
  • Add config setting to enable create-API-docs-mode. #447
  • API endpoint for sending gauge metrics to New Relic. #440

Bug fixes

  • API docs REST endpoint doesn’t work for pre-built binaries #443
  • Change name of New Relic event for failed and aborted reload tasks. #418
  • Change New Relic metric names for Butler uptime metrics. #419
  • Verify that Slack/Teams message template file exists before opening them. #427

Other

  • Change Butler’s log prefixes for failed reloads across all notification channels. #425
  • Make source code file names consistent throughout Butler. #422
  • Update dependencies to stay sharp and secure.

What’s new in version 7.3

Features

  • Send Butler memory and uptime metrics to New Relic. #398
  • Send failed/aborted task events to New Relic. #400
  • Add rate limiting to Butler’s REST API. #403

Bug fixes

  • Better parsing of Sense log files before sent to Teams/Slack. #408
  • Include Signl4 status in telemetry data. #402
  • Incorrect telemetry status (true/false) for uptime data sent to InfluxDB. #401

Other

  • Update dependencies to stay sharp and secure.
  • Now using Node.js v18 when building Docker images.

What’s new in version 7.2

Features

  • Create stand-alone binaries to make it easier to get started with Butler. No need to install Node.js any more, just download Butler, configure it and run. #383
  • Make a few important config options available as command line parameters. Specifically, the config file to use and the log level can be specified via command line options --configfile and --loglevel, respectively. #381
  • Store full reload logs for failed reload tasks to disk, for easier analysis at later time. #94

Bug fixes

  • Better error checking when calling Qlik Sense APIs. #386
  • Clean up Docker image and release ZIP files. #361
  • Better handling of long script logs in notifications sent to MS Teams. #389
  • Better handling of long script logs in notifications sent to Slack. #388

Other

What’s new in version 7.1

Features

  • Add control of what tasks can be started via Butler’s REST API. Also known as “task filtering”. #284
  • api: Verify that task IDs are valid (both that they are valid guids and that they exist in Sense) before trying to start the associated tasks. #319
  • Refactor API for starting tasks. Add magic task guid “-” that can be used as URL parameter when all task IDs (and other parameters) are passed in via the message body. #326
  • Show URL to API docs/Swagger page on Butler startup. #317

Bug fixes

  • api: API calls with http “Expect” header no longer fails. #322
  • Increase timeout in API test cases from 5 to 15 seconds. This gets rid of occasional timeouts in the test suite. #329
  • Use correct return body format in API docs. #330
  • Use correct return body format in scheduler API docs. #331

Other

  • Various documentation updates, both relating to new features and typos in previous docs. #332, #335
  • Updated dependencies to latest versions to keep Butler safe and secure.
  • Document all test cases. #328
  • Add test cases for Expect: 100-continue header. #323
  • Add test cases for start task API. #320
  • Replace deprecated later library with @breejs/later. #280

What’s new in version 7.0

⚠️ Breaking changes

  • Make property names returned from reloadtask call consistent. #279
  • Incorrect return code when creating schedule. #277
  • Remove session/connection monitoring feature. These features have been moved to the Butler SOS tool. #254
  • Return 201 + appId in body, to better align with REST API best practices. #267
  • Return 201 vs 200 after creating KV entry, to better align with REST API best practices. #264

Other changes

Features

  • Graduate Signl4 (incident mgmt tool) integration from beta to released.
  • Add API endpoint to get low-level scheduler status. #269
  • Add API for starting/stopping all schedules. #261
  • Add CI test cases for all API endpoints. #271

Bug fixes

  • Consistent re-write of remoteIp in http response. #256
  • Consistent return body when starting task. #266
  • Correct error msg when getting app owner. #181
  • Docker healthcheck working again. #255
  • File copy/move APIs now respect options preserveTimestamp and overwrite. #263
  • Return proper JSON from successful API calls. Refactoring the API code in v6.0 introduced a bug, causing empty responses from successful calls to some API endpoints. #260
  • Sort API endpoints in docs alphabetically. #268

Other

  • Various documentation updates
  • Updated dependencies to latest versions to keep Butler safe and secure
  • Applied consistent source code formatting across the entire project

What’s new in version 6.1

  • Fixed too verbose logging of calls to the REST API. #240
  • Add POST variant of start task API endpoint. #185
  • Start multiple tasks with a single API call. #183
  • Start all tasks that have a certain Qlik Sense task set. #243
  • Start all tasks that have a certain Qlik Sense custom property set to a specific value. #244
  • Fix bug that caused starting tasks to fail in previous version of Butler. #241
  • Change logging so that the IP of the client calling the REST API is logged, instead of the IP of the host where Butler is running. #242
  • Update dependencies.

What’s new in version 6.0

  • ⚠️ Breaking change: Changed http response codes for some REST API endpoints, where those were not following general best practices. #210, #216
  • ⚠️ Breaking change: Fixed bug where MQTT message parameters were taken from URL instead of from the body of the API call. #217
  • Total re-write of the entire REST API. #208, #211, #213
  • Add Butler version number in response from ping endpoint. #209
  • New, more flexible, reliable and scalable process (using GitHub Actions) for building Docker images. #77, #187
  • Include more info in error messages from the REST API. #224
  • Make validation of Qlik Sense certificates optional. #192
  • Fixed bug where key-value namespace wasn’t properly deleted even when instructed to do this via REST API. #222

What’s new in version 5.4

What’s new in version 5.3

  • Added a new API endpoint for listing all keys in a key-value namespace.  #150.
  • Fixed a bug where Butler would not start properly if there were empty config sections in the YAML config file. Butler is now more tolerant against slightly incorrectly formatted config files. #152.

What’s new in version 5.2

  • It’s now possible to include zero or more (i.e. optional) key-value pairs when starting QSEoW reload tasks using the /v4/reloadtask/{taskId}/start REST endpoint.
    There are also helper subs available in the demo app included in the GitHub repository - as well as in the online docs at butler.ptarmiganlabs.com. (#147, #148)

What’s new in version 5.1

  • First version of telemetry added to Butler (#142). More info here.
  • Fixed bug #143.
  • Show high level system info when starting Butler (#140).
  • Don’t waste memory when MQTT is not used: Fixed #139.
  • Refined the documentation, fixed typos and updated dependencies. The usual stuff that comes with every release.

What’s new in version 5.0

  • Greatly improved failed reload notifications for both MS Teams and Slack.
    Task failure alerts for these channels now use the same advanced templating solution that’s already available for Butler’s email notifications. This is in many ways a milestone as it brings a new level of reload alerts to Qlik Sense Enterprise.
    The downside is that the Slack and Teams settings in Butler’s config file have been changed in a breaking way - make sure to update the config file as needed when upgrading Butler.
    Due to the breaking nature of the config file changes, the version number was bumped to 5.0 rather than 4.4.
  • Added a new API endpoint for doing app reloads. Both full and partial reloads are supported. When the app has reloaded, a one or more reload tasks can be started based on whether the app reload completed successfully or not.
  • Added new API endpoints for listing all apps in the Sense server, as well as extracting metadata for a specific app. Those features have been available in Butler for many years, they just get a couple of new endpoints that better align with Butler’s current API naming standard.
  • Refined user session monitoring. The previous XML appender file provided by Butler was too generous and passed on too many user activity events to Butler. The new appender files provide a tighter/more relevant filtering and only returns session start/stop events to Butler (from which this info can be sent to Slack or MS Teams).

What’s new in version 4.3

  • Fixed a bug that in some cases prevented Sense reload tasks from being started using Butler’s API.
  • Added instruction for creating the data connections needed to use Butler APIs from Sense load scripts.
  • Added concept page explaining how Butler can be used to copy/move/delete files from load scripts.
  • Added example page showing how file manipulation (copy/move/delete) is done from Sense scripts, using Butler’s APIs.

What’s new in version 4.2

  • Email reload alerts taken to a new level. Emails are created using template files, with full support for HTML formatting, emoji support in both email subject/body etc.
    This makes it possible to create nice looking alert emails that contain just the information you need, while also conforming to corporate design, colors etc.
  • Alert emails can be set up for either failed scheduled reloads, or running reloads that are stopped from the QMC or via APIs. Or both.
  • More than 40 templating fields available, including task history (what steps the task has been through), beginning and end of reload script log, app/task metadata, 5+ date formats and more.
  • Template fields can be used in both subject and body of email.
  • Rate limiter that prevents email spamming for frequently failing tasks.

What’s new in version 4.1

  • The REST API now lets you copy files in a controlled, secure way. Version 4.0 added similar features for file moving and deletes, so copying is a natural complement.

What’s new in version 4.0

  • An advanced scheduler that makes it possible to trigger reloads in Sense in a much more flexible way, compared to the scheduler available in the Qlik Sense QMC. It’s essentially Cron for Qlik Sense.

  • A generic key-value store can be used to send parameters between reload tasks. The reload script of the first task stash it’s parameters away in the KV store, and the following task(s) pull the parameters from the store.
    KV pairs can optionally also have a time-to-live (TTL) value. This can be an easy way to keep the KV store clean and tidy, or as a way to tell Sense apps that they are reloading within x hours of some event happening, for example.
    Key-value stores are a very versatile tool and a great addition to Qlik Sense.

  • Moving and deleting files in the file system of the Sense servers, or on any disks accessible by those servers. You customize what directories are approved for these operations, and thus prevent this feature from becoming a security risk.

  • Reload failure notifications can now be sent to Microsoft Teams, in addition to Slack and as email.

  • Better logging, including continuous logging of Butler’s own memory usage to InfluxDB, from where it can be graphed using for example Grafana.

  • API docs using the OpenAPI/Swagger format.

  • A totally re-engineered REST API that now better follows best practices when to use GET/POST/PUT/DELETE. Previously everything was done using GETs… which was really ugly. The downside is that this is a major breaking change! Please review the API docs for details.


About

Information about the Butler software, community, docs and more.

Are you stuck on something while setting up Butler? Got ideas for new features?
Don’t hesitate to post your thoughts in the Butler forums.

Getting started

What you need to know to get Butler off the ground.

Concepts

Deep dive into the various components that make up Butler.

Examples

Butler in action!

Reference docs

Detailed, more technical descriptions of Butler’s REST API and other parts of Butler.

Security considerations

Security is important! Keep these things in mind when deploying Butler.

Legal stuff

Information om licenses, personal integrity and more.


Last modified 2022-06-22: Docs for Butler 8.3.3 (2969dbb)