query_builder
query_builder
This Documentation contains trade secrets or otherwise confidential information owned by Siemens Industry Software Inc. or
its affiliates (collectively, “Siemens”), or its licensors. Access to and use of this Documentation is strictly limited as set forth in
Customer’s applicable agreement(s) with Siemens. This Documentation may not be copied, distributed, or otherwise disclosed
by Customer without the express written permission of Siemens, and may not be used in any way not expressly authorized by
Siemens.
This Documentation is for information and instruction purposes. Siemens reserves the right to make changes in specifications
and other information contained in this Documentation without prior notice, and the reader should, in all cases, consult
Siemens to determine whether any changes have been made.
No representation or other affirmation of fact contained in this Documentation shall be deemed to be a warranty or give rise to
any liability of Siemens whatsoever.
If you have a signed license agreement with Siemens for the product with which this Documentation will be used, your use of
this Documentation is subject to the scope of license and the software protection and security provisions of that agreement.
If you do not have such a signed license agreement, your use is subject to the Siemens Universal Customer Agreement, which
may be viewed at https://www.sw.siemens.com/en-US/sw-terms/base/uca/, as supplemented by the product specific terms
which may be viewed at https://www.sw.siemens.com/en-US/sw-terms/supplements/.
SIEMENS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS DOCUMENTATION INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF
INTELLECTUAL PROPERTY. SIEMENS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL OR
PUNITIVE DAMAGES, LOST DATA OR PROFITS, EVEN IF SUCH DAMAGES WERE FORESEEABLE, ARISING OUT OF OR RELATED
TO THIS DOCUMENTATION OR THE INFORMATION CONTAINED IN IT, EVEN IF SIEMENS HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.
TRADEMARKS: The trademarks, logos, and service marks (collectively, "Marks") used herein are the property of Siemens or other
parties. No one is permitted to use these Marks without the prior written consent of Siemens or the owner of the Marks,
as applicable. The use herein of third party Marks is not an attempt to indicate Siemens as a source of a product, but is
intended to indicate a product from, or associated with, a particular third party. A list of Siemens’ Marks may be viewed at:
www.plm.automation.siemens.com/global/en/legal/trademarks.html. The registered trademark Linux® is used pursuant to a
sublicense from LMI, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis.
Quick search is available by default in the rich client. No configuration is required to use this search with
its default search queries.
You can add custom search items to the Quick search menu by:
2. Updating the two Quick search preferences with the name and attribute of the custom query.
You must update the following preferences when adding custom queries to the Quick search menu:
• Quick_Access_Queries
Specifies which queries appear in the Quick search menu. Valid values are query names defined in
the qry_text_locale.xml locale file.
• General
• Item
• Item Revision
• Remote
• Checked-Out Dataset
• Quick_Access_Queries_Attribute
Specifies the criteria attribute displayed for a query in the Quick search menu using the following
format:
internal-query-name_SearchAttribute=L10N-key
The internal query name is specified in the qry_text_locale.xml locale file. The L10N key is the User
Entry L10N Key value specified for the given query.
In the following example, a custom query named Find PDFs is created. The value of the L10N key is
set to datasettype_name.
• Default_Quick_Access_Query
Specifies the default quick search name, for example, Item ID.
Simple search is available by default in the rich client. This powerful search tool does not require an
in-depth knowledge of the Teamcenter POM schema. Users can create business object searches based
on one or more property values, with only the following limitations:
To allows users to search for other POM objects, you must build queries containing these objects using
Query Builder. Such queries are accessed from Advanced search.
• Only attribute properties and typed referenced properties can be specified for this type of search.
Simple search and Query Builder do not support run-time properties and compound properties.
To allow users to search remote Teamcenter databases, use the Remote saved query, or build a
custom query using Query Builder. Such queries are accessed from Advanced search.
• Search results display in the Search Results view. Users can refresh, compare, save, and assign these
search results. However, the search criteria cannot be saved or shared.
No configuration is required before users can begin using this search mechanism. However you can
modify its behavior by setting Simple search preferences.
You can use the following preferences to modify the behavior of Simple search:
• Default_Business_Object_To_Search
Specifies which business object displays when the Simple search view is opened.
• Favorite_Business_Objects_To_Search
• Searchable_Business_Objects
Filters the business object types that display in the Business Object Type list, limiting the list to the
business objects specified by this preference. Limit the list to only those business objects used at your
site, allowing users to locate business object types quickly.
This preference can be set as a site preference by an administrator and as a group or role preference
by a group administrator.
Advanced search is available by default in the rich client. No configuration is required to use its default
search queries.
• Display hundreds of saved queries available by default. Users access the saved queries as search forms
in which they can type search criteria.
• Distribute saved queries throughout your local site or throughout a global enterprise.
You can use the following preferences to modify the behavior of Advanced search:
• Change_Search_Default
This preference accepts a single string as a value. The value must be a valid saved query.
• QRY_dataset_display_option
Determines whether the latest version or all versions of a dataset object are displayed when query
results are returned.
Set this preference to 1 to display all versions of a dataset object. Set to 2 to display only the latest
version of the dataset object.
• QRY_query-name_SortKeys
Determines the class attributes used to sort the query results. This preference must be used in
conjunction with the QRY_query-name_SortOrder preference, which determines sort order.
The value type of the class attribute must be a primitive value type. For example, char, int, double, or
date. If a query name contains one of the following characters, this character must be replaced with
the underscore (_) character:
• Space character
• QRY_query-name_SortOrder
Determines the sort order of query results. This preference must be used in conjunction with the
QRY_query-name_SortKeys preference, which determines the class attributes used to sort query
results.
Set this preference to 1 to sort query results in ascending order. Set to 2 to sort query results in
descending order.
• QRY_search_type_hierarchy
Determines whether subtypes are included in query results. The system uses type hierarchy
functionality to query types and subtypes.
Administrators can add this as a site preference in the Options dialog box, which can be accessed
from the Edit menu, or in the tc_preferences.xml preferences file. Users can set this, as a user
preference, to true from the search interface:
In the rich client, choose Edit→Options to display the Options dialog box. Select the Search folder
from the tree on the left. Select the Query Options tab. Then select the Enable Hierarchical Type
Search check box. Checking this check box automatically adds this preference to the database, and
sets it to true.
Query Builder enables you to create complex queries based on the Teamcenter data schema, a
hierarchical arrangement of types, subtypes, and properties. Query Builder provides hints to assist you in
navigating the schema. The hints present a relationship as a starting point, for example, the relationship
between an item and its item revision, and then provide you with the steps to build that relationship
into your search definition.
Queries created in Query Builder display in the Saved Queries tree. Saved queries can be used for
searches and to generate reports.
In the context of Advanced search, these queries also appear in the System Defined Searches tree,
accessed by clicking the Select a Search button on the Advanced search view to display the Change
Search dialog box.
The following graphic illustrates a few of the saved searches available by default.
Tip:
When creating objects for your data model in Business Modeler IDE, be sure that you create
related queries that allow users to find them.
Because the queries list is not searchable, be sure to use descriptive query names that users can
recognize by purpose or use. Consider grouping similar queries using common prefixes.
Query Builder is selected during Teamcenter installation, which makes it available with no further
configuration. Use of Saved Queries is subject to user security access rules. Query Builder does not
support run-time or compound properties.
• import or export query definitions to share with other Teamcenter sites. The XML contents are
parsed and verified before the data is imported.
To begin using Query Builder, click in the navigation pane. Saved Queries display a list of
predefined queries.
Saved Queries tree Displays all saved queries in the database. When you select a saved query in the
tree, the details are displayed in the panes on the right side.
For example, a saved query might find all items that have been shipped.
Saved query Displays the name, description, query type, and search type of the selected
properties Saved Queries.
You can modify these properties and then create or modify a saved query. You
can also delete a saved query.
Localization Language Translations lists existing translation values.
• Add or remove a translation value for a locale without altering the master
value of the property.
Search Type Displays the Business Type Selection dialog box that lists the Query types.
Property Selection Displays the attributes of the selected type and either all inherited types or only
pane the direct attributes of the type, depending on the display setting you select.
Search Criteria Defines the search criteria clauses using attributes, user entry keys, operators,
pane and default values. Boolean operators process multiple search criteria clauses.
Type a name (and an optional wildcard) in the box at the top and click Search . The number of types
matching your search are displayed at the bottom, and the first result is highlighted in the tree.
Selecting properties
To create query definitions, select the type of property to use in the search criteria.
Related properties are displayed in Property Selection pane. Displayed properties show all inherited
types or only the direct attributes of the type.
Display Settings
• Properties without the plus symbol can be directly set when searching for objects.
• Properties with the plus symbol refer to another type in the type structure, which may have direct
properties or more properties with plus symbols.
3. Populate the Property Selection list with the properties required to build the search criteria.
Properties are either type properties, parent type properties, or reference type properties.
Double-click attributes without the plus symbol to add them directly to the Search Criteria table.
4. You can add reference types, which are types related to the search type. Navigating reference type
requires knowledge of the Teamcenter data model.
• Double-click references with the plus symbol to list more attributes or to open Property
Selection. Double-click a type from the Property Selection to add the type and its properties to
the Property Selection list.
• Double-click Referenced By at the bottom of the Property Selection list to open Property
Selection. Double-click the Search Type box to search for a type. Select a reference and click OK
to add the reference and its attributes to the Property Selection list.
Property Selection
Property Selection displays the properties of the selected type and either all inherited type properties or
only the direct properties of the type.
Character array
Date
Date array
Double array
Float
Float array
Integer
Integer array
Logical
Logical array
Short
Short array
String
LongString attributes cannot be used in queries.
String array
Typed reference
Untyped reference
External reference
Note
Note array
Typed relation
Untyped relation
Class
vi overlay
Boolean The Boolean rules (AND/OR) are used to combine clauses to create a custom query. When
rules you use AND clauses together, both must be satisfied to return a match. When you use
OR clauses together, either can be satisfied to return a match.
The indented search feature only supports AND clauses.
Attribute The selected database attribute displays in this box.
User Entry Specifies the localization key used to look up user entry names. The localization key-value
L10N Key pairs are defined in qry_user_entry_names_locale.xml. The value in this column can be
modified and must be unique within the search criteria definition.
User Entry Displays the query box names as they appear in the search form. The user name is the
Name value of the localization key entered in the User Entry L10N Key column. If the key-value
pair is not defined in the qry_user_entry_names_locale.xml file, the user entry name
is the same as the key entered in the User Entry L10N Key column. The value in this
column cannot be modified.
Logical You can specify a range of values using >, >=, <, and <=, or invert search criteria using !=.
operators
Specify one of the following logical operators in each search clause.
= Equal to
!= Not equal to
> Greater than
>= Greater than or equal to
< Less than
<= Less than or equal to
IS_NULL Reference property value is not set (blank). You may also specify
=$NULL.
IS_NOT_NUL Reference property must have a value. You may also specify !=$NULL.
L
Default You can specify a default values for a search clause. Enter a default value as a text string
Value or select it from the associated list of values. This value is required only when you do not
specify the user entry name or if the logical operator is IS_NULL or IS_NOT_NULL.
If you make any change to the default Teamcenter queries, the modified values are
displayed unless you explicitly enter the variable name over its displayed value.
Default Teamcenter query variables
• Use $USERID, $USERNAME, and $GROUP variables as default values for the end user
who is running the query.
The $NULL variable can be a default value when the logical operator is = or !=. The User
Entry L10N Key is not required.
To use a list of values (LOV) for a property on a form business object, the LOV must be
attached to the same property on the form’s parent business object. The form parent is
the storage class for the properties. Otherwise, the LOV is not attached to the property
and does not display in Teamcenter clients.
• Make certain the User Entry L10N Key value is unique for each clause.
• Use the AND operator (rather than OR) to place multiple default values, each separated by a
semicolon, in the Default value column.
Example
Attribute User Entry L10N Key User Entry Name Default Value
object_name object_name Name = *
AND object_type object_type Type = UGMASTER;DirectModel
Sort order
Default sort attributes are defined on the Order By tab. In My Teamcenter, use the Search view Sort
dialog box to specify sort order or override the default sort order for a saved query.
1. Create a query.
2. Next to Search Criteria, click Order By and select an attribute to display the Order By tab.
3. In the Order By tab, select an attribute to move it up or down in the Sort By precedence order list.
Specify whether to arrange in Ascending or Descending order.
When you perform your search, Teamcenter examines each search clause for matching values. The
Search Criteria pane defines the elements in the Search Criteria table. Double-click an attribute in the
Property Selection box to add it to the Search Criteria table.
Your changes are committed to the database when you click Create or Modify.
Example:
This Search Criteria table finds users that meet the person name and user ID search criteria.
The combination of the User Entry L10N Key and Default Value elements control how the search
criteria is displayed.
1. The User Entry L10N Key has a value and the Default Value is blank.
Result: The attribute displays in the saved query for the user to populate.
2. The User Entry L10N Key has a value and the Default Value has a value.
Result: The attribute displays in the saved query with the default value. The user can change the
default value in the saved query pane.
3. The User Entry L10N Key is blank and the Default Value has a value.
Result: The attribute does not display in the saved query. The value is evaluated in the query.
Note:
When the User Entry L10N Key is blank, the Default Value must have a value.
Example
Attribute User Entry L10N Key User Entry Name Default Value
1 owning_user.user_id OwningUser Owning User = $USERID
2 AND owning_group.name OwningGroup Owning Group = $GROUP
3 AND object_type Type Type = ItemRevision
1. The user ID of the Workspace Object owning user is the user logged on and running the query.
Result: The attribute displays the user ID of the current user in the saved query. The query looks for
workspace objects owned by the user ID.
2. The name of the Workspace Object owning group is the current group of the user logged on and
running the query.
Result: The attribute displays the group name of the current user in the saved query. The query
looks for workspace objects owned by the group name.
Result: The attribute displays Item Revision in the saved query. The query looks for workspace
objects with a matching type.
You may create custom queries that search for objects in Teamcenter databases. When you create a
query, you must provide the following:
Create a query
1. Type a unique Name for the query. You may provide a Description.
If you create a query using “__” preceding the name, the query will only be visible to the dba
group.
4. You can expand or narrow the focus depending on the type you choose. Limit the search to the
lowest possible type in the hierarchy.
To locate a type, type the type name (or partial name and wildcards) in the box at the top, and click
Search . The number of types matching your search are displayed at the bottom, and the first
result is highlighted in the tree.
5. To display the search results in an indented or hierarchical form, select Show Indented Results.
Direct properties of the type are displayed in the tree. Reference types and properties can be
accessed by expanding Referenced By in the tree.
• Attribute
• Logical operators
9. Click Create .
The query name appears in the Saved Queries tree of Query Builder and in System Defined
Searches in My Teamcenter.
Modify a query
1. Select a query from Saved Queries. Query information is displayed on the right side of the
window.
2. Change the information in Name, Description, or Search Type, and/or Search Criteria table
columns.
Delete a query
1. Select a query from Saved Queries. Query information is displayed on the right side of the
window.
3. Click Yes to delete the query from the database and remove it from the Saved Queries tree.
3. Click Show Hints next to Search Type to display the hints pane.
5. For this example, expand the Item Queries folder, select Item to Item Master Form, and click OK.
The selected hint displays in the hint pane. The first entry in the hint is the base type, followed
by the traversal steps, ending with the property of the item master form type that is added to the
query clause.
The Item type is highlighted in the schema tree of Business Type Selection.
8. The item type and its properties display in Property Selection. The Find in Tree and Add Clause to
Table buttons are available.
9. The Item to Item Master Form hint traverses the schema to the project_id property from the Item
Master Form. To add this property to the query definition, click Add Clause to Table.
10. You can also search for the project_id property of the Item Master Form. Click Find in Tree to
display the Property Selection pane, and search for the Project ID property.
11. Double-click any of the other properties to add them to the clause table.
You can use other hints to add more clauses to the query table. Select a new hint and repeat the
previous steps.
1. Select an existing query from the Saved Queries tree and enter a unique Name.
2. Change the information in the Description box, Search Type box, and/or Search Criteria table
columns.
The system adds the query to Saved Queries. The query form is also available in System Defined
Searches+ in My Teamcenter.
Example
3. Click Search Type to select the target type for the query.
4. Expand the POM Application Object type. Find and expand the Workspace Object type.
5. Select Item Revision and then close. Item Revision is now displayed on Search Type and Item
Revision and its properties are displayed in the Property Selection pane.
6. Click Display Settings and select All Properties. Select the Release Status property in the tree,
and then click Add .
The Release Status property and default operator (IS_NULL) are displayed in Search Criteria table.
7. Click the right corner of the operator cell and change IS_NULL to IS_NOT_NULL.
The system adds the query to the Saved Queries tree. The query form is also available in System
Defined Searches in My Teamcenter.
Example
2. Select Local Query from the Modifiable Query Types list. Click Search Type to select
the target type for the query.
3. Expand the POM_application_object type, then find and expand the WorkspaceObject type.
Double-click the Dataset type to display the type and its attributes in the Property Selection box.
4. Double-click the Referenced By node in the Property Selection pane to display the Property
Selection dialog box. Select the type and through which attribute the given object is referenced in
that type. You can add selected attributes to the Search Criteria table.
5. Click Search Type to select the referencing type for the query.
The referencing type and its attributes are displayed in the Property Selection dialog box.
Only those attributes that may reference the objects of the type being queried, in this case the
Dataset type, are displayed.
Property Selection displays the referencing attribute and type, in this case Specifications and
ItemRevision.
8. Select the attributes of the referencing type on which you want to build query clauses. In this
case, find and double-click the Name attribute to display it in the Search Criteria table. The display
name is ItemRevision←IMAN_specification.object_name. The ← symbol indicates a reversed-
reference relationship.
9. Type a key name in User Entry Key to make User Entry Key unique when you perform a query
from My Teamcenter search. Then click Create .
The system adds the query to the Saved Queries tree. The query form is also available in System
Defined Searches in My Teamcenter.
• Define a query that restricts the search to Bolt and makes all Bolt properties available as the search
criteria. In the Find application, the user can enter values for one or more Bolt properties.
• Define a query that restricts the search to Bolt but makes a subset of Bolt properties (for example,
Length and Radius) available as the search criteria.
• Define a query that restricts the search to item and makes item properties and bolt properties through
the IMAN_classification reference be available as the search criteria.
1. Select a Classification type from the type schema using the Type Selection dialog box, accessed
by clicking the Search Type button .
When creating a saved query, the search type must have at least one of its own properties (a
property not inherited from its parent type). Otherwise, the search returns objects from its parent
type, rather than the specified type.
2. After selecting a Classification type, select Classification properties through the Property
Selection pane to build query clauses.
The Classification hierarchy used by Query Builder is exactly the same as the Classification hierarchy
used in the Classification applications. The highest level of the hierarchy represents groups that do not
contain properties and cannot be used in a search. These group nodes display a different icon. The
nodes below the group level correspond to a Classification type. The type level nodes can be used to
build saved queries.
After a Classification property is selected from the Property Selection tree, its internal property ID is
shown as Property name in the Search Criteria table while its property display name is shown as User
Entry Name in the Search Criteria table. You can modify the user entry name if required.
Note:
When you double-click the Tc_classification property, only the Classification hierarchy is shown in
the Type Selection dialog box to enable you to select a Classification type and use its properties to
build query clauses.
Note:
Classification LOVs do not show up as cascading LOVs when used in saved queries or with
extended multi-application search. Instead they are displayed as a flat list with all selectable
entries.
The Name, Description, Property Selection and Search Criteria display the information for
FindObjectsWithNameValuePairs query.
If you prefer, you can create your own saved query for table properties.
2. Select Local Query from the Modifiable Query Types list. Click Search Type to select
the target type for the query.
4. Click Display Settings and select All Properties and Real Names.
6. Click Search Type and search for your table row business object.
7. Select the table row business object and open fnd0OwningObject, which lists the table row
properties for your search.
8. Add the owning object and build your search by selecting the attributes on which you want to build
the query clauses. When finished, click Create to create the query.
Your new query now appears in the Saved Queries tree pane and is available in Select a Query in
My Teamcenter.
The following steps show how to create a query of a subtype on a typed reference. In this case, the
purpose of the query is to find folders containing datasets that are checked out.
2. Click Search Type to select the target type. The Business Type Selection Popup
displays the business objects in tree format.
3. Expand the POM Application Object type. Find the Workspace Object type and expand it. Select
the Folder type, and close.
Folder is displayed on the Search Type button, and the Folder type and its properties are displayed
in the Property Selection pane.
The Business Type Selection Dialog displays the referenced type, in this case, WorkspaceObject,
and all of its subtypes.
The Property Selection pane displays the Contents [ Dataset ] properties and its properties of the
Dataset type.
6. Double-click the Revision chain anchor [ RevisionAnchor ] property node. The Business Type
Selection Dialog displays the RevisionAnchor type.
Expand the RevisionAnchor in the tree to display the properties in the Property Selection pane.
7. Double-click the IMAN_RES_checkout type. The Business Type Selection Dialog displays the
business object schema.
Expand the ImanReservation type to display its properties in the Property Selection pane.
Double-click the Reservation State property to add it to the Search Criteria table.
The system adds the query to the Saved Queries tree. The query form is also available in System
Defined Searches in My Teamcenter.
• QRY_exception_list
Specifies the list of queries to be excluded from using join approach on relations and references.
• QRY_query_name_SortKeys
Determines the type property used to sort the query results. This preference must be used with the
QRY_query_name_SortOrders preference, which determines sort order.
• QRY_query_name_SortOrders
Determines the sort order of query results. This preference must be used with the
QRY_query_name_SortKeys preference, which determines the type property used to sort query
results.
• QRY_query_name_REVRULE
Specifies the revision rule applied to search results for searches against ItemRevision and its
subclasses.
• TC_QRY_search_by_rev_rule
Finds the latest item revisions based on revision rules. For example, when querying for the latest
working item revision, you can set this preference to Latest Working before running your query.
• TC_QRY_display_latest_dataset_only
Displays the latest version of dataset objects when you set this preference to 1 before running your
query.
• SEARCH_RESULT_LOAD_ALL_LIMIT
• Open_previous_open_search
Display a previous search result in the search results view when you set this preference to 1.
A set of PFF objects corresponding to the basic search types are part of the Teamcenter installation.
Additional PFF objects may be defined by a Teamcenter administrator, as this action requires knowledge
of property data storage and relationships between data objects. If you build queries using property
finder formatter objects, you cannot include the dot character (.) in type names.
3. Enter a Name which reflects the related query and an optional Description.
4. Select a type for the PFF criteria. Click Principle Query Object and select the type that matches the
base type of the query. When you close, the type appears in Principle Query Object.
If you don't know the base type, view the query details in the search criteria definition.
You can display all properties, rather than only type properties, by clicking Display Setting and
selecting All Properties.
5. Add a search clause to Search Criteria. In Property Selection, double-click a property to add it to
the Search Criteria table.
If you change display settings after adding search clauses to the Search Criteria table, the table is
cleared.
6. You may include a secondary type in the PFF property search criteria, and add the related search
clauses to the Search Criteria table.
Click Add Clauses From and select a secondary type that matches one of the object types returned
by the original query.
When you close, the selected type appears in Add Clauses From. The type and its properties
appear in Property Selection.
Add a search clause to the Search Criteria table for each property of the secondary type in the
same manner you added one for the primary type.
If you specify criteria for a PFF for an ad hoc query but do not click Create, the file size, byte size,
and MIME type information is not displayed in the ad hoc results.
8. Verify that the PFF search returns what you expect. In the Search Results view, open the PFF list
and choose the one you created. The results are applied to the Search Results objects.
The PFF object also appears in Saved Property Formatter Finder in the Edit window. You may open it
and make changes from there.
Attribute index
If there are more than 5,000 instances of the search type to be found, you must add an index to the
attribute on which you are searching. Doing this helps search performance. However, if the table is very
small (that is, the type has less than 500 instances), a full-table scan is more efficient than an index
scan.
If you do not create an index on an attribute, a full-table scan of the Oracle table automatically takes
place. This affects the System Global Area (SGA) of the Oracle server. SGA is the portion of memory
where Oracle caches queries and their execution plan. You can use the install utility -add_index
argument to add an index for an attribute.
You can import a query definition from an XML file and create a corresponding query in the Teamcenter
database. Correctly formatted data in the XML file may be incompatible with the local database schema,
causing an error when creating a query definition from incompatible data.
1. Open Query Builder and click Import, which displays the last query definition file that was
imported.
2. Click Browse to find the XML file containing the definition you want to import.
3. In the Read Query Definition, find the XML file and click Import, which displays the contents of
the XML file.
4. Click Verify. If the file format is valid, the query data is displayed in the Query Builder pane.
Verify validates that the POM class matches existing classes in the database. If there are parser
errors, a message describes the nature of the errors.
5. Click OK to load the query in the saved query tree. Then close Import.
7. Click Create .
The system verifies that the definition is compatible with the local database schema. If so, the query is
saved in the database. If not, an error message describes the discrepancies.
1. Select the query in the Saved Queries tree to display the query definition in the right pane.
3. Click Save to specify the path and file where you want to save the definition. Include the .xml
file extension in the file name.
2. Click Search Type to select the target type for the query.
3. Expand the POM Application Object type and locate the Saved Search type.
4. In Property Selection, click Display Settings. Select All Properties and then Display Names.
5. Double-click the Owner subtype in the tree. Property Selection displays the Owner [User]
property and its properties of the Saved Search type.
6. In the Search Criteria pane, specify Name, Description, and Query Type.
• Folders
Used to group hints by category. They have two associated attributes: folder name and description.
The folder name is displayed in the Choose Hint dialog box tree and the description is the tool tip
displayed when the user places the mouse over the folder. Folders can be nested to arbitrary depths
and can contain both folders and hints.
• Hints
Contain four fields: name, description, search type, and query clause. The hint name is the text you
see in the hint tree. The description is the tool tip displayed when the user hovers over the hint. The
search type is the origin of the query, and the query clause is the hint that provides the path to the
attribute.
The simplest way to obtain the query clause is to copy it from the Query Builder Search Criteria table
from an existing query and paste it into the query hints XML file.
If you edit the file in a text editor, convert the angle brackets (>) and (<) characters to the XML
equivalents, > and <. There is no mechanism during an upgrade to preserve customizations to the
Fnd0SavedQueryHint dataset.
<!DOCTYPE ImanQueryHintFile [
<ImanQueryHintFile>
<!-- =============================================== -->
<!-- ========= item hints ========================== -->
<!-- =============================================== -->
<folder name="Item Queries" description="Query Hints for Item Relationships">
<hint name="Item to Item Revision" description="adding item revision criteria to the
item
search" class="Item" hint_text="ItemRevision<-items_tag.item_revision_id"/>
<hint name="Item to Item Master Form" description="adding master form criteria to the
item
search" class="Item" hint_text="Form:IMAN_master_form.ItemMaster:data_file.project_id"/>
<hint name="Item to Item Revision Form" description="adding criteria from an item
revision master form into the item search" class="Item"
hint_text="ItemRevision<-items_tag.Form:IMAN_master_form_rev.ItemVersionMaster:
data_file.project_id"/>
<hint name="Item to IMAN_Specification" description="adding criteria from an underlying
hint_text="structure_revisions.PSOccurrence<-
parent_bvr.ItemRevision:child_item.object_name"/>
<hint name="Child Components to Assembly (Precise Structure)" description="adding
assembly
item revision criteria to the child component item revision search"
class="ItemRevision" hint_text
="PSOccurrence<-child_item.parent_bvr.ItemRevision<-structure_revisions.object_name"/>
</folder>
<!-- =============================================== -->
<!-- ========= workspace object hints ============== -->
<!-- =============================================== -->
<folder name="Workspace Object" description="Query Hints for Workspace Objects">
<hint name="Contents to owning Folder" description="adding folder criteria to the
content
object search" class="WorkspaceObject" hint_text="Folder<-contents.object_name"/>
<hint name="Workspace Object owner id" description="adding owner criteria to the
workspace
object search" class="WorkspaceObject" hint_text="owning_user.user_id"/>
<!-- note that this hint is repeated below.
hints can be duplicated under different folder haedings as needed -->
<hint name="Workspace Object in an EPMJob" description="adding EPMJob criteria
to the workspace object search" class="WorkspaceObject"
hint_text="EPMTask<-attachments.EPMJob<-root_task.object_name"/>
</folder>
<!-- =============================================== -->
<!-- ========= EPMJob hints ======================= -->
<!-- =============================================== -->
<folder name="Workflows" description="Query Hints for EPMJobs">
<hint name="Job by state" description="adding job state criteria to the EPMJob search"
class="EPMJob" hint_text="root_task.state_value"/>
<!-- note that this hint is repeated above.
hints can be duplicated under different folder headings as needed -->
<hint name="Workspace Object in an EPMJob" description="adding EPMJob criteria
to the workspace object search" class="WorkspaceObject"
hint_text="EPMTask<-attachments.EPMJob<-root_task.object_name"/>
</folder>
<!-- ==================================================== -->
<!-- === one of every relationship type hints ========= -->
<!-- -->
<!-- This block includes an example of each type of -->
<!-- hint in a relationship by relationship type basis -->
<!-- -->
<!-- It is not intended that these be made available -->
<!-- in a production environment. This is why the are -->
<!-- commented out -->
<!-- -->
<!-- The below hints also demonstrate the sub-folder -->
<!-- capability of the hint tree. It is possibly to -->
<!-- organize hints by tc class (as above) or by -->
<!-- organization - as detailed below. -->
<!-- -->
<!-- -->
<!-- ==================================================== -->
<!-- commented out...
<folder name="Dept 1 hints" description="hints for joe's department">
<hint name="simpleName" description="no levels of indirection" class="Item"
hint_text="item_id"/>
<hint name="inClass" description="inClass classification... " class="Item"
hint_text="<Complex_analysis>:IMAN_Classification.1000"/>
<hint name="inClass2" description="inClass classification...with funny name "
class="Item" hint_text="<33333>:IMAN_Classification.1003"/>
<hint name="alias" description="iman alias relationship" class="Item"
hint_text="Alias:iman_alias"/>
<hint name="owner id" description="one level of indirection" class="Item"
hint_text="owning_user.user_id"/>
<hint name="item rev reference" description="references example" class="Item"
hint_text="ItemRevision<-items_tag.owning_user.user_id"/>
</folder>
<folder name="Designer's Hints" description="a list of queries used in the design group">
<folder name="engine design" description="yes we can nest n-levels deep">
<hint name="simpleName" description="no levels of indirection" class="Item"
hint_text="item_id"/>
<hint name="inClass" description="inClass classification... " class="Item"
hint_text="<Complex_analysis>:IMAN_Classification.1000"/>
<hint name="alias" description="iman alias relationship" class="Item"
hint_text="Alias:iman_alias"/>
<hint name="owner id" description="one level of indirection" class="WorkspaceObject"
hint_text="owning_user.user_id"/>
<hint name="item rev reference" description="references example" class="Item"
hint_text="ItemRevision<-items_tag.owning_user.user_id"/>
</folder>
<hint name="simpleName" description="no levels of indirection" class="Item"
hint_text="item_id"/>
<hint name="inClass" description="inClass classification... " class="Item"
hint_text="<Complex_analysis>:IMAN_Classification.1000"/>
<hint name="alias" description="iman alias relationship" class="Item"
hint_text="Alias:iman_alias"/>
<hint name="owner id" description="one level of indirection" class="WorkspaceObject"
hint_text="owning_user.user_id"/>
<hint name="item rev reference" description="references example" class="Item"
hint_text="ItemRevision<-items_tag.owning_user"/>
</folder>
-->
</ImanQueryHintFile>
Some Geolus databases may contain parts relating to Item Revisions that are inaccessible by the rich
client user. By default, the Geolus integration with Teamcenter omits inaccessible Item Revisions from
the search results displayed. However, there are preferences which can be set enable the display of
inaccessible search results and control what information is displayed. The only functionality available
to the user for an inaccessible result, when displayed as part of a shape search, is to display some of
the textual information held by Geolus associated with that Item Revision and the thumbnail image.
Whether to display the thumbnail image or not and what textual information to make available can be
configured by the Teamcenter administrator.
A result is classed as inaccessible if it does not exist on the current Teamcenter site (it is owned by a
different site and has not been published/exported), or if the currently logged-in Teamcenter user does
not have permission to access the Item Revision.
Preferences allow the individual elements of inaccessible results to be shown or hidden. There are
preferences to control how the thumbnails are faded so that they appear different, and there are
preferences which allow the padlock symbol and other images to be customized.
Any image files specified should be located in the icons subdirectory of the results JAR file.
The preference Geolus_IA_InfoFormat controls the information displayed in the tool-tip box when
the mouse hovers over an inaccessible result. The same text can also be copied to the clipboard by
right-clicking the result and selecting Copy Inaccessible Text.
This preference may contain any text. Special values can also be used so that attribute values from
Geolus can be displayed. If any of these special values are put into the preference, they are replaced
with the corresponding attribute value for each result.
The default value includes the Item ID, Name, Revision and Owning User:
To assist in setting preferences, the defaults are in an XML file that can be imported directly to the
Teamcenter server using the preferences_manager utility.
GEOLUS_HOME\GeolusTeamcenterIntegration\TC_VERSION
The recommended command for importing the preferences to Teamcenter is (enter as a single line):
The GROUP scope is recommended but can be changed. If GROUP is used, the preferences must be
imported for each group of users on the Teamcenter server. The SITE scope can be used to specify the
preferences once for the entire Teamcenter site.
Modifying the search describes how the user controls the degree of shape match in a search. This
interface control will be the same in the modify search and the preferences dialogs. By default, this
interface control will match the one used on Geolus web pages in the browser interface.
It is recommended that this is done in the Teamcenter preferences interface, or using the
preferences_manager tool. Note that this is usually a SITE wide preference.
Troubleshoot errors
Any errors that occur during the search will typically be reported on the Geolus Search Results page or
in a pop up.
Geolus Search can only be performed on Item The Item Revision selected to initiate the search
Revisions that contain a DirectModel DataSet did not contain a DirectModel (or JT) dataset.
Error connecting to the Geolus Server. The GeolusServer preference has been set
Please check that the Teamcenter preference incorrectly, or the Geolus Server to which it
GeolusServer is specified correctly. refers is not available. The Geolus administrator
should verify the setting of the GeolusServer
preference and the status of the Geolus server.
Part not found in Geolus Database. Error The JT dataset associated with the part contains
occurred during extraction: Model doesn’t no geometry.
contain triangles
Part not found in Geolus Database. Error The JT dataset was too large to be indexed in
occurred during extraction: Java heap space memory.
Access to Shape Search denied to user (0) The Teamcenter Single Sign On token cannot
be authenticated. Contact the Teamcenter
administrator.
The specified Geolus server is not compatible The Geolus database associated with the
with Shape Search. specified Geolus server does not contain
the right attribute names for use with the
Geolus Teamcenter Integration. The Geolus
administrator should refer to the Geolus
Teamcenter Indexer manual to ensure the
database is appropriately synchronized with the
Teamcenter database.
The Geolus Teamcenter Integration plug-in does If, after installation, the Geolus icon does
not appear in the rich client. not appear in the Send To menu, it may
be necessary to rebuild the cache of plug-ins
recognized by the rich client. To achieve this,
close the rich client and run the genregxml
utility located in the portal/registry folder within
the rich client installation folder.
Shape searches are very slow and the Check access to thumbnails. Network or
Teamcenter log file contains the message: configuration issues with thumbnails can impact
search performance.
Cannot download result thumbnail Contact the Geolus administrator for thumbnail
configuration problems.
The Send To action fails with the message: Unregister and reregister the plugin.
And there are messages in the error details that 3. Run the genregxml utility in the registry
include the string: folder inside the rich client installation
location.
java.lang.NoClassDefFoundError:
org/apache/axis2/AxisFault 4. Copy the new Teamcenter Integration files
and folders into the plugins folder.
This may be associated with an upgrade of 5. Run the genregxml utility once more.
Geolus software.
Shape Search functionality is available from any Teamcenter application that displays selectable Item
Revisions. As an example, start My Teamcenter, and find an Item Revision which contains a JT dataset.
Right-click on the Item Revision, choose Send To > Shape Search.
The results of the Shape Search appear as a grid of thumbnails in the Shape Search Results view in the
current application or perspective.
Each part listed in the new view will be an Item Revision whose shape has some degree of similarity to
the query part. The first part in the array is always the query part and has a gray background area. Parts
are ordered in decreasing order of similarity from left to right and down the page.
The results displayed depend on the query part, the contents of the Geolus database, and on how the
search has been configured. Results will be excluded if the current Teamcenter user does not have read
privileges on the Item Revision(s) unless the display of inaccessible parts has been enabled (see Display
of inaccessible parts).
For each part, the name and size relative to the query part is usually shown. The information displayed is
configurable.
Parts can be selected from the array: the selected part has a blue border. When in the My Teamcenter
application, the Summary, Details and Viewer views relate to the current selected part.
Option Action
Send to Shape Search Initiates a new Shape Search using the selected part
Send to Lifecycle Viewer Opens the selected part in the Lifecycle Viewer (the Shape Search
Results view remains open)
Send to My Teamcenter Opens the selected part in My Teamcenter (the Shape Search Results
view remains open).
Properties Opens the Teamcenter properties dialog to show the Item Revision.
Larger sets of Shape Search results are usually divided into pages. A typical page might consist of 30
items (the exact number that are displayed on each page is configured). Up and down arrows allow
navigation through several pages, and you can display all the results on one page.
Before displaying all the search results, check the total number of results indicated at the top of the
Shape Search Results view. It can take an appreciable length of time to render the thumbnails if there
are more than a hundred results to display at once.
Modify the current search by selecting Modify Search. The Shape Match control displayed in this dialog
box and in Preferences can be changed by the Teamcenter administrator. See Configuring shape
match control.
The relative minimum and maximum sizes are used to filter the search results to include only those parts
whose size relative to the query part is within the given bounds.
Ask your Geolus Server administrator to explain other terms that appear in this list.
If the Geolus administrator makes changes to the server configuration that affect the shape match
options, these changes will not be available until the rich client is restarted.
A slider can be used to control shape match. The left-most position of the slider corresponds to Identical.
Dragging the slider to the right will increase the number of results obtained from a search. The right-
most position corresponds to all similar results.
The Save Options section controls if and how the modified search is saved for later use.
Option Action
Add New Search Save the modified search as a new search, in addition to the original
Replace Current Search Replace the search which is being modified with the modified
version
Do Not Save Modified Search Do not save the modified version of the search
Attribute Filters allows search results to be refined by applying alphanumeric filters on the generic
attributes stored in Geolus. The filter labels will depend on the Geolus database and may vary in
number.
A search can be modified so that only parts where the attribute ITEM NAME starts with 04_s will be
returned.
The characters * and ? are wild card characters, matching any number of characters and any single
character respectively.
If the Geolus Server administrator connects to a different database or makes a change to the
database which affects the attributes stored in it, the rich client must be restarted. This is a very rare
circumstance. If the rich client is not restarted, then the result of any search that includes attribute filters
will be unpredictable.
• The Search preferences control the minimum and maximum size filters and shape match parameter
used for all subsequent searches. Shape match is set by a slider control but may be replaced by a
drop-down.
• The Results preferences control what is displayed with each part, how many results are displayed per
page (default 30), and how many results are saved with persisted searches (default 30).
The Teamcenter administrator can enable this functionality which is disabled by default. If this
functionality has been enabled, Item Revisions that are not directly accessible by the currently logged in
Teamcenter user will be shown in the results of searches. Depending on the configuration, more or less
information about these results can be seen, enabling suitable candidate results to be explored.
Configure this functionality by configuring the display of inaccessible results. Many of the
preferences affect the appearance.
All accessible results are shown with normal thumbnails, the Item/Revision name and the size match
information. If objects are inaccessible, they display with a padlock image (this image can be changed),
and are slightly faded (the amount of fading can also be changed).When an inaccessible result is
selected, the thumbnail will be shown without any fading.
The accessible and inaccessible search results appear in the same order as they would if the same search
were performed through the Geolus web interface.
To show more information about an inaccessible result, hover over the thumbnail to show a tool-tip. The
text can be configured by the Teamcenter administrator. To copy this text, right-click on the result and
select Copy accessibility text to clipboard.
Every time a Shape Search is run, the search query parameters are saved for later use, including
between Teamcenter sessions. This means that running a saved search against a Geolus server that has
changed (in configuration or content) may produce different search results.
You can see a list of the saved searches in the Shape Search Results view. This displays a list of the most
recent searches, with the option of showing all saved searches by clicking on More Open Shape Search
Results.
If a search is saved and the maximum number of saved searches has been reached, the oldest search
will be deleted to make space. The maximum number of saved searches can be configured using
Preferences as explained in modifying the default search.
The More Open Shape Search Results option opens the Previous Shape Searches dialog, allowing the
entire list of saved searches to be accessed. Individual searches or the entire list can be deleted. Searches
can run again using Open.
Selecting the option Clear All Shape Search Results removes all saved searches.
Searches may be run again either by clicking on the entry in the list or by clicking Open in the dialog
box. If parts were added or removed from the Geolus server since the search was originally created, the
new results will reflect this.
In rare situations, a saved search may refer to shape match values that do not correspond to the current
Geolus server configuration. A dialog prompts for an alternative shape match value selected from those
currently available. Choosing the correct shape match value depends on the type of search required.
Contact the Geolus administrator for guidance.
If the Geolus administrator connects it to a different database or makes a change to the database which
affects the attributes stored in it, this will affect any saved search which refers to attribute filters. If this
happens, restart the rich client and clear the list of saved searches.