Teamcenter Query Builder Guide. Publication Number PLM00031 J

Transcription

1 Teamcenter 10.1 Query Builder Guide Publication Number PLM00031 J

2 Proprietary and restricted rights notice This software and related documentation are proprietary to Siemens Product Lifecycle Management Software Inc Siemens Product Lifecycle Management Software Inc. All Rights Reserved. Siemens and the Siemens logo are registered trademarks of Siemens AG. Teamcenter is a trademark or registered trademark of Siemens Product Lifecycle Management Software Inc. or its subsidiaries in the United States and in other countries. All other trademarks, registered trademarks, or service marks belong to their respective holders. 2 Query Builder Guide PLM00031 J

3 Contents Proprietary and restricted rights notice Getting started with Query Builder What is Query Builder? Before you begin Query Builder interface Basic concepts for using Query Builder Basic tasks using Query Builder Creating and managing queries Creating customized searches using Query Builder Create queries Managing queries Using class attribute selections Using preferences when querying Using search criteria clauses Managing the query hints file Managing the query hints file Sample hints file Importing and exporting query definitions Importing and exporting query definitions Import query definitions Export query definitions Application notes Attribute index Best practices Best practices Restore My Saved Searches folder Export saved searches to another Teamcenter installation Glossary A-1 Index Index-1 PLM00031 J Query Builder Guide 3

4

5 Chapter 1 Getting started with Query Builder What is Query Builder? Before you begin Query Builder interface Saved Queries tree pane Saved query properties pane Localization button Search Class button Attribute Selection pane Search Criteria pane Rich client perspectives and views Basic concepts for using Query Builder Basic tasks using Query Builder PLM00031 J Query Builder Guide

6

7 Chapter 1 Getting started with Query Builder What is Query Builder? Query Builder allows you to create customized searches for objects in both local and remote Teamcenter databases. Building query definitions requires knowledge of the Teamcenter POM (persistent object manager) schema, which is an hierarchical arrangement of classes, subclasses, and attributes. Query definitions, also called saved queries, identify search criteria used to find information in Teamcenter. Administrators define query definitions for end users. For example, you can create a saved query to find in the database all items that have been shipped. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Before you begin Prerequisites Enable Query Builder You do not need any special permissions to use the Query Builder application. Query Builder does not need to be enabled before you can use it, but during installation, this feature must be selected. If you have trouble accessing Query Builder, see your system administrator; it may be a licensing issue. Configure Query Builder Note You can log on to Teamcenter only once. If you try to log on to more than one workstation at a time, you see an error message. Query Builder does not need to be configured before you use it. Start Query Builder Click Query Builder in the navigation pane. PLM00031 J Query Builder Guide 1-1

8 Chapter 1 Getting started with Query Builder Query Builder interface 1 Saved Queries tree pane 2 Saved query properties pane 3 Localization button 4 Search Class button 5 Attribute Selection pane Displays all saved queries in the database. Displays the name, description, query type, and search class of the saved query selected in the saved queries tree. Displays the Language Translations dialog box that lists existing translation values. For more information about the Localization button, see the Localization Guide. Displays the Class/Attribute Selection dialog box that lists the query classes for selection. For more information, see Search Class button. Displays the attributes of the selected class and either all inherited class attributes or only the direct attributes of the class, depending on the display setting you select. For more information, see Attribute Selection pane. 1-2 Query Builder Guide PLM00031 J

9 Getting started with Query Builder 6 Search Criteria pane Defines the search criteria clauses using attributes, user entry keys, operators, and default values. Boolean operators are added for multiple search criteria clause processing. For more information, see Search Criteria pane. Saved Queries tree pane The Saved Queries tree pane 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 of the box. Saved query properties pane The saved query properties pane displays the name, description, query type, and search class of the saved query selected in the saved queries tree. You can modify these properties and then create or modify a saved query. You can delete the selected saved query. Localization button Clicking the Localization button displays the Language Translations dialog box that lists existing translation values. The presence of the Localization button indicates the dialog box content can be localized. For example, if the master locale is set to English, you can add a translation for an employee information query. Using the Localization button, you can perform the following tasks: View the existing localization text. Modify the existing localization text. Add a translation value for a new locale without altering the master value of the property. Remove a translation value without altering the master value of the property. For more information about the Localization button, see the Localization Guide. Search Class button Clicking the Search Class button displays the Class/Attribute Selection dialog box, which allows you to navigate and search the Teamcenter POM schema and select classes and attributes for use in query definitions. 1. Type the class name (or partial name of the class along with a wildcard) in the box at the top of the dialog box. 2. Click the Search button. The number of classes matching your search are displayed at the bottom of the dialog box, and the first result is highlighted in the tree. PLM00031 J Query Builder Guide 1-3

