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 documentsTemplates/Release/[name].{docx,xlsx}
to add a custom release document with an arbitrary name to each (unreleased) versionTemplates/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 variablename
{project.id}
: insert the propertyid
of an objectproject
Conditions and loops
{#condition}
…{/}
: insert the block within if the givencondition
is true{#items}
…{/}
: loop over a list ofitems
, 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
):
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):
Variable assignments
{$SET var = value}
: set the variablevar
to the givenvalue
Querying items
{$KQL items = query}
: resolve the KQL queryquery
and assign the resulting list of items to the template variableitems
Example:
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 variablertm
{$TRACE rtm: extraConfigName}
: uses the "extra" traceability configuration with the nameextraConfigName
, as defined in the advanced project document setting Requirements Traceability Matrix (underextraConfigurations
)
Example:
|
|
|
|
|
|
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
datetime
value | datetime
: renders the date/timevalue
in the default formatvalue | datetime:"yyyy-MM-dd"
: uses the specified format, based on the given Unicode date format stringvalue | datetime:"yyyy-MM-dd":"US/Eastern"
: uses the specified format and timezone, based on the given tz timezone ID
where
where
items | where:'...'
: filter the givenitems
based on the given filter expression; the expression can refer to properties of each item
Example:
sort
sort
items | sort:'...'
: sort the givenitems
based on the key determined by the given expression
Example (sorting items by their id
):
reverse
reverse
items | reverse
: reverse the order of the givenitems
Example (sorting items by their id
in reverse order):
group
group
items | group:'...'
: group the givenitems
based on the key determined by the given expression; the resulting list will contain entries with propertiesgroupKey
(the unique key of the group) andgroupItems
(list of items within that group)
Example (grouping items by their Requirement type and showing the item IDs in each group separately):
at
at
items | at:N
: returns the item at indexN
in the given list of items; the index is 0-based, so0
denotes the first item; negative indices count from the end, so-1
denotes the last itemobject | at:"..."
: returns the value for the given key in an object such as anItemRecord
'sfieldValue
object; this could also be done using "dot" access (object.property
), but thisat
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
):
Example (accessing a traceability column with a key containing a -
dash):
count
count
items | count
: returns the number of items in a given list or properties in a given object
join
join
values | join
: returns all the values in a list concatenated, using ", " as the separator between themvalues | join:"..."
: uses the given separator string between values in the list
Example (rendering list of items using a custom separator):
inMilestone
inMilestone
item | inMilestone
: determines whether an item is in the document's milestone
Example:
If the document is not generated for a particular milestone, inMilestone
returns true
.
inRegion
inRegion
item | inRegion
: determines whether an item is in the document's region
Example:
If the document is not generated for a particular region, inRegion
returns true
.
itemContent
itemContent
{~~ item | itemContent}
: display the givenitem
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 fieldsContext
andRequirement type
when rendering the item
Example:
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 givenpath
{:include $RELEASEDOC name}
: include the release document with the givenname
{:include $RELEASEDOC milestone / name}
: include the milestone document with the givenname
from the givenmilestone
{:include $RELEASEDOC project -> name}
: include a release document from a referenced project
Examples:
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 |
---|---|
| |
| |
| |
| |
| |
| list of |
| list of |
| list of |
| list of |
| list of |
| list of |
| list of |
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
Organization
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the organization |
| string | Organization name |
Project
Project
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the project |
| string | Project name |
ProjectReference
ProjectReference
Property | Type | Description |
---|---|---|
| number | Reference depth |
| Referenced project | |
| Referenced version |
Version
Version
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the version |
| string | Version name |
| string | Version number |
Milestone
Milestone
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the milestone |
| string | Milestone name |
| date | Creation date |
Document
Document
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the document |
| string | Document title |
| date | Generation date |
Item
Item
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the item |
| string | Jira issue key of the item |
ItemRecordCore
ItemRecordCore
The core data for an item record contains the following properties:
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the record |
| string | Document ID of the record |
| string | Title |
| string | Name of item type |
| string | Short name of item type |
| number | Record revision number |
| date | Record creation date |
|
| Diff of the item to the baseline version |
| list of string | Regions |
| string | Version number introducing this item |
| string | Version number obsoleting this item |
| boolean | Whether this record is in a controlled state |
| boolean | Whether this risk record has an acceptable risk |
| string | URL of the record's item record detail page |
| 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
ItemRecordFull
A full item record contains all the properties from ItemRecordCore
, plus the following:
Property | Type | Description |
---|---|---|
| string | Hash of the record contents (Base64-encoded SHA-256 value) |
| list of | Relations from or to this record |
| list of | Approvals of this record |
| object | Rendered content of each field |
| 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:
Relation
Relation
Property | Type | Description |
---|---|---|
| string | Relation name |
| Respective record of the related item | |
| string | Title |
TraceabilityMatrix
TraceabilityMatrix
Property | Type | Description |
---|---|---|
| list of | Rows in the traceability matrix |
| list of | Results of checks performed in the traceability matrix |
| boolean | Whether all checks are fulfilled, i.e. the matrix is "green" |
TraceabilityCheck
TraceabilityCheck
Property | Type | Description |
---|---|---|
| string | Title of the check |
| number | Progress percentage (0 – 100) |
| string | Description of the check |
| boolean | Whether the check is complete upon reaching 100% |
| boolean | Whether the check is complete |
TraceabilityRow
TraceabilityRow
Property | Type | Description |
---|---|---|
| object containing | 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
TraceabilityCell
Property | Type | Description |
---|---|---|
| Item associated with this cell | |
| Test status associated with this cell |
TestStatus
TestStatus
Property | Type | Description |
---|---|---|
| string | Title of this test |
| boolean | Whether this test is in the test plan |
| Test Case item associated with this test (if any) | |
| date | Execution time stamp (if any) |
|
| Effective test result (if any) |
| list of | Effective manual test executions |
| list of | Effective automated test executions |
| list of | All manual test executions, including not effective ones |
AutomatedTestExecution
AutomatedTestExecution
Property | Type | Description |
---|---|---|
| string | Title of this automated test |
| date | Timestamp |
|
| Test status result |
ApprovalData
ApprovalData
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the approval |
| date | Timestamp |
| date | Timestamp of the revocation, if the approval was revoked |
| Approving user | |
| date | Approved item record, if the approval was for an item record |
| Approved version, if the approval was for a version |
User
User
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the user |
| string | Full name of the user |
| string | Email of the user |
TrainingStatus
TrainingStatus
Property | Type | Description |
---|---|---|
| User the training status is for | |
| list of string | Names of groups the user is a member of |
| list of | Training status for each relevant document |
TrainingStatusDocument
TrainingStatusDocument
Property | Type | Description |
---|---|---|
| Document being trained on | |
| Latest acknowledgement of the document by the user |
TrainingDocument
TrainingDocument
Property | Type | Description |
---|---|---|
| Relevant record of the training document | |
| list of | Approvals of the document |
Vulnerability
Vulnerability
Property | Type | Description |
---|---|---|
| Vulnerability information | |
| string | Rendered content for the vulnerability description |
| Data associated with the vulnerability | |
| Dependency affected by the vulnerability | |
| list of | Linked risks |
| list of | 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
VulnerabilityInfo
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the vulnerability |
| string | Summary |
| string | Description (raw value) |
| number | Numerical severity rating |
| string | Affected version |
| list of string | Vulnerability URLs |
| string | External ID of the vulnerability |
| date | Date the vulnerability was published |
Dependency
Dependency
Property | Type | Description |
---|---|---|
| string | Name of the dependency |
| string | A |
| string | A |
| string | Earliest used version of the dependency |
| string | Latest used version of the dependency |
| string | Latest available version of the dependency |
| string | Accepted versions of the dependency |
| string | Review status of the dependency |
| string | Level of risk of the dependency |
| string | Repository issues URL of the dependency |
| string | Manufacturer of the dependency |
| string | License of the dependency |
| string | Intended use of the dependency |
| string | Security impact of the dependency |
| string | Security impact justification of the dependency |
| string | Reliability impact of the dependency |
| string | Reliability impact justification of the dependency |
| string | Additional notes of the dependency |
| Related requirements of the dependency | |
| Related software items of the dependency | |
| Related risks of the dependency | |
| Related tests of the dependency | |
| Associated library | |
| list of | Information for vulnerabilities of the dependency |
| string | Manual vulnerabilities of the dependency |
Library
Library
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the library |
| string | Name of the library |
| string | Unique identifier of the library's registry |
| string | URL of the library's registry |
| string | Ecosystem name of the library |
Last updated