The reference data setup consists of two main steps:

  • Importing the Reference data. Data is imported on a project level so the same set of reference data can be used in multiple StoryTeller reports. 
  • Reporting on the uploaded reference data in the StoryTeller

The reference data uploads are made in a new Reference data page in the administration menu as shown below.

The Reference data page.
 


Upload data
 
Select the file(s) to be uploaded via the Browse button or the Drag and Drop function. After file selection click “Start Upload” to start the upload and the file validation. If any errors are found the upload stops and the file needs to be corrected.

Note, it is recommended to zip the files for a faster upload.

Activate data
 
You decide which of the uploaded data files to be used in the reporting by activating the files to be used, click Activate/Deactivate icons in the Active columns. Deactivated files are not used in reporting.

Note: the survey metadata needs to be imported before you activate the reference data as the system maps the ids of the questions and answers in the reference data against the ids in the survey meta data.

Here we see that only two of the uploaded data sets are activated and will be used in the reporting.
 

Delete uploaded data
 Only inactivate files can be deleted, an active file cannot be deleted.

It is recommended to delete unused data files.

Categories and Filter sets
 A Categories and Filter sets panel can be opened from the toolbar and here you see all the Categories and Filter sets from the activated reference data files. From here you can also update the sort order of the Categories and Filter sets if these should be shown in a specific order for the Report users in the reference filter list in the StoryTeller.

The Categories and Filter sets panel. Change the sort order by drag and drop or by entering the desired sort order number in the Order column or alternatively by using the alphabetical sort order function in the toolbar. 

Note: all the Categories and Filter sets are default ordered by the order of imported data files.

 

File format

The reference data should be imported in CSV files and below you see an example of a file, further down you see more details. Use comma, tab, semicolon-separated values in the CSV file, the system detects automatically what is used during upload.

Example of CSV reference data file opened in Excel, in this example, the reference values are connected to the Age group and Gender filters (this data is used in the dashboards example in chapter 9).

 

As shown above each row in the file contains a reference value connected to a Category, Question id, Answer id, calculation type, and a Filter set (a filter combination). The answer id column is used only when uploading reference values for Count or % on a categorical question.

Note, all the reference values to be used in reporting should be uploaded as there are no further aggregations of the reference value in the system. If, as an example, reference data should be available for a grouped answer such as a top 2 box (4+5) created in Dapresy you need to upload the reference data for the grouped answer even if you uploaded reference data for the answers 4 and the answer 5.  

Below you see a more detailed explanation of the columns in the reference file, the order of the columns does not matter but the exact column names must be used.

Category
The name of the Category the reference value belongs to. The category names are displayed for the Report users in the StoryTeller reports so these should be user-friendly.

Here we see where the Category names are shown to Report users.

 

Question id
 The id of the Question in the project the reference value should be connected to.

Note, in the project you find the question ids in the “Code” column in the Questions page. ( NB Not the ID column in the Questions screen.)

Answer id
 The id of the Answer alternative the reference value should be connected to in case of uploading reference data for % or counts on categorical questions.

Example of % reference data connected to answer 5.

Note: in the project, you find the Answer ids in the Id column on the Answer block page.

Filter columns
 
If the reference data should be connected to the hierarchical filter or any optional filters the reference file should contain a column per filter the data should be connected to. The filter connections are used in the StoryTeller reporting to show relevant Filter sets based on what hierarchy and optional filters the user selects. 

Optional filters: the column header should be “Filter:” followed by the question id of the filter variable, the ids of the filter answer options should be used in each row as shown in the example below.

Example of filter columns (column G and H) in the reference file for demonstrating purpose. As shown a Filter set can be connected to no filter (row 2-3), a filter (row 4-11 or a filter combination (row 12-15).

Hierarchical filters: the column header should be named “Hfilter”, in the codes of the units shall be should be used in each row as shown in the example below.

Example of a hierarchical filter column in the reference file for demonstrating purpose. In this example “Internal target” are uploaded and connected to each hierarchical unit.

Above the Filter, sets are connected to the hierarchical unit only but the Filter sets can also be connected to a combination of hierarchical and regular filters as shown below. 

For example where Filter sets are connected to a combination of hierarchical and regular filters, here we see that Business area 1 has internal targets for two different countries.

The codes of the hierarchical units to be used in the reference data file can be seen in the Hierarchical filter page, you can also get a list of all the codes by downloading the Report user template Excel from the Report user page.

Here we see the unit codes in the Hierarchical filter page and in the downloaded Report user template.

Note, if the Hierarchy module in Confirmit/Horizon is used for creating hierarchies a “Tag” concept can be used for grouping hierarchy units of the same type. The filter sets in the uploaded reference data can then be connected to the hierarchy tags instead of the hierarchy unit codes which reduce the number of reference data values to be uploaded. In a future version, a similar tag concept will be implemented in the hierarchies built-in Dapresy. For more information about the setup of tags in the hierarchy module of Confirmit/Horizon and how to structure the reference data contact support and they will assist you.

Filter set
The name of the Filter set (the filter combination). The Filter set names are displayed to the Report users in the StoryTeller reports so these should be user-friendly.

Example of Filter set names shown for Report user.
 

 

Note, all rows belonging to the same Filter sets should have the same filter connections. 

The file below is invalid as the same Filter set names are used for row 1 and 2 but these are connected to different filters.
 


 Calculation

 Specifies the calculation type the value is connected to, reference data can be uploaded to the following calculation types: 

  • Categorical: mean, %, count
  • Numeric: sum, mean, median, min, max

Example of reference values for both mean and % for the same question. Based on this calculation information system can pick the right value automatically based on calculation type applied to the survey data. 

 

Value
 
The reference value, uses the period as a decimal separator.

Percentile
 
This column is optional and should only be used when having percentile level reference data.  0-100 without decimals are valid values.

Example of percentile reference values, see column F.

Note, it is not required to include values for every percentile, you can, for example, only include values for percentile 10, 50, and 90 or for 10, 20, 30, 40, 50, 60, 70, 80, 90, 100 like in the example above. The granularity of the percentiles in the uploaded reference data will be reflected in the percentile ranking result. If the percentile ranking result should be 1-100 you need to include percentiles values for 1-100.