Query-Tree
The Query-Tree webject recursively navigates associations between Windchill objects, producing a tree of related objects.
A bill of materials (BOM) is an example of a tree of related objects. Given one or more base objects, this webject returns all of the objects associated with the base objects by a specified set of relationships. The webject performs this navigation operation recursively until it has descended a product structure to a maximum specified depth.
The output group produced by the webject contains elements representing all of the objects discovered by the recursive navigation process. In addition, when the MODE parameter is specified with the value FLAT, this webject supplies each element with the following metadata:
• com.infoengine.object.id
The unique identifier of the object represented by the element.
• com.infoengine.object.type
The type of object represented by the element. For example, the Java class name is an object represented by the element.
• com.infoengine.depth
The depth in the product structure, relative to the base objects, at which the object represented by the element was discovered. For example, base objects have a depth of 0, so their immediate children have a depth of 1.
• com.infoengine.link.[class].[role]
Specifies a relationship between the object represented by the element and another object. The value is an object identifier matching the com.infoengine.object.id value of some other element in the output group.
◦ The class component of the value name specifies the class name of the Windchill link class defining the relationship.
◦ The role component identifies the role that the related object plays in the relationship.
An example is com.infoengine.link.wt.part.WTPartUsageLink.uses.
Syntax
<ie:webject name="Query-Tree" type="OBJ">
<ie:param name="ACCEPT_LANGUAGE"
data="$(@SERVER[]accept_language[])"/>
<ie:param name="ATTRIBUTE" data="attribute_name"/>
<ie:param name="AUTHORIZATION"
data="$(@SERVER[]authorization[0])"/>
<ie:param name="AUTO_NAVIGATE" data="[TRUE|FALSE]"/>
<ie:param name="CIRCULAR_REFERENCE_BEHAVIOR"
data="[EXCEPTION | LABEL]"/>
<ie:param name="CONFIGSPEC_OBJECT_META" data="meta_name"/>
<ie:param name="CONNECTION_ATTEMPTS" data="attempts"/>
<ie:param name="CONNECTION_ATTEMPT_INTERVAL" data="interval"/>
<ie:param name="DBUSER" data="username"/>
<ie:param name="DEPTH" data="integer"/>
<ie:param name="DESCRIPTOR" data="attribute_name"/>
<ie:param name="DETECT_CIRCULAR_REFERENCES"
data="[TRUE | FALSE]"/>
<ie:param name="DIRECTION" data="role-name"/>
<ie:param name="FORMAT" data="[TRUE | FALSE]"/>
<ie:param name="GROUP_FILTER" data="group_name"/>
<ie:param name="GROUP_IN" data="group_in"/>
<ie:param name="GROUP_OUT" data="group_out"/>
<ie:param name="INCLUDE_ARGS" data="[TRUE | FALSE]"/>
<ie:param name="INCLUDE_CONSTRAINTS" data="[TRUE | FALSE]"/>
<ie:param name="INCLUDE_DESCRIPTORS" data="[TRUE | FALSE]"/>
<ie:param name="INSTANCE" data="appl_name"/>
<ie:param name="MODE" data="[FLAT | NESTED]"/>
<ie:param name="NEXT_OP" data="operation_name"/>
<ie:param name="OBJECT_REF" data="ufid"/>
<ie:param name="OUTPUT_TYPE" data="[OTHER_SIDE | FULL]"/>
<ie:param name="PASSWD" data="password"/>
<ie:param name="REFERENCE_EXCEPTIONS" data="[TRUE | FALSE]"/>
<ie:param name="SELECTBY" data="config_spec_name"/>
<ie:param name="SELECTBY_BASELINE_REF" data="baseline"/>
<ie:param name="SELECTBY_CONFIG_ITEM_REF" data="ufid"/>
<ie:param name="SELECTBY_CONFIGSPEC_REF" data="ufid" />
<ie:param name="SELECTBY_DATE" data="date"/>
data="[TRUE | FALSE]"/>
<ie:param name="SELECTBY_IN_USE_BY_USER" data="[TRUE | FALSE]" />
<ie:param name="SELECTBY_INCLUDE_WORKING"
data="[TRUE | FALSE]"/>
<ie:param name="SELECTBY_LIFECYCLE_STATE"
data="lifecycle_state"/>
<ie:param name="SELECTBY_UNIT" data="unit_value"/>
<ie:param name="SELECTBY_VIEW_REF" data="view_object_ufid"/>
<ie:param name="SESSION_ID" data="$(session_id[]SESSION_ID[])"/>
<ie:param name="TYPE" data="type_name"/>
<ie:param name="WHERE" data="where_clause"/>
<ie:param name="WHERE_CASE_SENSITIVITY" data="[TRUE | FALSE]"/>
</ie:webject>
Parameters
|
Required
|
Interdependent
|
Optional
|
|
DIRECTION
|
AUTHORIZATION
|
ACCEPT_LANGUAGE
|
|
INSTANCE
|
AUTO_NAVIGATE_TOPLEVEL
|
ATTRIBUTE
|
|
CONFIGSPEC_OBJECT_META
|
AUTO_NAVIGATE
|
|
DBUSER
|
CIRCULAR_REFERENCE_BEHAVIOR
|
|
DESCRIPTOR
|
CONNECTION_ATTEMPTS
|
|
GROUP_FILTER
|
CONNECTION_ATTEMPT_INTERVAL
|
|
GROUP_IN
|
DEPTH
|
|
INCLUDE_ARGS
|
DETECT_CIRCULAR_REFERENCES
|
|
INCLUDE_CONSTRAINTS
|
FORMAT
|
|
INCLUDE_DESCRIPTORS
|
GROUP_OUT
|
|
NEXT_OP
|
MODE
|
|
OBJECT_REF
|
OUTPUT_TYPE
|
|
PASSWD
|
SESSION_ID
|
|
REFERENCE_EXCEPTIONS
|
|
|
SELECTBY
|
|
|
SELECTBY_BASELINE_REF
|
|
|
SELECTBY_CONFIG_ITEM_REF
|
|
|
SELECTBY_CONFIGSPEC_REF
|
|
|
SELECTBY_DATE
|
|
|
SELECTBY_IN_USE_BY_USER
|
|
|
SELECTBY_INCLUDE_WORKING
|
|
|
SELECTBY_LIFECYCLE_STATE
|
|
|
SELECTBY_UNIT
|
|
|
SELECTBY_VIEW_REF
|
|
|
TYPE
|
|
|
WHERE
|
|
|
WHERE_CASE_SENSITIVITY
|
|
|
|
If a parameter is listed in the table but is not defined below, then it has a common parameter definition. For descriptions of those parameters, see Common Webject Parameters section in Adapter Webjects Overview. |
AUTO_NAVIGATE
Specifies whether the initial navigation results should be post-processed automatically to produce results that are usually more directly usable. If not specified, the default value is TRUE. This parameter is optional.
In Windchill, product structures are constructed from iterated and versioned objects that have a master and iteration data model.
The root of a product structure is a master object that might have multiple iterations. Masters are linked to their iterations, and each iteration is linked, in turn, to the masters that represent their children in the product structure. Typically, applications do not want to navigate the master and iteration links themselves. Instead, they prefer to see only the iterations, which contain all of the relevant attributes.
The AUTO_NAVIGATE parameter enables the webject to navigate automatically from masters to iterations so that the output group contains the information that the federated client application typically seeks. The AUTO_NAVIGATE parameter also enables the webject to de-reference LightweightProxy objects automatically, returning elements in the output group that have been retrieved from remote systems.
AUTO_NAVIGATE_TOPLEVEL
If set to TRUE, then the AUTO_NAVIGATE parameter applies to the top-level object in a product structure.
If AUTO_NAVIGATE_TOPLEVEL is set to FALSE, then the AUTO_NAVIGATE parameter works as it typically does. The default is FALSE.
Depending on the type of relationship within a structure, it might not be possible to apply automatic navigation to the top-level object.
This parameter only applies if AUTO_NAVIGATE is set to TRUE.
CIRCULAR_REFERENCE_BEHAVIOR
The webject behavior when a circular reference is detected. This parameter is optional.
• EXCEPTION—The expansion of the tree is terminated. This is the default value.
• LABEL—The webject causes metadata to be placed on the group and elements. Nodes that are detected as being the first circular node are inserted into the output, but are not expanded further.
When specified as LABEL, the following information is added:
• On the output group produced by the webject:
com.infoengine.circular.contains=true
This signals that the output group contains circular references.
• On the original element that is referenced by one of its descendants:
com.infoengine.circular.referenced=true
This signals that this element is the original node that has children, one of which refers back to this element.
• On the element that duplicates an element previously expanded within the path between this element and the root of the tree:
com.infoengine.circular.reference=true
Expanding on this element further constitutes a re-expansion of a portion of the tree previously expanded, allowing it to loop back on itself.
CONFIGSPEC_OBJECT_META
The name of the metadata containing the ConfigSpec object to use when filtering objects. This parameter only applies if SELECTBY=CONFIGSPEC_OBJECT.
The default value is com.ptc.windchill.configSpec.
DEPTH
The maximum number of levels of product structure to descend recursively. If not specified, the default value is 1. This parameter is optional.
DETECT_CIRCULAR_REFERENCES
If specified as TRUE, the webject attempts to detect circular references. If specified as FALSE, the webject does not detect circular references. The default value for this parameter is FALSE. This parameter is optional.
|
|
If specified as TRUE, the action the webject takes when circular references are detected can be tailored by using the CIRCULAR_REFERENCE_BEHAVIOR parameter.
|
DIRECTION
The role played by the link class for the objects to be returned. For example: usedBy, references, and referencedBy.
Valid values are dependent upon the link classes defined by the TYPE parameter. If the TYPE parameter is multi-valued, the DIRECTION parameter must be multi-valued, and the number of values specified for these two parameters must be the same. Each value of the TYPE parameter corresponds with a value of the DIRECTION parameter.
This parameter is required.
GROUP_IN
Specifies a group containing objects. For each element of the group that contains an object ID (OBID) attribute, the object referenced by the OBID attribute value is used as a base object.
If not specified, the OBJECT_REF parameter must be specified. If the OBJECT_REF parameter is not specified, this parameter must be specified. If both the OBJECT_REF and GROUP_IN parameters are specified, the multiple indicated base objects are navigated.
GROUP_OUT
The name of the output group containing the results. If this parameter is omitted, then the name of the output group is constructed by appending the string “-Output” to the webject name. This parameter is optional.
MODE
The mode of the list contained in the output group. Valid values for this parameter are the following:
• FLAT—The output group contains a flat list of objects. Relationships between objects and the relative depth of each object within the tree are registered in metadata returned in each object.
• NESTED—The output group contains a nested list of objects. Each object that has children includes attributes whose values are the children.
The names of these attributes are formed by concatenating the class name of the link that defines the parent and child relationship with the role name associated with the children. For example, if the link class is wt.part.WTPartUsageLink, and the role of the children is named “uses,” then an object having children will have an attribute named wt.part.WTPartUsageLink.uses and each value of this attribute is a child object. If a child object has children, it too will have attributes containing its children, recursively.
The default for this parameter is FLAT. This parameter is optional.
OBJECT_REF
Specifies the Unique Federation Identifier (UFID) of an object that serves as the base object, and returns all objects associated with this base object by the relationship specified in the TYPE parameter (and, recursively, all objects related to those objects).
If this parameter is multi-valued, the multiple base objects are navigated, and the output group contains the combination of all objects associated with multiple base objects by the link classes specified by the TYPE parameter.
If this parameter is not specified, then the GROUP_IN parameter must be specified. If this parameter and GROUP_IN are both specified, then multiple indicated base objects are navigated.
OUTPUT_TYPE
Specifies whether to return the associated objects, the link objects themselves, or both. Link objects are the objects defining the relationship between two objects. Valid values for this parameter are the following:
• OTHER_SIDE—Returns the objects to which objects specified by TYPE, WHERE, or OBJECT_REF are related.
• RELATION—Returns the link objects themselves.
• FULL—Returns the objects to which specified objects are related, merged with attributes from the link objects that define each such relationship. The name of each attribute obtained from a link object is formed by concatenating the object class name of the link object with attribute name from the link object in the following format:
wt.part.WTPartUsageLink.quantity.amount
◦ wt.part.WTPartUsageLink is the class of a link object.
◦ quantity.amount is the name of the link object attribute.
The default for this parameter is OTHER_SIDE. This parameter is optional.
SELECTBY
The Windchill configuration specification that is applied when the objects referenced by the specified type of link are members of a product structure (versioned objects). Valid values for this parameter are:
• LATEST—Returns the latest versions of the objects.
• USER—Returns objects selected by the default configuration specification defined for the calling user. If the calling user has no default configuration specification, LATEST is used.
• BASELINE—Returns objects associated with a specific baseline. The SELECTBY_BASELINE_REF parameter must also be specified to identify the baseline to apply.
• VIEW—Returns objects associated with a specific view. The SELECTBY_VIEW_REF parameter must also be specified to identify the view to apply.
• LIFECYCLE —Returns objects associated with a specific lifecycle state. The SELECTBY_LIFECYCLE_STATE parameter must also be specified to identify the lifecycle state to apply.
• IN_USE—Returns objects that are in use.
• EFFECTIVITY—Returns objects associated with specific effectivities. The SELECTBY_CONFIG_ITEM_REF, SELECTBY_DATE, and SELECTBY_UNIT parameters must also be specified to define the effectivity constraints to apply.
• STANDARD—Returns objects associated with the standard configuration specification. The SELECTBY_VIEW_REF, SELECTBY_LIFECYCLE_STATE, and SELECTBY_INCLUDE_WORKING parameters can also be specified to identify constraints to apply.
|
|
This value is specific to WTPart objects.
|
• STANDARD_DOCUMENT—Selects objects associated with the standard configuration specification. The SELECTBY_LIFECYCLE_STATE, SELECTBY_INCLUDE_WORKING, and SELECTBY_IN_USE_BY_USER parameters can also be specified to identify constraints to apply.
• CONFIGSPEC_REF—Selects objects based on a configured and persisted ConfigSpec object. The SELECTBY_CONFIGSPEC_REF parameter must also be specified.
• CONFIGSPEC_OBJECT—Allows a custom ConfigSpec object to be programmatically constructed and passed to the webject to use during filtering. The CONFIGSPEC_OBJECT_META parameter may also be specified. Using the SELECTBY value requires that a GROUP_IN is supplied to seed navigation and that the ConfigSpec object has been stored on the GROUP_IN object as metadata.
The default for this parameter is LATEST. This parameter is ignored when AUTO_NAVIGATE is specified as FALSE
SELECTBY_BASELINE_REF
The UFID of a baseline object used when SELECTBY is specified as BASELINE.
SELECTBY_CONFIG_ITEM_REF
The UFID of a configuration item used when SELECTBY is specified as EFFECTIVITY. When this parameter is specified, either SELECTBY_DATE or SELECTBY_UNIT must also be specified.
SELECTBY_CONFIGSPEC_REF
A reference to a persisted ConfigSpec object to use in filtering objects.
SELECTBY_DATE
A date used when SELECTBY is specified as EFFECTIVITY. This parameter can be used by itself, or it in conjunction with SELECTBY_CONFIG_ITEM_REF.
SELECTBY_IN_USE_BY_USER
Specifies whether only to select objects in use by the user. This parameter is a boolean. It is only used of SELECTBY=STANDARD_DOCUMENT. If not specified, then in use is not used as criteria when selecting objects.
SELECTBY_INCLUDE_WORKING
Specifies whether to include working objects when SELECTBY is specified as STANDARD. Working objects are objects in the personal cabinet of a user. Valid values for this parameter are TRUE and FALSE. The default for this parameter is TRUE.
SELECTBY_LIFECYCLE_STATE
The name of a life cycle state used when SELECTBY is specified as LIFECYCLE or STANDARD.
SELECTBY_UNIT
A unit value used when SELECTBY is specified as EFFECTIVITY. If this parameter is specified, then SELECTBY_CONFIG_ITEM_REF must also be specified.
SELECTBY_VIEW_REF
The UFID of a view object used when SELECTBY is specified as VIEW or STANDARD.
TYPE
The object type name. If WHERE is specified, TYPE must also be specified. For more information, see
Specifying the TYPE and WHERE Parameters.
OBJECT_REF can be specified instead of or in addition to this parameter. This parameter is required.
WHERE
A query expression identifying the objects to be queried. This parameter can be used instead of or in combination with OBJECT_REF and GROUP_IN. If neither OBJECT_REF nor GROUP_IN is specified, WHERE must be specified. If WHERE is specified, then TYPE must also be specified. For additional information, see
Specifying the TYPE and WHERE Parameters.
