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:

1. Navigate to a project's Documents page

2. Create a folder called Templates

3. Create a folder called Release inside the Templates folder

4. Upload the sample file sample-template.docx into the Release folder

20KB

sample-template.docx

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:

ID	Title	Type
{#items}{id}	{title}	{typeName}{/}

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}

Req ID	Spec ID	Test Title
{#rtm.rows}{columns.req.itemRecord.docId}	{columns.spec.itemRecord.docId}	{columns.test.testStatus.title}{/}

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.

Variable	Type
organization	Organization
project	Project
version	Version
milestone	Milestone
milestones	list of Milestone
document	Document
dependencies	list of Dependency
vulnerabilities	list of Vulnerability
trainingStatus	list of TrainingStatus
trainingDocuments	list of TrainingDocument
approvals	list of ApprovalData
projectReferences	list of ProjectReference
versions	list of Version

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

Property	Type	Description
id	string	Ketryx ID of the organization
name	string	Organization name

Project

Property	Type	Description
id	string	Ketryx ID of the project
name	string	Project name

ProjectReference

Property	Type	Description
depth	number	Reference depth
project	Project	Referenced project
version	Version	Referenced version

Version

Property	Type	Description
id	string	Ketryx ID of the version
name	string	Version name
versionNumber	string	Version number

Milestone

Property	Type	Description
id	string	Ketryx ID of the milestone
name	string	Milestone name
meetingNotes	list of MeetingNote	Meeting notes for this milestone
configurationItems	list of ItemRecordCore	Items associated with this milestone
completedAt	date	Completion date
createdAt	date	Creation date

MeetingNote

Property	Type	Description
id	string	Ketryx ID of the meeting note
content	string	Content rendered to HTML
date	date	Date of the meeting
participants	string	Plain text string containing meeting participants

Document

Property	Type	Description
id	string	Ketryx ID of the document
title	string	Document title
date	date	Generation date

Item

Property	Type	Description
id	string	Ketryx ID of the item
jiraIssueKey	string	Jira issue key of the item

ItemRecordCore

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

Property	Type	Description
id	string	Ketryx ID of the record
docId	string	Document ID of the record
title	string	Title
typeName	string	Name of item type
typeShortName	string	Short name of item type
revision	number	Record revision number
controlledRevision	number	Controlled revision counter
uncontrolledRevision	number	Uncontrolled revision counter
status	string	Status name
createdAt	date	Record creation date
diff	"NEW", "CHANGED", "REMOVED", "SAME"	Diff of the item to the baseline version
regions	list of string	Regions
introducedInVersion	string	Version number introducing this item
obsoleteInVersion	string	Version number obsoleting this item
isControlled	boolean	Whether this record is in a controlled state
isRiskAcceptable	boolean	Whether this risk record has an acceptable risk
url	string	URL of the record's item record detail page
item	Item	Item

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:

Property	Type	Description
contentSha256	string	Hash of the record contents (Base64-encoded SHA-256 value)
relations	list of Relation	Relations from or to this record
approvals	list of ApprovalData	Approvals of this record
attachments	list of Attachment	Attachments to this record
fieldContent	object	Rendered content of each field
fieldValue	object	Raw value of each field
fieldChanged	boolean	Whether the value of each field changed compared to the baseline release
fieldContentDiff	object	Rendered content of the difference ("diff" or "redline") of each field compared to the baseline release
steps	list of TestStep	Information for each step on an (Xray) Test Case
testEnvironments	list of string	Test environments associated with an (Xray) Test Case
testRuns	list of TestRun	Information for each test run on an (Xray) Test Execution
xrayData	object	Raw data from Xray

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

Property	Type	Description
id	string	ID of the resource
filename	string	File name associated with the resource
sizeBytes	number	File size in bytes
contentType	string	Content type (as a media type)
contentSha256	string	Hash of the file contents (Base64-encoded SHA-256 value)
createdAt	date	Timestamp of creation
url	date	Timestamp of creation
renderedContent	date	Timestamp of creation
isImage	boolean	Whether the resource is an image

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

Property	Type	Description
statusName	string	Status name
executedBy	User	User who executed this test run (if available)
assignee	User	User who was assigned this test run (if available)
steps	list of TestStep	Information for each step of the executed test
test	ItemRecordCore	Test Case being executed
testExecution	ItemRecordCore	Test Execution containing this test run
evidence	list of Attachment	Evidence attached to this test run
xrayData	object	Raw data from Xray

TestStep

Property	Type	Description
statusName	string	Status name (from Xray)
action	string	Raw value of the action field
actionContent	object	Formatted content for the action field
data	string	Raw value of the data field
dataContent	object	Formatted content for the data field
result	string	Raw value of the result field
resultContent	object	Formatted content for the result field
actualResult	string	Raw value of the actual result field
actualResultContent	object	Formatted content for the actual result field
comment	string	Raw value of the comment field
commentContent	object	Formatted content for the comment field
evidence	list of Attachment	Evidence attached to this step
attachments	list of Attachment	Other attachments on this step
statusName	string	Status name (from Xray)
xrayData	object	Raw data from Xray

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

Property	Type	Description
name	string	Relation name
other	ItemRecordCore	Respective record of the related item
isReverse	boolean	Whether the relation is a reverse relation, i.e. the other item is the source item of the relation

TraceabilityMatrix

Property	Type	Description
rows	list of TraceabilityRow	Rows in the traceability matrix
checks	list of TraceabilityCheck	Results of checks performed in the traceability matrix
isFulfilled	boolean	Whether all checks are fulfilled, i.e. the matrix is "green"

TraceabilityCheck

Property	Type	Description
title	string	Title of the check
progress	number	Progress percentage (0 – 100)
description	string	Description of the check
isPositiveProgress	boolean	Whether the check is complete upon reaching 100%
isComplete	boolean	Whether the check is complete

TraceabilityRow

Property	Type	Description
columns	object containing TraceabilityCell	Data for each cell in the row, using each column's ID as the key

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

Property	Type	Description
itemRecord	ItemRecordFull	Item associated with this cell
testStatus	TestStatus	Test status associated with this cell

TestStatus

Property	Type	Description
title	string	Title of this test
isInTestPlan	boolean	Whether this test is in the test plan
testCase	ItemRecordCore	Test Case item associated with this test (if any)
executedAt	date	Execution time stamp (if any)
result	"FAIL", "FAIL_ACCEPTED", "PASS", "PASS_WITH_EXCEPTION"	Effective test result (if any)
manualExecutions	list of ItemRecordCore	Effective manual test executions
automatedExecutions	list of AutomatedTestExecution	Effective automated test executions
allManualExecutions	list of ItemRecordCore	All manual test executions, including not effective ones

AutomatedTestExecution

Property	Type	Description
title	string	Title of this automated test
createdAt	date	Timestamp
result	"FAIL", "FAIL_ACCEPTED", "PASS", "PASS_WITH_EXCEPTION"	Test status result

ApprovalData

Property	Type	Description
id	string	Ketryx ID of the approval
createdAt	date	Timestamp
revokedAt	date	Timestamp of the revocation, if the approval was revoked
approver	User	Approving user
record	date	Approved item record, if the approval was for an item record
version	Version	Approved version, if the approval was for a version

User

Property	Type	Description
id	string	Ketryx ID of the user
name	string	Full name of the user
email	string	Email of the user

TrainingStatus

Property	Type	Description
user	User	User the training status is for
groupNames	list of string	Names of groups the user is a member of
documents	list of TrainingStatusDocument	Training status for each relevant document

TrainingStatusDocument

Property	Type	Description
document	TrainingDocument	Document being trained on
latestAcknowledgement	ApprovalData	Latest acknowledgement of the document by the user

TrainingDocument

Property	Type	Description
record	ItemRecordCore	Relevant record of the training document
approvals	list of ApprovalData	Approvals of the document

Vulnerability

Property	Type	Description
info	VulnerabilityInfo	Vulnerability information
descriptionContent	string	Rendered content for the vulnerability description
record	ItemRecordFull	Data associated with the vulnerability
dependency	Dependency	Dependency affected by the vulnerability
relatedRisks	list of ItemRecordFull	Linked risks
relatedMitigations	list of ItemRecordFull	Linked mitigations

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

Property	Type	Description
id	string	Ketryx ID of the vulnerability
summary	string	Summary
description	string	Description (raw value)
severity	number	Numerical severity rating
version	string	Affected version
urls	list of string	Vulnerability URLs
externalId	string	External ID of the vulnerability
publishedDate	date	Date the vulnerability was published

Dependency

Property	Type	Description
name	string	Name of the dependency
declaredVersions	string	A ;-separated list of all declared versions of the dependency
lockedVersions	string	A ;-separated list of all locked versions of the dependency
earliestUsedVersion	string	Earliest used version of the dependency
latestUsedVersion	string	Latest used version of the dependency
latestAvailableVersion	string	Latest available version of the dependency
acceptedVersions	string	Accepted versions of the dependency
status	string	Review status of the dependency
riskLevel	string	Level of risk of the dependency
issuesUrl	string	Repository issues URL of the dependency
manufacturer	string	Manufacturer of the dependency
license	string	License of the dependency
intendedUse	string	Intended use of the dependency
securityImpact	string	Security impact of the dependency
securityImpactJustification	string	Security impact justification of the dependency
reliabilityImpact	string	Reliability impact of the dependency
reliabilityImpactJustification	string	Reliability impact justification of the dependency
additionalNotes	string	Additional notes of the dependency
relatedRequirements	ItemRecordCore	Related requirements of the dependency
relatedSoftwareItems	ItemRecordCore	Related software items of the dependency
relatedRisks	ItemRecordCore	Related risks of the dependency
relatedTests	ItemRecordCore	Related tests of the dependency
library	Library	Associated library
vulnerabilityInfos	list of VulnerabilityInfo	Information for vulnerabilities of the dependency
manualVulnerabilities	string	Manual vulnerabilities of the dependency

Library

Property	Type	Description
id	string	Ketryx ID of the library
name	string	Name of the library
registry	string	Unique identifier of the library's registry
registryUrl	string	URL of the library's registry
ecosystem	string	Ecosystem name of the library