Overview

This course covers item report generation with a focus on parameterized reports. Normally a report runs with one input, the selected item. Using parameters, you can add additional inputs to the report which enables making comparisons, seeing an item in a context, etc. Examples and exercises are provided.

Course Type

Suitable for class training or for self study.

Course Length

Two hours to half-day course.

Prerequisites

• Completed the SystemWeaver Report Generation - Introductory Training course and the SystemWeaver Script Language - Introductory Training course.
• Familiarity with SystemWeaver concepts such as Items, Parts and Attributes, and also with the GUI and common operations of the swExplorer.  
• Knowledge of XML.
• An installation of the SystemWeaver client (swExplorer).
• A training server (If the course leader has not set up a server for the class, you can set up your own server by following the instructions in Setting up a Test Server).
• The Script Language Training sqlite database. See Database for Script Training.
• Assignment of the SW Architect role in the server if you wish to save your training configurations.

Exercises

The answers to all exercises in this article can be found on the Script Training>Answers ribbon tab:  

Note: This presentation does not cover GUI and view concepts.

Introduction

A parameterized report enables you to provide information about an ”object” in its surroundings. In other words, you can select specific items to include in your report while excluding others. An example would be a single component in an architecture. Other possibilities are to select among alternative contexts where the item is used or to choose among "traceability links". This way a report can be based on multiple objects rather than a single, selected item thus making the Report view a good alternative to customized views. Without parameterizing a report, the information about a specific item can still be provided, but the scope given may be too big given that you are only really wanting to focus on one item.

Parameters

Parameters are variables. From a selected item in the structure tree, it is possible to follow parts down or up in the structure to collect variables (Items/Parts) that can be selected before generating the report.

Example

How does Component C interface with other components?

Parameter Solution

In SystemWeaver, you can set up a parameter selection menu in your report and then make your selection when you want to parameterize your report. To do this, you need to: 

1. Declare a parameter. 
2. Assign possible values to the parameter.
3. Access the chosen value.

Declare a Parameter

<Parameter> declares the parameter. (A)

The caption attribute (B) is the label for the parameter drop-down visible in the view.
The name attribute (C) is the identification of the parameter to be used when the selected value of a parameter is used in the report or view.

The as attribute (D) is optional and can be used to indicate a data type. Valid values are: "String", "Boolean", or "Integer". If as is not defined, it will default to "Item".

The defaultValue attribute (E) is optional and can be used to pre-select a value for users. 

<Report>
   <Parameters>      (B)                (C)        (D)         (E) 
    (A) <Parameter caption="Component" name="comp" as="" defaultValue=""/>
   </Parameters>
</Report>

Note: <Parameters> can be used in reports as well as in the configuration of Grid views.

Exercise 1 - Declare a Parameter

1. Select an Architecture item. 
2. Access the Reports editor. 
3. Create a parameter named ”comp” and parameter selection field label ”Component” as demonstrated above. 

How to Assign Selectable Values to a Parameter

To add values to the Parameter selection drop-down list, use the <Values> and <AddValue> tags. In the below example Architecture, the components (have SID=EXAC) (A) have been defined as the values for the Parameter called "comp" (B).  The SID for the Software part is XESX (C).

<Report>

    <Parameters>

        <Parameter caption="Component" name="comp"> (B) 

            <Values>

                <ForEachPart type="XESX"> (C) 

                    <DefObj>

                        <ForEachPart type="EXAC"> (A) 

                            <DefObj>

                                <AddValue/>

                            </DefObj>

                        </ForEachPart>

                    </DefObj>

                </ForEachPart>

            </Values>  

        </Parameter>

    </Parameters>

</Report>

Note: Parameter values have to be items. This is the reason why <DefObj> is used.

How to Access the Chosen Value

In order to access the chosen value, parameters need to be accessed using a context (using the Context tag) or through the Path Query Language. For this training, we will use a dummy context named 'X'. In the below example, the chosen value is 'ParkingBrakeCtrl' (A). The context name is 'X' (B). The group attribute (C) defines how to access the context in the <ForEachInContext> tag.

