How to make a requirements specification with parameters?

End users are very fond of reports, which they can use to get their information from Relatics and share it with others such as project staff or other parties. With the press of a button, you can generate a complete report, including a logo, specific corporate identity and information from Relatics.
In this article, we discuss techniques and tips for creating a report for a requirements specification. End users can personally determine the content with regard to parameters for status and source document. The result is a PDF report displaying the chosen parameters and the set of requirements in accordance with the chosen parameter values.

A separate report part for parameters

In order to show various kinds of information in the requirements specification, it is useful to create different report parts in the report. Consider, for example, report parts with information (e.g. requirements) and report parts that contain report-specific components (such as images and project information).

The report part Parameters was created for the requirements specification. This ensures that the report is more manageable, because you can always find the parameters in the same place. An additional advantage is that this makes it easy to show all chosen parameter values in the report. This will be discussed later in this article.

Tip: Use a separate report part for parameters to make the report more manageable and display parameter values to end users in a more organised way.

Separate constraint queries for applied parameters

The report part Requirements shows the query in which all required metadata for the requirements have been configured. Normally, you would apply the parameters directly in the Status and Document nodes. However, when you look at the query again later on, it is not always clear where the parameters were applied, and it often takes search time to find an applied parameter, especially with larger queries. That is why we recommend creating a separate constraint query for basically every parameter used in a query. For the requirement specification, this was done for both parameters.

Tip: Use a separate constraint query for parameters in a query to make the query more intuitive. In order to even better distinguish from other constraint queries, you can use an additional prefix (e.g. “Param_”).

When you want to apply a parameter to an element with an optional relation, you often run into problems. In the requirements specification, this affects the source document. When an end user chooses a parameter value for ‘, everything is fine. Only the requirements with a relation to the chosen document are reported. The problem occurs when the end user does not choose a parameter value. The end user then expects all requirements to be reported, but unexpectedly finds that all requirements that are not related to a document are not included in the end result. This is because the constraint query acts as a mandatory relation. This can be solved using a special construction in the constraint of the Requirement node:

Special construction for parameters in combination with optional relations

Example: Constraint for the report part Requirements

Object.ConfigurationOfRef='2acfc93a-0884-e711-80ee-000af753dd43'

AND EXISTS(Param_RequirementStatus)

AND ('*'=@Source_Document OR EXISTS(Param_Document))

Tip: Use a constraint query and the following constraint in order to apply parameters to optional relations: ('*'=@MyParameter OR EXISTS(Param_MyConstraintQueryWithParameter))

Displaying chosen parameter values dynamically in Altova StyleVision

In Altova StyleVision, you can configure a table that dynamically displays the content of the report part with parameters. This makes smart use of the standard functionality of Relatics, which includes all configured parameters in the XML file of the report.

By creating a table in which each row contains the content of the RelaticsParameter node of the report part containing parameters, all available parameters for the requirements specification are displayed. The attribute Name shows the name of the parameter (e.g. “Status”) and the attribute DisplayValue shows the value that the end user has chosen (e.g. “Actual”).

The system parameter User is also included by default, but can be excluded in the XPath Filter of the RelaticsParameter node using the following XPath Expression:

Example: XPath Expression to exclude user

@Name != 'User'

A major advantage of this set-up is that it is not necessary to adjust the Altova StyleVision file of the requirement specification every time parameters in the report part containing parameters are changed. This increases the manageability of the report.

Tip: Display a table containing all parameters in the report part containing parameters in Altova StyleVision so that the report is easier to manage. Use the following XPath Expression in order to not show the default Relatics parameter “User”: @Name != 'User'

Applying a selection tree to a parameter

For the status and the source document, showing the parameter values as a list is most practical for end users. Some information is often shown as a tree in the end application – for example breakdown structures, such as the SBS, FBS and WBS.

The requirements specification can be expanded to include a parameter for a system object. This allows end users to limit the set of requirements to a chosen system object that is related to a requirement. By simply selecting a selection tree for the possible values in the parameter section of the query, the parameter values are displayed in a tree when generating the requirements specification.

Tip: Use as selection tree for a parameter if the end user prefers to choose a parameter value from a tree. E.g. for the SBS, FBS and WBS.

End result

A report with parameters enables end users to determine the content. In the example below, you will see that the only requirements displayed are those with (1) the status Actual, and (2) at least one relation with Contractdocument v.01. At the top of the document, you can see a table showing the selected parameters. This way, it is always clear afterwards what dataset was used to generate the report.

Downloads

Upload the following RCS file in your environment to view the elaborated examples of this article.

Contact

Do you need help in applying the techniques and tips in your own case? Or do you have questions, comments or suggestions about this article? If so, don’t hesitate to contact one of our consultants