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 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 receive reports?
Using in-app reporting with Qlik Cloud Analytics, you can send email reports to both internal and external recipients.
Identification of internal recipients
The recipient's email address is used to identify whether or not they are an internal recipient. If the email address matches the email address of a user in the Qlik Cloud tenant, the recipient is internal. If no match is found, the recipient is external.
Output and section access
The table below describes each type of recipient and what can they expect to see in their reports. This table outlines the behavior for apps with and without section access. For more information about in-app reporting and section access, see In-app reporting and section access.
| Recipient type | Description | Behavior |
|---|---|---|
| Internal |
A user in the Qlik Cloud tenant, identified by matching email address. To learn how to add a user to the Qlik Cloud tenant, see:
|
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. |
| External | A user who is not in the Qlik Cloud tenant. | Data included in report is always based on the access of the report task owner, regardless of whether the app uses section access or not. |
Microsoft SharePoint report distribution
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. The identification of internal recipients works the same as for email output.
Report delivery via Microsoft SharePoint distribution folder is not available if the app uses section access.
When sending reports via distribution folder, you must still define a distribution list for the app to generate report output. The distribution list still helps determine how many versions of the report output are generated when the report tasks runs (typically, one file for each individual recipient filter). For more information about storing reports to a distribution folder, see Delivering reports to a distribution folder.
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.
In-app reporting and section access
If the app uses section access, report generation works differently. For more information, see In-app reporting and 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 in-app reporting in managed spaces, see In-app 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.