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 enabling 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

Exercises

The answers to all exercises can be found in the swExplorer ribbon tab Report Training>Answers under Parameterized Reports. 


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.


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



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


Bildresultat för exercise icon freeExercise 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: 



Bildresultat för exercise icon freeExercise 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:


Attribute
Description
owner
The group that owns the parts to be added. Owner can be previously defined as defobj or "main". Main is a default keyword for the entry item. Note: If the report or view has any Parameters defined, there will automatically be contexts defined corresponding to each parameter, using the name(s) of the parameter(s).
sid
The SID for the part of interest.
part
A name for the parts to be added. This can later be used to traverse the virtual context tree with for instance <ContextGoForward/> and <ContextGoBack/>.
defobj
A name for the group of items, that the parts are linked to.


Example:

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


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.



Bildresultat för exercise icon freeExercise 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. Additional training in the SystemWeaver Script Language is available upon request.