Conditionally include report sections with $when

The $showonce report keyword makes it easy to have a conditionally appearing header section for a $repeat loop, but sometimes you want a little more control over when a section is included or excluded from a report. 

You can make a section of a report be conditionally included based on the presence or absence of project elements with attributes you specify. This is a little different from the $if and $exclude keywords, which test against conditions of a property – the new $when keyword tests for the presence of elements in your project. The example I’ll use here is a section that shows all of the use cases that are in development. I want to add that to my weekly status report to show what the developers are working on, and what the testing schedule is. If there aren’t any such use cases, I don’t want any of that section showing up in my report. Here’s my report template:

Status Report

CaseComplete Development Team

$whenUseCases where ImplStatus = ‘Started’

Project Use Cases in Development

These are the P1 use cases that are listed as top priority and are in development for this iteration.

$repeatUseCases where Priority = 1 and ImplStatus = ‘Started’

$Name ($ID)

$Description

$endrepeatUseCases

Testing Schedule

….

$endwhenUseCases

Here, the entire block within the $when and the matching $endwhen is only included in my report when there are use cases in the “Started” state. The $when keyword uses the familiar element type name with optional filtering with the “where” keyword. You can use more complex filtering using the same syntax as $repeat and other report filtering.