ReqSuite® Requirements Manager (RM)
MS Word Templates

For the purpose of an appealing visualization of project information, ReqSuite® RM provides powerful mechanisms to export the content from its database to MS Word documents. For this purpose, one or more MS Word documents acting as templates can be attached to a certain project template.

A MS Word document being such a template is a normal .docx-file whose appearance can be completely designed according to the corporate design and required chapter structure. At certain places in this document, variables of the word generation syntax of ReqSuite® RM have to be inserted, which are dynamically replaced by project contents during document generation.

The definition of the MS Word document template is done in the following steps.

Defining the Content Structure

In this initial step, the overall structure of the document is defined. For this purpose a normal word file is created in MS Word and filled with static content such as the desired chapter structure, the cover page, page numbers, logos, introductory remarks, etc.

Defining the Layout and Visual Appearance

In this second step, the visual appeareance of the contents to be displayed in documents based on this MS Word template has to be defined. This works by using MS Word’s built-in formatting features for paragraphs and tables. In particular the following styles must be modified or created.

Heading styles for chapters and sub chapters

The default headings of the MS Word document can be used or specific headers such as ReqSuiteHeading1, ReqSuiteHeading2, … can be created from scratch. However, the names of these headings must not contain umlauts (e.g. no “Ü”) as this is not understood by the generation engine. Note that there is no space between “Heading” and “1” because the headings are stored internally in Word like this.

Default paragraph style

This default style “Standard” being part of the MS Word document needs to be adapted to the desired format as it will be applied for every text generated by ReqSuite® RM (even text in table cells).

Table styles

In order to display tables generated by ReqSuite® RM, two table styles have to be created from scratch in the given MS Word document.

  • “ReqSuiteTableTemplate” for 2-column tables in which the first column shall contain the labels and the second the actual data
  • “ReqSuiteDynamicTableTemplate” for n-column tables in which the first row shall contain labels and the other rows the actual content
Caption style

For displaying figure captions automatically generated by ReqSuite® RM, a caption called “ReqSuiteCaption” must be defined in the MS Word document.

Defining the Representation of Individual Content Elements

For exporting project content from the ReqSuite® RM database, variables (so-called tags or commands) must be included at the appropriate places in the MS word document (see Figure 1). While ReqSuite provides a number of predefined tags such as ###HISTORY## or ###VERSION##, most tags are custom and based on the categories and attributes defined in the associated project template.

Figure 1: Example of a MS Word document template with ReqSuite® tags

In particular, the content of the different categories of a project template can be exported as individual descriptions according to the defined input form, tables and lists. Furthermore, there are tags/commands to export attached images, related elements and those for filtering, grouping, and sorting. Below, all commands are introduced in a FAQ style.

How can I basically export the items of a certain category?

If you want to export the items of a certain category according to the input form defined in the project template, please use ###CATEGORYNAME:INSTANCES###, e.g. ###REQUIREMENT:INSTANCES###. If desired attributes are specified using the keyword “WITH”, e.g. “CATEGORYNAME:INSTANCES WITH DESIRED ATTRIBUTES SEPERATED BY COMMA”, only these attributes will be exported. Otherwise, the attributes for which a check mark has been set in the input form in the project template will be exported.

If you want to export all elements of a category in a common table, please use ###CATEGORYNAME:TABLE WITH DESIRED ATTRIBUTES SEPARATED BY COMMA###, e.g. ###REQUIREMENT:TABLE WITH ID, NAME, DESCRIPTION### instead.

If you would rather export the items in a bullet list, please use ###CATEGORYNAME:LIST WITH DESIRED ATTRIBUTES SEPARATED BY COMMA###. Not defining the attributes here will export the ID and name of the items as default.

How can I export only a specific attribute of a certain category’s items?

For doing this, please use ###CATEGORYNAME.ATTRIBUTENAME###. However, this command only works when having exactly one item of the mentioned category in a project or when using a filter that finds exactly one item (see below).

How can I filter the export to a subset of items?

All the basic commands INSTANCES, TABLE and LIST can be combined with a filter. A filter is written in square brackets and can contain one or more conditions that relate to the attributes of the category or the attributes of a related category according to the project template.

For instances, ###REQUIREMENT:INSTANCES [STATUS=tested AND TEST CASE.RESULT=ok]### will only return requirements in state “tested” for which at least one linked test case result is “ok”. In addition, there is also the “CONTAINS” operator to query whether an attribute contains a certain value at any position.: ###REQUIREMENT:INSTANCES [Name CONTAINS Interface]###.

It is also possible to filter by the folder names. Either the direct folder names with [FOLDER=Name] or one of the folder names in the entire directory path with [FOLDER CONTAINS Name].

If you filter for attributes of transitively related elements, you can exclude paths to these elements. If a category is transitively linked to another category via more than one path, you can exclude one of these paths, e.g. “[Product.STATUS = tested NOT VIA Requirement]”.

How can I set an order in which the items are exported?

All the basic commands INSTANCES, TABLE and LIST can be combined with the specification of a desired output order. This order is defined by the SORT BY command followed by the name of the attribute to be sorted by.

For instance, ###REQUIREMENT:INSTANCES SORT BY SOURCE### will return all requirements ordered by (the name of) their source.

In addition to this, it is also possible to sort the output of related elements, e.g. “CATEGORYNAME:INSTANCES SORT BY ATTRIBUTENAME WITH RELATED CATEGORYNAME2:INSTANCES SORT BY ATTRIBUTENAME“.

How can I export the image assigned to the category or its items?

