Skip to main content Skip to complementary content

Creating a distribution list for your report

Before creating a report task, you must define the distribution list for the Qlik Sense app that is the basis for your report. The distribution list contains all recipients, and groups of recipients, who can be receivers of an app's report tasks.

Use the distribution list to configure the individuals to which reports are sent. When you configure a report task, you select the recipients and groups from your distribution list that will receive the output of that particular report task.

The distribution list provides the following details:

  • All recipients of tabular reports generated from the app, including their names, email addresses, which filters apply to them, and which groups they belong to.

  • All groups (collections of one or more recipients) who can receive reports generated from the app.

If you upload a source file as the distribution list, it is shown in the Recipients and Groups tabs within the Reporting section of the app.

The Recipients and Groups tabs

The 'Recipients' and 'Groups' tabs in the app's reporting section

Only one source file can be added to an app. If you need to make changes to the source file, edit the file (or data source) you originally uploaded and re-upload it. If you are instead using data connections to define the distribution list, make edits to the script as needed. Note that when you do so, equivalent changes must be made to the report task configuration and filters, as needed.

Who can I send tabular reports to?

You can include both internal and external recipients in the app's distribution list. The following table describes each type of recipient, and what you can expect them to see in their reports.

Possible recipients to email output of an app's report tasks
Recipient type Description Behavior

A user in the Qlik Cloud tenant.

To learn how to add a user to the Qlik Cloud tenant, see Adding users to Qlik Cloud or Adding users to Qlik Cloud, depending on the subscription type.

Unless the app uses section access, the data included in this recipient's report will be based on the access that the report task owner has to the app.

For section access behavior, see Tabular reporting and section access.

External A user who is not in the Qlik Cloud tenant. Data included in report is always based on the data access of the report task owner.

If you are instead distributing reports via a distribution folder (Microsoft SharePoint), anyone who has access to the location specified in the corresponding connection can access the reports. You must still define a distribution list for the app to begin generating report output, and to determine how many versions of the report output are generated each time the report task runs (one file for each individual recipient filter). For more information about storing reports to a distribution folder, see Delivering tabular reports to a distribution folder.

If the Qlik Sense app uses section access, it is important to be aware of how this affects who receives the reports. See Tabular reporting and section access.

The distribution list, recipient filters, and task output

The distribution list controls the report filters that are applied to each recipient individually. When you add the distribution list to the app, a separate recipient is created for each filter you apply to them. When configuring a report task, you add each recipient as a user-filter pairing corresponding to a single filter.

For example, if you apply filters A and B to a recipient named User1, two recipients are added to the app – User1 with filter A, and User1 with filter B.

For more information about how to configure your report task to generate the required output, see:

Reload schedule ownership considerations

Distribution lists work through automatic or manual modifications to the load script of an app. When you do any of the following actions, you could possibly become the new owner of the app’s reload schedule:

  • Uploading a source file as the distribution list

  • Deleting the distribution list

  • Making any manual edits to the load script

It is important to be aware of these scenarios because when reloading on a schedule, the owner of the schedule must have the required access to the app and its data sources. Otherwise, the app will fail to reload.

For more information, see Ownership of reload schedules.

Adding the distribution list

Add the distribution list using one of the following two methods:

  • Upload a source file

  • Define the recipients and groups manually in the load script

Each method is explained in the sections below.

Adding the distribution list by uploading a source file

You can define a distribution list by uploading a source file containing the required information. This file must contain specific formatting and structure. The easiest way to create the source file is to download the example file and modify it with your recipient and group information.

Uploading a source file as the distribution list replaces the existing source file, if any. Only one source file can be applied to an app. If you upload a source file, this file replaces the source file that was previously uploaded to the app, if any. This can cause existing report tasks to fail if there are mismatches between the old and new files.

When you add a distribution list by uploading a source file, a new section (Distribution List) is automatically generated in the app’s load script, and the app reloads. This script section lists the recipients and groups for the app. The details in the distribution file then become accessible in the app's data model.

When you upload a source file as the distribution list, the file is also added as a data file to the space containing the app. The Distribution List script section references this file as an item within the space.

Tip noteIf you do not want the fields in your uploaded distribution file list to be accessible when app users create visualizations and report filters, use the HidePrefix system variable in the script. Use this to hide the fields while keeping them in the data model. For more information, see HidePrefix.


