Bravo Notes template syntax reference

Full reference of Bravo Notes handlebars helpers

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

attachments

Lists attachments of current work item.

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

Use attachmentSection to include a heading and hide the whole section when there are no attachments in a work item.

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

{{#attachmentSection}}

**Attachments**

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

{{/attachmentSection}}

{{/workItems}}

Attachment properties

comments

Output comments linked to the current work item.

{{#workItems}}

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

{{#comments}}

**{{createdBy.displayName}} ({{createdBy.uniqueName}})** wrote on {{date createdDate format='dd.mm.yy'}}:

{{{text}}}

{{/comments}}

{{/workItems}}

Use `commentsSection` to include a heading and hide the whole section when there are no comments in a work item.

```handlebars
{{#workItems}}
### {{field 'Title'}}

{{#commentsSection}}

**Comments**

{{#comments}}

**{{createdBy.displayName}} ({{createdBy.uniqueName}})** wrote on {{date createdDate format='dd.mm.yy'}}:

{{{text}}}

{{/comments}}

{{/commentsSection}}

{{/workItems}}

### commits

Output commits linked to the current work item.

```handlebars
{{#workItems}}

### {{field 'Title' }}

{{#commits}}

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

{{/commits}}

{{/workItems}}

concat

Utility helper to concatenate multiple values to one string value

The example below concatenates the literal string title- with the State value of each work item.

{{#workItems}}

### {{{ field 'Title' class=(concat 'title-' (field 'State')) }}}

{{/workItems}}

This results in class attribute values title-New, title-Closed etc.

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

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

duration

Convert a number of milliseconds or seconds to a human readable format.

{{duration 180000 }}
{{!-- output: 00:03:00 --}}
 
{{duration 69 unit='seconds' }}
{{!-- output: 00:01:09 --}}

eachGroup

Iterate over groups generated via the group helper.

{{#group 'Priority'}}
{{#eachGroup}}
### {{$key}}

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

{{/eachGroup}}
{{/group}}

eachGroup helper options

env

Access environment variables when running in a build or release pipeline

Branch: {{ env 'BUILD_SOURCEBRANCHNAME' }}

env helper options

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

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

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

group helper options

//1.2.3.4 1.2.3.4.11 `|

markdown

Convert rich text fields from work items and any other HTML contents to markdown.

{{#markdown}}

{{{field 'Description' }}}

{{/markdown}}

hyperLinks

Output all hyperlinks of a work item

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

Hyperlinks:
{{#hyperLinks}}
- [{{comment}}]({{url}})
{{/hyperLinks}}

{{/workItems}}

Hyperlink properties

if-env

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

In the example below content is only output when the environment variable BUILD_SOURCEBRANCHNAME contains the value hotfix.

{{#if-env 'BUILD_SOURCEBRANCHNAME' operator='contains' value='hotfix'}}
⚠️This is a HOTFIX release⚠️
{{/if-env}}

Operators available for values

See the if-field helper.

if-env helper options

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

if-field helper options

if-format

Only output contents when exporting to one of the specified target formats 'md', 'html' or 'pdf'.

In the example below content is only output when the exporting as HTML or PDF.

{{#if-format 'html' 'pdf'}}
<div>

   <a href="{{param 'WikiUrl'}}">View this in our Azure DevOps Wiki</a>

</div>
{{/if-format}}

Operators available for testing field values

if-format helper options

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

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

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.

### Contents of intro.md from default branch

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

### Contents of intro.md from develop branch

{{import 'content/intro.md' branch='develop' }}

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

iteration

Output iteration information of the current work item

{{#workItems}}

### {{field 'Title'}}

{{#iteration}}

#### Iteration: {{name}}

- Id: {{id}}
- Starts: {{startDate}}
- Ends: {{finishDate}} 
- Path: {{path}}

{{/iteration}}

{{/workItems}}

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

iterations

Output iterations in the current project.

{{#iterations}}

### {{name}}

- Id: {{id}}
- Starts: {{startDate}}
- Ends: {{finishDate}} 
- Path: {{path}}

{{/iterations}}

link

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.

link helper options

links

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.

linkSection

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

progressBar

Output a simple progress bar.

Custom progress bar with static value: {{{progressBar value=76}}}

## Progress bars for each work item

| Epic | Stories | Progress by Story Points |
|:-----|:-------:|:------------------------:|
{{#workItems}}
|{{ field 'Title' }}|{{rollupTotal type='User Story'}}|{{#rollupProgress field="StoryPoints"}}{{{progressBar}}}{{/rollupProgress}}|
{{/workItems}}

project

Output name and other information from the current Azure DevOps team project

### Project info

{{#project}}

Name: {{name}}
Id: {{id}}
Description {{description}}

{{/project}}

repeat

Utility helper to repeat a string

{{#workItems}}

Rating: {{ repeat '⭐' times=(field 'Custom.Rating') }}

{{/workItems}}

rollupProgress

Get rollup values from child work items.

The rollupProgress helper works the same as Azure Boards rollup columns in your backlog.

## Epic progress rollup values

{{#workItems '$Epic'}}
- Progress by work item count: {{rollupProgress}}%
- Progress by Bugs completed: {{rollupProgress type='Bug'}}%
- Progress by Story Points: {{rollupProgress field='StoryPoints'}}%
- Progress by Story Points as progress bar: {{rollupProgress field='StoryPoints'}}%
- Progress by Story Points as progress bar: {{#rollupProgress field='StoryPoints'}}{{{progressBar value=value}}}{{/rollupProgress}}
{{/workItems}}

rollupSum

Get rollup sum values from child work items.

The rollupSum helper works the same as Azure Boards rollup columns in your backlog.

## Epic progress rollup values

{{#workItems '$Epic'}}
- Sum of Story Points: {{rollupSum field='StoryPoints'}}
{{/workItems}}

rollupTotal

Get rollup total values from child work items.

The rollupTotal helper works the same as Azure Boards count rollup columns in your backlog.

## Rollup totals for each work item 

{{#workItems}}

### {{field 'Title'}}

- Count of User Stories: {{rollupTotal type='User Story'}}
- Count of Bugs: {{rollupTotal type='Bug'}}

{{/workItems}}

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.

## Fixed bugs

{{#section 'bugfix'}}

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

{{else}}

No bugfixes in this release

{{/section}}

section helper options

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

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

value-if

Utility helper to return a specified value when specified conditions are met. Especially useful as a sub-expression in other helpers.

value-if helper options

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

wikiLinks

Output all links to wiki pages.

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

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

{{/workItems}}

Use wikiLinksSection to include a heading and hide the whole section when there are no linked wiki pages in a work item.

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

{{#wikiLinksSection}}

**Wiki pages**

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

{{/wikiLinksSection}}

{{/workItems}}

Wiki link properties

wikiPage

Allows you to import wiki page content from your Azure Boards Wikis.

Example using a project wiki

Use the accompanying wikiPageTitle and wikiPageContent helpers to easily output the title and content of a wiki page

{{#wikiPage wikiId='My Project Wiki' path='/legal/Disclaimer'}}

## {{wikiPageTitle}}

{{wikiPageContent}}

{{/wikiPage}}

You may also output subpages as shwon in this example

wikiPage helper options

workItem

Pulls in a single work item by its ID.

{{#workItem 182}}

### {{field 'Title'}}

{{{field 'Description'}}}

{{/workItem}}

workItem helper options

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

//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|| |queryId|hash argument|Retrieve work items for this block form a specified query|{{#workItems queryId='aaaa1744-2ec8-4762-80f8-31797b4702ca' }}`|