Overview

This is an introductory course that covers the basic Item Report Generation features of swExplorer. Topics include model, GUI and view concepts. Examples and exercises are provided. Much of the script language described in this training is applicable to other configurable views, such as tables, grids, charts and graphs. Therefore, this training is recommended as a prerequisite to other available script language courses.

Course Type

Suitable for class training or for self study. 

Course Length

Approximately a half-day course.

Prerequisites

Exercises

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



Note: This presentation does not cover more advanced report options like document generation, table generation, or the SWQL language. 


Introduction

The report generation features in SystemWeaver enable users to design efficient and powerful reports that, together with appropriate SystemWeaver system models, can entirely replace the use of handwritten system documentation. Report generation can be used with any size of system model, and is probably the most powerful report generation of its kind. Features include simple options such as generation of a report that follows an item structure or more advanced options that allow users to traverse the structure in any order. After completing this course, explore all available reporting features by using the SystemWeaver Help accessed by clicking the ? in the swExplorer or by taking the next course.



Basic Concepts

The report script language is defined using XML. Therefore, the swExplorer uses XML adapted editors for viewing and editing report templates. A report is always defined by the Report element and sub-elements in the report.


Example:


The following report will generate the string ”Simple text”:


<Report>

    <Text>Simple text</Text>
</Report>


The report language is basically declarative, i.e., it tells what should be done, rather than how, for the input that is given.
The output will therefore be controlled by both the input objects – item and part structures – and the report template.
A report starts operating on the specific item that the report script is invoked for, and can then start operating on that item’s part structure. However, at any given moment, a report element operates on a specific object.


Using Item Reports in swExplorer

In SystemWeaver, reports are generated out of Items. Item Reports are available in the Reports view which can be selected in the View drop-down. (A)

Here, you can chose to use a pre-defined report (if available) or create a new report using the Sandbox option. (B)

The report script operates on the item selected in the Item Structure Tree to the left. (C)


Available Report Elements

Available report elements are described in the SystemWeaver Script Language Reference section of the Help which can be accessed by pressing “F1” or clicking the ? in the top-right corner of swExplorer.


Reports - View Tab

When you select a pre-defined report via Reports in the View drop-down list, the report View tab will display. This is where the report output is displayed.

The content of the generated report displays in the top section of the View tab. (A)

The report can be printed, copied to the clipboard or saved as RTF. (B)

A log pane at the bottom of the View tab reports any problems, as well as other logging information produced by the report script. (C)


Reports - Definition Tab

Report script is written on the Definition tab. This tab displays the report script editor which is a simple XML editor. (A)

Some report tags refer to item types through their IDs. Right-click on the editor and select the Insert>Insert SID option which will allow you to look up the SIDs you might need. (B)

When you select Sandbox via Reports in the View drop-down list to create a new report, the report Definition tab will display so you can begin scripting the report.


Note: If using the Sandbox Mode, the content of the sandbox can be lost when you switch to another item and change view. It is recommended that you save intermediate revisions by copying and pasting into NotePad or some external editor.


The Training Meta Model

The meta model defines the language and processes for the various elements in SystemWeaver. The meta model used in the Report Training database is quite simple:

  • A Document can include any number of Sections
  • A Section can include any number of Subsections
  • A Section can include any number of Requirements
  • A Requirement can have a Priority number and Verification Method

Note:  SystemWeaver Item Type IDs are called SIDs  (indicated in brackets above) and are needed in report templates. All SIDs in this case, except Priority, are standardized in SystemWeaver.


Finding Item and Part SIDs 

Each Item Type has an ID called a SID. They are vital when designing reports. There are two main views you can use to find SIDs in swExplorer: 

  • Item Type
  • Parts


Item Type View

In the View drop-down, select Item Type. The view for the selected item will display. 


The Item Type view shows metadata information about the item selected (highlighted in blue) in the structure tree. This information may include data such as:

  • Other items that refer to the selected item as well as through what part types (A)
  • The inheritance structure for the selected item (B)
  • Items that the selected item refers to (C)


The SID is displayed at the top-right of each node. The SID for the item selected in the above example is BIAC.


Parts View

The Parts view shows the actual parts and part types used by the selected item unlike the structure tree’s simplified view. 

In the View drop-down, select Parts



To view SIDs for parts, right-click on one of the displayed column headers, e.g., Part Name, and select Expert>Add field column



The Add Field Column dialog will display. Enter 'SID' and click OK


A SID column will appear and display the part type SID. 


Note: Columns can be rearranged in the display by dragging and dropping.


Finding Attribute SIDs in the Client

An attribute is a value that helps to identify an item. Finding a SID for an attribute in the client is easily done in the Overview view, by pressing ALT and clicking on the attribute type name. A pop-up will display information about the attribute type including the SID within parenthesis. The SID for the Verification Method attribute in the screenshot below is ABVM.



Bildresultat för exercise icon freeExercise 1 - Text and Description Reports

  1. Open Item: x040000000000002A.  (Note that you need to always select an item so that you have something that the report script can operate on.)
  2. Script a report that includes the words "Hello World" using the <Text> tag. 
  3. Script another report that includes the Description of your item, using the <Description/> tag. Note that not all Items have content in their Description. 


Tip: You can use the example script provided above under Basic Concepts and just modify it! After completing each report, click on the View tab to view it.


Note: All tags are case sensitive.



Basic Constructs - Sequence

If the report script contains multiple report elements, they will appear in the sequence in which they appear in the script and on separate lines. 


Example:


The following report will generate the item name first, then the description second on a new line.


<Report>

  <Text>#{Name}</Text>

  <Description/>

</Report>


Tip: You can copy an example script provided in this article to get started! Note, however, that sometimes Windows will switch characters during the copying: “ (left quotation mark) is not the same character as " (quotation mark), and – (minus sign) is not the same as - (dash).



Is the Report Language in SystemWeaver an (imperative) programming language?

The sample sequence looks like a sequence of instructions. However, it should really be understood as a declaration of the output sequence of the report. The report output will first include a Text section and then a Description.


The script language does not include normal variables or means of programming generic algorithms. Rather, the report structure supports a declaration of:

  • The way to parse out the reported item and its part structure, and
  • The serialization to the output report


In many ways, it’s like style sheet language, e.g., XSLT.


Basic Constructs - Attributes

There are two basic ways of including item attribute values in a report:

  • Inclusion of a specific attribute type
  • Inclusion of all attributes

Example: 


The following report will include all attributes of the reported item.

<Report>
  <AttributeTable/>
</Report>

Example: 


The following report will include the Priority attribute (if there is any) of the reported item.
 
<Report>
  <Text>#{Attribute:PRIO}</Text>
</Report>


Bildresultat för exercise icon freeExercise 2 - Attribute Reports

  1. Open Item: x040000000000002A
  2. Select one of the item's requirements in the structure tree. (To find a requirement, expand the item until a requirement is viewable.) 
  3. Script the two examples given above in Basic Constructs - Attributes.

Basic Constructs – Text and Field Codes

It can often be useful to include an item's name and other properties or attributes in a text sequence on one line. For that purpose, SystemWeaver offers so called Field Codes


Examples of Field Codes


Property

Field Code

Item (or part) name

#{Name}

Item (or part) type name

#{Type.Name}

Item (or part) attribute value

#{Attribute:ASID}


Example


<Report>

  <Text>The #{Type.Name} #{Name} has the priority #{Attribute:PRIO}.</Text>

</Report>


Available Field Codes

The below field codes are the most commonly used. For a complete list, see the SystemWeaver Help.


Property


Field Code


Name of the current item


#{Name}


Name of the type of the current item


#{Type.Name}


Real name of the owner of the item/part


#{Owner.RealName}


Attribute value of the attribute with SID "ASID"


#{Attribute:ASID}


Unique ID number for the item in the database


#{Handle}


Complete version string, e.g., "Prel(3)"


#{Version}


Version text from the version string, e.g., "Prel"


#{VersionText}


Version number, e.g., "3"


#{VersionNumber}


Including Parts in a Report

The tag <ForEachPart> can be used to report on all parts of a specific type (SID) for an item.