10 Chapter 1 Getting started with Query Builder To navigate through the results: Go to next match Go to previous match Go to first match Go to last match Press F3, Page Down, or Down Arrow key. Press the Page Up or Up Arrow key. Press the Home key. Press the End key. Attribute Selection pane The Attribute Selection pane displays the attributes of the selected class and either all inherited class attributes or only the direct attributes of the class. The following symbols indicate the attribute type. Symbol Attribute type Character Character array Date Date array Double 1-4 Query Builder Guide PLM00031 J

11 Getting started with Query Builder Symbol Attribute type Double array Float Float array Integer Integer array Logical Logical array Short Short array String String array Typed reference Typed reference array Untyped reference Untyped reference array External reference External reference array Note Note array Typed relation Untyped relation Class External link default PLM00031 J Query Builder Guide 1-5

12 Chapter 1 Getting started with Query Builder Symbol Attribute type vi overlay Search Criteria pane When you perform your search, Teamcenter examines the attribute specified in each of your search clauses and looks for values that match your search. Following are the search criteria elements. Element Boolean Rules Description The Boolean rules (AND/OR) are used to combine clauses to create a custom query. When you use AND clauses together, both must be satisfied to return a match (both this clause and that clause). When you use OR clauses together, either can be satisfied to return a match (either this clause or that clause). Keyword clauses do not support the OR rule. Note The indented search feature only supports AND clauses. For more information about the indented search feature, see the Rich Client Interface Guide. Attributes User Entry L10N Key User Entry Name Logical Operators The selected database attribute displays in this box. Specifies the localization key used to look up user entry names. The localization key-value pairs are defined in the qry_user_entry_names_locale.xml file. The value in this column can be modified and must be unique within the search criteria definition. Displays the query box names as they appear in the search form. The user name is the 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. Matching values can be equal to, not equal to, less than, or greater than the value specified in your search clause. Matching values can also be null or not null. These conditions are called logical operators. You must specify one of the following logical operators in each search clause. Logical operator Description = Equal to.!= Not equal to. > Greater than. >= Greater than or equal to. 1-6 Query Builder Guide PLM00031 J

13 Getting started with Query Builder Element Description < Less than. <= Less than or equal to. IS_NULL IS_NOT_NULL Indicates that the reference attribute value must be blank (not set). Indicates that the reference attribute must have a value. Note Logical operators can only be used for string attribute types. Default Value You can search for ranges of values using the >, >=, <, <= logical operators or invert search criteria using the!= logical operator. Default values can be specified for the query clauses. Default values can be entered as a text string or selected from the associated list of values, where applicable. After the value is set, press Enter to save the default value. This box is required only when you do not specify the user entry name, unless the logical operator IS_NULL or IS_NOT_NULL is used. The following keyword variables can be used to display default values in the query form: $USERID $USERNAME $GROUP $TODAY The values displayed in boxes for which the $USERID, $USERNAME, and $GROUP variables are used as a default value correspond to the end user who is running the query. The $TODAY variable displays the current date. These variables are used in the default Teamcenter queries. If you make any change to the default queries, the modified values are displayed unless you explicitly enter the variable name over its displayed value. PLM00031 J Query Builder Guide 1-7

14 Chapter 1 Getting started with Query Builder Note Siemens PLM Software recommends the following when using the Search Criteria pane: For each clause, make certain the User entry L10N key value is unique. When you use AND and OR clauses together, the search result displays unexpected results. Therefore, use the AND operator (rather than the OR operator) and place multiple default values in the Default value column separated by a semicolon, as shown in the following example. Attribute User entry L10N key User entry name object_name object_name Name = * Default value AND object_type object_type Type = UGMASTER;DirectModel The Order By tab contains the following search criteria elements. Element Attribute User Entry L10N Key User Entry Name Order By Description The selected database attribute appears in this box. Specifies the localization key used to look up user entry names. The localization key-value pairs are defined in the qry_user_entry_names_locale.xml file. The value in this column can be modified and must be unique within the search criteria definition. Displays the query box names as they appear in the search form. The user name is the 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. Specifies the sort order or overrides a default sort order defined for a saved query. Each attribute can be set to arrange in either Ascending or Descending order. For more information about using the Order By tab, see Specify sort order for a saved query. Rich client perspectives and views Within the Teamcenter rich client user interface, application functionality is provided in perspectives and views. Some applications use perspectives and views to arrange how functionality is presented. Other applications use a single perspective and view to present information. Note Your administrator can use the HiddenPerspectives preference to prevent the display of some Teamcenter perspectives in the rich client. For information about editing preference values, see the Preferences and Environment Variables Reference. 1-8 Query Builder Guide PLM00031 J

