Overview

This training covers the SystemWeaver Path Query Language functionality in swExplorer. Examples and exercises are provided.

Course Type

Suitable for class training or self-study.

Course Length

Approximately a half day course.

Prerequisites

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

The SystemWeaver Path Query Language is a comprehensive and compact language to query SystemWeaver data. It provides powerful logic and a means to operate on sets of data. It is constantly evolving and does not replace normal report traversing. This specialized language for SystemWeaver can be used to generate information in reports and documents for complex scenarios that the basic report generation features cannot handle. It also provides a means of counting items and following parts backwards in the defined context. In addition, it enables you to "merge" different perspectives.


This course does not cover the complete functionality and available options. After completing this course, explore all available features by using the SystemWeaver Help accessed by clicking the ? in the swExplorer client or by taking additional courses.


Path Query Evaluation Editor

Path query expressions can be tested in the Path Query Evaluation editor. Normally, however, the Path Query Language is used together with other item report generation features. We will start by opening the Path Query Evaluation editor. To access it, click on the View drop-down and selecting Path query evaluation.



Expressions are entered into the ?> box at the top. Results are displayed in the area below it.



TIP: Prior to getting started, it is helpful if you add the Part SID and the Item.SID as columns in your structure tree view.


Traversing Parts

Parts are traversed by starting with a forward slash ”/” and then entering the Part SID. The expression shown below will return all of the Application Components


Example

/XESX/EXAC


If you enter the above expression into the Path Query Evaluation editor and hit Enter, the result will be: 



Note: As seen in the above example, the part order is NOT preserved. The main purpose of the Path Query Language is to collect and evaluate data. The standard means of traversing reports is still the best choice if part order is important. Using both constructs together produces the best results. 


You can evaluate multiple path queries in the editor one after another and each result will appear in the results area in the order in which you evaluate. The result area is editable.



Bildresultat för exercise icon freeExercise 1 - Printing Requirements

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture top node, use the Path Query Language to print all Requirements (RQ).
    Expected result:


    {Requirement 3, Requirement 6, Requirement 1, Requirement 4, Requirement 2, Requirement 5}



Traversing Parts using Axis Steps

When traversing a structure, you may wish to move to a part or traverse backwards, etc. This is done using axis steps. Some of the available axis steps and their functions are explained below. For a complete list of axis steps, consult the Help. 


Axis StepDescription
partStep forward, stopping on the part. Returns a set of the parts of an item.
backFollow parts backwards. Returns a list of all items which include the current obj as the specified part. Note: The use of /back:: is not recommended due to its potentially negative effect on performance for all system users as it is executed on the server-side.
defobjFrom a part, step forward to the item. Returns the DefObj object of a part
issuerefFrom an item, follow an issue reference to the issue. Returns a list of all issues which reference the current obj



Axis steps are always inserted after the ”/”, followed by two semi-colons (::) and before the SID it is operating on as shown below. The two examples illustrate how to traverse parts with "back" and "part" axis steps:


Example

/back::3E2F

/XESX/part::EXAC


Bildresultat för exercise icon freeExercise 2 - Printing Requirements

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, use the Path Query Language to print all issues connected to the Application Components.
    Hint: The SID for issuereferenses = IR
    Expected result: 


    {Implement ParkingBrakeHdlr, Error in BatteryManagementCtrl, Faulty Parameter handling in ParkingAssist, Implement ParkingBrakeCtrl}

Single Items and Sets

The Path Query Language works with sets when handling more than one Item. A set is an unordered collection of unique Items. A set is indicated by  ”[” and ”]” surrounding the result as shown below. When creating reports, grids, etc., it is important to know if you are operating on sets or single items because accessing attributes and object properties are done in different ways.



Attributes and Object Properties - Single Item

Attributes are accessed by writing ”@ASID” for single items. Object properties are accessed by writing ”PropertyName” for single items. 


Examples


SystemWeaver Object Properties

SystemWeaver object properties are used to access information about an item. Below is a list of all of the available object properties. 


  • AllVersions
  • AncestorHandle
  • AssignedTo
  • Attachments
  • Color
  • CreatedBy
  • CreationDate
  • DefObj
  • DefType
  • EMail
  • Field
  • ForeignAncestorId
  • ForeignId
  • From
  • Handle
  • Issue
  • IssueId
  • Item
  • LastChanged
  • LastChangedBy
  • Name
  • Notes
  • Obj
  • Owner
  • OwnerType
  • Parent
  • Part
  • PartNo
  • PartTypes
  • RealName
  • RefObj
  • RefType
  • SID
  • Status
  • StatusLastChanged
  • StatusLastChangedBy
  • To
  • TopNode
  • Type
  • Version
  • VersionInfo
  • VersionNumber



For more information on output type and which objects they are valid for, see the Help manual:



Attributes and Object Properties - Sets

When accessing object properties for items in sets, the method ”Select(”attributeOrProperty”)” is used. This will return a new list containing the result of the ”Select” function for every individual item in the list.


Examples 