Images being part of a rich text field are exported whenever this field is part of the export (e.g. when using ###CATEGORYNAME:INSTANCES###).

Images uploaded as so-called notations can be exported with specific commands.

With ###CATEGORYNAME:INSTANCE WITH RELATED INSTANCEMODELS## you can export the description of the category’s items followed by their detail graphic. This command can be combined with the filter mentioned above.

With ###CATEGORYNAME:INSTANCEMODELS### you just export the assigned detail graphics without the actual item description. This command can be combined with a filter too.

With ###CATEGORY:OVERVIEWMODEL### you can export a notation assigned to the whole category as an overview graphic.

Is it possible to include images when using the TABLE command?

Yes, use INSTANCEMODELS command in the same way as you use the attributes in a table, e.g. ###REQUIREMENTS:TABLE WITH ID, NAME, DESCRIPTION, INSTANCEMODELS###

How can I export the items of a category followed by the linked items of the same or another category?

If you want to export the linked items according to their input form, please use ###CATEGORYNAME:INSTANCES WITH RELATED RELATEDCATEGORYNAME###, e.g. ###REQUIREMENT:INSTANCES WITH RELATED TEST CASE###

If you want to export them as a table, please use ###CATEGORYNAME:INSTANCES WITH RELATED RELATEDCATEGORYNAME:TABLE WITH DESIRED ATTRIBUTES SEPARATED BY COMMA###.

Again, both commands can be combined with a filter as mentioned above. In particular, it is possible to filter the first category and the second category separately, e.g. ###REQUIREMENT:INSTANCES [STATUS=tested] WITH RELATED TEST CASES:TABLE WITH ID, NAME, DESCRIPTION, OBSERVATION [RESULT=ok]###.

Furthermore, you can add WITH INSTANCESMODELS behind the main category and INCLUDE INSTANCEMODELS behind the related category, e.g. ###REQUIREMENT:INSTANCES WITH INSTANCEMODELS WITH RELATED TEST CASE INCLUDE INSTANCEMODELS###.

Please note that all these commands will also export items that are linked transitively and not only those that are linked directly.

How can I export linked items of multiple categories?

If exporting them according to their input form, you can list them after the WITH RELATED in a comma-separated way, e.g. ###REQUIREMENT:INSTANCES WITH RELATED TEST CASE, COMPONENT###

If you want to export them as table, you must separate their names by semicolon because the commas are already used for separating the attributes, e.g. ###REQUIREMENT:INSTANCES WITH RELATED TEST CASE:TABLE WITH ID, NAME, DESCRIPTION; COMPONENT:TABLE WITH ID, NAME, DESCRIPTION###

All the combinations with other commands as described above work here as well.

How can I export information about linked items when using the TABLE command?

The simplest way is just to write the name of the linked items’ category in the same way as the desired attributes, e.g. ###REQUIREMENT:TABLE WITH ID, NAME, DESCRIPTION, TEST CASE###

This will result in a column that lists the IDs and names of all linked items.

If you rather want to export specific attributes of the linked items, please use RELATEDCATEGORYNAME.ATTRIBUTENAME instead, e.g. ###REQUIREMENT:TABLE WITH ID, NAME, DESCRIPTION, TEST CASE.RESULT###

How can I rename the column labels when using the TABLE command?

Just set a | behind the attribute name followed by the desired label, e.g. ###REQUIREMENT:TABLE WITH ID, NAME|Title, DESCRIPTION|Summary###

How can I dynamically insert the exported elements into different sections of the Word document?

To create a separate section for each exported item, please use ###CATEGORYNAME:INSTANCES ON HEADINGFORMAT###, where HEADINGFORMAT is the name of a heading style in the Word template, e.g. ###REQUIREMENT:INSTANCES ON Heading1###.

It is also possible to select the attribute to display in the header. To select this attribute, it must be specified via “USING” after specifying the “HEADINGFORMAT”, e.g. “REQUIREMENT:INSTANCES ON Heading1 USING ATTRIBUTENAME“. If no attribute is specified, the name of the element will be exported to the header.

When using this command, a subsection will be created during export and the names of the corresponding items will be used as headings. If you want to include the item ID in the heading too, please use INCLUDE ID additionally, e.g. ###REQUIREMENT:INSTANCES ON Heading1 INCLUDE ID###.

If you want to include linked items using the WITH RELATED command (see above), the export will also generate subheadings describing the type of the relationship to these linked items. If you do not want these subheadings, include a NO SUBHEADER command, e.g. ###REQUIREMENT:INSTANCES ON Heading1 NO SUBHEADER WITH RELATED TEST CASE###.

If you want to export the linked elements without showing the input form of the main item itself, you can use HIDETEMPLATE. For example, ###REQUIREMENT:INSTANCES ON Heading1 HIDETEMLATE WITH RELATED TEST CASE### exports test cases grouped by the associated requirement with a heading that names that requirement.

Of course, as in all the aforementioned cases, filters also work here.

How can I export meta information when using the INSTANCES command?

The status, deadline and version meta information is exported if you append a + to the INSTANCES command, e.g. ###REQUIREMENT:INSTANCES+###. All the above commands can be added in the same way as to INSTANCES without +.

How can I export meta information when using the TABLE command?

For exporting meta information in in a table, you must list the meta information in the same way as you list the attributes of the category (i.e. in comma-separated way behind WITH). The following meta information are available.

  • LAST_EDITOR
  • RESPONSIBLE_USER
  • INSTANCESMODELS
  • DEADLINE
  • CREATION_DATE
  • LAST_CHANGE
  • VERSION
  • STATUS
  • TEMPLATE
How can I export the comments, attachments or version assigned to the items?

When using the INSTANCE command, you can export comments, versions and attachments in the same way as linked items using ###CATEGORYNAME:INSTANCES WITH RELATED ATTACHMENTS, VERSIONS, COMMENTS###. In particular, using :TABLE, e.g. ATTACHMENT:TABLE, is not necessary here, this information will be exported as a table by default.

When using the TABLE command, attachments and comments can be exported by including RELATED_COMMENTS or RELATED_ATTACHMENTS in the attribute list, e.g. ###REQUIREMENT:TABLE WITH ID, NAME, DESCRIPTION, RELATED_COMMENTS, RELATED_ATTACHMENTS###

How can I dynamically group items during export?

If you have organized your items in a folder hierarchy, you can export the items according to this hierarchy into hierarchical document sections by using ###CATEGORYNAME:INSTANCES ON HEADINGFORMAT BY FOLDER###

If you want to export items grouped by the value of a certain attribute, please use ###CATEGORYNAME:INSTANCES ON HEADINGFORMAT GROUP BY ATTRIBUTENAME###, e.g. ###REQUIREMENT:INSTANCES ON Heading1 GROUP BY PRIORITY###.

If you rather want to export items grouped by the name of a linked parent item, please use ###CATEGORYNAME:INSTANCES ON HEADINGFORMAT BY CATEGORY RELATEDCATEGORYNAME### instead, e.g. ###REQUIREMENT:INSTANCES ON Heading1 BY CATEGORY COMPONENT###.

Finally, there are also means to export the entire refinement hierarchy of items according to the link structure defined in the project template.

By using the WITH RELATED CHILDREN command, you can export the complete refinement hierarchy of an item and its linked sub items of the same category, e.g. ###REQUIREMENT:INSTANCES ON Heading1 WITH RELATED CHILDREN###.

Using the WITH RELATED HIERARCHY command will basically do the same but also take items of other categories into consideration.

All these commands require that that you use the INSTANCES command and that you define a heading format using the ON command (see above). Furthermore, it must be considered that CHILDREN and HIERARCHY commands cannot be combined with filters or other related items.

If I have directly linked and transitively linked items of the same category: How can I decide which of them to export?

Imagine you have requirements with linked sub requirements and to all requirements you have linked test cases.

If you use the WITH RELATED command in this case, e.g. ###REQUIREMENT:INSTANCES WITH RELATED TEST CASES###, the export will export

  1. only the directly related test cases, if such direct links exists
  2. all transitively related test cases, otherwise

To restrict the export more explicitly, you can use ALL and DIRECT commands. The ALL command will always export all related items, e.g., directly and transitively related ones independent of the two aforementioned cases. The DIRECT command will do the opposite, i.e. only export directly related links (or nothing if such direct links do not exist).

Furthermore, the DIRECT command can also be applied to filters. For instance, if you want to filter by an attribute of a linked item, but you are only interested in the directly linked items, please use [DIRECT RELATEDCATEGORYNAME.ATTRIBUTENAME=DESIRED VALUE]

How can I dynamically distribute items in different Word files?

If you want to export items (including linked items) to different Word documents (e.g. a separate specification for each component), you can use specific commands for that.

By putting ###CATEGORYNAME:DOCUMENT### at the beginning of the Word file, the export will create an own document for each item of this category. For then making sure that only corresponding content is exported, a dynamic filter must be used in every following command.

By using ###CATEGORYNAME:INSTANCES [ID=*]### the description of the item to export in this document will be generated and it will be avoid that the descriptions of other items of the same category are exported as well.

The same works for items of other categories being linked with the item to export using ###RELATEDCATEGORYNAME:INSTANCES [CATEGORYNAME.ID=*]### and for specific attributes of the item ###CATEGORYNAME.ATTRIBUTENAME [ID=*]###

The dynamic filters can be combined with other filters, if necessary.

How can I filter items to those not having a link to items of another category?

Please use the following filter for that: ###CATEGORYNAME:INSTANCES [RELATEDCATEGORYNAME.ID=NULL]###

How can I export the attribute value of the relationships when exporting certain items with their linked items?

Exporting the relationship attribute is only possible when exporting data with the TABLE command. There are two ways how to do this.

###CATEGORYNAME:INSTANCES WITH RELATED RELATEDCATEGORYNAME:TABLE WITH DESIRED ATTRIBUTES SEPARATED BY COMMA, RELATIONATTRIBUTE### or ###CATEGORYNAME:TABLE WITH DESIRED ATTRIBUTES SEPARATED BY COMMA, RELATEDCATEGORYNAME.RELATIONATTRIBUTE###

How can I limit the export to one particular link (and the corresponding attribute value)?

When using a command like ###CATEGORYNAME:INSTANCES RELATED RELATEDCATEGORY:TABLE WITH … [RELATEDCATEGORY.ATTRIBUTE=DESIRED VALUE]### there is nothing to do specifically.

When only using a TABLE command instead, you must use the command FITTING and a filter based on an attribute of the related category, e.g. ###REQUIREMENT:TABLE WITH ID, NAME, FITTING TEST CASE.NAME, FITTING TEST CASE.RELATIONATTRIBUTE [TEST CASE.ID=TC5]###.

Of course, such filters or the FITTING command are not necessary if the project templates assure that there can be only one link of this type between two items.

How can I have certain commands executed only when elements of a category exist?

To prevent ranges from being output even though there is nothing in them, you can use If-Conditions. If you use the commands ###IF ANY <CATEGORY>### or ###IF ANY <CATEGORY> [<FILTER>]###, it will be checked, if these elements exist. Only if they do, the following static contents or commands will be shown respectively executed. A block must be terminated with ###END IF ANY###, otherwise the condition is valid until the end of the document.

Which basic in-built commands exist?
ReqSuite Document Markup Content Pasted Into Document
###ALL COMMENTS ([<FILTER_ATTRIBUTE>{=|<>|<|>|<=|>=} <FILTER_VALUE>])### List of all comments across all elements (restricted according to the given filter attribute and filter value referring to the elements that include comments).
###ATTACHMENTS ([<FILTER_ATTRIBUTE>{=|<>|<|>|<=|>=} <FILTER_VALUE>])### List of all attachments across all elements (restricted according to the given filter attribute and filter value referring to the elements that include attachments).
###AUTHOR### First and last name of the person who triggered the document generation.
###CONTENT PROBLEMS (WITH <ATTRIBUTE>)### Result of the quality checker results (including value of the attribute of the corresponding content elements).
###CONFIGURATION HANDBOOK (ON <FORMAT_TEMPLATE>)### Generates a manual of the project configuration on which the project is based (in a section according to the specified format template (e.g., Heading1)).
###CURRENT DATE (+<DAYS>)### Today’s date (or future date, which is anticipated in days after a certain period in days from today’s date).
###:DEFINITION### Stored definition of the content type.
###DOCUMENT CHANGES (TO <Document1>) (WITH DETAILS)### Changes of a particular document generated with the ###<TYPE>:DOCUMENT### marker to its previous version (or to a specific previous version). If desired, also the details of the changes (comparison of each item in both versions) can be exported.
###DOCUMENT VERSION### Version of a particular document generated with the ###<TYPE>:DOCUMENT### marker.
###ENABLE INTERNAL LINKS### References from one element description according to the marker “<TYPE>:INSTANCES” to another element description are exported as clickable hyperlinks in the document.
###HISTORY### Table with history information about the different baselines of the project.
###OPEN ISSUES### List of all open clarification points
###PROJECTLEADERS### All persons with first and last name assigned to the project in the “ProjectAdmin” role.
###PROJECT NAME### Name of the project.
###STATISTICS### Project statistics.
###TEAMMEMBERS### All persons with first and last names assigned to the project as users in any role.
###TRACEABILITYMATRIX WITH <TYPE_1>, <TYPE_2>### Traceability matrix showing the relationships in pairs between all content elements of both content types.
###VERSION### Baseline number of the project on which the document was generated.
###VERSION CHANGES ({BETWEEN<Baseline1> AND <Baseline2> | TO <Baseline1>}) (WITH DETAILS)### Changes of the current baseline to previous baselines (or the changes between two specific baselines, or the changes of the current baseline to a specifc baseline). If desired, also the details of the changes (comparison of each item in both versions) can be exported.
##BASELINE DESCRIPTION### Description of the current baseline

Legend for table:
<…> Variable value
(…) Optional value
{…|…} Alternative values
[…] Regular brackets as part of filters