15 Getting started with Query Builder If your site has online help installed, you can access application and view help from the rich client Help menu or by pressing F1. For more information about rich client perspectives and views, see the Rich Client Interface Guide. Basic concepts for using Query Builder Depending on your needs, you can use an existing query from the saved queries tree. Saved queries are subject to standard object protection and are accessed by users through the search feature in My Teamcenter. For more information, see Create a new query based on an existing definition. You can also use Query Builder to create queries based on the following features: Queries using the hints feature Queries that include a keyword search Queries based on an existing definition Queries using the IS_NULL or IS_NOT_NULL operators Referenced-by queries Queries based on classification attributes Subclass queries on a typed reference Once created, query definitions can be exported and saved as XML files that can be shared with other Teamcenter sites. Conversely, query data saved in XML files can be imported into Teamcenter. The XML files are parsed and verified before the data is imported. For more information, see Importing and exporting query definitions. Basic tasks using Query Builder Query Builder is a Teamcenter administrative application that is used to perform the following tasks: Create customized searches for objects in both local and remote Teamcenter databases. Store query hints in the query hints file, queryhint.xml. Export query definitions saved as XML files, which can be shared with other Teamcenter sites. Import into Teamcenter query definitions saved as XML files. For more information about these tasks, see Creating customized searches using Query Builder, Managing the query hints file, and Importing and exporting query definitions. PLM00031 J Query Builder Guide 1-9

16

17 Chapter 2 Creating and managing queries Creating customized searches using Query Builder Create queries Create a query using the hints feature Create a query that includes a keyword search Create a new query based on an existing definition Create a query using the IS_NULL or IS_NOT_NULL operator Create a referenced-by query Create a saved query on classification attributes Create a saved query using a revision rule Specify sort order for a saved query Create a subclass query on a typed reference Managing queries Modify a query Delete a query Using class attribute selections Add class attributes to search criteria Using preferences when querying Using search criteria clauses Search criteria clause example Assign precedence to clauses Remove clauses from the table PLM00031 J Query Builder Guide

18

19 Chapter 2 Creating and managing queries Creating customized searches using Query Builder Query Builder allows you to create customized searches for objects in Teamcenter databases. When using Query Builder to create a query, you must provide the following information: The search class for the query For more information, see Using class attribute selections. At least one search criteria clause For more information, see Using search criteria clauses. Create queries 1. Click the Clear button to remove existing information from the Query Builder boxes. 2. In the Name box, type a unique name for the query. 3. Optionally, type a description of the query in the Description box. 4. Select Local Query from the Modifiable Query Types list. 5. Click the Search Class button. The Class/Attribute Selection dialog box appears. PLM00031 J Query Builder Guide 2-1

20 Chapter 2 Creating and managing queries 6. Specify the desired search class by selecting an entry from this dialog box. Tip You can significantly expand or narrow the focus of your query depending on the class you select. It is best to limit the search to the lowest possible class in the hierarchy. To locate a class, type the class name (or partial name and wildcards) in the box at the top of the dialog box, and click the Search button. The number of classes matching your search are displayed at the bottom of the dialog box, and the first result is highlighted in the tree. To navigate through the results: Go to next match Go to previous match Go to first match Go to last match Press F3, Page Down, or Down Arrow key. Press the Page Up or Up Arrow key. Press the Home key. Press the End key. 7. To display the search results in an indented or hierarchical form, select Show Indented Results. 8. Double-click to select at least one of the attributes in the Attribute Selection tree. Direct attributes of the class are displayed in the tree. Reference classes and attributes can be accessed by double-clicking the Referenced By node in the attribute tree. 2-2 Query Builder Guide PLM00031 J

21 Creating and managing queries The attribute is added to the Search Criteria table. For more information about class attribute selections, see Using class attribute selections. 9. Specify the desired search criteria. You must specify the following required search criteria boxes: Attribute User Entry L10N Key Logical operators For more information, see Using search criteria clauses. 10. Click the Create button. The query is created, and the name appears in the saved queries tree of the Query Builder application and in the System Defined Searches list in My Teamcenter. Create a query using the hints feature Query hints are provided to assist you in navigating the schema by presenting a relationship to traverse (for example, item-to-item master form) and the steps required to build that relationship into your query definition. 1. In the Name box, type a unique name for the query. 2. Optionally, type a description of the query in the Description box. 3. Select Local Query from the Modifiable Query Types list. 4. Click the Show Hints button in the saved query properties pane. The system displays the hints pane. 5. Click the Choose Hint button located at the top of the hint pane. The system displays the choose hint pane containing the directory of query hints. 6. Expand the Item Queries folder, select Item to Item Master Form, and click OK. The dialog box closes and the system displays the selected hint in the hint pane. The first entry in the hint is the base class, followed by the traversal steps, ending with the attribute of the item master form class that is added to the query clause. PLM00031 J Query Builder Guide 2-3