Bildresultat för exercise icon freeExercise 3 - Printing Requirement Verification Attribute

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. Select Requirement 1 in the structure tree.
  4. Get the Verification Method attribute (SID=ABVM) for Requirement 1 using the Path Query Language.


Bildresultat för exercise icon freeExercise 4 - Printing Requirement Priority Attribute

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, use the Path Query Language to get all Requirements and print the Prio attribute(SID=PRIO)

More on Methods

Unlike the path expressions, methods used on sets return lists. Lists derived from methods do not require occurrences to be unique. This is useful when the information queried for in a method contains multiple values that are the same. In the below example, the first three requirements have a Prio value of 1. 


<Report>
  <Text>#{?/XESX/EXAC/IBAR.Select(@PRIO)}</Text>
</Report>



Below is a list of some of the available methods. For more information and to view a complete list, see the Help manual.


Count

  • Returns the number of objects in a set
  • Example: /XESX,Count


Max

  • Returns the highest numerical value in the list
  • Example: /SID.Select(@ASID).Max


Distinct

  • Returns a list with unique occurrences of items or values. Only useful on lists
  • Example: /SID.Select(@ASID).Distinct


Matches

  • Performs a regular expression check. Returns true or falue whether a match was found or not
  • Example: /SID.Select(Name).Matches("hdlr")


Sum

  • Returns the mathematical sum of all values in a list
  • Example: /SID.Select(@ASID).Sum

The [ ] Operator

The ”[]” operator is used to filter the Path Query Language queries based on a defined logical expression. Below are a couple of examples. 


Example 1

Return all requirements found below the application components whose Priority attribute (SID=PRIO) equals 1.


/XESX/EXAC/IBAR[@PRIO=1]


Example 2

Returns all application components that have more than one requirement.

/XESX/EXAC[/IBAR.Count>1]


Basic Operators

Below is a list of all of the available basic operators, in order of precedence from highest to lowest, and a short explanation. More than one operator is allowed in a ”[]” expression.


OperatorDescription
*Multiply
+,  -Plus, Minus
>, <Greater Than, Less Than
=, !=Equal, Not Equal
in
[]Predicate
|Set union
all ... satisfy ... any ... satisfies ...Set expressions
notConditional not
andConditional and
oror
if .. then .. elseConditional
:=Assignment

Bildresultat för exercise icon freeExercise 5 - Printing Components with Particular Attribute Value

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, select all application components that have at least one requirement where the Prio attribute equals 3.
    Expected result:

Set Operations

When comparing sets, the following operations prove to be useful: 

  • Minus
  • Union
  • In


Minus

set1 - set2

  • Removes all occurrences in one set from another. The least possible value is an empty set. 
  • Examples: [1,2,3] - [2,3] = [1],   [2,3] - [1,2,3] = []


Union

set1 union set2

  • Adds two sets together
  • Example: [1,2,3] union [2,3,4] = [1,2,3,4]


In

set1 in set2

  • Returns true if all members of set1 are included in set2
  • Examples: [1,2,3] in [2,3] = false,  [2,3] in [1,2,3] = true,  [] in [1,2,3] = true



Bildresultat för exercise icon freeExercise 6 - Check Send Ports using "in"

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, check if all send ports have at least one corresponding receive port using the ”in” operation.


Bildresultat för exercise icon freeExercise 7 - Check Receive Ports using "minus"

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, find all receive ports that do not have a corresponding send port using the ”minus” operation.
    Expected result: 


Bildresultat för exercise icon freeExercise 8 - Printing End to End Functions

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, print ALL available End to end functions, regardless of whether they are in the application components or in the End to End Function List.
    Expected result: 

Using Path Query Language in Reports, Grids, etc. 

You can apply your newly gained knowledge in the Report Editor. There may be cases where you would like to see more information than is available in the standard views in swExplorer or in the available report tags. The solution is to use so called field codes which support viewing of additional information like properties or attributes. It is possible to use the Path Query Language in the tags used for field codes.


In a report template, you can use the field code in any <Text> element. Enclose the field code with a hash sign # and curly brackets { } and start it with a "?":



Tip: Path Query Language expressions can be used in every place where #{} is valid.

 


Bildresultat för exercise icon freeExercise 9 - Path Expression in Text Tag

  1. Open Item x0400000000000292.
  2. Open the Path Query Evaluation editor.
  3. From the Vehicle Architecture, try out some of your earlier exercise solutions inside the Text tag.

Flexibility in Formatting Results

Join

When printing, sets are presented by default inside the ”[ ]” brackets. Sometimes, another presentation format is preferred. This can be achieved with the ”Join” operation. The ”Join” operation creates a string of the items in the set, delimited by what has been defined inside the ' '. 


Example

<Report>
    <Text>#{?/XESX/EXAC.Join(', ')}</Text>
</Report>


+ NewLine

The special keyword ”NewLine” inserts a newline character. Note that the ”+” is required when combining the string with the ”NewLine” keyword.


Example