Consider the following details that are important to know before you upload a source file:

  • The new Distribution List script section is added as the last section in the script. As a result, any script formatting issues on the last section before Distribution List will result in reload failure. For example, this could be something like not having a semicolon at the end of the last table to load.

  • Do not modify the SubField function expressions in the auto-generated Distribution List script section. These expressions are required to support comma-separated values for your filters and groups.

    SubField([Filters],',') AS [DL_DISTRIBUTION_FILTERS], SubField([Groups],',') AS [DL_DISTRIBUTION_GROUP_NAMES]
  • Since uploading the source file works by loading data into your app, it also counts towards the purchased data load volume defined in the Qlik Cloud subscription (only applicable for capacity-based subscriptions). See Qlik Cloud capacity-based subscriptions.

Downloading the example file

The example source file is an Excel workbook you can modify before uploading it to the app.

  1. Open the Recipients or Groups tab in the Reporting section of an app.

  2. Click Add recipients and groups.

  3. Select Magic wand Download example.

Downloading the example distribution list file

Clicking the button in the Recipients tab to download the example source file

After you download the example file, you can modify it to add the recipients and groups for the app.

Adding recipients

Open the example file you just downloaded and make sure you have the following worksheet opened:


Next, you can replace the data within the sheet to add your own recipients. Do not change or remove the first row showing the column headers.

  1. In the Name column, add the recipient's name.

  2. In the Email column, add the recipient’s email address. Note that this column is automatically formatted to be a hyperlink with an email address destination.

  3. In the Filters column, add the filter groups that correspond to those added in the Filters tab in the app’s Reporting section. Separate filter groups with commas.

  4. In the Groups column, add the groups to which the recipient belongs. Separate each group with a comma.

Adding groups

In the source file, groups are defined in the sheet with this title:


Open this worksheet and replace the data to create the groups in the distribution list. Do not change or remove the first row showing the column headers.

  1. In the Name column, add the name of the group.

  2. In the Description column, add a description of the group.

Uploading the distribution list file

After you’ve created the source file, upload it into the Recipients or Groups tabs in the Reporting section of the app. When you do this, the app reloads, and the recipients and groups populate in their respective sections.

  1. Open the Recipients or Groups tab.

  2. Click Add recipients and groups.

  3. Select Upload new version (.xlsx).

Uploading the source file

Clicking the button in the Recipients tab to upload the newly created source file

Defining the distribution list manually in the load script

Adding a distribution list through a file upload indirectly modifies the app's load script. Alternatively, use the load script directly to add recipients and groups. This is a suitable option for advanced users, and especially helps if you would like to use data source connections to provide the recipient and group information.

For example, if your recipients and groups are defined in an external source file, or are located in a database or human resource system (for example, Workday), this option allows the recipients and groups in the app to dynamically update based on the connected source.


For the fields in the script to be recognized as belonging to the app’s distribution list, you must apply tags to each required field that corresponds to the required element of the distribution list. See the table below for more information.

Options when configuring report filters
Field requiring tag Required tag Example
Recipient name DL_DISTRIBUTION_SVC__recipientName tag field [GetSheetValues.Name] with 'DL_DISTRIBUTION_SVC__recipientName'
Recipient email address DL_DISTRIBUTION_SVC__recipientEmail tag field [GetSheetValues.Email] with 'DL_DISTRIBUTION_SVC__recipientEmail'
Recipient filters DL_DISTRIBUTION_SVC__recipientFilters tag field [GetSheetValues.Filters] with 'DL_DISTRIBUTION_SVC__recipientFilters'
Group name DL_DISTRIBUTION_SVC__groupsName tag field [GetSheetValues.Groups] with 'DL_DISTRIBUTION_SVC__groupsName'
Group description DL_DISTRIBUTION_SVC__groupDescription tag field [GetSheetValues.GroupDescription] with 'DL_DISTRIBUTION_SVC__groupDescription'

Example script

Here is an example of a script section connecting to recipients and groups:

