Unlock a world of possibilities! Login now and discover the exclusive benefits awaiting you.
Download latest version
Challenge:
Many of us likely know that after developing a Qlik Sense app, documentation needs to be created to deploy our analysis to production. This process is time-consuming, often requiring several days to produce what feels like just a "piece of paper". Another issue is that documentation is often made using standard templates, leading to materials that aren't complete and can be hard to comprehend. Documentation can be mandatory for both regulatory and operational reasons. Following the idea of “working smarter,” I want to automate this process using DocuGen with Qlik Application Automation (QAA). This approach can save us valuable time, allow us to transfer use cases to production faster, and provide documentation that is both thorough and easy to read.
Idea:
It all started with this simple idea and a first prototype, which I built in QAA. Various Qlik Cloud Services blocks are used to extract the relevant metadata from the individual app (e.g. table definitions, sheets and visualizations, variables, measures and dimensions, etc.). This data is then stored in variables and once all the information has been collected it gets passed into a “Custom Code” block. This block uses Python 3.11 and creates a dynamic HTML file without external references. This means that the created HTML file remains transportable and does not require any external resources, as it contains all the necessary functions itself. Finally, the created HTML file is saved to MS Sharepoint.
Input parameters for the python script.
Outcome:
This approach enables us to produce standardized documentation significantly more quickly on a daily basis, reducing the time required from an estimated 3 to 5 days to approximately 30 minutes. In my day-to-day job as a BI Specialist, I am now able to transfer analysis prototypes to production much faster for my customers and deliver added value for the business departments even faster. I think many other people in similar roles like me face the same challenge. This is the reason why I created a community project out of this idea together with Dennis Jaskowiak (Qlik PreSales). We started to extend the documentation with more functionalities, generalized the design of the documentation and reworked the code. In this article, we would like to share the project and its content with the Qlik Community.
App general information overview.
Sheets & visualizations section.
Data model section.
Script section.
Content of the package:
The archive consists of only 4 files:
To import the QAA you need the DocuGen v(x).json file. This file contains the exported QAA workspace.
The "code" folder contains the code segments used if you want to customise the code for your needs.
-
custom_code_block.py: This file contains the code that we use in the
"Custom Code"blog in the automation. -
used_css.css: This file contains the CSS definition that we use in the
"Variable - vCSS"blog in the automation and imports the style description for our HTML file. The definition is not minified in this file. -
used_js.js: This file contains the Java scripts that we use in our Python script (custom_code_block.py at the very end). The JavaScript is implemented in the Python code (last
<script></script>section). It is important that'{'and'}'are replaced with'{{'and'}}'so that they are not evaluated in Python.
Installation:
- Create a new blank Qlik Application Automation
- Upload workspace (right click on canvas) à DocuGen v(x).json
- Create a connection for SharePoint a. scroll to the bottom and click on the “Create File on Microsoft SharePoint” Block that has a red border b. click on the Connection tab and create a connection to your Microsoft SharePoint c. After you receive the information
“Connection is linked”you can use it by clicking on your created connection. The connection tab should now change its colour from red to black. - (optional) If you want to switch the number format from ‘comma’ to ‘point’ as decimal separator you can switch the value of the block named
“Variable – vNumber Format”from'de'to'us'. It’s the second block of the automation. - Now you can run the automation to generate your first documentation
Running the automation:
When you click on “Run” the automation gets executed. By default, the automation has configured “Run Mode: Manual”. It requires a few inputs for processing:
- Space – where the app is located (Personal doesn’t work)
- App name
- List of Sections that need to be documented (e.g. Data Model, Measures, Dimensions etc.)
- Screenshots (yes/no)
- List for type of sheets (e.g. Public, Community, Private)
If you want to run the automation triggered (e.g. by REST call) it needs to me modified. We will post an example later to showcase this option.
Features:
This list showcases what DocuGen covers:
-
General app information:
- app name, description, Id, Resource type, type of usage, owner, published, published time, space Id, has section access, is encrypted, create date, modified date, last reload time, app memory footprint, app reload peak RAM
-
Data model:
- For every table it generates:
- title, number of rows, number of fields, number of key fields, is loose, comment, table size,
- table containing field name, number of distinct values, number of non-null values, tags, ishidden, iskey, connected tables
- For every table it generates:
-
Measures:
- For every measure it generates:
- title, label, description, Id, definition, expression, grouping, custom formatted, format type, format, color, tags
- For every measure it generates:
-
Dimensions:
- For every dimension it generates:
- title, label, description, Id, definition, grouping, tags
- For every dimension it generates:
-
Variables:
- For every variable it generates:
- title, Id, definition, comment, tags
- For every variable it generates:
-
Sheets & Visualizations:
- list of sheets
- for every sheet it generates title, type, Id, description, grid resolution, sheet mode, list of used objects
- link to sheet
- list of objects on the sheet
- for every object on a sheet, it generates screenshot, type, Id, title, subtitle, footnote, color mode, color definition, dimensions, measures, link to object
- if the object is a container (layout container, tabbed container or normal container) it creates a list of all child objects containing the following information:
- type, Id, title, subtitle, footnote, color mode, color definition, dimensions, measures, link to object
- list of sheets
-
Load Script:
- For every script section it generates:
- title, script
- For every script section it generates:
Closing:
This is it for now. I hope this community project can help you automate and reduce the time you spend on documentation. On the bottom of that article, you will find the necessary files. The current version of the files will be hosted on GitHub.
Link to GitHub : LINK
A special thanks to Emil Koslowski (Product Manager Qlik Application Automation) for his invaluable support with various Qlik Application Automation questions. Your efforts have been instrumental in shaping a robust solution. Additionally, a big shoutout to Dennis Jaskowiak (PreSales Qlik) for his genuine enthusiasm for the idea, as well as his mentorship and unwavering support throughout the development - your guidance has been truly instrumental. Thank you!
This project has been created by Prodromos Chatziagorakis (Volkswagen Financial Services) & Dennis Jaskowiak (Qlik).