Bildresultat för exercise icon freeExercise 3 - Document Reports

  1. Open Item: x040000000000002A
  2. Script a report for the ”Document 1” example item (available in the training database) that includes:
    • The Description of the "Document 1" item itself.
    • The Name and Description of all top-level Sections of the item.

Tip: Use the Insert SID option (right-click in the XML editor) to get the SID of the Document Section parts.


Recursion and ItemTemplates

In Exercise 3, we explicitly iterated for each "Document 1" Section. By nesting several <ForEachPart> elements, we can traverse arbitrarily deep into an item structure.


Example


<Report>

  <ForEachPart type="IRRS"> <!-- Document Sections -->

    <DefObj>

      <Text>#{Name}</Text>

      <ForEachPart type="ISSE"> <!-- Sub Sections -->

        <DefObj>

          <!-- Do something with the Section -->

        </DefObj>

      </ForEachPart>     

    </DefObj>

  </ForEachPart>

</Report>


A disadvantage of the above solution is that we explicitly have to traverse the entire structure that we want in the report. In most cases, the better alternative is to use ItemTemplates instead.

Below is the above example rewritten using an <ItemTemplate> element.

  • The ApplyItemTemplates element will apply any declared template for the specific item. 
  • By using ApplyItemTemplates in an ItemTemplate, the report will traverse recursively down a Subsection structure. 
  • AppyItemTemplates will look up an ItemTemplate that corresponds to the current item's type or one of its sub-types, i.e., it takes inheritance into account. 
  • The search for a matching template is done from the first to the last template. 
  • A good rule is to always place the ItemTemplates for types at the bottom of the inheritance tree first. Otherwise, it will be blocked by more general types. 
  • If no ItemTemplate is found for an Item type when generating a report, a warning will be produced in the log window, but it will not stop the generation of the report.

Bildresultat för exercise icon freeExercise 4 - Recursive Document Reports

  1. Open Item: x040000000000002A
  2. Modify the report script from Exercise 3 so that the report will include all Sections of ”Document 1” using an ItemTemplate.


Structured Output

So far, the report output has been in ”plain text” and based on the input item structure. The script language, however, includes construct for the creation of structured output in sections which can include titles and automatic numbering.


Example


<Report>

    <Section title="Introduction">

    </Section>

    <Section title="Chapter 1" no="5">

        <Section title="This is a section">

        </Section>

        <Section title="This is another section">

        </Section>

    </Section>

</Report>


Result: 



Section elements can be used anywhere in the report script including in ItemTemplates.


Bildresultat för exercise icon freeExercise 5 - Structured Reports

  1. Open Item: x040000000000002A
  2. Rewrite your last report and include sections for all Document Section items.  (The order of all sections should reflect the number indicated in each section’s name.)

Tip: Use #{Name} to set the name of the sections.


If Statements

The content of an If statement will execute if the test condition is fulfilled.


The content of the test=“” clause in If statements is defined using the SystemWeaver Path Query Language which will be covered in more depth in the next section of this course. The examples provided demonstrate only some of the capabilities of the Path Query Language. 


Example


<Report>

  <If test=“IsSID('BIAC')">

    <Text>This is a Application Component or one of its subtypes</Text>

  </If>

  <If test="SID ='RQ'">

    <Text>This is a Requirement</Text>

  </If>

</Report>


Result: 


Choose Statements

The Choose construct functions similar to an If-then-else clause in programming. The first When construction with a condition evaluated to true will be executed and the remaining statements will not be tested. If no When condition has been evaluated to true, the content of the Otherwise clause will execute.


The content of the test=“” clause in Choose statements is defined using the SystemWeaver Path Query Language which will be covered in more depth in the next section of this course. The examples provided demonstrate only some of the capabilities of the Path Query Language. 


Example


<Report>

  <Choose>

    <When test=“IsSID('BIAC')">

      <Text>This is a Application Component or one of its subtypes</Text>

    </When>

    <When test="SID ='RQ'">

      <Text>This is a Requirement</Text>

    </When>    

    <Otherwise>                        

      <Text>This is something else than an Application Component or a Requirement</Text>

    </Otherwise>

  </Choose>

</Report>


Result:


SystemWeaver Path Query Language – Brief introduction