22 Chapter 2 Creating and managing queries 7. Select the base class by clicking the Search Class button. The system displays the Class/Attribute Selection dialog box. 8. To locate the Item class, type Item in the search box and then click the Search button. The Item class is highlighted in the schema tree of the Class/Attribute Selection dialog box. 2-4 Query Builder Guide PLM00031 J

23 Creating and managing queries 9. Close the Class/Attribute Selection dialog box by clicking the X in the upper-right corner. The system displays the item class and its attributes in the Attribute Selection area, and the Find in Tree and Add Clause to Table buttons are available in the hint pane. 10. The Item to Item Master Form hint traverses the schema to the project_id attribute from the Item Master Form. To add this attribute to the query definition, click the Add Clause to Table button. The system adds the clause to the table. For more information, see Using search criteria clauses. 11. If you want to search for project_id attribute of the Item Master Form, click the Find in Tree button. The system expands the tree in the Attribute Selection pane to display the Project ID attribute. 12. Double-click any of the other attributes to add them to the clause table. PLM00031 J Query Builder Guide 2-5

24 Chapter 2 Creating and managing queries You can use other hints to add more clauses to the query table by selecting a new hint and repeating the previous steps. Note Only those hints applicable to the selected search class are available in the choose hint pane. 13. Modify the search criteria and clause precedence, as required. For more information, see Using search criteria clauses. 14. Click the Create button to save the query definition. The query form is also available in the System Defined Searches list in My Teamcenter. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Create a query that includes a keyword search Including the keywords attribute in a query definition allows you to develop queries to find dataset files that contain a specific keyword or combinations of keywords. Note The Autonomy server must be installed and configured at your site to enable full-text keyword search functionality. 1. In the Name box, type a unique name for the query. 2. Optionally, type a description of the query in the Description box. 3. Select Keyword Search Query from the Modifiable Query Types list. 4. Click the Search Class button to select the target class for the query. The Class Selection dialog box displays the POM schema in tree format. 5. Expand the POM_application_object class and locate the WorkspaceObject class. Expand the WorkspaceObject class, and then double-click the Dataset class. The system displays the Dataset class on the Search Class button, and the Dataset class and its attributes are displayed in the Attribute Selection pane. 6. Add the Keywords attribute to the Search Criteria table by either double-clicking the attribute in the tree or by selecting it in the tree and clicking the Add button. The system displays the attribute (tc_fts_keyword) and default operator (=) in the table. 7. Optionally, modify the default operator and default attribute value. 8. Optionally, add other search clauses to the table. 9. Click the Create button. 2-6 Query Builder Guide PLM00031 J

25 Creating and managing queries The system adds the query to the saved queries tree. The query form is also available in the System Defined Searches list in My Teamcenter. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Create a new query based on an existing definition 1. Select an existing query from the saved queries tree. 2. In the Name box, type a unique name for the query. 3. Change the information in the Description box, Search Class box, and/or Search Criteria table columns. 4. Click the Create button. The system adds the query to the saved queries tree. The query form is also available in the System Defined Searches+ list in My Teamcenter. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Create a query using the IS_NULL or IS_NOT_NULL operator The IS_NULL and IS_NOT_NULL operators allow you to create queries to find objects with null attribute values, such as items that do not have descriptions, or objects with an attribute containing any value other than null. Clauses that use this operator are treated as having a fixed value; therefore, there is no need to enter a name and default value for the clause. The following steps illustrate the process of creating a null-value query to find released ItemRevision objects: 1. In the Name box, type a unique name for the query. 2. Optionally, type a description of the query in the Description box. 3. Select Local Query from the Modifiable Query Types list. 4. Click the Search Class button to select the target class for the query. The Class Selection dialog box displays the POM schema in tree format. 5. Expand the POM_application_object class and locate the WorkspaceObject class. 6. Expand the WorkspaceObject class and select the ItemRevision class by selecting it and closing the dialog box. ItemRevision is now displayed on the Search Class button, and the ItemRevision class and its attributes are displayed in the Attribute Selection pane. PLM00031 J Query Builder Guide 2-7

