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
The first 3 parameters are are self-explanatory. The "Columns" field has a specific syntax:
| 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 |
|---|---|
| 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 Test and Compliance add-on) |
Options
A few formatting options are available:
| 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:
