Document Templating

Reference of the document templating mechanism in Ketryx

Ketryx can generate highly customizable documents based on user-managed templates in the form of Word or Excel files.

Getting started

To get started with custom templates in Ketryx:

Navigate to a project's Documents page
Create a folder called Templates
Create a folder called Release inside the Templates folder
Upload the sample file sample-template.docx into the Release folder

Create a few Requirement items and a new version, and navigate to the version's Documents page. The document sample-template.docx should show up as another release document that can be generated and approved.

Template locations

Templates are managed in dedicated folders in the Documents section:

Templates/System/[name].{docx,xlsx} with [name] being the name of a system document type, to override the built-in rendering of those documents
Templates/Release/[name].{docx,xlsx} to add a custom release document with an arbitrary name to each (unreleased) version
Templates/Milestones/[milestone]/[name].{docx,xlsx} to add a custom document with an arbitrary name to milestones that match the name [milestone]

The following system documents can be overwritten inside the Templates/System folder:

Authority Matrix
Change Management File
Change Request Verification Report
Code Review Report
Cyber Risk Management File
Problem Report
Release History
Release Notes
Risk Control Matrix
Risk Management File
Risk Matrix
System Architecture Chart
System Design Specification
System Design Structure Matrix
System Requirements Specification
SBoM SOUP Software Configuration Report
Test Plan
Testing Report
Traceability Matrix
Unresolved Anomalies

Template-based release documents are considered out of date when any active records in the relevant project and version change. This may result in documents being indicated as requiring an update, even if regenerating them does not ultimately result in different document content. If this enforcement is too strict, the release control Require up-to-date release documents in the project settings can be deactivated.

Template tags

A template can be a Word or Excel file with any user-defined content. Certain tags delimited by {...} are recognized by the Ketryx document generator and can be used to insert dynamic data from a Ketryx project into the document. The template syntax is inspired by the Mustache template language.

Data

{name}: insert template variable name
{project.id}: insert the property id of an object project

Conditions and loops

