RY Reports

How to configure the "RY Reports" macro, notably the columns.

In Properties, we've introduced the ability to write reports. This page describes the report syntax.

We recommend using the Traceability matrix, because it will allow you to define much more advanced columns. After saving the traceability matrix, you can paste it on a page and it will render like an RY Report.

First, insert the macro named "RY Report":
Then you can edit the properties:

Syntax

In the "Query field”, you can use this search syntax.

The "Columns" field has a specific syntax:

Configuration for "Columns"	Result

Configuration for "Columns"	Result
key, description	2 columns.
key, description+properties+links	2 columns. The second one contains the description, the properties and the links.
key, @Prop1	The value of the property "Prop1" for the requirement
key, jira	The list of JIRA issues attached to the key.
key, jira@resolves	The list of JIRA issues, filtered for the relationship named "resolves".
key, description+properties, links+jira	3 columns, the default layout, similar to the search screen.

Field	Contents

Field	Contents
key	The key of the requirement
description (since 2.5.3)	The main description of the requirement
properties	The properties of the requirement
jira	The JIRA issues linked to the requirement
status	The status of the requirement
original (since 2.5.3)	The link to the original page
links	The pages linked to the requirement
to	Dependencies to this requirement
from	Dependencies created by this requirement
tests	Tests that apply to this requirement (requires the RY Testing and Compliance add-on)

Options

A few formatting options are available:

Field definition	Result

Field definition	Result
to	Displays the "to" field (as above)
to?format=short	Link to the key only, without a list, without the lozenge
to?format=page	Link to the page only, without a list, without the lozenge
to?format=page&li=false	Same as above, without showing the bullet points of the list.
links?duplicates=false (since 2.5.3)	Display the links, but don't display when there are several of them per page.
to?li=true	Display as a list.
to?li=false	Display the list without the bullet points.
tests?li=last	Display the last test only.

Reporting on the last macro

Sometimes, one wants to add details about the last requirement, particularly the Jira issues associated to the requirement. For example, the last colum in this picture, contains an RY Report:

The way to do this is to double-click on the macro and tick "Use the last requirement":

This feature is available:

For legacy reports, where you define the search query and columns using text-based fields in this macro. In this case, ticking those checkboxes will ignore the search query.
For traceability reports. In this case, you may build and save the traceability matrix with any search query, and when you insert the macro and double-click to tick those checkboxes, the initial search query will be ignored.

Gotchas

The first limitation is that building many reports on a single page may cause pages to be very slow, and therefore it is not recommended to use this feature too much.

The options are:

Use the last requirement: It will use the last link or definition. For example, in the screenshot above, the reports will be made respectively on DEF-1, DEF-1, DEF-2 and DEF-3, since they are the last requirements cited.
Use the last requirement definition: It will only use the last definition. If ticked, it doesn't matter whether you also tick "Use the last requirement". In the example, the reports will be made on DEF-1, DEF-2, DEF-3 and DEF-4.

However, there is a trick if you tick "Use the last requirement definition", because of the recursivity / inception: You are showing a report of the current requirement, in the current requirement, which causes an infinite recursion. Therefore:

If you tick "Use the last requirement definition", be aware that the report only displays the previous description, not the current one. Hence the next recommendation.
We recommend using those reports to only display external properties or Jira issues, which are not recursive with the current page.
We require that you put an RY Property macro in those columns, to ensure that Requirement Yogi doesn't index the report recursively. See the screenshot: