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.
| 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.
| 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).
{
"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.
| 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:
Create an IAM user without console access.
Attach the policy you created in Creating Permissions.
-
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:
Environment variables
Single sign-on
Shared credentials files
Web identity token (EKS)
Container credentials (ECS)
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.
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.
-
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
Click Add Integration to open the pop-up screen.
Select S3 as the Type.
Pick a unique Id. The Id will be displayed in the destination list, so keep that in mind when you're creating it.
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.
-
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.
-
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.
| 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.
| 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.
In the VMC menu, click on Writeback Settings, then Destinations, and open the destination you want to use.
In the Attachments card, turn on Enable Attachments.
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.
-
(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.
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
| 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
| 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.