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
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.
| Recipient type | Description | Behavior |
|---|---|---|
| Internal |
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.
Considerations
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.
Do the following:
-
Open the Recipients or Groups tab in the Reporting section of an app.
-
Click Add recipients and groups.
-
Select
Download example.
Downloading the example distribution list 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:
DL_DISTRIBUTION_SVC_USERS_QCS
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.
Do the following:
-
In the Name column, add the recipient's name.
-
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.
-
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.
-
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:
DL_DISTRIBUTION_SVC_GROUPS_QCS
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.
Do the following:
-
In the Name column, add the name of the group.
-
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.
Do the following:
-
Open the Recipients or Groups tab.
-
Click Add recipients and groups.
-
Select Upload new version (.xlsx).
Uploading the 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.
Requirements
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.
| 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:
Deleting a distribution list
If needed, you can remove all recipients and groups from the app.
Do the following:
-
Open the Recipients or Groups tab.
-
Click
next to any recipient or group and select 
Delete all.
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.