Skip to main content

Automate your reporting

Read this first
  • Make sure you completed the installation process, if you ran into issues try following the installation guide.
  • Did you already create an app template in one of the previous tasks? Then you can continue to implementing the report.

Set up the app template​

When you start creating a new app the first thing you need to do is to create an app template. The required steps depend on the chosen installation method.

Would you like to watch a short video?

  1. Create a new folder for your app

    Add a new folder in your filesystem (e.g. C:\Users\<username>\viktor-apps\my-app) and open it in your code editor of choice

  1. In your terminal enter the following command and hit enter:

    viktor-cli create-app --app-type editor

    This will make all the necessary files in your app folder for you.

  2. Install the app and it's dependencies and start it in your development workspace by using the following command in the terminal:

    viktor-cli clean-start

    If all went well, your app is installed and running in your development workspace:

    INFO    :  __      __ __  __  __
    INFO    :  \ \    / / | | | |/ /
    INFO    :   \ \  / /  | | | ' /
    INFO    :    \ \/ /   | | |  <
    INFO    :     \  /    | | | . \
    INFO    :      \/     |_| |_|\_\
    INFO    :   _______   ____    _____
    INFO    :  |__   __| / __ \  |  __ \
    INFO    :     | |   | |  | | | |__) |
    INFO    :     | |   | |  | | |  _  /
    INFO    :     | |   | |__| | | | \ \
    INFO    :     |_|    \____/  |_|  \_\
    INFO    : VIKTOR connector vX.Y.Z
    INFO    : VIKTOR SDK vX.Y.Z
    INFO    : Connecting to platform...
    INFO    : Connection is established: <URL>  <---- here you can see your app
    INFO    : The connection can be closed using Ctrl+C
    INFO    : App is ready

    Do not close the terminal as this will break the connection with your app.

  3. Open your development workspace if you are not in it yet

    You can now navigate to the URL shown in the terminal (as highlighted above), and enter your Development workspace by clicking the open button.

Define your input fields​

Restarting your app
  • The app will update automatically after adding your code and saving the app.py file, as long as you don't close the terminal.
  • Did you close your code editor? Use viktor-cli start to start the app again. No need to run the install and clear commands.
  • Once your app is started you will be able to interact with it in your Development workspace

As we all know, writing reports is boring and updating is a repetitive cycle that never ends... That is why VIKTOR lets you connect a report template so that every time you change the input values, the report can automatically be generated.

Open app.py, this is where we will place all the code for our app. We will begin by adding all the required imports to the top of the file:

from pathlib import Path

from viktor.external.word import render_word_file, WordFileTag
from viktor.utils import convert_word_to_pdf
from viktor.views import PDFResult, PDFView
from viktor.parametrization import TextField, DateField, Text

For the sake of this tutorial, we will keep it simple and automate the addition of the name and date to the report from within the VIKTOR application. The possibilities do not end there, with VIKTOR's reporting capabilities you can add schematics, tables, images, and more all from the results of the calculations within your app.

Let's begin by adding some parameters that we want to add to our report. First we will use the Text class to indicate that this part of the input fields is dedicated to automatic reporting. Then we will use a TextField and a DateField for user input. You only need to add the highlighted lines of code.

class Parametrization(ViktorParametrization):
    text_report = Text('## Report inputs')
    user_name = TextField('Your name')
    project_date = DateField('Choose a project date')

Refresh your browser and have a look at the app to see what these fields looks like in the user interface!

Add a PDF preview​

The next step is to make sure we can preview the report in the app.

For this we will use the PDFView, which can be used to visualize PDFs. Feel free to copy the highlighted lines of code template into your Controller class from below:

class Controller(ViktorController):
    label = 'My Entity Type'
    parametrization = Parametrization

    @PDFView("Report", duration_guess=10)
    def starter_guide_report(self, params, **kwargs):
        components = []
        return PDFResult()

Connect a report template​

The next step is to connect a template which we can fill, to our app. For this tutorial you can download this template and add it to your app folder. The app folder's structure should now look like this:

viktor-demo
├── tests
├── app.py
├── CHANGELOG.md
├── README.md
├── report_template.docx
├── requirements.txt
└── viktor.config.toml

If you open the template, you will notice some parts are placed in double curly brackets. These are the tags that we need to connect to the parameters that we made earlier.

To connect these tags we will make a Python list with WordFileTag components. Here we will need to make sure that the name of each tag is exactly the same as in the Word file. The inputs defined on the Parametrization are passed to the PDFView method with the params argument. For example, to use the name of the user you reference it by its variable name params.user_name. You only need to add or change the highlighted lines of code.

class Controller(ViktorController):
    label = 'My Entity Type'
    parametrization = Parametrization

    @PDFView("Report", duration_guess=10)
    def starter_guide_report(self, params, **kwargs):
        components = [
            WordFileTag("user_name", params.user_name),
            WordFileTag("project_date", str(params.project_date))
        ]
        return PDFResult()

Combine all of the above!​

Now that we have our report's tags matched with our parameters, let's combine them to automate the reporting process. We will refer to the template using its file path. Then we will render the template together with the components and finally convert it to a PDF file which we can display in our VIKTOR app. The final result should look something like the code snippet below. You only need to add the highlighted lines of code.

class Controller(ViktorController):
    label = 'My Entity Type'
    parametrization = Parametrization

    @PDFView("Report", duration_guess=10)
    def starter_guide_report(self, params, **kwargs):
        components = [
            WordFileTag("user_name", params.user_name),
            WordFileTag("project_date", str(params.project_date))
        ]

        # Get path to template and render word file
        template_path = Path(__file__).parent / "report_template.docx"
        with open(template_path, 'rb') as template:
            word_file = render_word_file(template, components)

        # Convert to PDF
        with word_file.open_binary() as f:
            pdf_file = convert_word_to_pdf(f)

        return PDFResult(file=pdf_file)

If you fill in the user name and date and click the update button on the bottom right of the PDFView you should see the following:

As you can see the name and date appear in the report. Like we mentioned at the beginning, this is only the basics of reporting and there are so many things you can automate. If you want to start learning more about what you can do with reporting, feel free to try out the full tutorial.

Continue the next section or come back tomorrow to spread the workload!