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 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

Example:

{$KQL reqs = type:Requirement}
{#reqs}
* {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 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

Example (sorting items by their id):

{#items | sort:'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.

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
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
createdAt	date	Creation date

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
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

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
fieldContent	object	Rendered content of each field
fieldValue	object	Raw value of each field

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

The values in fieldContent 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}

Relation

Property	Type	Description
name	string	Relation name
other	ItemRecordCore	Respective record of the related item
title	string	Title

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	ItemRecordCore	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