Document Templating
Reference of the document templating mechanism in Ketryx
Last updated
Reference of the document templating mechanism in Ketryx
Last updated
© 2024 Ketryx Corporation
Ketryx can generate highly customizable documents based on user-managed templates in the form of Word or Excel files.
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.
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.
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.
{name}
: insert template variable name
{project.id}
: insert the property id
of an object project
{#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
):
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):
{$SET var = value}
: set the variable var
to the given value
{$KQL items = query}
: resolve the KQL query query
and assign the resulting list of items to the template variable items
{@$KQL items = query}
: resolve the KQL query query
without leaving an empty line
Examples:
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.
{$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:
|
|
|
|
|
|
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.
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 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:
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
):
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
):
reverse
items | reverse
: reverse the order of the given items
Example (sorting items by their id
in reverse order):
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):
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
):
Example (accessing a traceability column with a key containing a -
dash):
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):
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
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
{~~ 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:
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.
{: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:
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.
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:
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.
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 |
| list of |
In addition, templates may query for certain items in a project using the $KQL
tag (as explained here).
Data in templates consists of objects (with certain properties), lists, strings, numbers, and dates. The following object types may appear.
Organization
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the organization |
| string | Organization name |
Project
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the project |
| string | Project name |
ProjectReference
Property | Type | Description |
---|---|---|
| number | Reference depth |
| Referenced project | |
| Referenced version |
Version
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the version |
| string | Version name |
| string | Version number |
Milestone
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the milestone |
| string | Milestone name |
| list of | Meeting notes for this milestone |
| list of | Items associated with this milestone |
| date | Completion date |
| date | Creation date |
MeetingNote
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the meeting note |
| string | Content rendered to HTML |
| date | Date of the meeting |
| string | Plain text string containing meeting participants |
Document
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the document |
| string | Document title |
| date | Generation date |
Item
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the item |
| string | Jira issue key of the item |
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 |
| number | Controlled revision counter |
| number | Uncontrolled revision counter |
| string | Status name |
| 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 |
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 |
---|---|---|
| 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 |
| list of | Attachments to this record |
| object | Rendered content of each field |
| object | Raw value of each field |
| boolean | Whether the value of each field changed compared to the baseline release |
| object | Rendered content of the difference ("diff" or "redline") of each field compared to the baseline release |
| list of | Information for each step on an (Xray) Test Case |
| list of string | Test environments associated with an (Xray) Test Case |
| list of | Information for each test run on an (Xray) Test Execution |
| 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:
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 |
---|---|---|
| string | ID of the resource |
| string | File name associated with the resource |
| number | File size in bytes |
| string | Content type (as a media type) |
| string | Hash of the file contents (Base64-encoded SHA-256 value) |
| date | Timestamp of creation |
| date | Timestamp of creation |
| date | Timestamp of creation |
| 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 |
---|---|---|
| string | Status name |
| User who executed this test run (if available) | |
| User who was assigned this test run (if available) | |
| list of | Information for each step of the executed test |
| Test Case being executed | |
| Test Execution containing this test run | |
| list of | Evidence attached to this test run |
| object | Raw data from Xray |
TestStep
Property | Type | Description |
---|---|---|
| string | Status name (from Xray) |
| string | Raw value of the action field |
| object | Formatted content for the action field |
| string | Raw value of the data field |
| object | Formatted content for the data field |
| string | Raw value of the result field |
| object | Formatted content for the result field |
| string | Raw value of the actual result field |
| object | Formatted content for the actual result field |
| string | Raw value of the comment field |
| object | Formatted content for the comment field |
| list of | Evidence attached to this step |
| list of | Other attachments on this step |
| string | Status name (from Xray) |
| 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 |
---|---|---|
| string | Relation name |
| Respective record of the related item | |
| string | Title |
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
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
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
Property | Type | Description |
---|---|---|
| Item associated with this cell | |
| Test status associated with this cell |
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
Property | Type | Description |
---|---|---|
| string | Title of this automated test |
| date | Timestamp |
|
| Test status result |
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
Property | Type | Description |
---|---|---|
| string | Ketryx ID of the user |
| string | Full name of the user |
| string | Email of the user |
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
Property | Type | Description |
---|---|---|
| Document being trained on | |
| Latest acknowledgement of the document by the user |
TrainingDocument
Property | Type | Description |
---|---|---|
| Relevant record of the training document | |
| list of | Approvals of the document |
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
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
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
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 |