The SystemWeaver Path Query Language is a comprehensive and compact language to query SystemWeaver data. It provides a way to navigate the item/part structure and to select lists of items and calculate values from the data. This specialized language for SystemWeaver can be used to generate information for complex scenarios that the basic Script Language features cannot handle. It also provides a means of counting items and following parts backwards in a defined context. In addition, it enables you to "merge" different perspectives. This article introduces the SystemWeaver Path Query Language functionality.


Prerequisites


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, but it's a useful tool. 



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.



Traversing Parts using Axis Steps

When traversing a structure, you may want 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


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
  • HomeLibrary
  • Issue
  • IssueId
  • Item
  • LastChanged
  • LastChangedBy
  • Mother
  • Name
  • Notes
  • Obj
  • Owner
  • OwnerType
  • Parent
  • Part
  • PartNo
  • PartTypes
  • RealName
  • RefObj
  • RefType
  • SID
  • Status
  • StatusLastChanged
  • StatusLastChangedBy
  • To
  • TopNode
  • Type
  • Version
  • VersionInfo
  • VersionNumber
  • VersionText


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 



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

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



Using Path Query Language in Reports, Grids, etc. 

There may be cases where you would like to see more information than is available in the standard views or in the available view tags. The solution is to use field codes which support viewing of additional information like Properties or Attributes. It's possible to use the Path Query Language in the tags used for field codes.


For example, in a report configuration you can use it 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.

 


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>


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.


What's Next?

Learn about using the Path Query Language with creating charts in Combining Knowledge - Charts and the Path Query Language, or how to define custom functions using path expressions.