{#condition} … {/}: insert the block within if the given condition is true
{#items} … {/}: loop over a list of items, inserting the block within for each of them

Conditions and loops are expressed using the same template syntax. Whether data is looped over depends on whether it is a list.

In the block inside a loop, the properties of the item that is currently iterated over become available as template variables. Example (showing the id of each of the iterated items):

{#items}
{id}
{/}

The item as a whole object is available using the special syntax . (a literal dot).

Loops can be used in tables (including Excel files) to create multiple rows, by putting the starting tag (e.g., {#items}) in the starting cell, and the ending tag {/} on another cell to right in the same row. Example:

The ending tag {/} is shorthand for repeating the full expression as in {#items} … {/items}.

If a variable is not set, a corresponding condition hides the contained block. This can be used to "comment out" a part of a document. Example (assuming there is no variable HIDDEN defined):

{#HIDDEN}
some text that will not be in the generated document
{/HIDDEN}

Variable assignments

{$SET var = value}: set the variable var to the given value

Querying items

{$KQL items = query}: resolve the KQL query query and assign the resulting list of items to the template variable items
{$KQL @version:version items = query}: resolve the KQL query query for the given version (specified by its Ketryx ID or by its full name)
{$KQL @version:(version1,version2) items = query}: resolve the KQL query query for several versions (concatenating the list of all records)
{@$KQL items = query}: resolve the KQL query query without leaving an empty line

Examples:

{$KQL reqs = type:Requirement}
{#reqs}
* {title}
{/}

{@$KQL items = (RQ and diff:new) CR}
{#items}
* {title}
{/}

{@$KQL @version:("Version 1.0","Version 2.0") items = RQ}
{#items}
* {title}
{/}

Each item in the resulting list has the data type ItemRecordFull.

$KQL expressions are only supported at the "top level" of the document structure, not inside other loops or conditions.

Traceability matrices

{$TRACE rtm}: stores data from the project's requirements traceability matrix in the template variable rtm
{$TRACE @version:version rtm}: compute traceability for the given version (specified by its Ketryx ID or by its full name)
{$TRACE rtm: extraConfigName}: uses the "extra" traceability configuration with the name extraConfigName, as defined in the advanced project document setting Requirements Traceability Matrix (under extraConfigurations)

Example:

{$TRACE rtm}

The resulting object has the type TraceabilityMatrix.

$TRACE expressions are only supported at the "top level" of the document structure, not inside other loops or conditions.

Expressions

Conditions (as in {#expr}) and some filters (such as where : expr) involve expressions. Expressions may involve constants (e.g., "John", 42) as well as access to template data and properties (e.g. project.id). They may contain the following operators:

ternaries: a ? b : c
equality/inequality: a == b, a != b
relational: a > b, a < b, a >= b, a <= b
logical AND: a && b
logical OR: a || b
addition: a + b
subtraction: a - b
multiplication: a * b
division: a / b

Parenthesis can be used for grouping, to enforce a particular operator precedence.

Filters

Filters can be used to transform data before it is displayed or used in a condition or loop.

Filters are applied to values using the | operator, potentially followed by one or more arguments separated by :.

The following filters are available:

`datetime`

value | datetime: renders the date/time value in the default format
value | datetime:"yyyy-MM-dd": uses the specified format, based on the given Unicode date format string
value | datetime:"yyyy-MM-dd":"US/Eastern": uses the specified format and timezone, based on the given tz timezone ID

`where`

items | where:'...': filter the given items based on the given filter expression; the expression can refer to properties of each item

Example:

{#items | where:'typeName=="Requirement"'}
{id}
{/}

`sort`

items | sort:'...': sort the given items based on the key determined by the given expression

When using this to sort by a string, there is no numeric collation and file_100.docx would be sorted before file_11.docx. To sort using numeric collation use sortByNumericTextField.

Example (sorting items by their id):

{#items | sort:'id'}
{id}
{/}

`sortByNumericTextField`

items | sortByNumericTextField:'...': sort the given items based on the key determined by the given expression

When using this to sort by a string, numeric collation would sort file_11.docx before file_100.docx.

Example (sorting items by their id):

{#items | sortByNumericTextField:'id'}
{id}
{/}

`reverse`

items | reverse: reverse the order of the given items

Example (sorting items by their id in reverse order):

{#items | sort:'id' | reverse}
{id}
{/}

`group`

items | group:'...': group the given items based on the key determined by the given expression; the resulting list will contain entries with properties groupKey (the unique key of the group) and groupItems (list of items within that group)

Example (grouping items by their Requirement type and showing the item IDs in each group separately):

{#items | group:"fieldValue.Requirement_type"}
{groupKey}

{#groupItems}
{id}
{/}

{/}

`at`

items | at:N: returns the item at index N in the given list of items; the index is 0-based, so 0 denotes the first item; negative indices count from the end, so -1 denotes the last item
object | at:"...": returns the value for the given key in an object such as an ItemRecord's fieldValue object; this could also be done using "dot" access (object.property), but this at filter can be useful for computed property names or names that contain spaces or other special characters

Example (accessing an object property for each vulnerability, equivalent to info.summary):

{#vulnerabilities}
{info | at:"summary"}
{/}

Example (accessing a traceability column with a key containing a - dash):

{(columns | at:"system-requirements").itemRecord.docId}

`count`

items | count: returns the number of items in a given list or properties in a given object

`join`

values | join: returns all the values in a list concatenated, using ", " as the separator between them
values | join:"...": uses the given separator string between values in the list

Example (rendering list of items using a custom separator):

{#trainingStatus}
{groupNames | join:" - "}
{/}

`inMilestone`

item | inMilestone: determines whether an item is in the document's milestone

Example:

{#items | where:'. | inMilestone'}
{id}
{/}

If the document is not generated for a particular milestone, inMilestone returns true.

`inRegion`

item | inRegion: determines whether an item is in the document's region

Example:

{#items | where:'. | inRegion'}
{id}
{/}

If the document is not generated for a particular region, inRegion returns true.

`itemContent`

{~~ item | itemContent}: display the given item using the standard Ketryx rendering
{~~ item | itemContent:"HEADINGS +2"}: shift the levels of headings in item content by 2 levels, to account for nested headings in the template itself while maintaining a sensible navigation hierarchy
{~~ item | itemContent:"OMIT Context,Requirement type"}: omit the fields Context and Requirement type when rendering the item

Example:

{#items}
{~~ . | itemContent}
{/}

Note the use of . to refer to the currently iterated item, and the use of ~~ to render rich-text (HTML) content. If you omit the ~~ prefix, you might see raw HTML code in the generated file.

Inserting other documents

{:include $DOC path}: include the EDMS document with the given path
{:include $RELEASEDOC name}: include the release document with the given name
{:include $RELEASEDOC milestone / name}: include the milestone document with the given name from the given milestone
{:include $RELEASEDOC project -> name}: include a release document from a referenced project

Examples:

{:include $DOC Some folder/Subfolder/Document A}

{:include $RELEASEDOC Test Plan}

{:include $RELEASEDOC First milestone / Test Plan}

{:include $RELEASEDOC Other project -> Test Plan}

Template variables are also available in the specified path with a $ prefix. However, arbitrary expressions are not supported, to avoid ambiguity with regards to where the expression would end. This can be circumvented by assigning an expression to another variable using $SET and using that in the included document path.

Included documents inherit the styling of the containing template document, including any named styles. For instance, paragraphs using the Normal style in the included document will be formatted according to the definition of the Normal style in the template.

Summarizing items

This is an experimental feature based on an LLM and not validated. Use at your own risk. Always manually check if summaries are accurate.

The $SUMMARIZE command allows summarizing an array of objects of the type ItemRecordFull into a textual summary using an LLM. This command is only available for projects that have Enable AI setting turned on in advanced settings.

{$SUMMARIZE mySummary = itemRecords:myItems}: summarize the item records saved in the variable myItems and store the result in the variable mySummary
{$SUMMARIZE mySummary = itemRecords:myItems totalWordTarget:200}: summarize the item records saved in the variable myItems with a total target of 200 words
{$SUMMARIZE mySummary = itemRecords:myItems wordTargetPerItem:20 instructions:"Some special instructions." systemPromptOverride:"Some special system prompt."}: summarize the item records saved in the variable myItems with a target of 20 words per item, special instructions, and a special system prompt

Example:

{@$KQL items = (RQ and diff:new) CR}
{@$SUMMARIZE summary = itemRecords:items totalWordTarget:500 instructions:”Summarize the given items into a release note summary. Do not use bullet points. Use paragraphs. End each paragraph with two newline characters. Add 2 lines between each paragraph.”}
{~~ summary}

Adding an @ symbol before the $KQL and $SUMMARIZE commands will prevent them from leaving an empty line. Without using the @ symbol, we would have to write all three commands into a single line, which hurts readability.

Template data

Templates receive data based on the containing project, version, etc. See the section on Data types below for more information about each type and its available fields.

In addition, templates may query for certain items in a project using the $KQL tag (as explained here).

Data types

Data in templates consists of objects (with certain properties), lists, strings, numbers, and dates. The following object types may appear.

`Organization`

`Project`

`ProjectReference`

`Version`

`Milestone`

`MeetingNote`

`Document`

`Item`

`ItemRecordCore`

The core data for an item record contains the following properties:

For controlled records, controlledRevision counts the number of controlled records so far (starting with 1 for the first controlled record), and uncontrolledRevision is 0. For uncontrolled records, controlledRevision is the controlled revision counter of the upcoming controlled revision (i.e., the controlled revision worked on towards), and uncontrolledRevision counts the number of revisions since the previous controlled revision. These counters can be used to establish a record numbering scheme such as 1-1 (first draft towards the first controlled record), 1-2, …, 1-0 (first controlled record), 2-1, etc.

Some other properties that are more expensive to compute are only exposed under ItemRecordFull, to improve performance and avoid a potential infinite recursion.

`ItemRecordFull`

A full item record contains all the properties from ItemRecordCore, plus the following:

The keys in the objects fieldContent, fieldValue, fieldChanged, and fieldContentDiff are field names, where spaces are replaced by underscores (_), e.g., Rationale_for_deferring_resolution.

The values in fieldContent and fieldContentDiff are pieces of rich-text (HTML) content that need to be rendered with a ~~ prefix, similarly to the itemContent filter. Example:

{~~ item.fieldContent.Rationale_for_deferring_resolution}

The raw Xray data exposed in xrayData is not currently documented in detail, as it might change depending on their data structure.

`Attachment`

The value in renderedContent is a piece of rich-text HTML that can be rendered with a ~~ prefix, similarly to the itemContent filter. If isImage is true, then {~~renderedContent} will render an image; otherwise, it will render a link to the resource, using the filename as the displayed text.

`TestRun`

`TestStep`

Content fields such as actionContent, dataContent, resultContent, actualResultContent, commentContent are pieces of rich-text HTML that can be rendered with a ~~ prefix, similarly to the itemContent filter.

Actual results and evidence are only available for steps on a TestRun, but not on the ItemRecordFull of the underlying Test Case.

`Relation`

`TraceabilityMatrix`

`TraceabilityCheck`

`TraceabilityRow`

To access the values of columns using dot property access (e.g., columns.useCase), make sure they don't contain special characters such as spaces or -. Otherwise, direct property access does not work, and the at filter should be used instead.

`TraceabilityCell`

`TestStatus`

`AutomatedTestExecution`

`ApprovalData`

`User`

`TrainingStatus`

`TrainingStatusDocument`

`TrainingDocument`

`Vulnerability`

The value of descriptionContent is a piece of rich-text (HTML) content that needs to be rendered with a ~~ prefix, similarly to the fieldContent field of ItemRecordFull and the itemContent filter. This is the HTML version of the raw value of info.description.

`VulnerabilityInfo`

`Dependency`

`Library`

PreviousTraceability Configuration NextProject Settings

Last updated 19 days ago