Skip to main content

Vizlib Writeback Table Guides - Integration Setup - S3

If you're using Vizlib Writeback Table with Vizlib Server, you can store the attachment files of a Writeback destination in an Amazon S3 bucket or in an S3-compatible store instead of a Postgres database. To do this, you'll need to set up and select an Integration. Integrations allow you to connect Vizlib products with your existing solutions (e.g. an email server or a database) to improve data sharing and collaboration. Integrations are configured in the Vizlib Management Console (VMC).

Users see no difference in the Qlik Sense app. File details (name, size, and who uploaded it) stay in the Vizlib Server database, and only the file contents are stored in S3. Browsers never connect to S3: every upload and download goes through Vizlib Server, so the bucket needs no public access, no CORS configuration and no presigned URLs.

Note: Attachments in S3 require a Collaboration license. Existing destinations keep their Postgres storage, and there is no tool to move files from Postgres to S3. Attachments are still not available in Plug and Play mode.

This topic contains the following sections:

Before you Start - Checklist

Before you add an integration, make sure you have all the information and permissions you need. Work through all the items in this list and then you'll be ready to start.

  • Installations - Vizlib Writeback Table and Vizlib Server should be installed before you start. We have online tutorials for installing Vizlib Server and Vizlib Products to help you (Vizlib Products are all installed in the same way, so while the tutorial uses Vizlib Library, it can also be used for Vizlib Writeback Table).

    Note: If you haven't installed any Vizlib products before, please install the product (Vizlib Writeback Table) then install Vizlib Server. If you have already installed Vizlib Server, please perform a restart after installing Vizlib Writeback Table.

  • Collaboration license - required to store attachments in S3.

  • VMC login / Password - to create and configure the integration and the writeback destination. The VMC is installed as part of Vizlib Server.

  • AWS account permissions - to create the bucket, the lifecycle rules, and the IAM policy and user or role. If you're using an S3-compatible store, you'll need the equivalent permissions for your store.

  • S3 account information (Bucket name, Region, and for S3-compatible stores, the Endpoint) - to enter when you're adding the integration.

  • Credentials - an access key id and secret access key, or a server that can use the default credential chain (see Choosing How Vizlib Signs In).

  • Key pattern - to decide where each attachment is stored in the bucket (see Key Pattern).

  • Writeback destination - the destination you want to store attachments for. For more information on adding a destination, see our article here.

  • Integration rights - the destination owner needs manage rights on the integration.

Setting up Amazon S3

Before you add the integration in the VMC, prepare your bucket and the permissions Vizlib Server uses to access it.

Supported S3-Compatible Stores

Vizlib Server uses only basic S3 calls: create, read, delete and check an object, multipart upload for files over 8 MiB, and custom object metadata. Any store that offers these through the S3 API and accepts access keys should work. Select S3 Compatible as the Provider in the VMC for all of them. Table 1 lists the stores we have tested and the stores we expect to work.

Supported S3-Compatible Stores
Status Stores

Tested

MinIO, SeaweedFS

Expected to work, not tested

Ceph RGW (RADOS Gateway), NetApp StorageGRID, Dell ECS, Wasabi, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Akamai (Linode) Object Storage, Scaleway Object Storage, IBM Cloud Object Storage, Oracle Cloud Infrastructure Object Storage (S3 compatibility API), Google Cloud Storage (XML API with HMAC keys), Garage, RustFS

Note: Directory buckets (S3 Express One Zone) are not supported. The default credential chain applies to Amazon S3 only. Other stores use access keys.

Creating the Bucket

Create a bucket in your AWS account with the settings in Table 2.

Bucket Settings
Setting Value Why

Bucket type

General purpose

Directory buckets (S3 Express) are not supported.

Name

3 to 63 characters: lowercase letters, digits, dots and hyphens. Starts and ends with a letter or digit.

You enter the same name in the VMC.

Region

The region closest to Vizlib Server

You enter the same region in the VMC.

Block all public access

On

Vizlib Server never needs public access.

ACLs

Disabled

Vizlib Server uses no ACLs.

Versioning

Off (simplest)

If versioning is on, a deleted file stays in the bucket, and is billed, until a lifecycle rule removes it.

Object Lock

Off

Deletes would not free the data.

Default encryption

SSE-S3 (the AWS default)

Vizlib Server sends no encryption header, so the bucket default applies. With SSE-KMS, the identity Vizlib Server uses also needs kms:GenerateDataKey and kms:Decrypt on the key.

Important: Do not add a bucket policy that denies uploads without an x-amz-server-side-encryption header. Vizlib Server sends no such header, so every upload would be denied.

Adding Lifecycle Rules

