Document Template Specification

Each document template in DSW has metadata stored. If developing locally with Template Development Kit, you can find and manage them in template.json file. In case of using Document Template Editors, you can manage them on Settings tab.

Specification Structure

  • id = composed full ID of the template (organizationId:templateId:version)

  • organizationId = identifier of organization developing the template (lowercase, numerics, dot)

  • templateId = identifier of template (lowercase, numerics, dash)

  • version = version (semver) in X.Y.Z format where X, Y, and Z are non-negative numbers

  • name = name of the template

  • description = short description of the template

  • license = name of the used license

  • readme = longer description usually containing changelog

  • metamodelVersion = supported version of template metamodel, it affects with which DSW version is can be used

  • allowedPackages = list of package filters (see Package Filters) to specify supported packages

  • formats = list of available formats (see below Formats) with specified steps for generation

  • _tdk = TDK configuration for local development (not stored in DSW, see TDK Config)

Note

TDK handles id and readme for you, so you can skip them and naturally use README.md file separately.

Package Filters

For filtering, the null value serves as wildcard, i.e., filter with all null values means that all packages are allowed.

  • orgId: identifier of organization (e.g. myorg)

  • kmId: identifier of knowledge model (e.g. root)

  • minVersion: minimal package version (in format X.Y.Z, inclusive)

  • maxVersion: maximal package version (in format X.Y.Z, inclusive)

Formats

A template can describe how to produce several formats, each with these metadata:

  • uuid: UUID of the format (within template)

  • name: display name of the format

  • icon: icon style (CSS classes), preferably Font Awesome, e.g. fas fa-file-word

  • steps: list of steps for document worker to produce the document with this format, each step has name and options (see Steps)

Steps

Each step of template produces output based on its (optional) input and options. Steps can be chained in order to generate the document and eventually transform it. All steps have always name and options based on one of the desired step. There are the details for steps supported by the document worker component:

TDK Config

Those are local-only metadata used for development of the template. You can use them in versioned template.json but those are never stored directly in DSW.

  • version: metadata version for needs of migrations

  • readmeFile: files used to get content for readme of the template, usually README.md

  • files: list of patterns to specify files that are part of the document template (it uses Git wildcard-match patterns, so you can also exclude files or directories)

Document Template Metamodel Versions

Here are described the changes in metamodel for template specification as well as document context so developers can easily update their templates to a newer metamodel version when needed. It is also possible to check JSON schemas in higher detail, see Metamodel Schemas.

Version 18.0 (since 4.29.0)

  • Renamed questionnaire to project

  • Renamed package to knowledgeModelPackage (to km_package in the objectified context)

  • Removed WidgetIntegration and ApiLegacyIntegration and replaced them with new PluginIntegration that can be used for both widget and API integrations (and also other types of integrations in the future, e.g., CLI or database integration). If you are using those legacy integrations, you need to rename them to PluginIntegration and reflect the following changes in the template:

  • Removed roles, permissions, and sources from user object in context

  • Value of StringReply (if value type is TextQuestionValueType) can be now with Markdown syntax. You can use markdown_html or markdown_plain helpers to get the value rendered as HTML or plain text, respectively.

Version 17.1 (since 4.26.0)

  • Added configurable instance properties for Document Templates, see ContextConfig.

Version 17.0 (since 4.22.0)

  • Switched to semantic versioning (MAJOR.MINOR) for document template metamodel in order to avoid unnecessary changes in template. For example, template for 17.2 will work with DSW that supports 17.MINOR where MINOR≥2; however, will not work with DSW that supports 17.0 or 17.1. All older versions are considered as MAJOR with MINOR=0.

  • Renamed ApiIntegration to ApiLegacyIntegration and introduced new ApiIntegration. Added optional raw field to IntegrationReply to support the new integration that allows to store response item from API directly.

  • Renamed props to variables (in all integrations and IntegrationQuestion).

  • Updated WeasyPrint dependency (used in Step: weasyprint) from 60.2 to 66.0 which may cause necessary changes in CSS formatting of HTML in order to produce identical PDF (esp. avoid height: 100% styling).

Version 16 (since 4.13.0)

  • Added validations for value questions.

Version 15 (since 4.12.0)

  • Added file question, questionnaire file, and file reply.

Version 14 (since 4.10.0)

  • Rearranged and enriched document context for clarity and completeness. If you are using the object-oriented document context (via to_context_obj), the changes will not affect you and you can start using new attributes/types; otherwise, you need to reflect the following changes in the passed document context ctx:

    • config, knowledgeModel, package, and report of context stay the same;

    • uuid, createdAt, and updatedAt are moved to new document object that contains additional fields, namely createdBy, documentTemplateId, formatUuid, and name;

    • questionnaireUuid (and other questionnaire* fields) and createdBy are moved to new questionnaire object where are additional fields, namely labels, createdAt, and updatedAt;

    • documentTemplateMetamodelVersion is renamed to metamodelVersion;

    • there are new lists users and groups containing the information about sharing and permissions of the project (i.e. what users have access to the project and with what permissions).

  • Added item select questions.

  • Added resource collections and pages, incl. change in resource page references.

Version 13 (since 4.3.0)

  • Removed states from templates.

Version 12 (since 4.1.0)

  • Dropped support of deprecated wkhtmltopdf (for PDF, weasyprint is used instead).

  • Changed several properties of Integration and IntegrationReply to optional (see Document Context).

Version 11 (since 3.20.0)

  • Removed recommendedPackageId from template metadata and shortName together with color from formats.

Version 10 (since 3.12.0)

  • New possible value types for value questions: DateTimeQuestionValueType, TimeQuestionValueType, EmailQuestionValueType, UrlQuestionValueType, and ColorQuestionValueType (no changes needed in existing KM-specific templates).

Version 9 (since 3.10.0)

  • If you are using integration object, the requestItemUrl is changed to itemUrl.

  • Integrations now have type, where the new Widget Integration has a different fields than API Integration (see schema).

Version 8 (since 3.8.0)

  • Annotations and integration HTTP headers are changed from dict-like object with string-string key and value to a list of string-string tuples. Be aware that now there can be more values with the same “key” but that is usually unlikely.

Version 7 (since 3.7.0)

  • Added description and project tags to the questionnaire object (if you do not need them, nothing has to be changed in the template).

Version 6 (since 3.6.0)

  • Integration item template replaced item name. In templates you probably need to rename for integrations the property itemUrl to responseItemUrl.

Version 5 (since 3.5.0)

  • All KM entities has now annotations (key-value dictionary). If you do not want to use those in your template, no changes are required.

Version 4 (since 3.2.0)

  • Levels are renamed into phases and are using UUIDs. Phases are as part of the KM in knowledgeModel.entities of the context.

  • Metrics are now also identified by UUID and part of the KM.

Version 3 (since 2.12.0)

  • Additional metadata about each replies has been added and structure of reply is changed (extra .value needed). In case you are using filters such as reply_str_value no changes are needed.

  • For integration reply, the type values are renamed IntegrationValue -> IntegrationType and PlainValue -> PlainType for consistency.

Version 2 (since 2.6.0)

  • Changed questionnaireReplies to use path-reply map and removed then redundant questionnaireRepliesMap from document context.

  • Replies for list of items question represented as list of UUIDs instead of size used for numeric indexing.

Version 1 (since 2.5.0)

  • Initial version of metamodel, introduced in DSW 2.5.0 as start of versioning.