Syntax reference

Name Short Description
areaPath Generates prettier output of Area Path values.
attachments Lists attachments of current work item.
comments Output comments linked to the current work item.
commits Output commits linked to the current work item.
count Outputs the number of work items in the current context.
date Outputs the current date.
field Outputs a work item field value.
filter Filters the current list of work items.
group Allows grouping work items by a specified field.
if-field Checks if a field value has a value or checks if the value meets a defined condition.
if-param Checks if a parameter value has a value or checks if the value meets a defined condition.
images Lists image attachments of current work item.
import Imports text from a file within a git repository or from a remote URL.
index Outputs a 1-based index to help when iterating over items.
commits Output issues from Jira.
iterationPath Generates prettier output of Iteration Path values.
commits Output commits linked to the current work item.
link Output a link to the current work item
links Output linked work items.
pageBreak Forces a page break when exporting as PDF
param Outputs a parameter value anywhere in your template
section Separate work items into sections.
sum Sums up values of the specified field in all work items in the current context.
tags Iterate of all tags of the current work item.
testSteps Iterate of all tests steps of a Test Case work item.
andlebars
when For the most part we recommend using custom labels to segment work items in your documents.
wikiLinks Output all links to wiki pages.
workItem Pulls in a single work item by its ID.
workItems Iterates over all work items in the current context.

areaPath

Generates prettier output of Area Path values.

{{!-- output area path of current work item  --}}