If Vizlib Server stops during a large upload, S3 keeps the uploaded parts and bills for them, but they do not show in the object list. Add the following lifecycle rules to clean them up:

  • Delete incomplete multipart uploads after 1 day, for all objects in the bucket.

  • On a versioned bucket, also permanently delete noncurrent versions after the number of days you want to keep deleted files.

Important: Never add a rule that expires current objects (the file would be gone while Vizlib Server still lists it) or moves objects to Glacier or Deep Archive (downloads would fail). Standard-IA and Intelligent-Tiering are fine.

Creating Permissions

Create an IAM policy (for example vizlib-attachments-rw) using the following example. Replace <BUCKET> with your bucket name and <PREFIX> with the fixed text at the start of your key pattern, before its first tag (see Key Pattern).

Copy
{
                "Version": "2012-10-17",
                "Statement": [
                {
                "Sid": "BucketAccess",
                "Effect": "Allow",
                "Action": ["s3:ListBucket"],
                "Resource": "arn:aws:s3:::<BUCKET>"
                },
                {
                "Sid": "ObjectAccess",
                "Effect": "Allow",
                "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:AbortMultipartUpload"],
                "Resource": "arn:aws:s3:::<BUCKET>/<PREFIX>/*"
                }
                ]
            }

s3:ListBucket is used for the connection check, and it makes S3 answer "not found" instead of "access denied" for a missing file.