LIB CONNECT TO 'My_Sample_Connection'; LOAD Name as [GetSheetValues.Name], Email as [GetSheetValues.Email], SubField([Filters],',')AS [GetSheetValues.Filters], SubField([Groups],',') AS [GetSheetValues.Groups]; SELECT Name, Email, Filters, Groups FROM GetSheetValues WITH PROPERTIES ( spreadsheetKey='abc', range='DL_DISTRIBUTION_SVC_USERS_QCS!A1:D100', valueRenderOption='FORMATTED_VALUE', dateTimeRenderOption='FORMATTED_STRING', generatedNumberedColumns='false', skipRows='' ); tag field [GetSheetValues.Name] with 'DL_DISTRIBUTION_SVC__recipientName'; tag field [GetSheetValues.Email] with 'DL_DISTRIBUTION_SVC__recipientEmail'; tag field [GetSheetValues.Filters] with 'DL_DISTRIBUTION_SVC__recipientFilters'; LOAD GroupName as [GetSheetValues.Groups], GroupDescription as [GetSheetValues.GroupDescription]; SELECT GroupName, GroupDescription FROM GetSheetValues WITH PROPERTIES ( spreadsheetKey='abc’, range='DL_DISTRIBUTION_SVC_GROUPS_QCS!A1:B100', valueRenderOption='FORMATTED_VALUE', dateTimeRenderOption='FORMATTED_STRING', generatedNumberedColumns='false', skipRows='' ); tag field [GetSheetValues.Groups] with 'DL_DISTRIBUTION_SVC__groupsName'; tag field [GetSheetValues.GroupDescription] with 'DL_DISTRIBUTION_SVC__groupDescription';

Deleting a distribution list

If needed, you can remove all recipients and groups from the app.

  1. Open the Recipients or Groups tab.

  2. Click Three-dot menu next to any recipient or group and select Garbage can Delete all.

Information noteThe above procedure only works if you have uploaded a source file as your distribution list. If you have defined recipients and groups using the alternative scripting workflow, you must remove the tags from the fields to de-identify them as being related to the distribution list.

Tabular reporting and section access

The data reduction applied to a report is dependent on whether the source app uses section access.

Any internal report recipient (user in the Qlik Cloud tenant) must have access to the app and be included in the section access table for the report to be generated and sent to them. Additionally, the data in the report output will still be filtered based on the data access restrictions defined for that user in the section access script.

If a section access table is added to or removed from the app, the report task is automatically disabled. This allows the report developer to evaluate whether they want to proceed with report deliveries, based on the definitions of the recipients in the distribution list.

Managing data security with Section Access

Distribution lists in managed spaces

For apps in managed spaces, the distribution list cannot be edited from the Reporting section of the app. Before publishing an app to a managed space, upload a mock distribution list file, or refer to the required remote sources manually in the script. It is recommended to use space-aware syntax in the load script. In other words, the references to the data sources should point to the current space in which the app is located. Depending on how you add the distribution list, this syntax might be used automatically.

The data sources providing the distribution list must contain the same parameter names (names of connections, files, and fields) as the distribution list sources used in the source app's load script.

You upload the actual data sources for the distribution list to the managed space.

For more information, refer to the following guides:

Permissions for distribution lists

Managing the distribution list within a Qlik Sense app requires specific roles. The permissions requirements vary depending on the type of space in which your app is located.

Requirements for apps in shared spaces

The following requirements apply for apps in shared spaces:

  • To view the distribution list in the Reporting section of the app, you need Can edit access to the space.

  • To edit, re-upload, and delete the distribution list, you must have Can edit data in apps access in the space.

For more information, see Managing permissions in shared spaces.

Requirements for apps in managed spaces

The distribution list is not directly configurable in a managed space. The load script references the data sources that will be used to load the distribution list. To add these data sources to the space, you must have the required permissions for adding and managing data sources in a managed space. For further information, see Managing permissions in managed spaces.

For more information about tabular reporting in managed spaces, see Tabular reporting in managed spaces.

Requirements for an app in your personal space

You must have the Private Analytics Content Creator user role in the tenant to have full control over the distribution list.

Distribution list limitations

  • You cannot use commas in the fields containing names of recipients and groups, as well as email addresses of recipients. This limitation applies both to uploading the distribution list as a file, as well as defining it manually in the load script.

  • You can add a maximum of 1000 recipients and 1000 groups to the distribution list of an app.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – let us know how we can improve!