The item report generation tool 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.  This article introduces basic item report Generation. Topics include model, GUI and view concepts. Much of the script language described in this training is applicable to other configurable views, such as tables, grids, charts and graphs.

Prerequisites

• Familiar with the SystemWeaver meta model building blocks (e.g., Items, Parts and Attributes)
• Familiar with the SystemWeaver Explorer Interface and common operations
• An installation of the SystemWeaver Explorer client (swExplorer)
• Knowledge of XML (A good resource is w3schools' XML tutorials)
• Assignment of the SW Architect role in the server

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 Documents meta model is used in the script training database and 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.

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

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

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 Field codes in the SystemWeaver Help.

Including Parts in a Report

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

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

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

 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

Object Properties

Operators

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>

 If Statements

1. Open Item: x040000000000002A
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.
     

 Choose Statements

1. Open Item: x040000000000002A
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. 

Example

<Report>
    <Section title="#{Name}">
        <Table>
            <Header visible="true"/>
            <Columns>
                <ItemNameColumn width="auto"/>
                <ItemLastChangedColumn caption="Changed" format="yyyy-mm-dd" width="100"/>
            </Columns>
            <ForEachPart type="4SPE">
                <Row/>
            </ForEachPart>
        </Table>
    </Section>
    <Log>#{Name}</Log> 
</Report>

All field codes (e.g., #{Item.Name}, #{Item.SID}, #{Version}) and text will work. Even path queries should work with <Log>. See the SystemWeaver Script Language Reference guide in the Help for available field codes, etc.

Another method to help with debugging 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)

What's Next?

Interested in SystemWeaver Script Language training? You can also learn about the numerous scripting options in the SystemWeaver Script Language Reference Manual in the Help.