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

Output all hyperlinks of a work item

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

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

{{/workItems}}
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' }}

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.

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

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

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

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

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

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