Because the object permissions are limited to <PREFIX>/*, the key pattern in the VMC must start with <PREFIX>/, for example <PREFIX>/{{DESTINATION}}/{{ATTACHMENT_ID}}{{EXT}}. With a pattern outside the prefix, every upload is denied.

Note: If the key pattern starts with a tag (the default does), there is no fixed prefix. Use arn:aws:s3:::<BUCKET>/* as the object resource, and use a bucket that only Vizlib uses.

Note: The connection check in the VMC does not test write access. A missing s3:PutObject permission still shows connected, and the first upload fails.

Choosing How Vizlib Signs In

Vizlib Server can sign in to S3 with access keys or with the default credential chain. Table 3 shows when to use each mode.

Authentication Modes
Mode Use it when Stored in Vizlib

Access keys

This is the default choice. It works everywhere, including Vizlib-hosted servers.

Access key id and an encrypted secret

Default credential chain

Vizlib Server runs on AWS (EC2, ECS, EKS), or long-lived keys are not allowed.

Nothing. Not available on Vizlib-hosted servers.

To use Access keys, do the following:

  1. Create an IAM user without console access.

  2. Attach the policy you created in Creating Permissions.

  3. Create one access key and copy the secret immediately.

    Note: AWS shows the secret only once.

To rotate an access key, create a second key, enter it in the VMC, check that the status is connected, and then delete the old key.

To use the Default credential chain, attach the policy to an IAM role and give the role to the machine that runs Vizlib Server (EC2 instance profile, ECS task role, or EKS service account), or set the standard AWS environment variables on the server process. The AWS SDK takes the first source that answers, in this order:

  1. Environment variables

  2. Single sign-on

  3. Shared credentials files

  4. Web identity token (EKS)

  5. Container credentials (ECS)

  6. EC2 instance profile

Note: The server has one identity, shared by every S3 integration on it. Anyone allowed to manage integrations can point an integration at any bucket that identity can reach.

Note: A stray AWS_ACCESS_KEY_ID variable or an old ~/.aws/credentials file takes priority over the instance role.

Note: If Vizlib Server runs in Docker on EC2, the default metadata hop limit of 1 blocks containers. Raise the instance's metadata response hop limit to 2.

Note: After you change environment variables, restart Vizlib Server.

Adding an Integration

The first step to connecting is to add or configure an integration.

  1. Log in to the VMC. You should see the dashboard, with all your current integrations listed in the top left panel (Figure 1). The symbol indicates a successful setup, and  indicates a setup error.

  2. Go to System Settings > Integrations (Figure 2) to open the list of integrations. If an integration is not set up correctly, the sign is displayed beside it.

    Figure 1:  Integrations Page

  3. Click Add Integration to open the pop-up screen.

  4. Select S3 as the Type.

  5. Pick a unique Id. The Id will be displayed in the destination list, so keep that in mind when you're creating it.

  6. Choose Public or Private settings. Public settings can be managed by all VMC users, but private can only be managed by the creator and Admin/Root Admin users.

  7. In the S3 Settings panel, enter the values listed in Table 4.

    S3 Integration Settings
    Field Value

    Provider

    Amazon S3, or S3 Compatible for MinIO and similar stores.

    Bucket

    Your bucket name.

    Region

    The bucket's region. For an S3-compatible store, any region it accepts (for example us-east-1).

    Endpoint

    Required for S3 Compatible only. The store's URL, for example http://localhost:9000.

    Path-style addressing

    For S3 Compatible only. Turn this on for MinIO and most on-premises stores.

    Key pattern

    Where an attachment is stored in the bucket. Build the pattern with the Insert Tag menu (see Key Pattern). The default is {{DESTINATION}}/{{FILENAME}}_{{ATTACHMENT_ID}}{{EXT}}. The fixed text before the first tag must match the IAM policy prefix.

    Authentication

    Access keys or Default credential chain.

    Access key id, Secret access key

    For Access keys only. The secret is stored encrypted, shown masked, and kept when you save without changing it.

  8. Click Add Integration when you're finished. You should see the new integration listed in the dashboard.

    Check: Your integration should display the green tick icon before going to the next step. If it's showing an error, follow the advice in the message, or see Troubleshooting. To run the check again, click the status icon.

    Figure 2:  Integration Completed Successfully

Note: connected means the VMC reached the bucket in that region with those credentials. An integration in error is not offered in the destination list, and an integration that a destination uses cannot be deleted.

Key Pattern

The key pattern is the full path of an attachment in the bucket. It is text with tags that Vizlib Server replaces for each file, and / makes folders. Table 5 lists the tags you can use.

Key Pattern Tags
Tag Replaced with

{{ATTACHMENT_ID}}

The attachment's unique id (lowercase uuid). Required in every pattern, so two files never get the same key.

{{DESTINATION}}

The destination id. Special characters are URL-encoded (a space becomes %20).

{{FILENAME}}

The uploaded file name without its extension. Characters other than letters, digits, ., _, space and - become _. The name is cut to 100 characters.

{{EXT}}

The extension with its dot, for example .pdf. Empty if the file has none.

{{DATE}}, {{YEAR}}, {{MONTH}}, {{DAY}}, {{HOUR}}, {{MINUTES}}, {{SECONDS}}, {{TIMESTAMP}}

When the attachment was created, in UTC, for example 20261118, 2026, 11, 18, 14, 05, 09, 20261118T140509.

The following rules apply to key patterns:

  • Leading, trailing and repeated / are removed.

  • Unknown tags, .. and patterns over 512 bytes are rejected on save.

  • A resulting key over 1024 bytes (the S3 limit) makes the upload fail.

Table 6 shows examples of the key each pattern creates for the file Q3-report.pdf, uploaded on 18 Nov 2026 at 14:05:09 UTC to the destination sales-forecast, with the attachment id 6f2a1c94-3b7e-4d58-9a0c-1e5f8b2d7a43.

Key Pattern Examples
Pattern Key in the bucket Use it when

{{DESTINATION}}/{{FILENAME}}_{{ATTACHMENT_ID}}{{EXT}} (default)

sales-forecast/Q3-report_6f2a1c94-3b7e-4d58-9a0c-1e5f8b2d7a43.pdf

You want to recognise files in the bucket, with a folder per destination.

{{DESTINATION}}/{{ATTACHMENT_ID}}/{{FILENAME}}{{EXT}}

sales-forecast/6f2a1c94-3b7e-4d58-9a0c-1e5f8b2d7a43/Q3-report.pdf

The file name should stay clean. A bucket browser or a copy shows the real name. One folder per file.

{{ATTACHMENT_ID}}

6f2a1c94-3b7e-4d58-9a0c-1e5f8b2d7a43

You want all files in one flat folder, with no file names, no extension and no destination in the key. Nothing readable is exposed in the bucket.

writeback/{{ATTACHMENT_ID}}

writeback/6f2a1c94-3b7e-4d58-9a0c-1e5f8b2d7a43

Like the previous one, in a shared bucket. The IAM prefix is writeback.

attachments/{{YEAR}}/{{MONTH}}/{{DESTINATION}}/{{ATTACHMENT_ID}}{{EXT}}

attachments/2026/11/sales-forecast/6f2a1c94-3b7e-4d58-9a0c-1e5f8b2d7a43.pdf

You want to sort, report on or archive files by month. The IAM prefix is attachments.

Use the following guidance when you choose a key pattern:

  • Readable keys (the first two examples) help when someone has to find, copy or check a file in the bucket. The folder per destination also lets an administrator list or remove the files of one destination.

  • Id only keeps file names and destination ids out of the bucket and out of its access logs. The disadvantage is that someone browsing the bucket cannot tell which destination or file a key belongs to, and an administrator cannot list or remove one destination's files by folder.

  • A fixed prefix (writeback/…, attachments/…) lets you limit the IAM policy to that prefix and share the bucket with other applications. Without it, the policy needs access to the whole bucket (see Creating Permissions).

Note: The file's content type is always stored with the object, so a pattern without {{EXT}} still downloads correctly through Vizlib Server.

Note: Changing the pattern later only affects new uploads. Existing files keep the key they were saved under and stay readable. There is no tool to move old files to the new layout, so leave them where they are.

Adding Attachment Storage to a Destination

Now, you'll need to select the integration as the attachment storage for your Destination.

  1. In the VMC menu, click on Writeback Settings, then Destinations, and open the destination you want to use.

  2. In the Attachments card, turn on Enable Attachments.

  3. In Attachment Storage Integration, pick the S3 integration you created. The list shows connected Postgres and S3 integrations, with (Postgres) or (S3) after each id.

  4. (Optional) Override Max File Size and Allowed File Extensions for this destination.

    Note: Defaults for all destinations are set on the Defaults page: max file size (up to 1024 MB), allowed extensions, and Cleanup After hours for files uploaded but never saved (default 24, minimum 1). You can also switch off attachments for every destination on the Defaults page.

  5. Click Save to save your destination in the VMC.

Important: Changing a destination to another storage integration, turning attachments off, or deleting the destination permanently deletes all its attachment files. The VMC asks you to confirm first. To move to another bucket or endpoint, copy the files first, then edit the existing integration. Changing only the key pattern is safe for existing files, as they keep the key they were saved under.

How Attachments Are Stored

This section explains what Vizlib Server does with your files, so you know what to expect in the bucket.

  • Where files go - the integration's key pattern decides where each file is stored. The key is fixed when the upload starts, so a retry of the same upload writes to the same key.

  • What each object carries - the file's content type and a Vizlib marker with the attachment id. The original file name, size and checksum are only in the Vizlib Server database. Vizlib Server reads, reports or deletes only objects with the matching marker.

    Important: Do not add or edit objects under the prefix by hand.

  • Upload - files up to 8 MiB are one upload. Larger files go in 8 MiB parts.

  • Download - the file streams through Vizlib Server, which checks its checksum. If the object was changed or corrupted in the bucket, the download fails instead of delivering a damaged file.

  • Deleting - deleting a file in a writeback, deleting a row, and the hourly cleanup of never-saved uploads all remove the object from the bucket. On a versioned bucket, this only adds a delete marker.

  • Encryption - the bucket's default encryption applies. There is no encryption setting in the VMC.

Important: Give each Vizlib Server its own bucket or prefix. Never point a test server that runs on a copy of the production database at the production bucket: deleting a file or destination there would delete the production file.

For information on backing up and restoring attachments, see our article here.

Troubleshooting

Users see only a generic error. The administrator can find the reason (bucket, region, endpoint, and S3 error code) in the Vizlib Server log. Keys are never logged.

Integration Status in the VMC

Integration Status Messages
Status Usual cause Fix

Bucket not found

Typo in the bucket name

Check the name.

Access denied

Wrong secret, missing s3:ListBucket, or a bucket policy

Re-enter the secret, and check the policy.

Access denied (invalid access key or secret access key)

Key id or secret wrong, or key deleted

Create a new key.

Access denied (no credentials found in the default credential chain)

No source in the chain provides credentials

Attach the role, set the variables, check the hop limit, and restart Vizlib Server.

Wrong region (the bucket is in …)

Region differs from the bucket's region

Use the region in the message.

Endpoint unreachable

No network path, firewall, wrong endpoint, or an HTTP proxy (not supported)

Allow outbound HTTPS to S3. For Amazon S3, use the provider Amazon S3.

Credentials expired

Temporary credentials ran out

Refresh them, or use a role or access keys.

Storage service error (HTTP …)

S3 itself

Retry later.

Problems After the Status Is Connected

Problems After Connecting
Symptom Cause

Every upload fails

Missing s3:PutObject; a key pattern outside <PREFIX>/* while the policy allows only that; a bucket policy that requires an encryption header; or an SSE-KMS key the identity may not use.

Uploads fail only for some files

The key built from the pattern is over 1024 bytes (the S3 limit), for example with a very long destination id. The server log says so. Shorten the pattern.

"Not available" on download

The file was removed or expired in the bucket, or the integration now points to another bucket or endpoint.

Download fails

The file moved to Glacier or Deep Archive, or S3 is unreachable.

Download ends early or fails in the browser

The object was changed in the bucket.

Deleted files still use space

Versioned bucket without the noncurrent-version rule, or Object Lock is on.

Access denied only from some networks

The bucket policy limits access to a VPC endpoint or IP range.

Users see only a generic error. The administrator finds the reason (bucket, region, endpoint, S3 error code) in the Vizlib Server log. Keys are never logged.

Was this article helpful?

We're sorry to hear that.