<Report>
    <Text>#{?/XESX/EXAC.Join(', ' + NewLine)}</Text>
</Report>



Special XML Tags for Using Path Query Language in Configurable Views

There are some special XML tags for using path queries in reports, grids and other configurable views. They are: 

  • <ForEach>
  • <If>
  • <Choose>


<ForEach>

ForEach is the path query version of <ForEachPart>, but the expressions here can be much more complex. 


<ForEach select="path-expression"/>


The tags following the ForEach are applied to all items that fulfill the path expression. 

The below example produces a similar result as the <Text> tag demonstrated earlier. However, here ForEach is used to loop through the resulting set produced by /XESX/EXAC.


Example

<Report>
    <ForEach select="/XESX/EXAC">
        <Text>#{Name}</Text>
    </ForEach>
</Report>


Note: Sorting is supported by using order methods in the path expression. If no order method is used a path expression returns a set, which by default is traversed in alphabetic (ascending) order.


<If>

The content of an <If> tag only executes if the condition set up in the ”test” is true. In the below example, only application components that have more than one Receive Port will be included in the results. 


Example

<Report>
    <ForEach select="/XESX/EXAC">       
        <If test="/ITIS.Count>1">
            <Text>#{Name}</Text> 
        </If>
    </ForEach>
</Report>

<Choose>

<Choose> is a more advanced version of <If>. If the condition in a <When> statement is met, its content will be executed. If the condition is false, the next <When> statement will be tested. If all <When> statements are false, the content of the <Otherwise> tag will be executed.


Example

<Report>
  <ForEach select="/XESX/EXAC">       
    <Choose>
      <When test="/ITIS.Count=1">
        <Text>One port: #{Name}</Text>   
      </When>      
      <When test="/ITIS.Count=0">
        <Text>Zero port: #{Name}</Text>   
      </When>       
      <Otherwise>
        <Text>More than one port: #{Name}</Text>     
      </Otherwise>      
    </Choose>
  </ForEach>
</Report>


Sets and Boolean Expressions

It is possible to use a resulting set to evaluate a condition using <If>, <When>, etc. If the set is empty, the expression will be evaluated to false. If the set contains at least one element, it will evaluate to true. In the below example, only application components that have at least one Receive Port will be printed.


Example

<Report>
    <ForEach select="/XESX/EXAC">       
        <If test="/ITIS">
            <Text>#{Name}</Text> 
        </If>
    </ForEach>
</Report>



Bildresultat för exercise icon freeExercise 10 - Printing Requirement Names with Defined Prefix

  1. Open Item x0400000000000292.
  2. Open the Reports editor.
  3. From the Vehicle Architecture, print all requirements that have Prio =1 with the text ”High! - ” before the requirement name and all other requirements with ”Low! -” before the name.
  4. Try to solve it with both <If> and <Choose>.
    Expected result: 


Path Query Language Variables

Results in path queries can be assigned to variables in the context of a report. In other words, a variable tag is a means of accessing values from the path queries. They are valuable when complex expressions are evaluated in succession and intermediate results are needed for subsequent evaluation and use. They can also be used to avoid repeating the same path expression twice or more. 


<Variable name="" as="" select="path-expression">


name: defines the name of the variable to be used in path expressions.
as: specifies the type of the variable. The types that are supported by the Path expressions are defined in the Path Query Reference manual in the Help.

select: specifies the path expression to be used when the value is assigned to the variable.


Note: The value of a variable can only be assigned once. This means that a variable, as identified by its name, may only occur in a single <Variable> element and there is no way to change the value again. However, for elements that will be evaluated for multiple parts of the model structure (like ForEachPart), the assigned value of a variable may differ for each model element.



The example below shows how to assign a value to a variable and then accessing it in the <Text> tag.


<Report>
    <Variable name="applicationComponents" as="[Item]" select="/XESX/EXAC"/>       
    <Text>#{?$applicationComponents}</Text> 
</Report>



The "?" question mark tells that a path expression should be evaluated and the "$" dollar sign tells that the value of the variable should be used.


Bildresultat för exercise icon freeExercise 11 - Create a Variable That Contains All of the End To End Functions

  1. Open Item x0400000000000292.
  2. Open the Reports editor.
  3. From the Vehicle Architecture, create a variable with the name ”endToEndFunctions” that contains all the End To End Functions found in the End To End Function List.
  4. Print the End To End Functions one per row.
    Expected result: 


Bildresultat för exercise icon freeExercise 12 - Combining New and Old Knowledge

  1. Open Item x0400000000000292.
  2. Open the Reports view.
  3. From the Vehicle Architecture, print only the application components that realize an End To End Function available in the End to End Function List. The order of the application components shall correspond to the structure tree.
    Expected result: 

What's Next?

We hope that you enjoyed this course and have increased your knowledge of the SystemWeaver Path Query Language. You can extend your skills by practicing the numerous scripting options described in the Path Query Reference section of the Help. You can also test combining your Path Query Language skills with creating charts using Combining Knowledge - Charts and the Path Query Language.