<Report>

    <Parameters>

        <Parameter caption="Component" name="comp">

            <Values>

                <ForEachPart type="EXAC">

                    <DefObj>

                        <AddValue/>

                    </DefObj>

                </ForEachPart>

            </Values> 

        </Parameter>

    </Parameters>

    <Context name="X"/>  (B)

    <ForEachInContext name="X" group="comp"> (C) 

        <Text>#{Name}</Text> 

    </ForEachInContext>

</Report>

The generated report for the above definition will look like this: 

Exercise 2 - Parameterized Report for Component

1. Open Item x040000000000018B
2. Access the Reports editor. 
3. Define a report that shows how a component interfaces with other components in the Architecture. (Implicit connections are used).

To build the virtual tree for the context, all parts of interest must be added with <AddParts/>. The AddParts tag is always applied with at least the 4 attributes - owner, sid, part and defobj:

Example:

<Context name="X">

    <AddParts owner="comp" sid="ITOS" part="compSendPort" defobj="compSignals"/>
<AddParts owner="comp" sid="ITIS" part="compReceiveport" defobj="+compSignals"/>
</Context>

Note: In the example above, it is assumed that a parameter is involved. When a parameter is used, it will automatically become the selected item in the context. Therefore, it is not required to use main as a group name.

The below Training Meta Model provides the part SIDs. 

Training Meta Model

The <ForEachPathReference> Tag

So far, we have used parameters to drill down in an architecture to dig up the relevant information about a single component. What if you want to see how the component interfaces with other components in another architecture? Open that architecture and run the report? There is a better way!

The <ForEachPathReference> tag is used to follow parts backwards rather than drilling down. It works similarly to the <ForEachItemReference> tag, but the performance is better.

Example

In the below example, you could trace the references from the Application Component [BIAC] back to a top-level Architecture. The paths are XESX (A) and EXAC (B).

<Report>

    <Parameters>

        <Parameter caption="Architecture" name="arch" hintContextPath="XESX;EXAC"> 

            <Values>

                <ForEachPathReference path="XESX;EXAC">

                    <AddValue name="arch"/>                      

                </ForEachPathReference>                            

            </Values>

        </Parameter>

    </Parameters>

</Report>

The resulting Architecture selection drop-down includes all the other referenced architectures:

Asterisk

If you want to follow a specific part type an arbitrary number of times, add an asterisk ’*’ as shown below for path XESX: 

<Report>

    <Parameters>

        <Parameter caption="Architecture" name="arch" hintContextPath="XESX;EXAC"> 

            <Values>

                <ForEachPathReference path="XESX*;EXAC">

                    <AddValue name="arch"/> 

                </ForEachPathReference>                            

            </Values>

        </Parameter>

    </Parameters>

</Report>

HintContextPath

The optional HintContextPath attribute lets you preselect a parameter value if it exists in the structure tree. It basically holds a list of part SIDs that defines a default selection of an item in the tree.

Another way to configure a preselected value is to use the defaultValue attribute. In the below example, the type of path expression is Boolean and the preselected value will be "true". 

        <Parameter caption="Boolean" name="Boolean" as="Boolean" defaultValue="true">

            <Values>

                <ForEach select="[true, false]">

                    <AddValue/>

                </ForEach>

            </Values>

        </Parameter>

Exercise 3 - Component as Report Object

1. Open Item x040000000000018B
2. Access the Reports editor. 
3. Define a report that shows how a component interfaces with other components in the Architecture. This time use the component as the report object.

Tip: Use the solution from Exercise 2 as your starting point!

What's Next?

We hope that you are pleased with this course and feel ready to start creating parameterized reports. You can extend your knowledge by practicing the numerous scripting options described in the SystemWeaver Script Language Reference section in the Help, or reviewing other articles on the support portal, such as Parameter Support for String, Integer and Boolean Data Types. Additional training in the SystemWeaver Script Language is available upon request.