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.
concat	Utility helper to concatenate multiple values to one string value
count	Outputs the number of work items in the current context.
date	Outputs the current date.
duration	Convert a number of milliseconds or seconds to a human readable format.
eachGroup	Iterate over groups generated via the [group](#group) helper.
env	Access environment variables when running in a build or release pipeline
field	Outputs a work item field value.
filter	Filters the current list of work items.
group	Allows grouping work items by a specified field.
markdown	Convert rich text fields from work items and any other HTML contents to markdown.
hyperLinks	Output all hyperlinks of a work item
if-env	Checks if a environment variable has a value or checks if the value meets a defined condition.
if-field	Checks if a field value has a value or checks if the value meets a defined condition.
if-format	Only output contents when exporting to one of the specified target formats 'md', 'html' or 'pdf'.
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.
iteration	Output iteration information of the current work item
iterationPath	Generates prettier output of Iteration Path values.
iterations	Output iterations in the current project.
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
progressBar	Output a simple progress bar.
project	Output name and other information from the current Azure DevOps team project
repeat	Utility helper to repeat a string
rollupProgress	Get rollup values from child work items.
rollupSum	Get rollup sum values from child work items.
rollupTotal	Get rollup total values from child work items.
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.
value-if
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}}

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

property	Explanation
comment	comment provided when attachment was uploaded to work item
title	title / 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}}

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

<div class="border-b border-gray-200 pb-8"><a href="#">↑ Back to top</a></div>

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

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

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

Option	Type	Purpose	Example
class	hash argument	CSS class to use for this block - adds a HTML container element to the output

env

Access environment variables when running in a build or release pipeline

Branch: {{ env 'BUILD_SOURCEBRANCHNAME' }}

env helper options

Option	Type	Purpose	Example
environmentVariable	literal argument

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' }}
locale	hash argument	use localization in formatted date values to get localized month and day names	{{field 'CreatedAt' format='dddd mmm yyyyy' locale='fr' }}
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' }}

group helper options

Option	Type	Purpose	Example
groupField	literal argument
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

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

property	Explanation
url	URL of the hyperlink
comment	Comment of the hyperlink

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

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

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' }}
not-empty	Tests if field has a non-empty value	{{#if-field 'Description' operator='not-empty' }}
matches	Tests if field matches a pattern (regular expression)	{{#if-field 'Description' operator='matches' value='/^J\d\d/' }}
not-matches	Tests if field does not match a pattern (regular expression)	{{#if-field 'Description' operator='not-matches' value='/^J\d\d/' }}

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

Option	Type	Purpose	Example
formats	literal argument	list of formats - only output the blocks contents, if exported to one of the specified formats	{{#if-format 'html' 'pdf' }}Don't show this in markdown exports{{/if-format}}

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.

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

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

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

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

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

Option	Type	Purpose	Example
parameterName	literal argument

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

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

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

Option	Type	Purpose	Example
value	literal argument	value to return if specified conditions are met	{{#field 'Description' class=(value-if 'important' (when 'Tags' operator='contains' value='important')) }}
conditions	literal argument	list of conditions that have to be true in order to return the specified value. Can be either a condition defined by logical helpers `when`, `or`, `and` or a label that matches the workitem in the current context	{{#field 'Description' class=(value-if 'important' (when 'Tags' operator='contains' value='important') 'myLabel' ) }}

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

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

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