Marek SuchánekIn the FAIR Wizard, you can create a project, fill the questionnaire there, and then generate a document by selecting the desired document template and format. For example, you want to export your project using the Horizon Europe DMP Template in PDF format. The document template takes replies from a questionnaire together with related project metadata, and transforms it to any output text needed — can be human or machine readable. This article will quickly explain how you can start working on a document template.
Creating a document template for FAIR Wizard is very simple programming using Jinja2 templating language and currently requires a bit of work on the command-line. You will need:
To install TDK, we recommend using Python virtualenv:
$ python -m venv env
$ source env/bin/activate
(env) $ pip install dsw-tdk
With TDK installed, you can try basic commands. It is always possible to simply get --help and figure out the installed --version (that should match with your FAIR Wizard instance).
$ dsw-tdk --help
$ dsw-tdk --version
$ dsw-tdk list --help
Some of the commands require interacting with a FAIR Wizard instance via its API. You need to provide an API URL (that you can discover in Help > About) and your credentials. The most convenient way is to define .env file in your project root as follows:
Then, you can easily run commands interacting with FAIR Wizard API such as listing remote templates, getting a remote template as a local project, or vice versa (putting a local template project to the FAIR Wizard).
$ dsw-tdk list
INFO: Connecting to https://api-example.fair-wizard.com
INFO: Successfully authenticated as albert.einstein@example.com
INFO: Listing remote templates
codevence:h2020-dmp:1.9.0 Horizon 2020 DMP
codevence:horizon-europe-dmp:1.2.0 Horizon Europe DMP
codevence:questionnaire-report:2.7.0 Questionnaire Report
codevence:rda-madmp:1.13.0 maDMP (RDA DMP Common Standard)
codevence:science-europe:1.12.0 Science Europe DMP Template
You can easily control the verbosity of the output:
$ dsw-tdk --quiet list
codevence:h2020-dmp:1.9.0 Horizon 2020 DMP
codevence:horizon-europe-dmp:1.2.0 Horizon Europe DMP
codevence:questionnaire-report:2.7.0 Questionnaire Report
codevence:rda-madmp:1.13.0 maDMP (RDA DMP Common Standard)
codevence:science-europe:1.12.0 Science Europe DMP Template
To start working on a document template project, you can either start a new one or download an existing one (e.g. via get command). Here, we want to start from scratch, i.e. by using the new command. It will launch an interactive wizard in CLI asking for basic information about the new template such as name, license, or supported document formats.
$ dsw-tdk new .
Template name: CV (Resume)
Organization ID: codevence
Template ID [cv-resume]:
Version [0.1.0]:
Description [My custom template]: Curriculum Vitae / Resume document of a person
License [CC0]: Apache-2.0
============================================================
Do you want to add a format? [Y/n]:
Format name [HTML]:
File extension [html]:
Content type [text/html]:
Jinja2 filename [src/template.html.j2]:
============================================================
Do you want to add yet another format? [y/N]: y
Format name [HTML]: JSON
File extension [json]:
Content type [application/json]:
Jinja2 filename [src/template.json.j2]:
============================================================
Do you want to add yet another format? [y/N]:
SUCCESS: Template project created: /Projects/dsw-template-cv-example
Once the wizard is finished, the initial template files are created in the desired directory (passed as argument to the new command). The template.json together with README.md file contains the metadata about the template. Then, there are prepared Jinja2 template files, one per each format supported. However, you can create more files on the go based on your needs. The directory structure may also be altered. In the template.json file, you can see all the metadata as well as formats and their steps. You can easily edit this information according to the documentation in the User Guide.
A document template is basically (and practically) about printing out some text based on a project (questionnaire, its replies, and additional metadata) from FAIR Wizard. The structure containing this source information is called document context. You can easily investigate it as a JSON object, by printing it out in your template.
The document context is documented in User Guide. As FAIR Wizard evolves over time, the structure of document templates may also change. In that case, the so-called metamodel version is increased. When you upgrade the template to adopt such changes, the metamodel version in template.json file must be increased accordingly.
$ dsw-tdk put
INFO: Loading local template project
INFO: Connecting to https://api-example.fair-wizard.com
INFO: Successfully authenticated as albert.einstein@example.com
INFO: Creating remote template
SUCCESS: Template codevence:cv-resume:0.1.0 uploaded to https://api-example.fair-wizard.com
After putting the template to your FAIR Wizard instance successfully, you can try it out by creating a testing project and selecting it as the default document template (in Settings tab). If you continually improve the template, it is recommended to use a combination of --force and --watch flags with the put command.
To retrieve and print out a reply to a specific question, you must know its UUID path from the knowledge model. In this example, we will use our CV KM where there are basic questions about a person to build a resume or Curriculum Vitae document. The UUIDs can be easily found in KM Editor and copied by clicking on its short version.
The best approach is to store UUIDs as constants in your template file (or another Jinja2 file dedicated for UUIDs). With that, it is easy to compose a reply path and retrieve the actual reply. However, the reply itself is not yet the value entered by a user, but a structure with additional information as you can see from document context (or printing it out). There are filters provided to simplify the work with replies. You have to access its value but first you should always check if the reply is actually present.
When the question is not of value-type but options or multi-choice, you need to work with the UUID of the answer/choice. As the document context contains the entire knowledge model, it is possible to quickly access the answer/choice entity and, for example, print its label. Similarly, you can work with integration questions. Reply to a list question is a list of UUIDs — one per each item in the list that needs to be added to the reply path.
So far, we used HTML output format which is suitable for humans (you can make it more visually appealing with some CSS styling). However, a document template can generate any textual format. For example, we can easily create a JSON representing a CV/Resume. In a similar way we could do RDF formats, YAML, XML, or TOML.
The document project template is very similar to basic programming projects. It is suitable to be maintained via traditional VCS such as Git and eventually published, e.g. on GitHub. In such a case, do not forget to Git-ignore the .env file and your Python virtual environment. To properly version the template, the README should contain a changelog and the version in template.json should match with Git-tag / GitHub Release (you can attach an importable ZIP file to a release after creating it using the package command).
You can get inspiration from our example project for CV/Resume template where you can also find stuff mentioned in this article and more…
Now you know how to create and work on your own document template with formats suitable for humans as well as for machines. It allows you to further benefit from using FAIR Wizard via its versatility and configurability. You should now know how to:
dsw-tdk and prepare .env file