This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

REST API documentation (alternative format)

Alternative documentation for the Butler API.
Butler API documentation
API docs by Redocly

Butler API documentation (9.4.0)

Download OpenAPI specification:Download

Butler is a microservice that provides add-on features to Qlik Sense Enterprise on Windows. Butler offers both a REST API and things like failed reload notifications etc.

This page contains the API documentation. Full documentation is available at https://butler.ptarmiganlabs.com

Butler family of tools on GitHub

Get an array of all enabled API endpoints.

Get an array of all enabled API endpoints, using the key names from the Butler config file.

Note: Endpoints are enabled/disabled in the Butler main configuration file.

Responses

Response samples

Content type
application/json
[
  • "activeUserCount",
  • "activeUsers",
  • "apiListEnbledEndpoints"
]

Converts strings from base62 to base16.

Converts strings from base62 to base16.

query Parameters
base62
required
string
Example: base62=6DMW88LpSok9Z7P7hUK0wv7bF

The base62 encoded string that should be converted to base16

Responses

Response samples

Content type
application/json
{
  • "base62": "6DMW88LpSok9Z7P7hUK0wv7bF",
  • "base16": "3199af08bfeeaf5d420f27ed9c01e74370077"
}

Converts strings from base16 to base62.

Converts strings from base16 to base62.

query Parameters
base16
required
string
Example: base16=3199af08bfeeaf5d420f27ed9c01e74370077

The base16 encoded string that should be converted to base62

Responses

Response samples

Content type
application/json
{
  • "base16": "3199af08bfeeaf5d420f27ed9c01e74370077",
  • "base62": "6DMW88LpSok9Z7P7hUK0wv7bF"
}

Tests if Butler is alive and responding

Tests if Butler is alive and responding

Responses

Response samples

Content type
application/json
{
  • "response": "Butler reporting for duty",
  • "butlerVersion": "5.5.0"
}

Copy file(s) between well defined, approved locations.

Copying of files is only posttible between pre-approved directories. Defining approved source and destination directories is done in Butler's config file.

If the source directory contains subdirectories, these will be copied too.

Request Body schema: application/json
fromFile
string

Name of source file.

toFile
string

Name of destination file. Can be different from source file name, if needed.

overwrite
boolean

Controls whether destination file should be overwritten if it already exists. Note that the copy operation will silently fail if you set this to false and the destination exists. Defaults to false.

preserveTimestamp
boolean

When true, the timestamp of the source file(s) will be preserved on the destination file(s). When false, timestamp behaviour is OS-dependent. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "fromFile": "subfolder/file1.qvd",
  • "toFile": "archive/file1_20200925.qvd",
  • "overwrite": false,
  • "preserveTimestamp": false
}

Response samples

Content type
application/json
{
  • "fromFile": "subfolder/file1.qvd",
  • "toFile": "archive/file1_20200925.qvd",
  • "overwrite": false,
  • "preserveTimestamp": false
}

Move file(s) between well defined, approved locations.

Moving of files is only posttible between pre-approved directories. Defining approved source and destination directories is done in Butler's config file.

If the source directory contains subdirectories, these will be moved too.

Request Body schema: application/json
fromFile
string

Name of source file.

toFile
string

Name of destination file. Can be different from source file name, if needed.

overwrite
boolean

Controls whether destination file should be overwritten if it already exists. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "fromFile": "subfolder/file1.qvd",
  • "toFile": "archive/file1_20200925.qvd",
  • "overwrite": false
}

Response samples

Content type
application/json
{
  • "fromFile": "subfolder/file1.qvd",
  • "toFile": "archive/file1_20200925.qvd",
  • "overwrite": false
}

Delete file(s) in well defined, approved locations.

It is only possible to delete files in pre-approved directories, or subdirectories thereof. Defining approved directories is done in Butler's config file.

Request Body schema: application/json
deleteFile
string

Name of file to be deleted. Use forward/backward slashes in paths as needed, depending on whether Butler runs on Windows/non-Windows platform.

Responses

Request samples

Content type
application/json
{
  • "deleteFile": "data/qvdstore/sales/file1.qvd"
}

Response samples

Content type
application/json
{ }