26 Chapter 2 Creating and managing queries 7. Click the Display Settings button and select All Attributes. Add the Release Status attribute to the Search Criteria table by selecting it in the tree and clicking the Add button. The attribute and default operator (IS_NULL) are displayed in the table. 8. Change the operator from IS_NULL to IS_NOT_NULL by clicking the right corner of the operator cell and selecting IS_NOT_NULL from the list. 9. Click the Create button to create the query. The system adds the query to the saved queries tree. The query form is also available in the System Defined Searches list in My Teamcenter. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Create a referenced-by query You can create queries using clauses on a reversed-reference relationship. The following example illustrates the process of creating a query using clauses on a reversed-reference relationship. In this case, the purpose of the query is to find dataset objects that are referenced, through an IMAN_specification relationship, by an item revision with a specific name. 1. In the Name box, type a unique name for the query. 2. Optionally, type a description of the query in the Description box. 3. Select Local Query from the Modifiable Query Types list. 4. Click the Search Class button to select the target class for the query. The Class Selection dialog box displays the POM schema in tree format. 5. Expand the POM_application_object class and locate the WorkspaceObject class. 6. Expand the WorkspaceObject class and select the Dataset class by double-clicking it. The dataset is now displayed on the Search Class button. The Dataset class and its attributes are displayed in the Attribute Selection box. Attribute Selection box 2-8 Query Builder Guide PLM00031 J

27 Creating and managing queries Dataset Revision Anchor [ RevisionAnchor ] ref_names Tool Used [ Tool ] Classification ref_types Format References 7. Double-click the Referenced By node in the Attribute Selection pane. The Class Attribute Selection dialog box appears. Note If you select the Referenced By attribute, the Class Attribute Selection dialog box appears. Use this dialog to select the class and through what attribute the given object is referenced in that class. You can add selected attributes to the search criteria table. 8. Click the Search Class button to select the referencing class for the query. The Class Selection dialog box displays the POM schema in tree format. 9. Expand the POM_application_object class and locate the WorkspaceObject class. 10. Expand the WorkspaceObject class and select the ItemRevision class by highlighting it and closing the dialog box. The referencing class and its attributes are displayed in the Class Attribute Selection dialog box. PLM00031 J Query Builder Guide 2-9

28 Chapter 2 Creating and managing queries Note Only those attributes that may reference the objects of the class being queried, in this case the Dataset class, are displayed in the dialog box. 11. Select a referencing attribute, in this case IMAN_specification, by double-clicking the node. The referencing attribute, Specifications, and class, ItemRevision, are displayed in the Attribute Selection area. 12. Select the attributes of the referencing class on which you want to build query clauses. In this case, locate and double-click the Name attribute. The attribute is displayed in the Search Criteria table. Note that the display name of the attribute is ItemRevision IMAN_specification.object_name. The symbol indicates a reversed-reference relationship. 13. Type a key name in the User Entry Key box. This makes the User Entry Key unique when you perform a query from the My Teamcenter search pane. 14. Click the Create button to create the query Query Builder Guide PLM00031 J

29 Creating and managing queries The system adds the query to the saved queries tree. The query form is also available in the System Defined Searches list in My Teamcenter. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Create a saved query on classification attributes With this function, and appropriate privileges, you create a saved query on Classification attributes, using Query Builder. In particular, you can create a saved query that combines Classification attributes and Teamcenter attributes. The following examples illustrate a few scenarios where the user can create a saved query to perform searches using Classification attributes and/or Teamcenter attributes: Define a query that restricts the search to Bolt and makes all Bolt attributes available as the search criteria. In the Find application, the user can enter values for one or more Bolt attributes. Define a query that restricts the search to Bolt but makes a subset of Bolt attributes (for example, Length and Radius) available as the search criteria. Define a query that restricts the search to item and makes item attributes and bolt attributes through the IMAN_classification reference be available as the search criteria. 1. Select a Classification class from the class schema using the Class Selection dialog box, accessed by clicking the Search Class button. Note When creating a saved query, the search class must have at least one own attribute (an attribute not inheriting from its parent class). Otherwise, the search returns objects from its parent class, rather than the specified class. 2. After selecting a Classification class, select Classification attributes through the Attribute 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 attributes and cannot be used in a search. These group nodes are shown with a different icon. The nodes below the group level correspond to a Classification class. The class level nodes can be used to build saved queries. After a Classification attribute is selected from the Attribute Selection tree, its internal attribute ID is shown as Attribute name in the Search Criteria table while its attribute display name is shown as User Entry Name in the Search Criteria table. You can modify the user entry name if required. A Classification object (ICO) is attached to a Teamcenter object through the Tc_classification relationship. This Tc_classification relationship is shown as one of the attributes for a Teamcenter class whose instances are classified. For such a Teamcenter class (for example, item and item revisions), you can expand its Tc_classification attribute in the Attribute Selection tree to access the Classification attributes. In doing so, you build a saved query that combines Classification attribute search criteria and Teamcenter attribute search criteria. PLM00031 J Query Builder Guide 2-11