The SystemWeaver Path Query Language is extensive and powerful. This introduction will cover some basic constructs. Note that a lot of the functionality regarding field codes is redundant with functionality in the Path Query Language.


Path Query - Highlights


Object Methods

Method

Description

IsSID(‘ASID’)

Returns true if the current object is of the type ‘ASID’ or one of its subtypes


Object Properties

Property


Description


@ASID

Returns the value of the attribute ‘ASID’ from the current object

CreatedBy

Returns the user name of the creator of the object

LastChangedBy

Returns the user name of the user that was the last one to make a change on the object

Name

Returns the name of the current object

SID

Returns the SID of the current object

Version

Returns the version(version number + version info) of the current object

VersionNumber

Returns the version number of the current object

VersionInfo

Returns the version info of the current object


Operators

Property

Definition

Example

=

Equals

@PRIO = 1

!=

Not Equals

@PRIO != 1

not

Not (used as a prefix)

(not @PRIO > 10)

and

And (used as infix)

<@PRIO = 1> and <SID='RQ'>

or

Or (used as infix)

<@PRIO = 1> or <@PRIO = 2>


Path Query - Types

In Path Query Language, types are important. Strings cannot be compared to numbers and vice versa. Strings are defined using ' ', e.g. 'Hi ' or ' 1' are strings while 1 is a number.


Example


<Report>

  <If test="@PRIO = 1">

    <Text>The attribute Prio is 1</Text>

  </If>

  <If test="SID ='RQ'">

    <Text>This is a Requirement</Text>

  </If>

 </Report>

  • The attribute Prio with SID=’PRIO’ is an integer
  • To check if the value equals 1, the below construct  is used:


<Report>

  <If test="@PRIO = 1">

    <Text>Prio equals 1</Text>

  </If>

</Report>


  • If Prio were a string, the following would be valid:


<Report>

  <If test="@PRIO = '1'">

    <Text>Prio equals 1</Text>

  </If>

</Report>


Bildresultat för exercise icon freeExercise 6 - If Statements

  1. Open Item: x0400000000000292
  2. Modify the report from Exercise 5 for this item and include the names of the requirements.
  3. Use If statement: 
    • If a requirement has Prio 1, put ‘HIGH:’ before its name. Otherwise, just print the name.



Bildresultat för exercise icon freeExercise 7 - Choose Statements

  1. Open Item: x0400000000000292
  2. Modify the report from Exercise 6.
  3. Use Choose statement: 
    • If a requirement has Prio 1, put 'High:' before its name. Otherwise, just print the name.


Debugging

Style sheets like the report scripts are inherently difficult to debug since there is no explicit execution order. A way to trace problems, however, is to include logging messages in the script using the <Log> element. Another method is to implement the script incrementally and continuously test it as you go along.


Saving and Publishing Reports

When you are satisfied with the view of your report, you can save it. 


Note: This requires SystemWeaver Architect rights.


  1. Click the Save XML Definition button. The New Config Item dialog will display. 
  2. Enter a Name for your report in the Enter Name text box provided. 


Saved reports appear in the View drop-down list under Reports. (A)

Reports can also be added as a menu option to an existing or new tab ribbon. (B)


Creating a New Report By Copying An Existing

A quick way to create a new report that is similar to an existing one is to use the Save as new configuration option.

  1. In the View drop-down, select Reports and then select the existing report definition you wish to copy. 
  2. On the Definition tab, modify the script to to fit the needs of the new report.
  3. Click the Versioning button and select Save as new configuration.
  4. In the New Config Item dialog, enter a name for the new report and click OK. The new report will now appear as on option under Reports.


Documentation

The creation of a good report script can take many hours, and you should always document your report so that others (and yourself) can maintain the report. As always, what should be documented is not what is evident in the scripts, but what is not: The purpose and principles behind the report – why something is done, rather than how. (The ”how” is always evident from the report script.).  It can be a good idea to include a header where all changes are collected: who, what, when.


What's Next?

We hope that you are pleased with this course and feel ready to start writing reports. You can extend your knowledge by practicing the numerous scripting options described in the SystemWeaver Script Language Reference section in the Help, such as formatted document generation, table generation and SystemWeaver Query Language. Also, check out the SystemWeaver Forum for related topics.