Creates a directory in designated QVD directory.

Creates a directory in QVD directory (which is defined in Butler's config file).

Request Body schema: application/json
directory
string

Directory that should be created.

Responses

Request samples

Content type
application/json
{
  • "directory": "subfolder/2020-10"
}

Response samples

Content type
application/json
{
  • "directory": "subfolder/2020-10"
}

Creates a directory anywhere in the file system.

If the directory already exists nothing will happen. If permissions don't allow a directory to be created, or if the path is invalid, an error will be returned.

Request Body schema: application/json
directory
string

Path to directory that should be created. Can be a relative or absolute path.

Responses

Request samples

Content type
application/json
{
  • "directory": "/Users/joe/data/qvds/2020"
}

Response samples

Content type
application/json
{
  • "directory": "/Users/joe/data/qvds/2020"
}

List all currently defined namespaces.

Responses

Response samples

Content type
application/json
[
  • "Weekly sales app",
  • "Sales ETL step 1",
  • "Sales ETL step 2"
]

Get the value associated with a key, in a specific namespace.

path Parameters
namespace
required
string
Example: Sales ETL step 2
query Parameters
key
required
string
Example: key=Last extract timestamp

Responses

Response samples

Content type
application/json
{
  • "namespace": "Sales ETL step 2",
  • "key": "Last extract timestamp",
  • "value": "2020-09-29 17:14:56"
}

Create a new key-value pair in the specified namespace.

If the specified key already exists it will be overwritten.

If the posted data has a TTL, it will start counting when the post occur. I.e. if a previouly posted key also had a TTL, it will be replace with the most recent TTL.

path Parameters
namespace
required
string
Example: Sales ETL step 2

Name of namespace.

Request Body schema: application/json
key
string

Key to use

value
string

Value to set

ttl
number

Time to live = how long (milliseconds) the key-value pair should exist before being automatically deleted

Responses

Request samples

Content type
application/json
{
  • "key": "ce68c8ca-b3ff-4371-8285-7c9ce5040e42_parameter_1",
  • "value": "12345.789",
  • "ttl": 10000
}

Response samples

Content type
application/json
{
  • "namespace": "Sales ETL step 2",
  • "key": "Last extract timestamp",
  • "value": "2020-09-29 17:14:56",
  • "ttl": 60000
}

Delete a namespace and all key-value pairs in it.

path Parameters
namespace
required
string
Example: Sales ETL step 2

Name of namespace.

Responses

Response samples

Content type
application/json
""

Checks if a key exists in a namespace.

Returns true if the specified key exists, otherwise false.

path Parameters
namespace
required
string
Example: Sales ETL step 2
query Parameters
key
required
string
Example: key=Last extract timestamp

Responses

Response samples

Content type
application/json
{
  • "keyExists": true,
  • "keyValue": {
    }
}

Delete a key-value pair in a specific namespace.

path Parameters
namespace
required
string
Example: Sales ETL step 2

Name of namespace.

key
required
string
Example: ce68c8ca-b3ff-4371-8285-7c9ce5040e42_parameter_1

Key to use

Responses

Response samples

Content type
application/json
""

Retrieve a list of all keys present in the specified namespace.

path Parameters
namespace
required
string
Example: Sales ETL step 2

Name of namespace whose keys should be returned.

Responses

Response samples

Content type
application/json
{
  • "namespace": "Sales ETL step 2",
  • "keys": [
    ]
}

Publish a message to a MQTT topic.

Request Body schema: application/json
required
topic
required
string

Topic to which message should be published.

message
required
string

The message is a generic text string and can thus contain anything that can be represented in a string, including JSON, key-value pairs, plain text etc.

Responses

Request samples

Content type
application/json
{
  • "topic": "qliksense/new_data_notification/sales",
  • "message": "dt=20201028"
}

Response samples

Content type
application/json
{
  • "topic": "qliksense/new_data_notification/sales",
  • "message": "dt=20201028"
}

Post events to New Relic.

This endpoint posts events to the New Relic event API.

Request Body schema: application/json
required
eventType
required
string <= 254 characters

Event type. Can be a combination of alphanumeric characters, _ underscores, and : colons.

timestamp
number

The event's start time in Unix time. Uses UTC time zone. This field also support seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and query. Events reported with a timestamp older than 48 hours ago or newer than 24 hours from the time they are reported are dropped by New Relic. If left empty Butler will use the current time as timestamp.

Array of objects

Dimensions/attributs that will be associated with the event.

Responses

Request samples

Content type
application/json
{
  • "eventType": "relead-failed",
  • "timestamp": 1642164296053,
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "newRelicResultCode": "202",
  • "newRelicResultText": "Data accepted."
}

Post metrics to New Relic.

This endpoint posts metrics to the New Relic metrics API.

Request Body schema: application/json
required
name
required
string <= 254 characters

Metric name.

type
required
string
Value: "gauge"

Metric type.

value
required
number

Value of the metric.

timestamp
number

The metric's start time in Unix time. Uses UTC time zone. This field also support seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and query. Metrics reported with a timestamp older than 48 hours ago or newer than 24 hours from the time they are reported are dropped by New Relic. If left empty Butler will use the current time as timestamp.

interval
number

The length of the time window (millisec). Required for count and summary metric types.

Array of objects

Dimensions that will be associated with the metric.

Responses

Request samples

Content type
application/json
{
  • "name": "memory.heap",
  • "type": "gauge",
  • "value": 2.3,
  • "timestamp": 1642164296053,
  • "interval": 0,
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "newRelicResultCode": "202",
  • "newRelicResultText": "Data accepted."
}

Get all information available for existing schedule(s).

If a schedule ID is specified using a query parameter (and there exists a schedule with that ID), information about that schedule will be returned. If no schedule ID is specified, all schedules will be returned.

query Parameters
id
string
Example: id=e4b1c455-aa15-4a51-a9cf-c5e4cfc91339

Scheduld ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new schedule.

Request Body schema: application/json
required
name
required
string

Descriptive name for the schedule.

cronSchedule
required
string

5 or 6 position cron schedule.

If 6 positions used, the leftmost position represent seconds. If 5 positions used, leftmost position is minutes.

The example schedule will trigger at 00 and 30 minutes past 6:00 on Mon-Fri.

timezone
required
string

Time zone the schedule should use. Ex "Europe/Stockholm".

qlikSenseTaskId
required
string

ID of Qlik Sense task that should be started when schedule triggers.

startupState
required
string
Enum: "start" "started" "stop" "stopped"

If set to "start" or "started", the schedule will be started upon creation. Otherwise it will remain in stopped state.

tags
Array of strings

Can be used to categorise schedules.

Responses

Request samples

Content type
application/json
{
  • "name": "Reload sales metrics",
  • "cronSchedule": "0,30 6 * * 1-5",
  • "timezone": "Europe/Stockholm",
  • "qlikSenseTaskId": "210832b5-6174-4572-bd19-3e61eda675ef",
  • "startupState": "started",
  • "tags": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete a schedule.

path Parameters
scheduleId
required
string
Example: e4b1c455-aa15-4a51-a9cf-c5e4cfc91339

Schedule ID.

Responses

Response samples

Content type
application/json
""

Start a schedule.

Start a schedule, i.e. have the scheduler run the associated reload task according to the schedule's cron settings.

path Parameters
scheduleId
required
string
Example: e4b1c455-aa15-4a51-a9cf-c5e4cfc91339

Schedule ID.

Responses

Response samples

Content type
application/json
{
  • "id": "e4b1c455-aa15-4a51-a9cf-c5e4cfc91339",
  • "created": "2020-09-29T14:29:12.283Z",
  • "name": "Reload sales metrics",
  • "cronSchedule": "0,30 6 * * 1-5",
  • "timezone": "Europe/Stockholm",
  • "qlikSenseTaskId": "210832b5-6174-4572-bd19-3e61eda675ef",
  • "startupState": "started",
  • "tags": [
    ],
  • "lastKnownState": "started"
}

Start all schedules.

Start all schedules, i.e. tell the scheduler to run each schedule and start associated tasks according to each schedule's settings.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stop a schedule.

Stop a schedule, i.e. tell the scheduler to no longer execute the schedule according to its cron settings.

path Parameters
scheduleId
required
string
Example: e4b1c455-aa15-4a51-a9cf-c5e4cfc91339

Schedule ID.

Responses

Response samples

Content type
application/json
{
  • "id": "e4b1c455-aa15-4a51-a9cf-c5e4cfc91339",
  • "created": "2020-09-29T14:29:12.283Z",
  • "name": "Reload sales metrics",
  • "cronSchedule": "0,30 6 * * 1-5",
  • "timezone": "Europe/Stockholm",
  • "qlikSenseTaskId": "210832b5-6174-4572-bd19-3e61eda675ef",
  • "startupState": "started",
  • "tags": [
    ],
  • "lastKnownState": "started"
}

Stop all schedules.

Stop all schedules, i.e. tell the scheduler to no longer execute any schedule according to its cron settings.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get scheduler status.

Get basic status from the core scheduler.

No schedule metadata beyond ID, cron setting and job state will be returned, but as this comes from the core scheduler it is the authorative truth about what jobs are running (and which ones are not).

Responses

Response samples

Content type
text/plain
{
'3702cec1-b6c8-463e-bda3-58d6a94dd9ac': * */2 * * * status: Running 
'2d5dcebc-2440-4bd7-9aa1-fb69708715c8': */45 * * * * * status: Running 
'a93ca0f3-7980-439b-9eda-723a167352e3': */10 * * * * * status: Running 
'ad250f49-ffd8-45dc-9b2b-f76028e969a4': */5 * * * * * status: Running 
}

Do a stand-alone reload of a Qlik Sense app, without using a task.

path Parameters
appId
required
string
Example: 210832b5-6174-4572-bd19-3e61eda675ef

ID of Qlik Sense app.

Request Body schema: application/json
reloadMode
integer

Reload mode that will be used. 0, 1 or 2. If not specified 0 will be used

partialReload
boolean

Should a full (=false) or partial (=true) reload be done? If not specified a full reload will be done.

startQSEoWTaskOnSuccess
Array of strings

Array of task IDs that should be started when the app has successfully reloaded.

startQSEoWTaskOnFailure
Array of strings

Array of task IDs that should be started if the app fails reloading.

Responses

Request samples

Content type
application/json
{
  • "reloadMode": 0,
  • "partialReload": true,
  • "startQSEoWTaskOnSuccess": [
    ],
  • "startQSEoWTaskOnFailure": [
    ]
}

Response samples

Content type
application/json
{
  • "appId": "210832b5-6174-4572-bd19-3e61eda675ef"
}

Dump a Sense app to JSON.

Does the same thing as /v4/app/:appId/dump

path Parameters
appId
required
string
Example: 210832b5-6174-4572-bd19-3e61eda675ef

ID of Qlik Sense app.

Responses

Response samples

Content type
application/json
{
  • "properties": { },
  • "loadScript": "",
  • "sheets": [ ],
  • "stories": [ ],
  • "masterobjects": [ ],
  • "appprops": [ ],
  • "dataconnections": [ ],
  • "dimensions": [ ],
  • "bookmarks": [ ],
  • "embeddedmedia": [ ],
  • "snapshots": [ ],
  • "fields": [ ],
  • "variables": [ ],
  • "measures": [ ]
}

Dump a Sense app to JSON.

Does the same thing as /v4/senseappdump/:appId

path Parameters
appId
required
string
Example: 210832b5-6174-4572-bd19-3e61eda675ef

ID of Qlik Sense app.

Responses

Response samples

Content type
application/json
{
  • "properties": { },
  • "loadScript": "",
  • "sheets": [ ],
  • "stories": [ ],
  • "masterobjects": [ ],
  • "appprops": [ ],
  • "dataconnections": [ ],
  • "dimensions": [ ],
  • "bookmarks": [ ],
  • "embeddedmedia": [ ],
  • "snapshots": [ ],
  • "fields": [ ],
  • "variables": [ ],
  • "measures": [ ]
}

Get a list of all apps in Sense environment.

Does the same thing as /v4/apps/list

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of all apps in Sense environment.

Does the same thing as /v4/senselistapps

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start a Qlik Sense task.

An optional array of zero or more objects can be passed in the message body. It is used to pass additional info related to the reload task being started.

Currently supported values in this array are:

  • A key-value pair that will be stored in Butler's KV store. If Butler's key-value store is not enabled, any key-value information passed in this parameter will simply be ignored. Setting ttl=0 disables the TTL feature, i.e. the KV pair will not expire.
  • A task identified by its taskId that should be started.
  • Tasks identified by tags set on tasks in the QMC.
  • Tasks identified by custom properties set in the QMC.

This parameter uses a generic JSON/object format (type + payload). It's thus possible to add new integrations in future Butler versions.

path Parameters
taskId
required
string
Example: 210832b5-6174-4572-bd19-3e61eda675ef

ID of Qlik Sense task. Butler will ignore the "magic" task ID of "-" (=dash, hyphen). This ID will not be reported as invalid.

query Parameters
allTaskIdsMustExist
boolean
Example: allTaskIdsMustExist=true

If set to true, all specified taskIds must exist. If one or more taskIds does not exist in the Sense server, no tasks will be started.

If set to false, all existing taskIds will be started. Missing/invalid taskIds will be ignored.

In either case, missing/invalid taskIds will be reported in the result set back to the client calling the API.

Note: Tasks started by specifying tags and/or custom properties are not affected by this.

Request Body schema: application/json

Optional object with extra info.

Array
type
string
Enum: "keyvaluestore" "starttaskid" "starttasktag" "starttaskcustomproperty"
payload
object

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "tasksId": {
    },
  • "tasksTag": [
    ],
  • "tasksTagDenied": [
    ],
  • "tasksCP": [
    ],
  • "tasksCPDenied": [
    ]
}

Start a Qlik Sense task.

An optional array of zero or more objects can be passed in the message body. It is used to pass additional info related to the reload task being started.

Currently supported values in this array are:

  • A key-value pair that will be stored in Butler's KV store. If Butler's key-value store is not enabled, any key-value information passed in this parameter will simply be ignored. Setting ttl=0 disables the TTL feature, i.e. the KV pair will not expire.
  • A task identified by its taskId that should be started.
  • Tasks identified by tags set on tasks in the QMC.
  • Tasks identified by custom properties set in the QMC.

This parameter uses a generic JSON/object format (type + payload). It's thus possible to add new integrations in future Butler versions.

path Parameters
taskId
required
string
Example: 210832b5-6174-4572-bd19-3e61eda675ef

ID of Qlik Sense task. Butler will ignore the "magic" task ID of "-" (=dash, hyphen). This ID will not be reported as invalid.

query Parameters
allTaskIdsMustExist
boolean
Example: allTaskIdsMustExist=true

If set to true, all specified taskIds must exist. If one or more taskIds does not exist in the Sense server, no tasks will be started.

If set to false, all existing taskIds will be started. Missing/invalid taskIds will be ignored.

In either case, missing/invalid taskIds will be reported in the result set back to the client calling the API.

Note: Tasks started by specifying tags and/or custom properties are not affected by this.

Request Body schema: application/json

Optional object with extra info.

Array
type
string
Enum: "keyvaluestore" "starttaskid" "starttasktag" "starttaskcustomproperty"
payload
object

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "tasksId": {
    },
  • "tasksTag": [
    ],
  • "tasksTagDenied": [
    ],
  • "tasksCP": [
    ],
  • "tasksCPDenied": [
    ]
}

Send message to Slack.

Sends a basic message to Slack.

Request Body schema: application/json
required
channel
required
string

Slack channel to post message into. Prefix channel name with #.

from_user
required
string

Name of sending user, as shown in the Slack message

msg
required
string

Text going into the Slack message

emoji
string

Emoji to shown next to Slack message

Responses

Request samples

Content type
application/json
{
  • "channel": "#reload-notification",
  • "from_user": "Butler the Bot",
  • "msg": "This is a message from Qlik Sense",
  • "emoji": "thumbsup"
}

Response samples

Content type
application/json
{
  • "channel": "#reload-notification",
  • "from_user": "Butler the Bot",
  • "msg": "This is a message from Qlik Sense",
  • "emoji": "thumbsup"
}