30 Chapter 2 Creating and managing queries Note When you double-click the Tc_classification attribute, only the Classification hierarchy is shown in the Class Selection dialog box to enable you to select a Classification class and use its attributes to build query clauses. Create a saved query using a revision rule 1. In Query Builder, create a query. 2. Select an applicable revision rule from the Revision Rule list. Specify sort order for a saved query Note Default sort attributes are defined on the Order By tab in Query Builder. In My Teamcenter, the Search view Sort dialog box lets users specify sort order or override a default sort order defined for a saved query. 1. Create a query. 2. Next to the Search Criteria section, click the Order By tab, and then select an attribute to display the Order By tab. 3. In the Order By tab: a. Select an attribute and use the arrow keys to move it up or down in the Sort By precedence order list. b. For each attribute, specify whether to arrange in Ascending or Descending order. Create a subclass query on a typed reference You can create saved queries based on a subclass of a typed reference and then build clauses against the attributes of the subclass instead of against the attributes of the referenced class. For example, the contents attribute in the Folder class is a typed reference of the referenced class WorkspaceObject. You can, therefore, select the Dataset class as a referenced class of the contents attribute and build query clauses against the attributes of the Dataset class, rather than against the WorkspaceObject class. The following steps illustrate the process of creating a query of a subclass on a typed reference. In this case, the purpose of the query is to find folders containing datasets that are checked out. 1. In the Name box, type a unique name for the query. 2. Optionally, type a description of the query in the Description box. 3. Click the Search Class button to select the target class for the query. The Class Selection dialog box displays the POM schema in tree format. 4. Expand the POM_application_object class and locate the WorkspaceObject class Query Builder Guide PLM00031 J

31 Creating and managing queries 5. Expand the WorkspaceObject class and select the Folder class by selecting it and closing the dialog box. Folder is displayed on the Search Class button, and the Folder class and its attributes are displayed in the Attribute Selection pane. 6. In the Attribute Selection pane, double-click the Contents [WorkspaceObject] attribute. The Class Selection dialog box displays the referenced class, in this case, WorkspaceObject, and all of its subclasses. 7. Select the Dataset subclass by double-clicking the node in the tree. The Attribute Selection pane displays the Contents [Dataset] attribute and its attributes of the Dataset class. 8. Expand the rev_chain_anchor [RevisionAnchor] attribute node by double-clicking it. The Class Selection dialog box displays the RevisionAnchor class. PLM00031 J Query Builder Guide 2-13

32 Chapter 2 Creating and managing queries 9. Expanded the rev_chain_anchor [RevisionAnchor] in the tree; the attributes are displayed in the Attribute Selection pane. 10. Expand the IMAN_RES_checkout class by double-clicking it. The Class Selection dialog box displays the POM_object schema. 11. Select the ImanReservation class and expand it. The ImanReservation attributes are displayed in the Attribute Selection pane Query Builder Guide PLM00031 J

33 Creating and managing queries 12. Double-click the reservation_state attribute. The attribute is added to the Search Criteria table. 13. Type a default value 0 for this query clause. PLM00031 J Query Builder Guide 2-15

34 Chapter 2 Creating and managing queries 14. Click the Create button to create the query. The system adds the query to the saved queries tree. The query form is also available in the System Defined Searches list in My Teamcenter. For more information about searching the Teamcenter database using saved queries, see the Rich Client Interface Guide. Managing queries You can manage queries by either modifying them or deleting them. Modify a query 1. Select a query from the saved queries tree. Information about that query is displayed in the boxes on the right side of the window. 2. Change the information in the Name, Description, or Search Class box, and/or Search Criteria table columns. 3. Click Modify to save your changes in the database. Delete a query 1. Select a query from the saved queries tree. 2. Click Delete. Teamcenter displays the Delete Confirmation dialog box. 3. Click Yes to delete the query from the database and remove it from the saved queries tree. Using class attribute selections To create query definitions, you select the class attributes to use in the search criteria. Class attributes can be found on the: Search class. When a Search Class is selected, its attributes are displayed in the Attribute Selection box. Attribute Selection box User Nationality mailbox [ Folder ] Person [ Person ] TTCDate 2-16 Query Builder Guide PLM00031 J

