Qlik Sense Cloud Configuration

To use Butler Sheet Icons with Qlik Sense Cloud, you'll need to set up API authentication and understand the cloud-specific features.

Prerequisites

Before configuring Butler Sheet Icons for QS Cloud, ensure you have:

• Access to a Qlik Sense Cloud tenant
• Permissions to create API keys in your tenant
• User credentials for logging into the web interface
• App IDs or collection IDs for the apps you want to update

API Key Setup

Butler Sheet Icons uses API keys to access QS Cloud APIs for app information and image uploads.

Creating an API Key

1. Navigate to API Keys:

   • Log into your Qlik Sense Cloud tenant
   • Go to your profile menu → Settings. You should now be looking at your personal profile page
   • Select "API Keys" from the sidebar

2. Generate New Key:

   • Click "Generate new API key"
   • Provide a descriptive name (e.g., "Butler Sheet Icons")
   • Set appropriate expiration timeframe
   • Copy the generated key immediately (you won't see it again!)

3. Verify Permissions:

   • Ensure your user account has access to the apps you want to update
   • For published apps, you can only update private sheet icons

API Key Security

Store your API key securely using environment variables or secure secret management tools. Never commit API keys to source code.

Using the API Key

You can provide the API key in several ways:

Command Line:

butler-sheet-icons qscloud create-sheet-icons --apikey your-api-key-here

Environment Variable (recommended):

export BSI_QSCLOUD_CST_APIKEY="your-api-key-here"
butler-sheet-icons qscloud create-sheet-icons

Login Credentials

Butler Sheet Icons needs web login credentials to access the Qlik Sense Cloud interface for taking screenshots.

Username/Password Method

For standard Qlik Sense Cloud accounts:

butler-sheet-icons qscloud create-sheet-icons \
  --logonuserid your-email@company.com \
  --logonpwd your-password

When Butler Sheet Icons connects to your QS Cloud tenant, you'll see a login page like this:

SSO Environments

If your organization uses Single Sign-On (SSO), you may need to use the --skip-login option:

butler-sheet-icons qscloud create-sheet-icons \
  --skip-login

--skip-login relies on the browser profile Butler Sheet Icons uses already being signed in to Qlik Sense Cloud. If it is not — most often because the session has expired — the run stops at the first app rather than capturing the login page; see If you use --skip-login on Qlik Sense Cloud.

SSO Compatibility

The --skip-login option is experimental and may not work with all SSO configurations. Test thoroughly in your environment.

Changed in BSI 5.3.0

• --logonuserid and --logonpwd are no longer needed with --skip-login. They used to be required even though they were never used. Given anyway, they are ignored with a warning; a future major release will refuse the combination, so remove them from the job. Without --skip-login, both are still required.
• BSI_QSCLOUD_CST_SKIP_LOGIN=false now turns skip-login off. Until 5.2.x, setting the variable to any value — false included — turned it on. Its value is now read: true, 1, yes or on mean on; false, 0, no, off or empty mean off; anything else stops the run with a message listing the accepted values. A job that has =false and still worked has been skipping login without meaning to, and now signs in with the credentials it is given. --skip-login false on the command line works the same way.

Tenant Configuration

Tenant URL Format

--tenanturl takes the host name of your tenant. From BSI 5.1.0 you can also paste the address with the scheme in front — both of these mean the same thing:

# Host name
--tenanturl mytenant.eu.qlikcloud.com

# Address with the scheme in front (5.1.0 and later)
--tenanturl https://mytenant.eu.qlikcloud.com

Butler Sheet Icons reads the value as a URL and keeps only the host name from it, so a leading https://, a trailing slash, and upper-case letters are all handled for you. The same applies wherever the value is supplied: on the command line, in BSI_QSCLOUD_*_TENANTURL, in a .env file, and in the interactive wizard.

Requires BSI 5.1.0 or later

In earlier versions --tenanturl https://mytenant.eu.qlikcloud.com was accepted by the startup connection test and then failed on the first app with error: CLOUD APP: getaddrinfo ENOTFOUND https. Only the bare host worked. See that symptom in Troubleshooting.

A complete page address is not a tenant URL. The address in your browser while you are looking at an app carries a path — .../sense/app/<id> — and that path is not part of the host, so it is refused at startup rather than quietly dropped:

error: option '--tenanturl <url>' argument 'https://mytenant.eu.qlikcloud.com/sense/app/x' is invalid. Enter the host on its own, for example "tenant.eu.qlikcloud.com" - a path is not part of it.

Give the host on its own; name the app with --appid instead.

App Selection Methods

Using Environment Variables to provide default values

The examples below assume environment variables have been set for all required parameters.

Single App Update

Update a specific app using its ID:

butler-sheet-icons qscloud create-sheet-icons \
  --appid 12345678-1234-1234-1234-123456789012

Collection-Based Updates

Update all apps in a collection:

butler-sheet-icons qscloud create-sheet-icons \
  --collectionid your-collection-id

To find collection IDs in a specific tenant, use:

butler-sheet-icons qscloud list-collections \
  --tenanturl your-tenant \
  --apikey your-api-key

Complete Configuration Example

Here's a complete configuration example using environment variables:

Environment Variables

export BSI_QSCLOUD_CST_TENANTURL="mytenant.eu.qlikcloud.com"
export BSI_QSCLOUD_CST_APIKEY="eyJhbGciOiJFUzM4NCIsImtpZCI6..."
export BSI_QSCLOUD_CST_LOGON_USER_ID="user@company.com"
export BSI_QSCLOUD_CST_LOGON_PWD="your-password"

# Optional
export BSI_QSCLOUD_CST_APP_ID="12345678-1234-1234-1234-123456789012"
export BSI_QSCLOUD_CST_COLLECTION_ID="collection-uuid"

Command Execution

# With environment variables set, minimal command needed
butler-sheet-icons qscloud create-sheet-icons

# Or with specific options that will override their environment variable counterparts
butler-sheet-icons qscloud create-sheet-icons \
  --pagewait 7 \
  --includesheetpart 2 \
  --exclude-sheet-status published \
  --headless true

Advanced Options

Image Settings

# Custom image directory
--imagedir ./my-screenshots

# Include sheet titles in thumbnails
--includesheetpart 2

# Full screen capture
--includesheetpart 4

Sheet Filtering

# Exclude specific sheets
--exclude-sheet-number 1 2
--exclude-sheet-title "Welcome" "Help"
--exclude-sheet-status published public

# Blur sensitive sheets
--blur-sheet-number 3 5
--blur-sheet-title "Financial Data"
--blur-factor 8

Status-based exclusion in QS Cloud

In published apps, only private sheets can be updated by BSI. To avoid permission errors when processing published apps, exclude public and published sheets:

Bash

butler-sheet-icons qscloud create-sheet-icons \
  --exclude-sheet-status public published

PowerShell

butler-sheet-icons qscloud create-sheet-icons `
  --exclude-sheet-status public published

:::

Browser Configuration

# Browser selection (chrome is the only accepted value)
--browser chrome

# Show browser (for debugging)
--headless false

# Longer page wait times
--pagewait 10

Troubleshooting

Common Issues

Login Failures:

• Verify credentials are correct
• Check if MFA is required (not currently supported)
• Try --skip-login for SSO environments

API Key Issues:

• Ensure key hasn't expired
• Verify key has necessary permissions
• Check tenant URL is correct

Permission Errors:

• Use appropriate --exclude-sheet-status options
• Verify your user has access to target apps
• Check app publication status

The general troubleshooting approach:

• Use --headless false to see the embedded browser that is used for login and app access.
• Seeing what is shown in the browser usually helps in understanding what is causing the issue.

Debug Mode

Enable verbose logging for troubleshooting:

butler-sheet-icons qscloud create-sheet-icons \
  --loglevel debug \
  --headless false

Next Steps

• Learn about sheet exclusion and blurring
• See practical examples
• Explore advanced CI/CD integration