{{#workItems}}

- {{{ areaPath  }}}                     {{!-- Project\Accounting\Receipts  --}}
- {{{ areaPath separator=' > ' }}}      {{!-- Project > Accounting > Receipts  --}}
- {{{ areaPath display='last' }}}       {{!-- Receipts --}}

{{/workItems}}

As shown above you can use the areaPath helper inside a workItems block to output the value of the Area Path field of the current work item with more control.

The below example shows how you can use the areaPath helper to output the Area Path value together with the group helper.

{{#group 'AreaPath'}}

{{#each groups}}

{{!-- output area path value when grouping by area path  --}}

Area: {{{areaPath $key separator=' / '}}}

{{#workItems}}
- {{{ field 'Title' }}}
{{/workItems}}

{{/each}}

{{/group}}

When grouping by Area Path we have the actual Area Path value available via the $key variable. As we are not in the context of a work item we need to give a Area Path value to the areaPath helper as the first literal argument helper so it knows what to output.

areaPath helper options

Option Type Purpose Example
value literal argument optional value if not in the context of a work item {{areaPath $key }}
separator hash argument separator string to use when outputting the area path value {{areaPath separator=' > ' }}
display hash argument display mode to use. "last" : displays only the last segment of the path value {{areaPath display='last' }}

attachments

Lists attachments of current work item.

{{#workItems}}
{{#attachments}}
    [{{title}}]({{url}})
{{/attachments}}
{{/workItems}}

Attachment properties

property Explanation
comment comment provided when attachment was uploaded to work item
name file name of the attachment
url full URL of the attachment - only accessible when logged into Azure DevOps

comments

Output comments linked to the current work item.

{{#workItems}}

### {{{field 'Title' }}}

{{#comments top=2}}

- {{id}} - {{author.name}} - {{message}}

{{/comments}}

{{/workItems}}

commits

Output commits linked to the current work item.

{{#workItems}}

### {{field 'Title' }}

{{#commits}}

- {{id}} - {{author.name}} - {{message}}

{{/commits}}

{{/workItems}}

count

Outputs the number of work items in the current context.

The below example outputs the number of all work items before listing them.

{{count}} work items:

{{#workItems}}
- {{title}}
{{/workItems}}

The next example outputs the number work items in different sections.

{{#section '$UserStory'}}

{{count}} stories:

{{#workItems}}
- {{title}}
{{/workItems}}

{{/section}}

{{#section '$Bug'}}

{{count}} bugs:

{{#workItems}}
- {{title}}
{{/workItems}}

{{/section}}

Finally you can output counts of work items by label with this shorthand version of the count helper:

- User Stories: {{count '$UserStory'}}
- Bugs: {{count '$Bug'}}
- Major features: {{count 'major'}}
- Minor features: {{count 'minor'}}
- Frontend bugs: {{count '$Bug frontend'}}

count helper options

Option Type Purpose Example
label literal argument

date

Outputs the current date.

Today was: {{date}}  

{{!-- Today was: Sat Mar 28 2020 --}}

The date is output using the en-US locale as a short date string.

To gain more control over how the date (and time) is output the format argument can be used:

Today was: {{date format='dd.mm.yyyy' }}  

{{!-- Today was: 28.03.2020 --}}

A full reference of date formatting options can be found here.

date helper options

Option Type Purpuse Example
format hash argument date / time format string {{date format='dd.mm.yyyy' }}

field

Outputs a work item field value.

{{#workItems}}

{{ field 'Title' }}                        {{!-- A work item --}}
{{{ field 'Description' }}}                  {{!-- <p>Some description HTML content</p> --}}
{{{ field 'Custom.VideoURL' }}}    {{!-- Custom field value --}}

{{/workItems}}

Use tiple curly braces {{{ }}} when outputting HTML field content.

If the short field name does not work the fully qualified name like Microsoft.VSTS.CMMI.ImpactOnArchitecture can be used.

field helper options

Option Type Purpose Example
value literal argument name of the field to output {{{field 'Description' }}}
replace hash argument a regular expression replacement string {{field replace="/searchThis/replaceWithThis/" }}
format hash argument format string to use to format date values {{field 'CreatedAt' format='dd.mm.yyyy' }}
class hash argument CSS class to use for this field - wraps the value in a HTML container
tooltip hash argument Disable or enable the Edit tooltip in the preview of the Bravo Notes UI. Defaults to true. {{field 'Id' tooltip=false }}

filter

Filters the current list of work items.

The example below shows how to filter the full list of work items down to only work items of type User Story.

{{#filter '$UserStory'}}

{{#workItems}}

### {{field 'Title'}}

{{/workItems}}

{{/filter}}

Inside the work items block the workItems block only lists User Story work items. Outside the filter block the full list of work items is still available.

filter helper options

Option Type Purpose Example
label literal argument literal arguments labels to filter by {{#filter 'feature' 'major' }}
exclude hash argument comma separated list of labels to exclude in this block {{#filter 'feature' exclude='Performance,UX'}}

group

Allows grouping work items by a specified field.

The example below shows how to group work items by Area Path.

{{#group 'AreaPath' orderBy='$key'}}

{{#each groups}}

## Area Path: {{$key}}

{{#workItems orderBy='Title'}}
- {{{ field 'Title' }}}
{{/workItems}}

{{/each}}

{{/group}}

To make the grouping work the group helper has to be used in combination with the each helper.

The group block itself turns a list of work items into a list of work item groups available as the groups variable.

Inside the group block the each helper allows to iterate over the created groups.

Inside the each block the workItems helper allows to iterate over the work items of each group.

In addition to the workItems inside a group the value used for grouping is available with the $key variable.

group helper options

Option Type Purpuse Example
value literal argument name of the field to group by {{#group 'AreaPath' }}
orderBy hash argument value to use for sorting the list of groups {{#group 'AreaPath' orderBy='$key' }}
orderByDescending hash argument value to use for sorting the list of groups in descending order {{#group 'AreaPath' orderByDescending='$key' }}

if-field

Checks if a field value has a value or checks if the value meets a defined condition.

The below example checks for the presence of a custom work item field value and only outputs the blocks content if a value is present.

{{#workItems}}

### {{field 'Title'}}

{{#if-field 'Custom.ReleaseNotesBreakingChange'}}

*CAUTION: Breaking Change*


{{{field 'Custom.ReleaseNotesBreakingChange' }}}

{{/if-field}}

{{{field 'Description' }}}

{{/workItems}}

Advanced field checks

If more is needed than merley checking for the presence of a field value, the additional arguments operator and value can be used as shown in the example below.

{{#workItems}}

### {{field 'Title'}}

{{#if-field 'Tags' operator='includes' value='Important'}}
⚠️IMPORTANT⚠️
{{/if-field}}

{{{field 'Description' }}}

{{/workItems}}

Operators available for testing field values

Operator Purpose Example
eq Tests for equality against value {{#if-field 'Priority' operator='eq' value='1' }}
ne Tests for inequality against value {{#if-field 'ValueArea' operator='ne' value='Business' }}
gt Tests if field is greater than value {{#if-field 'Effort' operator='gt' value='4' }}
lt Tests if field is less than value {{#if-field 'Effort' operator='lt' value='20' }}
gte Tests if field is greater than or equal to value {{#if-field 'Effort' operator='gte' value='8' }}
lte Tests if field is less than or equal to value {{#if-field 'Effort' operator='lte' value='13' }}
under Tests if path field is below a given path value {{#if-field 'AreaPath' operator='under' value='ProjectA/Mobile' }}
not-under Tests if path field is not below a given path value {{#if-field 'AreaPath' operator='not-under' value='ProjectA/Mobile' }}
includes Tests if a field includes value {{#if-field 'Tag' operator='includes' value='Important' }}
not-includes Tests if a field not includes value {{#if-field 'Tag' operator='not-includes' value='Important' }}
included-in Tests if a field is included in value {{#if-field 'State' operator='included-in' value='Closed;Removed' }}
not-included-in Tests if a field is not included in value {{#if-field 'State' operator='not-included-in' value='Closed;Removed' }}
contains Tests if a text field contains the string value {{#if-field 'Title' operator='contains' value='API' }}
not-contains Tests if a text field does not contain the string value {{#if-field 'Title' operator='not-contains' value='API' }}
empty Tests if field is empty {{#if-field 'Description' operator='empty' }}

if-field helper options

Option Type Purpose Example
field literal argument
operator hash argument operator to use when testing / comparing the field value
value hash argument value to compare against when testing / comparing the current field value

if-param

Checks if a parameter value has a value or checks if the value meets a defined condition.

In the example below content is only output when the parameter ReleaseType has the value HoFix.

{{#if-param 'ReleaseType' operator='eq' value='HotFix'}}
⚠️This is a HOTFIX release⚠️
{{/if-param}}

Operators available for testing field values

See the if-field helper.

if-param helper options

Option Type Purpose Example
parameterName literal argument
operator hash argument operator to use when testing / comparing the parameter value
value hash argument value to compare against when testing / comparing the current parameter value

images

Lists image attachments of current work item.

An attachment is considered an image if its file extension is one of jpg jpeg png or gif.

{{#workItems}}
{{#images}}

<img title="{{title}}" src="{{url}}" alt="{{comment}}" />

{{/images}}
{{/workItems}}

Attachment properties

property Explanation
name file name of the attachment
url full URL of the attachment - only accessible when logged into Azure DevOps
comment comment provided when attachment was uploaded to work item

import

Imports text from a file within a git repository or from a remote URL.

The below imports the contents of the file intro.md located at /content/intro.md in the configured content repository.

{{import 'content/intro.md' }}

If content from a remote URL should be imported instead a fully qualified URL can be specified instead as shown below.

{{import 'https://public.bravonotes.com/content/hello-world.txt' }}

Please note that CORS settings might need to be adjusted for the file to be loaded inside the Bravo Notes UI.

index

Outputs a 1-based index to help when iterating over items.

{{#workItems}}

{{index @index}}. {{field 'Title'}} {{!-- 1. My work item --}}

{{/workItems}}

When iterating over work items or other arrays the @index variable yields the 0-based index of the current item.

Passing the variable to the index helper it will turn the zero based index to a 1-based index.

commits

Output issues from Jira.

{{#issues filterId="1000"}}
{{/issues}}

iterationPath

Generates prettier output of Iteration Path values.

{{!-- output iteration path of current work item  --}}

{{#workItems}}

- {{{ iterationPath  }}}                     {{!-- Project\Sprint 129  --}}
- {{{ iterationPath separator=' > ' }}}      {{!-- Project > Sprint 129  --}}
- {{{ iterationPath display='last' }}}       {{!-- Sprint 129 --}}

{{/workItems}}

As shown above you can use the iterationPath helper inside a workItems block to output the value of the Area Path field of the current work item with more control.

The below example shows how you can use the iterationPath helper to output the Area Path value together with the group helper.

{{#group 'IterationPath'}}

{{#each groups}}

{{!-- output area path value when grouping by iteration path  --}}

Iteration: {{{iterationPath $key separator=' / '}}}

{{#workItems}}
- {{{ field 'Title' }}}
{{/workItems}}

{{/each}}

{{/group}}

When grouping by Iteration Path we have the actual Iteration Path value available via the $key variable. As we are not in the context of a work item we need to give a Iteration Path value to the iterationPath helper as the first literal argument helper so it knows what to output.

iterationPath helper options

Option Type Purpose Example
value literal argument optional value if not in the context of a work item {{iterationPath $key }}
separator hash argument separator string to use when outputting the iteration path value {{iterationPath separator=' > ' }}
display hash argument display mode to use. "last" : displays only the last segment of the path value {{iterationPath display='last' }}

commits

Output commits linked to the current work item.

{{#workItems}}

### {{{field 'Title' }}}

{{#commits}}

- {{id}} - {{author.name}} - {{message}}

{{/commits}}

{{/workItems}}

Output a link to the current work item

{{#workItems}}

- {{#link}}{{ field 'Title' }}{{/link}}

{{/workItems}}

Inside the {{#link}}...{{/link}} block you can output anything you like as the link text.

Option Type Purpose Example
target hash argument Specify the target attribute of the link e.g. `_blank`

Output linked work items.

In the example below for each work item all child work items are listed as well as a bulleted list.

{{#workItems}}

## {{field 'Title'}}


### Child work items

{{#links 'Child' }}
- {{field 'Title'}}
{{/links}}

{{/workItems}}

In the links helper above the link type Child is specified. Child is a shortcut for the internal fully qualified link type name System.LinkTypes.Hierarchy-Forward.

A common issue when using the links helper is that a heading like "Child work items" above should only be output if there are actually linked work items. If there are no linked work items the heading should be omitted as well.

The linkSection helper comes to the rescue as shown below.

{{#workItems}}

## {{field 'Title'}}

{{#linkSection 'Child' }}

### Child work items

{{#workItems}}
- {{field 'Title'}}
{{/workItems}}

{{/linkSection}}

{{/workItems}}

Above you can see that we use linkSection in combination with workItems. The linkSection helper does the job of retrieving the child work items. Should the links of linked items be empty the whole block inlcuding an headings or other content will be omitted.

pageBreak

Forces a page break when exporting as PDF

## New features

{{#workItems 'feature'}}
- {{field 'Title' }}
{{/workItems}}

{{pageBreak}}

## Fixed bugs

{{#workItems 'bugfix'}}
- {{field 'Title' }}
{{/workItems}}

When exporting as PDF the {{pageBreak}} helper above will make sure that the "Fixed bugs" section will always start on a new page.

param

Outputs a parameter value anywhere in your template

{{ param 'myParam1' }}

{{#workItems}}

### {{ field 'Title' }}

{{ param 'myParam2' }}

{{/workItems}}

param helper options

Option Type Purpose Example
parameterName literal argument

section

Separate work items into sections.

The section helper filters the current list of work items specified by the labels passed as arguments.

{{#section 'major'}}

## Major features

{{#workItems}}

### {{field 'Title' }}

{{{ field 'Description' }}}

{{/workItems}}

{{/section}}

{{#section 'minor'}}

## Minor improvements

{{#workItems}}
- {{field 'Title' }}
{{/workItems}}

{{/section}}

The section helper does the job of retrieving a subset of work items. Should the subset be empty the whole block including headings or other content will be omitted.

Optional fallback

Should you need to output some alternate content if there are no work items for a specific section you can use else to output fallback content.

section helper options

Option Type Purpose Example
label literal argument labels to filter by {{#section '$UserStory' }}
exclude hash argument comma separated list of labels to exclude in this block {{#section '$UserStory' exclude='Performance,UX'}}
class hash argument CSS class to use for this block - adds a HTML container element to the output
showIfEmpty hash argument make sure the contents of the block is also shown if no work items match the section criteria

sum

Sums up values of the specified field in all work items in the current context.

In the sample below story points are summed up separately for user stories and bugs.

{{#section '$UserStory'}}

### Stories

Total story points: {{sum 'StoryPoints'}} 

{{#workItems}}
- {{title}}
{{/workItems}}

{{/section}}

{{#section '$Bug'}}

### Bugs

Total story points: {{sum 'StoryPoints'}} 

{{#workItems}}
- {{title}}
{{/workItems}}

{{/section}}

sum helper options

Option Type Purpose Example
field literal argument work item field for which to calculate the sum

tags

Iterate of all tags of the current work item.

The example below outputs all tags as a bulleted list.

{{#workItems}}

### {{field 'Title'}}

Tags
{{#tags}}
- {{name}}
{{/tags}}

{{/workItems}}

testSteps

Iterate of all tests steps of a Test Case work item.

The example below outputs a simple list of test steps.

{{#workItems}}

### Test Case: {{field 'Title'}}

Steps:

{{#testSteps}}
- {{{step}}}
{{/testSteps}}

{{/workItems}}

As each step can contain arbitrary HTML the result might not be a well formatted bulleted list.

Instead we recommend using a HTML table like in the second example below which also outputs the step number, expected result and step attachments:

{{#workItems}}

### Test Case: {{field 'Title'}}

Steps:

<table>
<thead>
<tr>
    <td>#</td>
    <td>Step</td>
    <td>Expected result</td>
    <td>Attachments</td>
</tr>
</thead>
<tbody>
{{#testSteps}}
<tr>
    <td>{{no}}</td>
    <td>{{{step}}}</td>
    <td>{{{expectedResult}}}</td>
    <td>

{{#attachments}}
 - [{{title}}]({{url}})
{{/attachments}}

    </td>
</tr>
{{/testSteps}}
</tbody>
</table>

{{/workItems}}

{{#timeline from="01.02.2020" to="01.12.2020" unit="iteration" extraColumnsEnd=(param 'endColumns') }}
{{/timeline}}

when

For the most part we recommend using custom labels to segment work items in your documents.

Sometimes you may want to be a bit more flexible and don't want to be forced to create labels to filter work items.

Example using labels

For this section to work you have to define the label titleContainsIOS separately.

{{#section 'titleContainsIOS'}}

{{#workItems}}
- {{title}}
{{/workItems}}

{{/section}}

Example using the when helper

Using the when helper you can define the condition inline.

{{#section (when 'Title' operator='contains' value='IOS') }}

{{#workItems}}
- {{title}}
{{/workItems}}

{{/section}}


More usage scenarios

Currently the when helper is supported as a sub expression in the workItems, filter, section and count helpers to filter work items.

However it also enables filtering objects that don't have labels applied like attachments. The attachmentSection helper enables you to filter attachments with the when helper as well:

{{#attachmentSection (when 'comment' operator='contains' value='release notes')}}

{{#attachments}}
- [{{title}}]({{url}})
{{/attachments}}

{{/attachmentSection}}

The when helper allows you to specify conditions just like the if-field helper.

when helper options

Option Type Purpose Example
field literal argument
operator hash argument operator to use when testing / comparing the field value
value hash argument value to compare against when testing / comparing the current field value

Output all links to wiki pages.

{{#workItems}}
### {{field 'Title'}}

Wiki pages:
{{#wikiLinks}}
- [{{pageTitle}}]({{pageUrl}})
{{/wikiLinks}}

{{/workItems}}
property Explanation
pageTitle title of the wiki page
pagePath path of the wiki page
pageUrl full URL of the wiki page

workItem

Pulls in a single work item by its ID.

{{#workItem 182}}

### {{field 'Title'}}

{{{field 'Description'}}}

{{/workItem}}

workItem helper options

Option Type Purpose Example
id literal argument id of the work item to import

workItems

Iterates over all work items in the current context.

The workItems helper can be used at the root of the template or inside other helpers like group section linkSection.

{{#workItems}}
- {{field 'Title'}}
{{/workItems}}

workItems helper options

Option Type Purpose Example
label literal argument comma separated list of labels to include in this block
exclude hash argument comma separated list of labels to exclude in this block {{#workItems 'feature' exclude='Performance,UX'}}
orderBy hash argument field to order the work item list by in ascending order {{#workItems orderBy='Title' }}
orderByDescending hash argument field to order the work item list by in descending order {{#workItems orderByDescending='Priority' }}
sortOrder hash argument Set a fixed sort order to be used for when ordering items {{#workItems orderBy='Category' sortOrder='Category B,Category C,Category A' }}
sortMode hash argument `alphanumeric` (default) => sort character by character `natural` => recognize multi-digit numbers in strings and sort accordingly {{#workItems orderBy='Version' sortMode='natural' }}

//1.2.3.4 1.2.3.4.11

class hash argument CSS class to use for this block - adds a HTML container element to the output
item-class hash argument CSS class to use for each item this block - adds a HTML container element to the output for each item

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us