35 Creating and managing queries Default Volume [ ImanVolume ] IP Clearance Parent classes. newstuff_folder [ Folder ] When all attributes for the Search Class are displayed, inherited attributes are also displayed in the Attribute Selection box. Attribute Selection box User Owning Site [ POM_imc ] pid object_properties lsd timestamp Status user_data_source Reference classes. When classes related to the Search Class are displayed, the reference class attributes are also displayed in the Attribute Selection box. Attribute Selection box Nationality Mailbox [ Folder ] Person [ Person ] Owning Site [ POM_imc ] pid object_properties lsd timestamp Referenced by classes. Reference class Reference class When classes related to the Search Class are not displayed, the Referenced By attribute is used to locate additional reference classes to display in the Attribute Selection box. Attribute Selection box PLM00031 J Query Builder Guide 2-17

36 Chapter 2 Creating and managing queries Default Volume [ ImanVolume ] IP Clearance newstuff_folder [ Folder ] Gov Clearance OS Name Geography home_folder [ Folder ] Referenced By Use the Display Settings box to display: Only attributes defined on the class or all attributes; those inherited from the parent. Attribute user interface display names or the attribute real database names. Display Settings Class Attributes All Attributes Display Names Real Names Double-click an attribute to add it to the Search Criteria table. The attributes without the plus symbol can be directly set when searching for objects. The attributes with the plus symbol refer to another class in the class structure, which may have direct attributes, or may have more attributes with plus symbols. Add class attributes to search criteria 1. Select a class as the search class. 2. Set Display Settings to All Attributes and Real Names. Display Settings 2-18 Query Builder Guide PLM00031 J

37 Creating and managing queries Class Attributes All Attributes Display Names Real Names 3. Populate the Attribute Selection list with the attributes required to build the search criteria. The attributes are either class attributes, parent class attributes, or reference class attributes. Reference classes are classes related to the search class. To list reference class attributes: Double-click references with the plus symbol to list more attributes or to open the Class Selection Dialog. Double-click a class from the Class Selection Dialog to add the class and its attributes to the Attribute Selection list. Double-click Referenced By at the bottom of the Attribute Selection list to open the Class Attribute Selection Dialog. Double-click the Search Class box to search for a class. Select a reference and click OK to add the reference and its attributes to the Attribute Selection list. Note Navigating reference classes requires knowledge of the Teamcenter data model. 4. Double-click attributes without the plus symbol to directly add them to the Search Criteria table. Using preferences when querying When querying, you can use the following preferences to further refine your query: 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. 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. TC_QRY_xxx_REVRULE Specifies the revision rule applied to search results for searches against ItemRevision and its subclasses. TC_QRY_search_by_rev_rule PLM00031 J Query Builder Guide 2-19

38 Chapter 2 Creating and managing queries Locates the latest item revisions based on revision rules. For example, when querying to locate the latest working item revision, you can set this preference to Latest Working before conducting your query. TC_QRY_display_latest_dataset_only Displays only the latest version of dataset objects when you set this preference to 1 before conducting your query. Search_result_load_all_limit Specifies the maximum number of loaded searches. The default value is 400. Also, you can set the Open_previous_open_search preference to 1 to display a previous search result in the search results view. For more information, see the Preferences and Environment Variables Reference. Using search criteria clauses Search criteria is specified using statements or clauses in the Search Criteria table. Each clause searches the class and examines a specific attribute in that class and each clause can examine only one attribute. Therefore, if you want to build a complex query that examines multiple attributes, you must build several search clauses (one for each attribute you want to examine). When you perform your search (run your query), Teamcenter examines the attribute specified in each of your search clauses and looks for values that match your search criteria. The Search Criteria pane defines the elements in the Search Criteria table. Attribute User Entry L10N Key User Entry Name person.user_name PersonName Person Name = AND user_id UserId User Id = Default Value The Search Criteria table example finds users that meet the person name and user ID criteria values entered by the user. Double-click an attribute in the Attribute Selection box to add it to the Search Criteria table. The combination of the User Entry L10N Key and Default Value elements dictate how the search criteria is presented to the user. 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 Query Builder Guide PLM00031 J

39 Creating and managing queries Note When the User Entry L10N Key is blank, the Default Value must have a value. Search criteria clause example Saved query: Admin Object Ownership Search class: WorkspaceObject User Entry L10N Attribute User Entry Name Default Key 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 owning user of the WorkspaceObject is the user logged on and executing 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 value of the user ID. 2. The name of the owning group of the WorkspaceObject is the current group of the user logged on and executing 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 value of the group name. 3. The object type of WorkspaceObject is ItemRevision. Result: The attribute displays ItemRevision in the saved query. The query looks for workspace objects with a type that matches the value of type. The resulting saved query: Assign precedence to clauses 1. Select the clause or clauses that you want to move up or down in the list. 2. Click the Gain Precedence button to move the clauses up or click the Lose Precedence button to move the clauses down. 3. Continue clicking the buttons until the clauses are moved to the position you want. PLM00031 J Query Builder Guide 2-21

40 Chapter 2 Creating and managing queries Remove clauses from the table 1. Select the clause or clauses that you want to remove from the list. 2. Click the Remove Search Clause button. The selected clauses are removed from the list. Creation or modification is not committed to the database until you click Create or Modify, respectively Query Builder Guide PLM00031 J

41 Chapter 3 Managing the query hints file Managing the query hints file Sample hints file PLM00031 J Query Builder Guide

42

43 Chapter 3 Managing the query hints file Managing the query hints file Query hints are stored in the queryhint.xml file located in the tc_root\data directory. Use either an XML editor or text editor to edit the hint file. For more information, see Sample hints file. Note If using a plain text editor, you must manually convert the greater than (>) and less than (<) characters to the XML equivalents, > and <, respectively. There is no mechanism during an upgrade for preserving your customizations to the queryhint.xml file. The XML file contains two element types: 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 class, 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 the mouse over the hint. The search class 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 XML file. Sample hints file <?xml version="1.0" encoding="utf-8"?> <!-- =============================================================================== Copyright (c) UGS Corporation Unpublished - All Rights Reserved =============================================================================== Filename: queryhint.xml Define dtd for tc query hints --> <!DOCTYPE ImanQueryHintFile [ PLM00031 J Query Builder Guide 3-1

44 Chapter 3 Managing the query hints file ]> <!ELEMENT folder ( (folder hint)* )> <!ATTLIST folder name CDATA #REQUIRED description CDATA #REQUIRED> <!ELEMENT hint EMPTY> <!ATTLIST hint name CDATA #REQUIRED description CDATA #REQUIRED class CDATA #REQUIRED hint_text CDATA #REQUIRED> <!ELEMENT ImanQueryHintFile ((folder hint)*)> <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 item revision s dataset to the item search" class="item" hint_text="itemrevision<-items_tag.dataset:iman_specification.format_used"/> <hint name="item to IMAN_Aliasid" description="adding criteria from an associated alias identifier to the item search" class="item" hint_text="alias:iman_aliasid.alias_id"/> </folder> <!-- =============================================== --> <!-- ========= item revision hints ================= --> <!-- =============================================== --> <folder name="item Revision Queries" description="query Hints for Item Revision Relationships"> <hint name="item Revision to IMAN_Specification" description="adding dataset criteria to the item revision search" class="itemrevision" hint_text="dataset:iman_specification.format_used"/> <hint name="item Revision to Item Revision Master Form" description="adding master form criteria to the item revision search" class="itemrevision" hint_text="form:iman_master_form_rev.itemversionmaster:data_file.project_id"/> <hint name="item Revision to Item" description="adding item criteria to the item revision search" class="itemrevision" hint_text="items_tag.item_id"/> </folder> <!-- =============================================== --> <!-- ========= dataset hints ================= --> <!-- =============================================== --> <folder name="dataset Queries" description="query Hints for Dataset Relationships"> <hint name="specification Dataset to owning Item Revision" description="adding item revision criteria to the specification dataset search" class="dataset" hint_text="itemrevision<-iman_specification.object_name"/> <hint name="dataset with unknown relation to Item Revision" description="adding item revision criteria to the dataset search" class="dataset" hint_text="imanrelation<-secondary_object.itemrevision:primary_object.object_name"/> </folder> <!-- =============================================== --> <!-- ========= folder hints ================= --> <!-- =============================================== --> <folder name="folder Queries" description="query Hints for Folder Relationships"> <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="folder to Contents" description="adding content object criteria to the folder search" class="folder" hint_text="contents.object_name"/> </folder> <!-- =============================================== --> <!-- ========= product structure hints ================= --> <!-- =============================================== --> <folder name="product Structure Queries" description="query Hints for Product Structure Relationships"> <hint name="assembly to child Components (Imprecise Structure)" description="adding child component item criteria to the assembly item revision search" class="itemrevision" hint_text="structure_revisions.psoccurrence<-parent_bvr.item:child_item.item_id"/> <hint name="child Components to Assembly (Imprecise Structure)" description="adding assembly item revision criteria to the child component item search" class="item" hint_text= "PSOccurrence<-child_item.parent_bvr.ItemRevision<-structure_revisions.object_name"/> <hint name="assembly to child Components (Precise Structure)" description="adding child component item revision criteria to the assembly item revision search" class="itemrevision" 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 3-2 Query Builder Guide PLM00031 J