Teamcenter Appearance Configuration Guide. Publication Number PLM00021 J

Transcription

1 Teamcenter 10.1 Appearance Configuration Guide Publication Number PLM00021 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 Appearance Configuration Guide PLM00021 J

3 Contents Proprietary and restricted rights notice Getting started Getting started with appearance configuration Before you begin Configuring appearances Appearance Configuration interface Basic concepts for using appearances Basic tasks using appearances Unsupported functionality Syntax conventions used in this guide Configuring for appearances Configuring Teamcenter for appearances Setting Teamcenter preferences Set environment variables Configuring user exits Configuring Workflow processes Editing effectivity Creating saved queries Creating revision rules Creating appearance attribute mappings Creating Classification searches Configuring NX and Lifecycle Visualization Configuring optional functionality Choosing a functionality level Running the Update Manager Running the Update Manager Update Manager processes Working with Update Manager packages Processing structure changes Configuring the Update Manager Start the Update Manager Stop and restart the Update Manager Running the Update Manager utilities Using the Appearance Configuration application Using the Appearance Configuration application Add a new revision rule (column) Add a new root item (row) Find set contexts Set flags Create an appearance attribute PLM00021 J Appearance Configuration Guide 3

4 Contents Define how appearance sets are tracked Creating and updating appearances Creating and updating appearances Creating a bootstrap appearance set Checking system operation Releasing the product Updating appearances Solving problems Solving problems Frequently asked questions Detecting and repairing inconsistencies Using diagnostic tools Troubleshooting Command reference A-1 Glossary B-1 Index Index-1 Figures Appearance update mechanism Historyless appearances mechanism Creating a published appearance set Performing a remote appearance search Modifying a structure at a remote site Sequence of events following structure change Structure changes Location of log files Appearance Configuration Guide PLM00021 J

5 Chapter 1 Getting started Getting started with appearance configuration Before you begin Configuring appearances Appearance Configuration interface Appearance Sets pane Appearance Attribute Mapping pane Rich client perspectives and views Basic concepts for using appearances Working with appearances Understanding occurrence and appearance threads Creating appearance searches Making appearances searches in Structure Manager Using historyless appearances Execute an all history search in Structure Manager Clear all-history lines in Structure Manager Enhancing searches with other attributes Creating appearances Creating appearance searches Enhancing searches with other attributes Updating appearances Creating a spatial cache Generating a spatial cache Updating the spatial cache Performing a spatial query Configuring appearances Release date only mode Unit effectivity only and date effectivity only modes Unit effectivity plus release date mode Updating appearances for precise assemblies Updating appearances with incremental change Creating historyless appearances Using Multi-Site Collaboration with appearances Basic tasks using appearances Unsupported functionality Syntax conventions used in this guide PLM00021 J Appearance Configuration Guide

6

7 Chapter 1 Getting started Getting started with appearance configuration The appearances functionality allows Teamcenter to cache a configured product structure, permitting faster searching of the structure for components configured at a specific date or unit. When an administrator creates an appearance cache, end users can perform spatial searches in Structure Manager, for example, to find all components within one centimeter of a selected part. They can combine appearance searches with other queries, for example, queries for item revision master attributes, Classification attributes, or occurrence notes. You can also implement appearance searches with Repeatable Digital Validation (RDV), defining your searches in the DesignContext application. The Appearance Configuration application allows you track and manage the appearance sets necessary to support these tasks. You can build a query to prefilter a set of components in Teamcenter that you can subsequently load into a CAD system. For example, you can query for all components within three centimeters of the left, front wheel, with item identifier , as of 1st May 2007 with material of Steel and class of Fastener. While you can create these filters in the CAD application, it may not be possible to set the configuration date or unit. Also, there may be performance issues with very large structures. Appearances are intended for very large structures with between 30,000 and 130,000 BOM lines. Before you begin Prerequisites Enable Appearance Configuration You must have system administrator privileges to create bootstrap appearance sets for the products you want to track with the Appearance Configuration application. Access to the Appearance Configuration application may be restricted and you may be unable to start it, even if you have administrator privileges. For more information, see the Security Administration Guide. Before using this capability, you must create appearances, as described in Creating and updating appearances. The Appearance Configuration application does not need to be enabled before you use it. PLM00021 J Appearance Configuration Guide 1-1

8 Chapter 1 Getting started Configure Appearance Configuration Start the Appearance Configuration application There are additional steps you must perform before you can configure appearances. For more information, see Configuring appearances. Click Appearance Configuration in the navigation pane. Configuring appearances Note To configure appearances, run appearance searches or view JT files, you must have the necessary RDV (Context Management) client and server licenses. No license is required to generate appearances. Ensure you have created all the necessary occurrence notes in Structure Manager before you start to define the attribute mappings. 1. Set Teamcenter preferences, as described in Setting Teamcenter preferences and Set viewer preferences. 2. Set environment variables, as described in Set environment variables. 3. Configure user exits, as described in Configuring user exits. 4. Configure workflow processes, as described in Configuring Workflow processes. 5. Create saved queries, as described in Creating saved queries. 6. Create revision rules, as described in Creating revision rules. 7. Configure NX and Lifecycle Visualization, as described in Configuring NX and Lifecycle Visualization. 8. Optionally, configure historyless appearances. See Managing historyless appearances before starting any of the configuration procedures, if you plan to use historyless appearances at your site. 9. Optionally, configure appearances for both precise and imprecise structures. See Creating appearances for precise and imprecise structures before starting any of the configuration procedures, if you plan to create appearances for precise structures. 10. Optionally, configure appearances for a Multi-Site Collaboration environment. If you use appearances with Multi-Site Collaboration, see Configure a Multi-Site Collaboration environment. Use the checklists in Choosing a functionality level to ensure you complete all the configuration procedures. 1-2 Appearance Configuration Guide PLM00021 J

9 Getting started Appearance Configuration interface The Appearance Configuration application user interface comprises two panes, Appearance Sets and Appearance Attribute Mapping. Appearance Sets pane Item Root Item list View list Revision Rule list Function Top-level (root) item tracked by the appearance set. Views being tracked. Ensure you select the required view type (BOM view) when multiple views are present. Revision rule applied to the appearance set. The column header contains the name of the revision rule and you can double-click the header to display its full details. Right-click the cells in this column to display more information about how the appearance is tracked. The symbols shown have the following meanings: Spatial data No spatial data With history Without history Supports remote search (published) Does not support remote search (not published) Top Add button Top Delete button Bottom Add button Bottom Delete button Save button Untracked appearances have a blank cell. Displays the Create New Context dialog box allowing you to create a new revision rule column. Deletes a selected revision rule column. Displays the Create New Appearance Set dialog box allowing you to add a new row for a new tracked root item. Deletes a root item and any appearance sets tracked on it. The appearance set is not deleted (destroyed) until you click Save. Saves any changes in the database. PLM00021 J Appearance Configuration Guide 1-3

10 Chapter 1 Getting started Item Restore button Refresh button Function Retrieves previous appearance sets from the database. Any changes are lost. Updates any previously selected row or column in the table. Note Root Item and View Type are always the first two columns in the table. During scrolling, they may move out of view but are restored on completion of scrolling. Appearance Attribute Mapping pane Use the Appearance Attribute Mapping pane to define the occurrence notes you want to track. These occurrence notes apply to all appearance sets. To track an occurrence note, create the corresponding appearance attribute, and then map it to the occurrence note. Item Mapping list Occurrence Note Types box Appearance Attributes box Add and Delete buttons Save and Restore buttons Appearance Attribute Mapping pane Displays the appearance attributes to occurrence note mappings. Use the arrow to sort the list in ascending or descending alphanumeric order. Lists the defined occurrence notes used to map to appearance attributes. The necessary occurrence notes must already exist in Structure Manager before you define any mappings. Lists the created appearance attributes. Creates or deletes an appearance attribute. Restores previous appearance sets from the database. Any changes are lost. 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. If your site has online help installed, you can access application and view help from the rich client Help menu or by pressing F Appearance Configuration Guide PLM00021 J

11 Getting started For more information about rich client perspectives and views, see the Rich Client Interface Guide. Basic concepts for using appearances To track appearances, the Teamcenter administrator creates bootstrap appearance sets for the products you want to track with the Appearance Configuration application. The administrator also creates attribute mappings for those occurrence notes whose changed values you want to track. To enable appearances functionality, you must obtain the following licenses from your Siemens PLM Software representative: Structure Manager search If you encounter problems configuring or running appearance searches in Structure Manager, they may be due to licensing issues. Lifecycle Visualization To view JT files that are associated with appearance sets, you require the appropriate Teamcenter lifecycle visualization license, even if you only use the embedded viewer, not the standalone product. There are several levels of license, including Teamcenter lifecycle visualization base, Teamcenter lifecycle visualization professional, and Teamcenter lifecycle visualization mockup. The level of license you choose depends on the level of functionality you require of the viewer and any level of license is adequate for creating or configuring appearances. The following table lists elements in a product structure when using the appearances functionality. Element Appearance Appearance root Appearance set (cache) Purpose Represents a unique multilevel path to a component through an exploded structure from the top-level product. An appearance stores attributes about its validity that allow searches for a given date or unit. For example, the left, front wheel in car model X, effective from 1 June In addition, an appearance stores the absolute transform and values of occurrence notes to track. An object in the database containing the set of parameters that define an appearance set the root item, configuration context, and view. The (typically large) collection of appearances that are created for a specific appearance root. It is updated each time a part is released within the root product being tracked, if the part has the appropriate release status. This allows Teamcenter to record a history of all changes since the appearance set was created, allowing you to search for components in the configuration at some specific date or unit number. PLM00021 J Appearance Configuration Guide 1-5

12 Chapter 1 Getting started Element Bootstrap appearance set Configuration context Purpose The initial appearance set created for a product for a specified appearance root. It defines the root item and configuration context that are tracked. The revision rule that configures the structure. It may contain one or more release status entries (which may be grouped) and a Precise entry, but no other entries. If you implement effectivity: The revision rule must also contain an end item entry when used with unit number effectivity. Do not mix configuration by date effectivity and by unit effectivity. However, you can mix release date and unit effectivity. Do not mix configuration by date effectivity and by date released. ERCT Historyless appearance set Mapped attributes Root item Spatial data You can group entries when appropriate. Effectivity release (date) configuration transition. A dividing line in the product structure between unit number effectivity configuration (above the line) and date released (below the line). You typically identify parts above the line by setting an attribute on the item master form. An appearance set that does not record history. Its status differs from the status of the production appearance set, for example, Pre-released. Occurrence notes that are mapped to appearance attributes so that changes in their values can be tracked. The top-level item of the product against which appearances are tracked. Typically, but not always, this is the end item for unit effectivity. Sometimes called the tracked item. A voxel file that defines the volume of a part (not its absolute position) as a set of cubes. The size of the cube is set in a preference. You define the absolute position when you associate the voxel file with an appearance. If you use NX, the voxel file can be generated from the model geometry and stored in Teamcenter. If you do not use NX but manage DirectModel visualization datasets with attached JT files, Teamcenter generates the voxel file directly from the DirectModel dataset during the appearance update process. Working with appearances An appearance represents a unique multilevel path to a component through an exploded structure from the top-level product. An appearance stores attributes 1-6 Appearance Configuration Guide PLM00021 J

13 Getting started about its validity that allow searches for a given date or unit, for example, the left, front wheel in car model X, effective from 1 June In addition, an appearance stores the absolute transform and values of occurrence notes to track. Appearances are collected into appearance sets (caches). Teamcenter creates an appearance set for each specific appearance root, that is, a top level product and revision rule that you want to track. Teamcenter updates the appearance set each time a new revision of a part is released within the tracked product and the release status specified in the revision rule for the appearance cache. Teamcenter records a cumulative history of all changes since the appearance set was created, allowing you to search for components in the structure that were released or made effective at any specified date or unit number. The combination of top-level product or tracked item, revision rule, and tracked view type is known as an appearance root. The appearance set contains all appearances under a particular appearance root, and defines the usage of every component ever included in the product. However, if you revise a piece part, Teamcenter does not update the appearance cache. If you use a formal change management process, the new revision should be form, fit, and function compatible with the previous revision (that is, no significant geometry changes were made), so an update is unnecessary. Users may attach notes representing data such as a 3D transform or a serial number to an occurrence. The corresponding appearance has a transform and mapped attributes that cache occurrence note data to make searching more efficient. Teamcenter can store appearances for certain working data, namely, any data that is configured by a revision rule that includes the Working entry. You cannot store appearances for other working data that does not include this entry in its revision rule. You can also create a historyless appearance cache to record the current working configuration of the product by creating baseline revisions. Understanding occurrence and appearance threads While an occurrence is specific to its parent item revision, successive revisions of an item may share common children. These occurrences of the same item or item revision under the same parent are linked by an occurrence thread that is present in each revision of the parent. If a revision of the parent no longer includes the child, the occurrence thread is broken. If a later revision subsequently includes the child again, Teamcenter starts a new thread. An individual appearance identifies a specific occurrence thread for a particular effectivity (interval or sequence of unit numbers). The appearance is valid only for that effectivity. Because an appearance identifies a particular occurrence thread for a particular effectivity, if its mapped attributes are the same throughout this thread, Teamcenter needs to create only one appearance for the thread. Its validity is the same as the thread. If the mapped attributes change once during the thread, there are two appearances. This set of appearances that are specific to an occurrence thread are called an appearance thread. An occurrence may have a current appearance thread, which is the appearance thread matching the occurrence thread in which the occurrence exists. An occurrence may also have a current appearance, the most recent appearance on the current appearance thread. PLM00021 J Appearance Configuration Guide 1-7

14 Chapter 1 Getting started Creating appearance searches Appearance searches are particularly useful for end items that represent large products containing a large number of BOM lines. To allow fast queries of a given configuration of a large product structure without needing to configure the entire product, you must maintain additional data in the appearance set. The appearance set is related to a particular root item and contains information about all BOM lines that exist for a family of product configurations. Definition of an appearance set is optional and it typically is only maintained for a few end items that represent large assemblies in which fast searching is critical. The system administrator defines those end items requiring appearance sets on a site-wide basis. Appearance sets contain information about tracked items, views and contexts. Making appearances searches in Structure Manager You can run appearance searches in Structure Manager if your administrator creates an appearance set for the product structure currently active in the Structure Manager window. An appearance set matches the current window if the following are true: The end item of the appearance set corresponds to the top (root) line in the product structure. The view of the appearance set is the same as in the current Structure Manager window. The context revision rule of the appearance set corresponds to the revision rule of the current structure window. For example, a Pending rule for the appearance set may correspond to a Pending as of 1-Jan-2008 rule on the structure. You can search precise or imprecise assemblies, if the Teamcenter administrator creates the appropriate appearance sets. If you use Classification and create saved queries to find items, you must classify items. If your saved query searches for item revisions, you must classify item revisions. Using historyless appearances You can create historyless appearance sets that record only the current working configuration of the product. They can be searched more quickly than full appearance sets but do not include data about production revisions. You cannot create appearances for unreleased working data. If you need to maintain appearance sets in this situation, create a special status such as Pre-released to which you can release the product. Changes made to historyless appearance sets can be rolled up into a production appearance set at an appropriate time. You may want to search for all matching appearances, even those not active in the current configuration. For example, you may want to apply an engineering change to any configuration of the product. You can initiate a spatial search in Structure Manager to find the locations of all parts that ever existed in the vicinity of the proposed change. This is called an all-history search because it finds all historical appearances that match the search criteria without limiting the search to the current configuration. 1-8 Appearance Configuration Guide PLM00021 J

15 Getting started Execute an all history search in Structure Manager 1. Define the search criteria as described previously. 2. Select the All History check box on the search criteria summary pane. Teamcenter shows the search results in the Search Results pane. If you want to display any of the all-history search results, the corresponding BOM lines are shown in a separate section of the structure tree. The all-history BOM lines are displayed separately because these lines may not be configured by the revision rules currently in effect. You can manage the visibility of all-history lines in the same way as other BOM lines. Some of the BOM lines listed in the all-history section of the structure tree might be applicable to the current configuration. It is therefore possible for Teamcenter to show the same BOM line in the all-history section and in the configured product structure. Clear all-history lines in Structure Manager To remove one or more BOM lines from the all-history section of the Search Results pane: 1. Highlight an All History BOM line or node image and choose Tools All History Lines. Teamcenter displays a shortcut menu. Note The All History Lines menu command is hidden if you do not have appearance searching enabled. 2. From the shortcut menu, choose Clear All or Clear Selected, depending on the BOM line or lines you want to remove. Teamcenter removes the applicable lines. Alternatively, you can right-click an All History node icon and choose Clear to remove the applicable lines. Enhancing searches with other attributes You can refine appearance searches with other attributes as follows: Classification If the items have been classified, you can refine the search with classification data. Item and item revision attributes You can refine the search by including attributes of the item or item revision. Typically, this is the item ID, but you can use any attributes stored on the item master or revision master forms. Occurrence notes PLM00021 J Appearance Configuration Guide 1-9

16 Chapter 1 Getting started You can refine the search with values for occurrence attributes (occurrence notes). However, the administrator must decide in advance the note types to track, as their values are stored on appearances so changes can be tracked. Creating appearances Before you begin to create appearances, you should understand the concepts behind appearance configuration, including creating appearance searches, creating a spatial cache, configuring appearances, and updating appearances for precise assemblies. Creating appearance searches Appearance searches are particularly useful for end items that represent large products containing a large number of BOM lines. To allow fast queries of a given configuration of a large product structure without needing to configure the entire product, you must maintain additional data in the appearance set. The appearance set is related to a particular root item and contains information about all BOM lines that exist for a family of product configurations. Definition of an appearance set is optional and it typically is only maintained for a few end items that represent large assemblies in which fast searching is critical. The system administrator defines those end items requiring appearance sets on a site-wide basis. Appearance sets contain information about tracked items, views, and contexts. Enhancing searches with other attributes You can refine appearance searches with other attributes as follows: Classification If the items have been classified, you can refine the search with classification data. Item and item revision attributes You can refine the search by including attributes of the item or item revision. Typically, this is the item ID, but you can use any attributes stored on the item master or revision master forms. Occurrence notes You can refine the search with values for occurrence attributes (occurrence notes). However, the administrator must decide in advance the note types to track, as their values are stored on appearances so changes can be tracked. Updating appearances Appearances are generated or updated as necessary by the update manager process. This process runs in the background and inspects a queue of update packages that require processing to update the appropriate appearance set. The following figure shows the operation of the update mechanism. In it, several appearance sets are impacted by a single change because more than one product uses the released revision and a product is tracked by more than one revision rule Appearance Configuration Guide PLM00021 J

17 Getting started Update Workflow Handler triggers update Affected appearance sets are updated seat/c-seat assy (view) steering/g (view) ski-left/ae (view) ski-right/a (view) skid-frame/a (view) Item: X200 Context: Effective Unit Item: X200 Context: Pending Item: X300 Context: Effective Unit Newly released item revisions Appearance Set Appearance Set Appearance Set Source Description Source Description Source Description Appearance Sets and Spatial Data Appearance update mechanism Creating a spatial cache When you search for BOM lines in a large product, you may want to restrict the search to a specific spatial region. For example, you may want to find all parts that are located within two centimeters of a selected part to collect the background parts to evaluate fits and clearances. To allow spatial searches with appearances, the administrator must maintain spatial data as well as the metadata stored on the appearances. Maintaining spatial data is optional; you can have appearance sets without spatial information, but you cannot perform spatial searches without spatial data. Generating a spatial cache When you configure spatial searches, Teamcenter creates a spatial cache and associates it with the appearance set. The spatial cache stores the volume occupied by the solid CAD geometry of each component in the product space for the complete history of the appearance set. This data is stored as voxels, where each voxel references the appearances of components that occupy the voxel space. The spatial cache is stored as two files (named references) in a single Spatial_Data dataset. An index file stores the bounding box of each appearance and a table of offsets to a larger data file. The data file stores the True Shape (voxel) data for each appearance positioned in the product space. The use of two files in this way optimizes performance. PLM00021 J Appearance Configuration Guide 1-11

18 Chapter 1 Getting started Updating the spatial cache If you make a change to an item revision, Teamcenter generates an update package. When this package is processed, it: Updates the metadata in the appearance cache, adding or modifying appearances as necessary. Updates the spatial cache. If there is a UGMASTER dataset with a TSO file attached, Teamcenter processes that dataset. If it does not find a UGMASTER dataset, it looks for and processes a DirectModel dataset. Teamcenter adds or removes references to components on the voxels, according to the geometry added or removed. To achieve this, Teamcenter uses the transform stored on the occurrence (and therefore also on the appearance) to position the geometry. Warning It is critical to the integrity of the spatial cache (and therefore to the accuracy of spatial searches) that spatial data (TSO or JT files) for a newly released part is available before the appearance set is updated. Although Teamcenter checks for piece parts and writes a warning in the appearance_updater.syslog log file if there is no spatial data, the user and the system administrator are not informed directly. You must develop a rule handler to detect this condition and run it before the APPR_update_from_targets handler updates the appearance set. If you create assembly level solids that are included in the spatial cache, additional checking is required; otherwise, it is only necessary to check for items with no BOM view revision and a UGMASTER dataset. Performing a spatial query When you perform a spatial search, Teamcenter first queries the spatial cache, which returns a list of appearances that intersect the volume specified in the spatial query. The list of appearances is passed as an input to the appearance query, where it intersects with the set of appearances matching the appearance query, for example, validity and mapped occurrence attributes. The final search result contains the appearances that match both the spatial query and the appearance query parameters. Configuring appearances To support appearances, the administrator performs two principal tasks: Defines those appearance sets that are necessary to track appearances. Maps previously created occurrence notes to appearance attributes. Each revision rule that you associate with an appearance set has an associated configuration mode. This mode defines how a particular appearance set is configured by combinations of release date, unit effectivity, or date effectivity. This definition affects how the appearances are updated. Teamcenter supports the following configuration modes: Release date only Date effectivity only 1-12 Appearance Configuration Guide PLM00021 J

19 Getting started Unit effectivity only Unit effectivity plus release date Precise structures Incremental change You can also create historyless appearances that do not record history but always record the latest current configuration. Note You cannot use a rule that contains both Working and Has Status(..., Configured Using Unit Number) entries. Release date only mode The appearance update mechanism calculates the deltas needed to update the appearance cache. It compares the released assembly structure of the item revision with the immediately preceding revision that matches the revision rule for the appearance set. The comparison is performed at a single level only. The calculated deltas include components added or removed and any tracked occurrence note type changes. When new appearances are added to the appearance set in this mode, the Valid In date is set to the release date of the relevant change. Any substructure added as a result of this change is also configured as at this release date. Any occurrences removed by the change do not result in removal of the associated appearance but it is modified and the Valid Out date is set to the release date of the relevant change. Unit effectivity only and date effectivity only modes In these modes, each appearance tracks its own validity range to enhance configuration performance. However, an appearance s true validity is impacted by the validity of its parent and other factors that are also calculated. This mode supports cases where the effectivity is subsequently changed and must be propagated correctly though the appearance cache. Effectivity supports discontinuous effectivity ranges and the appearance algorithm allows for this. Items can have multiple revisions, each with their own effectivity ranges, and this may also lead to discontinuous effectivity ranges. Unit effectivity plus release date mode This configuration mode is typical in aerospace manufacturing environments. Upper levels in the product structure are configured by unit number and lower levels by release date. There is a dividing line called the effectivity release configuration transition (ERCT). This level need not be consistent across the structure but may be at different levels in different paths in the structure; however, in any path, you can only transition from effectivity to as-released configuration once. To determine the ECRT, Teamcenter calls the USER_appr_item_is_above_ERCT user exit that enables a customer defined item master form attribute. Appearances above the ERCT are populated with unit effectivity that is propagated down to the ERCT level. Appearances below the ERCT are populated with the PLM00021 J Appearance Configuration Guide 1-13

20 Chapter 1 Getting started release date and also the unit propagated from the level immediately above the ERCT. Ensure that you always define a unit number range on item revisions above the ERCT or they are not configured. It is advisable to use a different release status type for items above the ERCT to those items below it, so that this condition is detected; for example: Has Status Released - Above ERCT, configured by Unit Effectivity Has Status Released - Below ERCT, configured by Release Date Updating appearances for precise assemblies You can use precise assemblies at the lower levels of the product structure to ensure that the configuration of the assembly at the time of release is stored. To configure precise assemblies, use a Precise entry at the top of the revision rule. It is followed by a Has Status entry to configure items at the higher levels above the precise structures, for example: Precise Has Status (Released, Configured By Date) Any changes made at any level of the precise structure only update the appearance set when the top-level precise assembly item is revised and released. Teamcenter generates a completely new set of appearances for the complete precise substructure with the Valid In date set to the release date. The Valid Out date for appearances of the previous precise structure are also set to the release date. Note You cannot use precise structures when effectivity or incremental change configures the upper levels. Updating appearances with incremental change If you control changes to a structure with incremental changes, Teamcenter still updates appearances. The appearance updates are initiated by releasing the incremental change. You must include the release status used on the incremental change in the revision rule for the appearance root. Because the structure changes (components added or removed) are stored with the incremental change, Teamcenter does not have to identify changes by comparing BOMs, as is necessary when item revisions are released. Teamcenter ignores incremental changes if you are updating appearance sets containing working data. Caution Changes to occurrence data, including occurrence notes, find numbers, transforms, and component substitutions are not tracked by appearances if you implement incremental change. Occurrence data under incremental change uses absolute occurrences, which are not supported by appearances. Creating historyless appearances You can create lightweight historyless appearance sets that do not record the history of previous configurations, only the current working configuration of the product. They can be searched more quickly than full appearance sets but do not include data 1-14 Appearance Configuration Guide PLM00021 J

21 Getting started about production revisions. Changes made to historyless appearance sets can be rolled up into a production appearance set at an appropriate time. Use a historyless appearance set when fast searching is required only of the latest, currently released data, and there it is not necessary to search for previous configurations. A historyless appearance set is useful during the design process before data is formally released into production (after formal release, you can track the structure in a regular appearance set, allowing searches of configurations at any date or unit effectivity). A historyless appearance set tracks revisions released with a defined special status such as Pre-Released or Publish. This distinguishes it from the regular appearance set that tracks production revisions, for example, those with a Released status. A typical scenario for using historyless appearances is shown in the following figure. In this scenario, revision A of item P123 is Released and updated the production appearance set. A designer now makes a change and creates a new working revision B. The designer then makes additional changes and creates the first baseline revision B1. After making additional changes, the designer saves and creates a second baseline revision B2, and subsequently for B3. Each of these baseline revisions updates the historyless appearance set, allowing all users to run fast spatial searches to see the changes in the context of other prereleased changes. Finally, revision B is submitted for formal approval through a process that updates the production appearance set. History-less Appearance set (no effectivity) Pre- Released B1 Pre- Released B2 Pre- Released B3 1-Up Released P123A Revise Revise Revise Revise Save Save Release /B /B /B 10-Up Released P123B Production Appearance Set (with effectivity and history) Working revision which is being changed and saved with periodic baseline revisions created over time. Revision B is approved and released with status Released, effectivity set and production appearance set updated. Historyless appearances mechanism Note Rollback is not supported for historyless appearance sets. If the appearance set becomes inconsistent, you must regenerate it. Using Multi-Site Collaboration with appearances You can use appearances in a Multi-Site Collaboration environment, allowing users at remote sites to perform appearance searches. You maintain an appearance cache at a single master site and all users perform appearance queries on that cache. You export items from the master site, transferring ownership to allow modifications at the remote sites. When the new item revisions with the modifications are released and imported back to the master site, Teamcenter updates the appearance cache at the master site. (The import action at the master site initiates the appearance PLM00021 J Appearance Configuration Guide 1-15

22 Chapter 1 Getting started update, not the revision release action.) You can import the modified items manually or by running the data_sync utility. The following example illustrates the use of appearances in a Multi-Site Collaboration environment. Site A is the lead design site for a car model, site B designs the power train and site C designs the interior. Site A is the master site and holds the complete product structure of the entire car and maintains the appearance cache. Ownership of the transmission parts is transferred to site B and, likewise, ownership of the interior parts is transferred to site C. Designers at sites B and C perform remote spatial searches for their released parts, which have been updated in the master appearance set. These searches include all components in the car, so the designers are aware of changes made by other groups that may affect their designs. From the user s perspective, the process of releasing changes and updating the cache is the same as with a single database. However, in a Multi-Site Collaboration environment, Teamcenter uses the IDSM and ODS processes to ensure updates and searches are consistent. For a detailed description of Multi-Site Collaboration, see Multi-Site Collaboration Guide. The following figure shows how Teamcenter publishes an appearance set in this Multi-Site Collaboration environment. Creating a published appearance set 1-16 Appearance Configuration Guide PLM00021 J

23 Getting started In this process, the following steps occur: 1. You publish item A1000 in the usual way. When you create a published appearance set by using the Appearance Configuration application to set the Published flag, Teamcenter publishes the appearance root for A1000 to the ODS. The second action occurs automatically on creation of the appearance set for the published appearance. 2. You create appearances in the usual way, applying the release status. Note Creating the appearances may happen at the same time as publishing the appearance root. The ods.syslog system log file logs creation and publication of the appearance root. A remote search for the appearance root class (entered manually) shows if the publication record was created. Before a search can be made, you must do the following: Create a status at the remote site with the same name as at the master site, for example, Production. Create a revision rule with the same name (Production) and entries as at the master site. Create an item master from and item revision master form attribute queries with the same name and entries as at the master site. Create a mapped attribute for occurrence notes (Pressure) with the same name as at the master site. Ensure the Classification schemas match at the two sites. The previous figure shows the following process that takes place when a user makes a remote search. 1. From the remote site, set up the remote search for item A1000. Import A1000 and any substructure to work on locally. Then, load A1000 into Structure Manager with revision rule Production. If the revision rule has status only entries, Teamcenter queries the ODS and checks if there is a publication record for an appearance root for item A1000 with the Production revision rule. If so, the Structure Manager search button is active. 2. Define a search, for example, for an item ID and spatial. This is transferred to the master site IDSM by the Multi-Site Collaboration RPC utilities for remote checkout. Retrieve a remote query from site by RPC. The Run Remote query executes and finds any appearances. 3. Teamcenter sends the results to site B as strings with UIDs. When the strings are received at site B, they become remote appearance objects. PLM00021 J Appearance Configuration Guide 1-17

24 Chapter 1 Getting started 4. Structure Manager displays the appearances and converts them to BOM lines. Any BOM lines with remote items that are not yet imported are displayed, but as stubs that indicate the items must be imported. Ownership must be transferred if modifications are required. You can view the following logs to resolve any issues with this process: ODS.syslog Logs the search for an appearance root. IDSM.syslog Logs failure of the RPC to import remote query, if the query itself fails and if the remote appearances fail to transfer to the remote site. The find_appearances utility locates remote appearance roots and remote appearances when they are set up. Performing a remote appearance search The following figure shows the synchronization process that takes place when a user modifies a structure at a remote site Appearance Configuration Guide PLM00021 J

25 Getting started Modifying a structure at a remote site For example, the designer at site B needs to modify P50 and obtains permission from the owner of the parts at site A to import and transfer ownership of the parent assembly A300 and all its components. The process is as follows: 1. The user at the master site publishes A300 to the ODS (if it is not already published) and transfers ownership of A300 to the remote site. 2. The remote user creates a new part (P51) and revises A300, replacing P The remote user releases the new revisions (A300/B and P51/A) with Production status. 4. The remote user requests the user at the master site A to do an import. Alternatively, the users allow the Multi-Site Collaboration synchronization process to initiate the import. The IDSM at the remote site must be running to permit the import action. When the new item revisions are imported, they have a release status contained in a revision rule for which an appearance set exists (Production) and consequently trigger the Update Manager. PLM00021 J Appearance Configuration Guide 1-19

26 Chapter 1 Getting started 5. The Update Manager creates a primary package to determine the appearance sets needing updating and a secondary package to perform the updates. In this example, the Update Manager adds an appearance for P51. Once the appearances are updated, users at site B can perform a remote appearance search to find the new released changes. Basic tasks using appearances When working with appearances in a production environment, you must perform the following basic tasks: Run the Update Manager periodically to update appearances in the database. For more information, see Running the Update Manager. Define the appearance sets for which you want to track appearances. Appearance sets are combinations of root item, view, and context revision rule. For more information, see Using the Appearance Configuration application. Configure the mapping of occurrence notes to appearance attributes, if you want to track occurrence note data with changes. You must create the necessary occurrence notes in Structure Manager before you begin to configure the mapping. For more information, see Define how appearance sets are tracked. Create new bootstrap appearance sets for products you want to track with the Appearance Configuration application. You also create attribute mappings for those occurrence notes whose changed values you want to track. For more information, see Creating a bootstrap appearance set. Ensure existing appearance sets are updated as necessary. When end users release assemblies with the appropriate release process, attaching the appropriate release status to each assembly, Teamcenter generates appearance update packages for the Update Manager to process offline. For details of how to manage these updates, see Updating appearances. Unsupported functionality You cannot use appearances with the following Teamcenter functionality: In-context edits (absolute occurrences). Incremental change with occurrence note changes and substitute components. Date effectivity and unit effectivity in a single revision rule for an appearance set. (Mixed unit effectivity and date release schemes are supported.) Nested effectivity Appearance Configuration Guide PLM00021 J

27 Getting started Release date The combinations of functionality listed in the following table are not supported with appearances. Effectivity Historyless Incremental change Incremental change with intents Precise Yes Yes Yes No Yes Yes Effectivity No Yes No No Yes Historyless No No Yes Yes Incremental No No change Incremental change with intents No No Precise Yes Multi-Site Collaboration Syntax conventions used in this guide This guide uses a set of conventions to define the syntax of Teamcenter commands, functions, and properties. Following is a sample syntax format: harvester_jt.pl [bookmark-file-name bookmark-file-name...] [directory-name directory-name...] The conventions are: Bold Bold text represents words and symbols you must type exactly as shown. In the preceding example, you type harvester_jt.pl exactly as shown. Italic Italic text represents values that you supply. In the preceding example, you supply values for bookmark-file-name and directory-name. text-text A hyphen separates two words that describe a single value. In the preceding example, bookmark-file-name is a single value. [ ] Brackets represent optional elements.... An ellipsis indicates that you can repeat the preceding element. Following are examples of correct syntax for the harvester_jt.pl: command: harvester_jt.pl harvester_jt.pl assembly123.bkm harvester_jt.pl assembly123.bkm assembly124.bkm assembly125.bkm harvester_jt.pl AssemblyBookmarks PLM00021 J Appearance Configuration Guide 1-21

28

29 Chapter 2 Configuring for appearances Configuring Teamcenter for appearances Setting Teamcenter preferences Set spatial data preferences Set appearance preferences Enable automatic appearance validation Prevent searches of inconsistent appearance sets Release historyless appearances Process spatial data in separate update package Limit number of appearances processed Set viewer preferences Set mail preferences Set environment variables Configuring user exits Set the appearance attribute mapper with USER_ps_update_appr_attr Set ERCT with USER_appr_item_is_above_ERCT Set Structure Manager search granularity with USER_appr_update_end_item_search_results Set preferred ancestor with USER_bomline_is_preferred_ancestor Configuring Workflow processes Editing effectivity Creating saved queries Creating revision rules Configure by release date only Configure with mixed effectivity Creating appearance attribute mappings Creating Classification searches Configuring NX and Lifecycle Visualization Configuring optional functionality Managing historyless appearances Configure a historyless appearance set Update a historyless appearance set Purge old revisions PLM00021 J Appearance Configuration Guide

30 Creating appearances for precise and imprecise structures Configure precise structures with appearances Configuring appearances with incremental change Configure a Multi-Site Collaboration environment Choosing a functionality level Minimal setup process Full setup process Appearance Configuration Guide PLM00021 J

31 Chapter 2 Configuring for appearances Configuring Teamcenter for appearances Note Certain combinations of functionality are not supported with appearances, as listed in Unsupported functionality, and should not be configured. Configuring unsupported combinations of functionality may result in inconsistent or inaccurate data. Setting Teamcenter preferences If you are configuring a minimal setup, you can leave most preferences at their default values. However, you must set the spatial data preferences to the appropriate values. Set spatial data preferences To ensure spatial data is handled correctly, you must set the following preferences: PS_assume_old_transform_format Set to Written_By_NX to ensure that Teamcenter uses the same units as NX. PS_assume_legacy_transform_units Set to the appropriate English (imperial) or metric units, for example, Inches. If you generate spatial data directly from DirectModel datasets because there is no NX data, set the TC_JT_voxel_size preference to control the voxel size in millimeters. The lower the value, the higher the precision of searches (less false positives). However, a lower value consumes more disk space and potentially slower searches. For more information, see the NX documentation. Set appearance preferences Set preferences to control the following functionality: Automatic appearance validation Inconsistent appearance validation Historyless appearance releasing Spatial data processing in a separate update package Limiting the number of appearances processed PLM00021 J Appearance Configuration Guide 2-1

32 Chapter 2 Configuring for appearances For more information about setting preferences, see the Preferences and Environment Variables Reference. Enable automatic appearance validation You can automatically validate appearances and detect any inconsistencies. Teamcenter performs this validation offline with the same mechanism as appearance update. If you do not enable validation, you can still validate appearances manually. If an appearance set becomes inconsistent, see Detecting and repairing inconsistencies for details of how to recover. Warning There may be a performance impact if you activate the following preferences. However, this impact occurs offline in the Update Manager and the user s session is not directly affected. To enable automatic appearance validation, set both of the following preferences to true: TC_allow_appr_checking If you activate this preference, Teamcenter generates an appearance checker package at intervals set by the TC_appr_checking_interval preference. Such a package performs one or more structure validations. TC_allow_appr_query_auditing If you activate this preference, Teamcenter creates a record in the database whenever a user performs a Structure Manager search that drives the appearance checker. To set the frequency of automatic appearance validation, set the TC_appr_checking_interval preference to the required number of hours between the execution of each appearance checker package. You must set this preference to an integer, for example, 10 for 10 hours. The more frequently you run the validation, the more quickly any inconsistency is detected. However, there is a performance consideration as these packages are run on the same queue as the appearance update packages. Prevent searches of inconsistent appearance sets To prevent Structure Manager searches of inconsistent appearance sets, set the TC_prevent_appr_query_on_corrupt_root preference to true. If you activate this feature and an appearance root is marked as inconsistent, users cannot perform searches on that appearance root. In this way, they receive immediate feedback that the appearance set has a problem and know they cannot rely on the results. Release historyless appearances Define the process that releases the baseline revisions that update historyless appearance sets in the Baseline_release_procedures preference, for example, Historyless Appearance Set Baseline Process. Process spatial data in separate update package Determine whether spatial data is processed by the same update package as structure data or in a separate package. Do this by setting the 2-2 Appearance Configuration Guide PLM00021 J

33 Configuring for appearances APPR_allow_separate_spatial_processing preference to true for separate processing, or false otherwise. There may be a performance advantage in using separate update packages if you manage your spatial and structure data separately. Limit number of appearances processed If you process very large appearance sets, the server may run out of memory. To avoid memory errors, set the APPR_max_appearances_per_process preference to the maximum number of appearance sets that Teamcenter should process at a given time. If you set it to 0 (the default value), the number of appearance sets that may be processed is unlimited. Set viewer preferences You can control the assembly level of detail shown in the viewer pane. Typically, assemblies do not have associated visualization files, unless there are solids in the assembly, but detail parts do have visualization files. Thus Teamcenter displays assemblies as a collection of component parts at the detail level. You can create a simplified solid in a particular NX reference set (for example, SIMPLE), with an associated visualization (JT) file. Thus you can view simplified representations of assemblies if they exist. In some cases, a single part file may represent an assembly with individual solid objects that correspond to components. These are generally referred to as monolithic JT files. This typically occurs when you import parts from third-party CAD systems. For such parts, the corresponding parts list does not, by default, show any substructure below the part level. That is, the solid components are not shown in the parts list, but a single JT file exists for each of the pseudoassembly part files. Using monolithic JT files to represent subassemblies can have a major positive impact on visualization performance. Set the following preferences to control how these files are displayed: JT_File_OverrideChildren_Refsets This preference sets the name of visualization files associated with reference set names that override the display of visualization files for the components of the assembly. This is only necessary when you create assembly level visualization files, and avoids the display of duplicate visualization data, that is, for both the assembly and its components; this duplicate data can be confusing when blanking parts. If the viewer loads the JT file for an assembly that matches the name you specify in this preference, Teamcenter displays this file and not the visualization files for the assembly s components. The structure of the BVR is suppressed and Teamcenter shows the structure contained in the monolithic JT file. For example, you can set the JT_File_OverrideChildren_Refsets preference to: SIMPLE MONOLITHIC If an assembly contains a JT file called SIMPLE or MONOLITHIC, Teamcenter displays the assembly JT file but none of its components, because the simple.jt and monolithic.jt visualization files were created as a monolithic JT assembly PLM00021 J Appearance Configuration Guide 2-3

34 Chapter 2 Configuring for appearances containing the geometry for all its components. If an item does not contain a simple.jt or monolithic.jt file, Teamcenter loads the Lifecycle Visualization files for the components. JT_File_Priority_Refsets This preference specifies the preferred order for displaying visualization files. For example, for DirectModel datasets created prior to Teamcenter 8, set this preference to: $LASTSAVED $ENTIREPART $MODEL $EMPTY For example, if the DirectModel dataset for an item contains a JT file called $LASTSAVED, it is displayed. If the DirectModel dataset does not contain a $LASTSAVED.jt file, Teamcenter looks for $ENTIREPART.jt, then $MODEL.jt, and finally $EMPTY.jt in turn. When you create visualization files in NX, they are named according to the reference set that you used to generate them, for example, solid.jt for the SOLID reference set. Teamcenter stores JT files as named references in a DirectModel dataset type. If you generate more than one JT file, they are stored in the same DirectModel dataset but as different named reference files. Set mail preferences During appearance updates, may be sent to the designated users defined in the.appr_update_env appearance preference file. Ensure you set the Teamcenter Mail_server_name preference to the name of the mail server used by these users. Set environment variables Set the following environment variables by adding them to the tc_profilevars script. To Obtain any custom user exits Retain Teamcenter or NX system logs Make the following entry TC_USER_LIB=${TC_USER_LIB:= custom user exits dir} The user exits shipped with Teamcenter in the core libuser_exits library are picked up by default. However, you should set this entry to the appropriate directory if you use custom user exits. By default, system logs are deleted if no errors are found. To retain these for debugging purposes, enter: NX_KEEP_SYSTEM_LOG=ON TC_KEEP_SYSTEM_LOG=ON 2-4 Appearance Configuration Guide PLM00021 J

35 Configuring for appearances To Ensure the temp directory is set Ignore any available TSO data and only use JT data Make the following entry TC_TMP_DIR=C:\temp (or appropriate directory). The correct setting is important for the generation of spatial data. IGNORE_TSO_DATA Set this variable to true to ignore TSO data. You typically only set this variable when debugging and not in a production environment. Normally, you use TSO data in production, rather than JT data, as it requires less processing and there is a reduced chance of errors, for example, due to incompatibilities in units or software versions. Configuring user exits The libuser_exits library shipped with Teamcenter contains function prototypes and sample implementations for the following user exits. If appropriate, you can modify the standard user exits. Set the appearance attribute mapper with USER_ps_update_appr_attr This exit takes an occurrence note type and partitions it into a number of appearance attributes that you can then search for separately in Structure Manager. This capability is useful with note types that are effectively a concatenation of several distinct attributes that you want to search. You should customize this user exit before creating the actual appearance attribute mapping that invokes the user exit. This limits the possibility of errors if users create appearances during the period between mapping creation and user exit compilation. Note A default user exit is available that maps the UG NAME occurrence note type to the ATA1, ATA2, ATA3, ATA4, and ATA5 appearance attributes. These attributes correspond to chapters, sections, and pages on which a component is illustrated in a service catalog. The administrator must create five appearance attributes (ATA1, ATA2, ATA3, ATA4, and ATA5), then map them to the UG NAME occurrence note type and select the User Exit check box. The user must enter a UG NAME occurrence note type or other component type attribute in NX in the format nn-nn-nn-nn-nnn. Set ERCT with USER_appr_item_is_above_ERCT If you use mixed effectivity, ERCT (effectivity release date configuration transition) is the division in the product structure between unit number effectivity configuration (above the line) and date released (below the line). The ERCT (USER_appr_item_is_above_ERCT) exit allows you to set the level at which the configuration rules switch from unit effectivity configuration to date released configuration when creating appearances. Typically, Teamcenter looks for the value of an attribute on the item master form to determine this transition point. PLM00021 J Appearance Configuration Guide 2-5

36 Chapter 2 Configuring for appearances If you customize this user exit, the custom ERCT function may not use the TCTESTINGAPPR environment variable. Take care when applying this user exit to ensure that the items have the attribute used to switch the configuration mode defined correctly. This is especially important if you use different status types for unit number configuration and release date configuration. Warning You must ensure that the is_above_erct value returned by this user exit matches the actual use of the item in the structure. For example, if the user exit returns is_above_erct as true (for example, because CI = true on the item master form), it must be possible to configure a revision of the item in the structure with a revision rule entry with unit number. Similarly, if is_above_erct is false (for example, because CI = false), it must be possible to configure a revision of the item in the structure with a revision rule entry with release date. If they do not match, the appearances are not generated correctly. The default implementation of this user exit switches on the user_data_1 = ABOVE ERCT item master form attribute. You can activate this exit for testing or demonstration purposes by setting the TCTESTINGAPPR=ON environment variable in the tc_profilevars script. If you encounter problems setting or sourcing this variable when the Update Manager is started, you can print statements to confirm if it is set. A default user exit is provided and works as follows: If the TCTESTINGAPPR environment variable is defined, Teamcenter uses the user_data_1 box of the item master form to determine if item usage is configured by unit number or release date. A value of ABOVE ERCT in this box means that item usage is configured by unit number, otherwise it is configured by release date. If the TCTESTINGAPPR environment variable is not defined, every item is configured by unit number regardless of the status or any other data. Set Structure Manager search granularity with USER_appr_update_end_item_search_results This exit allows the Structure Manager spatial search to return higher level assemblies, rather than parts. This allows a designer to identify assemblies in a particular region and can then select components of interest. This exit only affects spatial searches and not other searches, for example, searches by item attribute or Classification. Typically, this exit looks for the value of an attribute on the item master form. A default implementation is provided that switches on the item master form user_data_1 = ABOVE ERCT attribute. Set preferred ancestor with USER_bomline_is_preferred_ancestor This exit allows you to customize the value of the Preferred Ancestor property. Typically, you return the item ID of the higher level assembly associated with a given structure line, according to the value of an attribute on the item. 2-6 Appearance Configuration Guide PLM00021 J

37 Configuring for appearances This property allows you to identify the higher level assembly to which a structure line belongs. This is useful when viewing results in the Structure Manager Search dialog box, which contains a flat list of components. If you add the Preferred Ancestor column to the properties table, you can more easily identify the relevant higher level assembly. A default implementation is provided that switches on the item master form user_data_1 = ABOVE ERCT attribute. Configuring Workflow processes You release assemblies that are tracked by appearances with these Workflow processes. Note Siemens PLM Software does not provide default templates to implement these processes. Released Attaches a Released status to an assembly with signoffs as required. Use this process to release new detail parts before releasing a changed assembly revision. Appearance update Attaches a Released status and runs the APPR_update_from_targets handler on the Complete action. Use this process to release the new assembly item revisions with changed structure. It may be useful to ensure that parts configured by effectivity have the effectivity set before the process completes. If the parts are being released by change management, add the appropriate handlers to attach the targets. Note Use a status argument if you want to rename the status during the Workflow process, for example, from Pre-Release to Released. If effectivity is applied, this argument allows the effectivity to be copied to the new status. Rename the status using the EPM-set-status action handler with the RENAME option, for example, -f=pre-released, -t=released. In this scenario, the status argument is Released. Place the EPM-set-status handler on the Complete action, followed by the APR-update-from-targets handler, with the status argument. Historyless appearance update Attaches a Pre-Released status or other status of your choice, and runs the APPR_update_from_targets handler on the Complete action. Use this process to release new assembly item revisions with changed structure and update the historyless appearance cache. The APPR_update_from_targets handler creates an update package and places it on the queue for the Update Manager to process. PLM00021 J Appearance Configuration Guide 2-7

38 Chapter 2 Configuring for appearances Editing effectivity To edit effectivity, users must be defined as a Role Manager or Configuration Analyst under Effectivity Users in the Access Manager rule tree. You can also configure the rule tree to suit your own rules. To allow users to edit effectivity outside change management, set the WSOM_only_edit_effectivity_in_ecm preference to no. Creating saved queries You can build the following saved queries to allow a Structure Manager search of attributes of the item master or item master revision master forms. You can create these queries based on the standard query that returns an item or item revision as appropriate. Item master form attribute query Item revision master form attribute query You can include classification attributes in the saved queries. For more information about saved queries, see Structure Manager Guide. Creating revision rules Revision rules must be owned by the dba group to ensure the Update Manager process has read access (the Update Manager runs as a user in the dba group). For details of how to configure the rule tree for public and private revision rules, see the Access Manager Guide. As revision rule names can be long, it may be helpful to name the rules with the most significant description first. In Structure Manager, revision rules are listed alphabetically, so you could prefix rules used for appearances with the same letter. Configure by release date only When configuring by release date only, create a revision rule with the following entry. Revision rule AT-Date Released Entry Has Status: Released, Configured by Release Date. You typically create the following revision rules when you create the appearance root, that is, when the ID of the root (tracked) item is known. Configure with mixed effectivity When configuring with mixed unit number and date released (ERCT) effectivity, create a revision rule with the following entry. 2-8 Appearance Configuration Guide PLM00021 J

39 Configuring for appearances Revision rule Entries AT-End-Item-ID, Date and Unit Has Status: Released, Configured by Unit Number Has Status: Released, Configured by Release Date End Item = Tracked-Item-ID You must add the end item entry or appearances do not function. The appearance root must identify an end item in the revision rule, and this is required for unit number configuration. You may want to use a different status for items configured by date to ensure that those items configured by unit have a unit number value set. Note You can use separate release statuses for items configured by unit number (above ECRT) and those configured by release date (below ECRT). Creating appearance attribute mappings Create attribute mappings for occurrence note changes that are tracked and available for Structure Manager searches. You can use the USER_ps_update_appr_attr user exit, as described in Configuring user exits. Creating Classification searches If you want to include classified data in appearance searches, ensure you classify the items, not the item revisions. Configuring NX and Lifecycle Visualization TruShape (TSO) files may be created in NX for accurate spatial filtering. Teamcenter also uses the TSO files to generate and update the spatial cache used for spatial appearance searches. If you do not use NX, the appearance update process can create the TSO files from the DirectModel (JT) visualization files. In general, visualization or TSO files are created when users save parts in the CAD system. However, you can also create them with workflow handlers, but this is a more complex process. In either case, it is critical to the integrity of the spatial cache and to the accuracy of spatial searches that spatial data (TSO or JT) files exist and are current before you update the appearances. PLM00021 J Appearance Configuration Guide 2-9

40 Chapter 2 Configuring for appearances Caution Siemens PLM Software recommends that you write a workflow rule handler to check for the presence of a current TSO or JT file for each part that has solids. If you create assembly level solids that are included in the spatial cache, additional checking is required. Otherwise, it is only necessary to check for items with no BOM view revision and a UGMASTER dataset. As part of the process of configuring your system to support appearances, you should configure NX and Lifecycle Visualization to work with Teamcenter. An overview of the necessary configuration points follows; refer to the NX and Teamcenter lifecycle visualization documentation for detailed procedures. Using TSO or JT data to update the spatial cache An NX site typically has both TSO and JT files available. By default, the appearances functionality uses TSO data when both are present. Note Choosing units If the site creates assembly-level JT files, Teamcenter uses them to update the spatial cache. To avoid confusion, users should be aware that, when performing a spatial search, both piece parts and all assemblies that have JT files are returned. It is very important to ensure the units for the TSO files on which the spatial cache depends are consistent. Unfortunately it is not possible to identify the units once the TSO file is created. To avoid incompatibilities, follow these guidelines when importing data: o o o o Always use the same units in an appearance cache and (preferably) for all appearance caches. Do not mix metric and imperial (English) units, as it is difficult to detect and diagnose problems. Ensure the units of the TSO file are the same as those of the part from which it was generated. In later versions of NX, the units are stored in the TSO file. The units of the part are stored in the part itself and are not taken from an NX preference. The units of the spatial cache are metres, regardless of the units of the input TSO or JT files. The units for performing a spatial search, as displayed in the Structure Manager Search dialog box, are taken from the BVR assy_units property of the top-level item in the structure. (Unless this is set for very old parts, these are also the units of the first file loaded in the viewer.) Generating TruShape data TruShape data is a voxel 3D representation of the space occupied by the solids in a part. The availability of this data is critical to the correct operation of spatial searches in Structure Manager. Teamcenter uses the TruShape data (TSO files) to create the occupancy cache, which is a file stored in a Spatial_Data dataset type, in the database. Spatial data depends on the units (metric or English) applied when the TruShape files were created Appearance Configuration Guide PLM00021 J

41 Configuring for appearances Generating TruShape data from direct model data If you do not use NX, Teamcenter can create the occupancy cache from JT files stored in DirectModel datasets. In this case, Teamcenter creates the spatial data directly during the appearance update process, rather than from the TSO files in the UGMASTER dataset. If you use JT files in this way, you control the voxel size by setting the TC_JT_Voxel_size preference to the appropriate value, for example, 5 mm. All values must be in the same units, as it is not possible to mix metric and imperial units. For further information on how to choose the appropriate size, see the NX documentation. Teamcenter generates the occupancy cache when spatial data tracking is active and an appearance update package is processed. The appearance_updater process: o o Looks for a UGMASTER dataset and a.tso named reference. If one exists, Teamcenter uses it to update the occupancy cache. If there is no TSO file, Teamcenter looks for a DirectModel dataset. If one exists, Teamcenter uses the JT file to update the occupancy cache. If there are several JT files in the DirectModel dataset, it uses the same selection rules as those for displaying JT files in Structure Manager. Set the NX customer defaults You should set the NX customer defaults for TruShape file generation, visualization file generation and large assembly performance as follows: Default Assemblies_TrueShapeCellSize Assemblies_TrueShapeCellSizeUnits Assemblies_TrueShapeGenerate Assemblies_ModelReferenceSet Typical settings 0.2 for imperial or 0.5 for metric. Note The cell size depends on the overall product size. The typical settings given are appropriate for a car, but would be set higher for a larger product such as a ship. The lower the setting, the more accurate the search. Conversely, the larger the spatial dataset, the slower the search. English or metric Yes REFSOLID PLM00021 J Appearance Configuration Guide 2-11

42 Chapter 2 Configuring for appearances Default Assemblies_AdditionalModelRefSets NXMGR_StructureUpdateOnLoad On 1 NXMGR_StructureUpdateOnSave Generate Lifecycle Visualization data Typical settings Set if additional JT files are required. If this default is not set, NX still creates JT files, but uses all solids and sheet bodies in the part, rather than those in a particular reference set. You should generate Lifecycle Visualization data for each part that contains any solid and sheet geometry. In some cases, this includes assemblies that contain geometry. Each JT file only contains geometry for a specific part, not any components. You can create visualization data manually in NX by setting the Lifecycle Visualization save options on, or by running the run_nxtovis utility, as described in the NX documentation. On Generating assembly Lifecycle Visualization files You can also create a visualization file at assembly levels to avoid displaying the components, then manually import the monolithic JT file into Teamcenter. To manually import a monolithic JT file into Teamcenter, rename the JT file in the file system from solid$.jt (depending on the reference set used) to assembly$jt. Then select the DirectModel dataset for the assembly and choose the View Named References menu command. In the Named References dialog box, click the Import button to import the assembly$.jt file into Teamcenter. Note You must update the assembly level JT files at all levels if any changes are made to geometry at lower levels. This activity may be very time-consuming. In addition, the spatial search results will now return all assemblies for which there are JT files, as well as the piece parts. This may potentially confuse the users. Configuring optional functionality Certain product structure features are optional and should only be implemented in Appearance Configuration if the appropriate data is available at your site. Managing historyless appearances Use a historyless appearance set if you want to quickly search for the latest, currently released data and do not need to search for previous configurations. This capability is useful during the design process before formally releasing data into 1. You can temporarily turn off this default if there are load problems. It should generally be kept on to avoid problems with components added in Structure Manager Appearance Configuration Guide PLM00021 J

43 Configuring for appearances production; once the structure is released into production, you track it with a regular appearance set, so allowing searches of configurations at any date or unit effectivity. A historyless appearance set is smaller and faster to generate because it does not retain historical data. For a detailed description of historyless appearances, see Creating historyless appearances. Teamcenter creates a special package to update a historyless appearance set ApprUpdPreReleasedRevsPkg. This package is visible when inspecting the Update Manager. Configure a historyless appearance set 1. Use the Business Modeler IDE to create a status type with which item revisions are released to update the historyless appearance cache. You can use any appropriate status, for example, Pre-Released. 2. Create a revision rule for the historyless appearance set containing the two entries shown in the following example. The second entry is necessary to track items for which there are no prereleased revisions-these entries must be grouped to obtain the correct result: [ Has Status (Pre-Released, configured by Release Date) Has Status (Released, configured by Release Date) ] The same syntax applies as for regular appearance sets, that is, no entries with Working or Override clauses. In addition, you must configure by release date and not effectivity. Ensure the chosen status Pre-Released is used in the baseline release process. 3. Create a baseline release process that all handlers must run on the root task only (for example, Pre-Released). Use the EPM-create-status and EPM-add-status handlers to attach the previously defined status. Use the APPR_update_from_targets handler on the Complete action of the root task. Note Do not include signoffs in this process as it runs without interaction when a user creates a baseline. 4. Set the following preferences for baseline release processes. Baseline_release_procedures This preference lists the processes that can create baselines, for example: Historyless Appearance Process Other Baseline process Do not set this preference before creating the process or login fails. For information about naming rules for baseline revisions, see the Business Modeler IDE Guide. Baseline_allowed_baserev_statuses This preference sets the statuses that can be used in baselines, if any item revision has these statuses. 5. Configure historyless appearances as described in Using the Appearance Configuration application, by: PLM00021 J Appearance Configuration Guide 2-13

44 Chapter 2 Configuring for appearances Adding a column with the revision rule created previously. Adding a row for the desired end item. In the interlinking cell in the table, setting the appropriate attribute flags to define the appearance set, that is, Spatial (if required) and Pre-released Without History ( ). 6. Release the latest revision of all items in the structure with the appropriate status (for example, Pre-released) to populate the historyless appearance set. Update a historyless appearance set If you are working on changes to a design and want to make it available to the historyless appearance cache, create a baseline revision of the new assembly as follows. This allows you and other users to see the proposed change in the context of other current changes, and to make fast proximity spatial searches. 1. Open the assembly in Structure Manager, ensuring you select the top-level item against which to create the baseline, and choose Tools Baseline. Teamcenter displays the Baseline dialog box. 2. Select the appropriate baseline process, for example, Historyless Appearance Process, and click OK. This action revises every working revision component in the assembly and all working item revisions at lower levels in the structure, and releases them with the appropriate status, for example, Pre-Released. It also updates the historyless appearance set, as the process runs the APPR_update_from_targets handler. 3. You can now load the product top-level assembly in Structure Manager, select the revision rule used for the historyless appearance set, and do a search. You cannot set any past date in the revision rule; you can only configure by the latest current configuration. Note Depending on how fast the appearance set is updated (that is, how quickly the Update Manager processes the packages), there may be a delay before you can search for the item you have just revised or created. Purge old revisions The historyless appearance feature automatically purges old baseline revisions. However, if the automatic purge fails, you can manually purge old baseline revisions by running the purge_baselined_item_revisions utility. This utility takes the following arguments: -item_id=item_id of the historyless appearance root. -status=release-status the release status of the baseline revisions. [-date=date now today] date format is: yyyy MM dd hh mm ss now indicates immediately. today indicates 00:00 hours today Appearance Configuration Guide PLM00021 J

45 Configuring for appearances For more information about this utility including other arguments, see the Utilities Reference. Creating appearances for precise and imprecise structures You can create appearances for both precise and imprecise structures. By default, Teamcenter assumes a structure is imprecise when you create appearances and the revision rule applied should only contain release status related entries. If you want to create appearances for a precise structure, you must add a Precise entry to the revision rule, as shown in the following example: Precise Has Status (Released, Configured By Date) The Precise entry must come first, and takes priority over the following status entries in the revision rule. The revision rule cannot have only a Precise entry and must include Has Status entries. Do not group the Precise entry with any other entry. Note You cannot create historyless appearances for precise structures. Configure precise structures with appearances The appearance cache mechanism supports precise structures with the following limitations. The product structure is always imprecise at the upper levels and transitions to precise at a lower level. Below the transition level, all assemblies are precise, with no imprecise assemblies. This restriction is generally enforced in Structure Manager. If the user creates an assembly under a precise assembly, Teamcenter creates the new assembly as precise. However, if the user copies an imprecise subassembly under a precise assembly, it remains imprecise; no warning is displayed nor does the system administrator receive a message. The update does not fail, but the resulting appearances for the precise structure do not accurately reflect the product structure. As a result, searches may return incorrect results and further updates become less accurate due to the disparity between the cached and actual product structures. Warning Siemens PLM Software recommends you write a rule handler to detect this situation and use it in the workflow before running the appearance update to avoid incorrect data. Teamcenter only updates the appearance cache when you release the top level precise assembly. If the user makes changes at lower levels of the precise structure, the appearance cache is not updated. The top level precise assembly must be revised and released to trigger the appearance updates and update the appearance cache. Remember that (in precise structures) if you revise an item, it is only used in the parent assembly if you edit the parent assembly and substitute the new revision of the component for the old revision. PLM00021 J Appearance Configuration Guide 2-15

46 Chapter 2 Configuring for appearances At the time the top-level precise assembly is released, the precise assemblies must not reference working (unreleased) item revisions or item revisions that do not have a status listed in the historyless revision rule. Any such item revisions are not configured and do not cause updates to the appearance cache. This may cause inconsistencies between the data in the appearance cache (and thus the results of a Structure Manager search) and the real product structure. Warning Siemens PLM Software recommends that you write a rule handler to detect this situation and use it in the workflow prior to running the appearance update handler to avoid data inconsistencies. If the user toggles an assembly from imprecise to precise in a structure that is tracked with an imprecise revision rule, this has no impact on appearances the precise occurrences are treated as imprecise. (This is standard revision configuration functionality.) You cannot apply effectivity to revisions on the precise branch. (Certain effectivity algorithms do not work with precise structures.) You cannot use precise structures with historyless appearances You cannot set the historyless flag if the revision rule has a precise entry. Precise structures do not update the appearance cache if updated by an incremental change and the user receives an error message if they attempt to do this. Configuring appearances with incremental change Appearances can be updated by changes tracked by an incremental change. Use the same revision rule to configure the incremental change and the appearance root, for example: Item Type (Incremental Change) Has Status = Released, Configured by Unit Effectivity Item Type (Part) Has Status = Released, Configured by Date Released For detailed information about revision rules, see Getting Started with Product Structure. If you use effectivity to configure the incremental change, the incremental change may be created with a working status such as Pending. When the incremental change is released and the status changed to (typically) Released, the effectivity should be carried forward. However, you cannot rename the release status from Pending to Released in the workflow process as the appearance algorithm fails. To resolve this, add a new release status (for example, Released) with the create_status and add_status action handlers. To ensure the effectivity is set on the newly added release status, consider putting a Do task in the workflow to prompt the user to set the status. The APPR_update_from_targets handler must run before the user sets effectivity, that is, you should place it immediately after the add_status handler. The Do task is simply a prompt to the user and no special handlers are required. Setting 2-16 Appearance Configuration Guide PLM00021 J

47 Configuring for appearances effectivity triggers the appearance update automatically and it is not obligatory to include this step in the workflow. Configure a Multi-Site Collaboration environment For a description of how appearances work in a Multi-Site Collaboration environment, see Using Multi-Site Collaboration with appearances. The general requirements for configuring appearances in a Multi-Site Collaboration environment are as follows: 1. Set the following preferences, as described in the Preferences and Environment Variables Reference: TC_appr_allow_remote_query to True (default setting is False). TC_appr_remote_query_timeout to 60 (default setting). TC_publishable_classes to Item, AppearanceRoot (default setting). 2. Create a published appearance set, as described in Creating and updating appearances. If appropriate, you can also publish an existing appearance set and apply the appropriate revision rule. Once the appearance set is published, it is stored in the ODS and you can manually search for it; a remote search for the AppearanceRoot class shows if the publication record was created. The ODS must be running for this search to succeed. The Update Manager must also be running for publication to succeed but any publishing errors do not appear in the Update Manager system logs. Instead, check for problem reports in the ODS or Teamcenter server system logs. 3. Configure Access Manager rules to allow transfer of ownership of items. The remote user running the IDSM process must have Export and Transfer Out privileges. Depending on your business practices, you may want to restrict Transfer Out privileges to certain groups or users. The minimum privileges required at the master site as follows: Privilege fi Publish Export Import Transfer out IDSM user Y Y N Y N Administrator N N N N N World Y Y N Y N Remote site N N Y N Y Transfer in For detailed information on how to create the necessary ACLs, see Access Manager Guide. Note These are standard settings for a Multi-Site Collaboration environment and there are no special requirements to support appearance sets. 4. Set up the following at each remote site to allow Structure Manager users at each remote site to perform appearance searches: PLM00021 J Appearance Configuration Guide 2-17

48 Chapter 2 Configuring for appearances Create release status types with the same name as those at the master site. Create revision rules that exactly match those used in the appearance cache at the master site, that is, they must have exactly the same name and entries. Create an item master form attribute query with exactly the same name and entries as at the master site. Create appearance mapped attributes for occurrence notes with the same name as at the master site, as described in Map an occurrence note to appearance attributes. The remote user must import and load the top level item in the appearance cache into Structure Manager, then set the revision rule for the appearance set before performing the search. Teamcenter queries the ODS for a publication record for the relevant appearance root. If it finds one, it enables the Structure Manager search icon. When the user executes a spatial search, Teamcenter transfers the query to the master site IDSM using RPC utilities, executes the remote query and finds the appearances. The results are sent to the remote site, where Teamcenter converts them to RemoteAppearance objects. When the users displays the appearances in Structure Manager, the RemoteAppearance objects are converted to BOM lines. Remote BOM lines are visible and the remote user can import them if required. Note If the transaction does not succeed, ensure the master site IDSM is running, then check the IDSM and remote site server system logs for problem reports. Choosing a functionality level You can configure two levels of functionality a minimal setup that verifies correct operation of appearances and a full setup that provides the complete appearances capability. Minimal setup process The minimal setup supports: Spatial search. Item ID and name search. Classification search, if the parts are classified. Date released configuration. It does not support: Search on occurrence notes. Effectivity configuration Appearance Configuration Guide PLM00021 J

49 Configuring for appearances NX part and item revision master form attribute searches. Appearance checking. To configure the minimal level of functionality, do the following: 1. Set the following NX customer defaults for TruShape (TSO) file generation: Control Assemblies_TrueShapeCellSize: 0.2 Assemblies_TrueShapeCellSizeUnits: Assemblies_TrueShapeGenerate: Value English 2. Set the following NX customer default for DirectModel dataset (JT file) generation: Yes Control Assemblies_ModelReferenceSet: Value SOLID 3. Set the following NX customer defaults to ensure large assemblies load without problems: Control NXMGR_StructureUpdateOnLoad: NXMGR_StructureUpdateOnSave: Value Off On 4. Create TruShape data if it does not already exist by running the refile command, as described in the Teamcenter Integration for NX documentation. 5. Create visualization data if it does not already exist by running the NX run_nxtovis utility. 6. Set the PS_assume_old_transform_format preference to Written_By_Nx and the PS_assume_legacy_transform_units preference to Inches or Millimeters. 7. Configure the.appr_update_env and.appr_update_info files, as follows: a. Edit the section of the.appr_update_env file containing the following entries: supervisor.host=machine_name updater.login=1 default is 0 admin.logging=2 default is 1 admin. .address=admin@mycompany.com enter address of users to be ed on errors b. Create a file named.appr_update_info under tcdata containing the following entries: -u=infodba -p=infodba -g=dba PLM00021 J Appearance Configuration Guide 2-19

50 Chapter 2 Configuring for appearances Note You can substitute any member of the dba group for infodba. 8. Create a revision rule that is owned by a member of the dba group, for example, Status=Released, configured by Release Date. 9. Create a workflow process, adding the APPR_update_from_targets handler on the complete action after the add-status handler in a process that adds Released status. 10. Start the Update Manager by entering: start %TC_BIN%\appr_update_manager 11. Start the console by entering: %TC_BIN%\appr_update_console Full setup process To configure the full level of functionality, follow the minimal setup process in the previous section, then do the following additional steps: 1. If you change or extend the form storage class for the item revision master form, extract the form.properties file from the rich client JAR file and comment out the lines that define the forms for item master and item revision master, as follows: Item\ Master.FORMDEFINITION=com\teamcenter\rac.form.ItemMasterForm ItemRevision\ Master.FORMDEFINITION=com\teamcenter\rac.form.ItemRevisionMasterForm Place the modified file in the com\teamcenter\rac\form directory path. 2. Set the following appearance checking preferences as necessary: Purpose Do you check appearances? Do you audit the querying of appearances? How often (in hours) do you check appearances? Do you allow the querying of appearances associated with a corrupt appearance root? Preference setting TC_allow_appr_checking=true TC_allow_appr_query_auditing=true TC_appr_checking_interval=10 TC_prevent_appr_query_on_corrupt_root=true 2-20 Appearance Configuration Guide PLM00021 J

51 Configuring for appearances Purpose To ensure JT files display correctly. Preference setting JT_File_Priority_Refsets= For DirectModel datasets created prior to Teamcenter 8: $EMPTY $ENTIREPART $LASTSAVED $MODEL [user-defined] For DirectModel datasets created using Teamcenter 8 or later: EMPTY ENTIREPART LASTSAVED MODEL [user-defined] For a mixture of DirectModel datasets created using different Teamcenter versions: $EMPTY EMPTY $ENTIREPART ENTIREPART $LASTSAVED LASTSAVED $MODEL MODEL [user-defined] PLM00021 J Appearance Configuration Guide 2-21

52 Chapter 2 Configuring for appearances Purpose To allow users to edit effectivity outside change management. Preference setting JT_File_OverrideChildren_Refsets= SIMPLE MONOLITHIC WSOM_only_edit_effectivity_in_ecm=yes 3. Configure the user exits described in Configuring user exits, if appropriate. 4. Define the occurrence note types whose values are tracked and made available in Structure Manager Search, as described in Creating appearance attribute mappings. 5. Start the Update Manager by entering: start %TC_BIN%\appr_update_manager 6. Start the console by entering: %TC_BIN%\appr_update_console 2-22 Appearance Configuration Guide PLM00021 J

53 Chapter 3 Running the Update Manager Running the Update Manager Update Manager processes Working with Update Manager packages Primary package Secondary package Primary queue Secondary queue Updating working appearances Understanding update package states Understanding update package types Understanding checker packages Update package information Processing structure changes Configuring the Update Manager Setting preferences in the.appr_update_env file Setting supervisor preferences Setting the updater preferences Setting the updater controller preferences Setting retry preferences for Update Manager failures Setting administrator preferences Configuring the.appr_update_info file Start the Update Manager Stop and restart the Update Manager Running the Update Manager utilities Using the console Option 1 Query general status Option 2 Query specific update package Option 3 Show specific update package Option 4 Show primary queue Option 5 Show secondary queue Option 6 Log system status Option 7 Query log file name Option 8 Change logging level Option 9 Clear log file Option r Restart update manager Option R Restart update manager now PLM00021 J Appearance Configuration Guide

54 Option s Shutdown update manager Option S Shutdown update manager now Option 0 Exit Information in the supervisor log file Run the find_appearances utility Appearance root arguments Configuration arguments Appearance filtering arguments Output arguments Action arguments Examples Run the appearance_updater utility appearance_updater utility Appearance Configuration Guide PLM00021 J

55 Chapter 3 Running the Update Manager Running the Update Manager The Update Manager updates appearances in the database. It is separate from the Teamcenter server process and consequently the user s session is not delayed while processing takes place. The Update Manager comprises three programs and their associated processes: Supervisor (appr_update_supervisor). The supervisor coordinates multiple updater processes that perform appearance updates. It starts and stops updaters, as it requires them. It is not a Teamcenter application and has no direct connection to the database. Updater (appearance_updater). The updater processes update packages under the direction of the supervisor. It performs the following tasks: o Querying the primary and secondary update queues. o o Splitting a primary update package into secondary update packages, one per appearance set. Processing a secondary package. There is a special instance of the updater, called the controller. The controller is the supervisor s primary access point to the database. The controller is a label that tells the supervisor the process that is splitting the primary package. Manager (appr_update_manager). The manager is a script that runs the supervisor. It is responsible for restarting the supervisor, if it is shutdown. It is also called by the console utility and, if it is not running, the console is unable to restart the supervisor. The script sets an environment before running the supervisor, although you should set the environment in the Update Manager.appr_update_env configuration file in $TC_DATA as described in Setting preferences in the.appr_update_env file. Update Manager processes There is only one Update Manager and one supervisor per database. Typically, you run both the Update Manager supervisor and updater processes on the same machine as the main Teamcenter server. However, you can run the Update Manager run on any machine on which Teamcenter is installed. Set the Supervisor.host PLM00021 J Appearance Configuration Guide 3-1

56 Chapter 3 Running the Update Manager preference in the.appr_update_env configuration file to identify the machine on which the Update Manager runs. Note Take care that all installations share the same Teamcenter data, and hence the same.appr_update_env configuration file. The Update Manager has a single associated supervisor process. The supervisor spawns updater processes as required, depending on how many appearance sets are affected by the change. Teamcenter creates and terminates updater processes as required by the supervisor. The main controller update process should always run, to eliminate time spent logging in and out. To do this, set the controller process to not time out by setting the controller.idle.timeout preference to -1 in the.appr_update_env configuration file. You can observe the separate updater processes for the secondary packages for the brief period they run. Working with Update Manager packages An update package is a package of change information to apply to one or more appearance sets. It is a persistent object that is stored in the database. An update package may be of the primary or secondary type. Teamcenter creates update packages when the APPR-update-from-targets handler on the workflow process runs. They are also created when a user saves the bootstrap appearance set or changes effectivity. The queues associated with the primary and secondary update packages are persistently stored in the database, and you can query them to identify the packages in each queue. Primary package A primary package defines a set of changes that may apply to one or more appearance sets. The main controller updater process splits the currently active primary update package into secondary packages, one for each affected appearance root. There is only one primary package active (processing) at any time, because there may be dependencies between the updates. The primary packages must therefore be processed sequentially, in the order the changes (packages) were generated. Secondary package A secondary package defines a set of changes that apply to only one appearance set. An updater applies the changes from a specific secondary package to the affected appearance set. Typically, there is only one secondary package associated with a primary package, that is, the changed structure only impacts one appearance root. However, if the structure change impacts more than one appearance root, there is one secondary package for each affected root. This occurs if: The changed assembly is in two or more products that are tracked by appearances. 3-2 Appearance Configuration Guide PLM00021 J

57 Running the Update Manager The product has appearance sets for the same product that track different configurations. For example, one configuration may be needed for production and another that includes preproduction released parts. Secondary packages may execute in parallel in separate updater processes, because an update to one appearance set has no impact on any other appearance sets. Primary queue Primary packages are placed on the primary queue, which determines the processing order. Teamcenter processes primary packages serially because the result of one update may affect the next update. Secondary queue Secondary packages are placed on the secondary queue. This queue contains only secondary packages for the currently active primary package. The secondary packages have no defined processing order, and Teamcenter may process them in parallel. Updating working appearances Use the appr_working_scheduler utility to create an update schedule for working appearances, that is, any appearance set with a Working entry in its revision rule. This utility places an appearance working package (ApprUpdWorkingPkg) on the primary update queue at intervals you specify. When the appearance supervisor executes the working appearance package, Teamcenter updates the appearance cache. If an existing ApprUpdWorkingPkg update package is not already on the updater queue in an unprocessed or processing state, Teamcenter creates a new package. The scheduler waits until the end of the next elapsed time interval before attempting to put another package on the updater queue. Once initiated, the appr_working_scheduler utility monitors the queue continuously, determining whether to place packages on the queue. It is not necessary to run this utility at scheduled intervals. Understanding update package states A primary package can be in one of the following states: Processed (complete) These packages are listed by the appearance_updater -task=dump_primary,dump_secondary command unless you specify the -since option. Processing (being processed) Unprocessed (waiting on the primary queue) Unqueued A secondary package can be in one of the following states: Waiting (being processed) PLM00021 J Appearance Configuration Guide 3-3

58 Chapter 3 Running the Update Manager Complete Primary and secondary queues do not have a state. Understanding update package types The Update Manager creates the following types of update package: Bootstrap package A primary package that Teamcenter creates when the baseline appearance set is created. It does not have any secondary packages. Changed revisions package A secondary package that Teamcenter creates when a user releases a change to the product structure, that is, by releasing one or more new assembly item revisions. Changed effectivity package A primary package that Teamcenter creates when a user edits effectivity. It does not have any secondary packages. Understanding checker packages Teamcenter creates checker packages if you enable checking by setting the TC_allow_appr_checking preference. You set how often these checker packages are created in the TC_appr_checking_interval preference. There are two types of checker package: Appearance checker package A primary package that validates one or more appearance sets against the corresponding configured structures. It chooses the sets to configure and validate according to the historical usage information generated by the audit packages. If the validation fails, Teamcenter marks the appearance root as corrupt and sends an to the person nominated in the.appr_update_env file. You enable generation of such packages by setting the TC_allow_appr_checking preference. Audit package A primary package that stores information in the database about how users are utilizing appearances. Teamcenter generates a package when a user performs an appearances search in Structure Manager. When processed, it stores information in the database about the relevant appearance root and the date or unit number configuration. You enable generation of such packages by setting the TC_allow_appr_query_auditing preference. Update package information An update package contains the following information that is written to the appearance_updater.syslog log file. 3-4 Appearance Configuration Guide PLM00021 J

59 Running the Update Manager Area Information about Appearance root Appearance root/tracked item ID and revision rule name. Checking state and number of appearances. Process information The name of the Teamcenter process that created the update package. The user who created the process. The target item revisions of the process, including the ID, revision, and owning user. For further information, see Associated appearance_updater syslog. Processing structure changes The following figure shows an example of the sequence of events when a structure change updates the appearance cache in the database. In this example, two assemblies changed A100 and A500. Assembly A500 is used in two products, RB-X1000 and RB-Y500, so more than one appearance root is affected by the change. Consequently, Teamcenter splits the primary package into two secondary packages that are then processed in parallel by two updater processes. PLM00021 J Appearance Configuration Guide 3-5

60 Chapter 3 Running the Update Manager TC Database (Appearance Queues & Package + Appearance Cache) appr_update_manager Update Manager (script that runs Supervisor) Updater Process (controller) appearance-updater Mark primary package as processed 9 4 Query primary queue and fetch primary package Primary Packages There is only one primary and secondary queue in the database. The primary queue has only one active processing package and associated secondary packages. Primary Queue Prim. Package 1 State = Processed Prim. Package 2 State = Processing Ordered Message to request next primary package 3 5b Describe secondary queue to supervisor Supervisor Process appr_update_supervisor Updates report success/failure to Supervisor 8 Spawn updaters 6 8 Updater Process Simultaneous updates Updater Process 5b 5b Secondary Queue Sec. Package 1 (A100/C, A500/C) Sec. Package 2 (A500/C) Prim. Package 3 State = Unprocessed Secondary Packages Appr Root 1 (RB-X1000) Appr Root 2 (RB-Y500) Inform supervisor that new primary package has been placed on primary queue. 2b Create primary package and place on primary queue 2a 7 Appr. Set 2 - Appearances A600 P33 (*) A100 Appearance Cache A500 Appr. Set 1 - Appearances P10 (-) P33 (+) P11 (*) Client Workflow APPR_update_from_targets_AH Targets A100C A600C 1 Release changes & add status TC Process Appearance Update Manager System Flow Sequence of events following structure change The following figure shows the structure changes that triggered these events. 3-6 Appearance Configuration Guide PLM00021 J

61 Running the Update Manager The sequence of events is as follows: Structure changes 1. A user releases item revisions A100/C and A500/C with product structure changes using a workflow process that includes the APPR-update-from-targets appearance workflow handler. 2. The appearance workflow handler creates a primary update package, puts it in the primary queue, and asks the supervisor to perform an update. If the supervisor is busy, it caches the request in memory for later processing. If the supervisor is stopped, it queries the database through the controller when it restarts to ascertain the state of the queues. 3. If the supervisor is idle, it launches the updater (controller) process, if it is not already running. 4. The updater (controller) queries the primary queue and fetches the next unprocessed package. 5. The updater (controller) then splits the primary update package into one or more secondary packages, one for each affected appearance root. In this example, Teamcenter creates two secondary packages, one for appearance roots RB-X1000 and one for RB-Y500. Each secondary package contains the item revisions with changes to the product structure for the associated appearance root, in this case, A100/C and A500/C for RB-X1000 and A500/C for RB-Y The supervisor launches a separate updater process for each secondary package, so that Teamcenter can process the secondary packages at the same time. You can set a limit to the number of simultaneous updater processes by setting the updater.max preference in the.appr_update_env configuration file. PLM00021 J Appearance Configuration Guide 3-7

62 Chapter 3 Running the Update Manager 7. Each updater process locks a secondary package before processing it, to prevent other updaters processing the same package. It then applies the necessary changes to the affected appearance set. 8. The updaters report success or failure to the supervisor, then terminate. They also report any failures in the appearance_updater.syslog and appearance_updater.journal files. You can examine these files to diagnose problems, as described in Log and configuration files. 9. Optionally, the process may now loop back to step 5 if more updaters are required. 10. When all secondary packages are processed successfully for the currently active primary package, the updater (controller) process verifies completion and marks the primary package as complete (State = Processed). 11. The supervisor loops back to step 3. Configuring the Update Manager The Update Manager is controlled by two preference files stored under $TC_DATA:.appr_update_env, which is the main configuration file..appr_update_info. For more information, see Configuring the.appr_update_info file. A default preference file called appr_update_env.default is provided that you can use as the basis of these preference files. Copy the appr_update_env.default file found in the tcdata directory and, on completion, rename it.appr_update_env. Note Unlike other Teamcenter preferences, Update Manager preferences are stored in a preference file, rather than the database. This avoids the need for the supervisor process to access the Teamcenter server and hence improves performance. Setting preferences in the.appr_update_env file Operation of the Update Manager is controlled by preferences you set in the $TC_DATA/.appr_update_env file, as listed in the following table. In most cases, you can accept the default values. Module Preferences control Supervisor The machine running the supervisor. Will the supervisor run in Prod, Poll or Batch mode? Client Communications port. Number of retries. 3-8 Appearance Configuration Guide PLM00021 J

63 Running the Update Manager Module Preferences control Updaters Updater logon. Communications port. Maximum number of updaters. Number of retries. Updater controller Time-outs. Number of retries. Administrator Who receives if problems occur? Log level for debugging. Tip You can include comments in the configuration file by entering two forward slashes (//) as the first nonspace characters on a line. Any text from the double-slash to the end of the line is ignored. Setting supervisor preferences Use the following table to determine how to set supervisor preferences. Note In most systems, the default values of these preferences are acceptable. However, you must set the values of the supervisor.host, updater, updater controller and retry preferences for your site. For a full list of preferences, refer to the commented configuration file. Function Where is the supervisor run? How does the supervisor find new update packages on the queue? Preference and settings (Mandatory) supervisor.host = hostname or IP-address You can run the supervisor in one of three modes: Prod This is the default mode. The tcserver process notifies the supervisor whenever it puts an update in the queue. Possible settings: o supervisor.enabled = 1 o supervisor.shutdown = never o supervisor.polling = -1 Poll This mode requires no communication between the tcserver process and the supervisor. The supervisor polls the database regularly to check for updates. PLM00021 J Appearance Configuration Guide 3-9

64 Chapter 3 Running the Update Manager Function Preference and settings Possible settings, with polling once every minute: o supervisor.enabled = 0 o supervisor.shutdown = never o supervisor.polling = 60 Batch This mode allows the Update Manager to run as an overnight batch job. Users can launch the Update Manager from a job. The Update Manager processes all the updates in the queue and terminates when the queue is empty. Setting the updater preferences Use the following table to determine how to set updater preferences. Function How do updaters begin to log into the Teamcenter database? How many updaters (including the controller) can the supervisor support? Preference and settings Mandatory. updater.login Possible settings: 0 = automatic logon (default) 1 = use appr_update_info for login. The updater attempts automatic logon if this file does not exist or is invalid. For details of configuring the appr_update_info file, see Configuring the.appr_update_info file. Set this preference to 1 to ensure the updater process runs as a user in the dba group. updater.max The minimum value is 2. Typically, you set this to a higher value to allow update packages to be processed in parallel, for example, 5. The maximum value should not be higher than the number of shared appearance roots. Setting the updater controller preferences Use the following table to determine how to set updater controller preferences Appearance Configuration Guide PLM00021 J

65 Running the Update Manager Function How many updates can you perform before restarting the controller? How long (in seconds) does an idle system maintain a running controller? Preference and settings controller.limit.updates Set to an appropriate limit, for example, 100. Determine this setting by considering memory build up over time. You can verify how much memory the appearance_updater process for the controller uses and how many packages it processed by checking the console system status log. controller.idle.timeout Possible settings: 0 = immediate shutdown when idle. -1 = no time-out. If you enable supervisor.polling, set this idle time-out to -1 (disabled) or 0 (immediate shutdown when idle). All other values map to 0. Keeping the controller running while the Update Manager is idle minimizes the delay in starting the updater process when an update request arrives. However, a constantly running controller consumes memory. Setting retry preferences for Update Manager failures In the event of errors, you can control how many times Teamcenter retries an action before terminating and reporting a fatal error to the administrator. Function How many times can a specific controller fail to process a specific primary update package before the system terminates the controller and tries another one? How many times can Teamcenter fail to process a specific primary update package (possibly across multiple controllers) before it gives a fatal error? How many times can you retry processing of a secondary update package before Teamcenter gives a fatal error? Preference controller.restart.failures controller.limit.failures updater.limit.failures Setting administrator preferences You can control who Teamcenter contacts in the event of a serious error and the logs that are generated if this occurs. PLM00021 J Appearance Configuration Guide 3-11

66 Chapter 3 Running the Update Manager Function Who should be ed in the event of a serious error? You can enter multiple administrative address, separating entries with a semicolon as separator. Which SMTP server should Teamcenter use to send this ? Leave this entry commented out (preceded with //) to use the SMTP server defined in the Mail_server_name preference. If neither this preference or Mail_server_name is set, Teamcenter tries to route the through an SMTP server on the local machine. How much should the administrator receive? Set this preference to one of the following values: 0 = none 1 = client errors 2 = supervisor and updater errors 3 = client, supervisor and updater errors How much logging should Teamcenter perform? Set this preference to one of the following values: 0 = none 1 = configuration and errors 2 = full This preference determines the level of reporting in the supervisor log file ($TC_TMP_DIR/appr_ update_supervisor.log). Set it to 1 for normal use or 2 when troubleshooting. If you set it to level 2, set a limit to the supervisor log file size with the admin.log.size preference. What is the maximum log file size of the supervisor log file? You can set this preference to -1 for no limit or to a specific value. This log file can become very large and it is therefore wise to set a limit on its size. Specify the size in bytes, with no commas. The example shown specifies a size of 100 Kbytes, but a production site may require 10 Mbytes. Preference admin. .address = admin@mycompany.com admin. .server = smtp_server.mycompany.com admin. .level = 3 admin.logging = 2 admin.log.size = Configuring the.appr_update_info file This file determines the Teamcenter user as which the appearance_updater processes logs into the database. This process must run as a user with read and write access to the following required data. The revision rule on the appearance root (Read access) Appearance Configuration Guide PLM00021 J

67 Running the Update Manager Items and BVRs (Read access). Spatial_Data dataset (Read and Write access). You may also want to grant the administrator Write access to this dataset in the same rule, for example: Has Type (Spatial_Data) = Appearance Updates: System Administrator - Write; World - No Write Spatial data is particularly sensitive as write access is required to the Spatial_Data dataset which is both created by this process during the bootstrap, and subsequently updated by it. Note Use Access Manager to configure rules that control appropriate access to the required data. Create an.appr_update_info file in the format: -u=appearance_update_user -p=xxxxx -g=dba Place this file in $TC_DATA. Set updater.login in the.appr_update_env file to 1 to enable this login mechanism. Warning Ensure this file is appropriately protected to prevent unauthorized access to date. Start the Update Manager 1. Ensure the Update Manager is configured correctly as described in Configuring the Update Manager. 2. Log on to the machine on which the Update Manager runs. You can identify this machine from the supervisor.host preference in the.appr_update_env configuration file in $TC_DATA. 3. Set the Teamcenter environment according to your operating system. 4. Start the Update Manager by entering the following command: UNIX: $ nohup $TC_BIN/appr_update_manager & Windows: start %TC_BIN%\appr_update_manager This command takes no arguments. It runs the appr_update_manager script that starts the supervisor process that in turn starts an updater (controller) process. nohup ensures process keeps running after the user closes the shell. nohup also pipes the output (both stdout and stderr) to the nohup.out file, that is placed in the user s home directory. PLM00021 J Appearance Configuration Guide 3-13

68 Chapter 3 Running the Update Manager nohup.out is a cumulative file. Consider deleting this file before restarting the Update Manager. The appearance updater must have access to all data, including restricted data. Consequently, ensure infodba is a Teamcenter user so that spatial data is created correctly. Ensure the Teamcenter user running the appearance_updater processes spawned by the Update Manager supervisor is defined correctly in the.appr_update_info file. 5. Verify the Update Manager is running in one of two ways: Using the appr_update_console -query console utility. This reports the state of the supervisor, for example, Idle or Processing, and the number of packages in the primary queue. Directly viewing the processes. This allows you to monitor the following supervisor and updater processes: o o o appr_update_manager appr_update_supervisor appearance_updater Stop and restart the Update Manager If the Update Manager stops for any reason, you can restart it with the following console command: appr_update_console -u=infodba -p=password -g=dba -restart_now You must restart the Update Manager if you change the.appr_updater_env configuration file. You can also use the console to shut down the Update Manager, as follows: Warning appr_update_console -u=infodba -p=password -g=dba - shutdown Do not stop the Update Manager by killing the process. You must be logged in as the Teamcenter infodba user to stop or restart the Update Manager, not the operating system user with the same name. Running the Update Manager utilities You can use two utilities to obtain information about the Update Manager: The console Use this interactive dialog to query the supervisor. Launch the console by entering the appr_update_console command. The appearance_updater command line utility 3-14 Appearance Configuration Guide PLM00021 J

69 Running the Update Manager Use this utility to query the updater processes and queues. You can also use it to run the updater manually in troubleshooting mode, if there are problems with the supervisor. You can also use the find_appearances command line utility to obtain information about appearances, for example, for a particular appearance set, unit number, or date. Using the console The console reports information about the update queues that it obtains from the Supervisor. If you need more detailed information query the database with the appearance_updater utility described in appearance_updater. You can run the console from any machine that has a Teamcenter environment, not necessarily the machine on which the Update Manager runs. When you start the console, it displays the following list of options. Enter the character corresponding to the command you want to perform. 1 Query general status 2 Query specific update package 3 Show specific update package 4 Show primary queue 5 Show secondary queue 6 Log system status 7 Query log file name 8 Change logging level 9 Clear log file r Restart update manager R Restart update manager now s Shutdown update manager S Shutdown update manager now 0 Exit Option 9 and the restart and shutdown menu options are available only if you run the console as the system administrator, for example, by entering appr_update_console -u=infodba -p=infodba -g=dba. If the Update Manager or supervisor is not running, all commands return the following message: Failed to query status, ifail = Option 1 Query general status This option returns the state of the queue, the UID of the primary package being processed and the number of primary update packages, for example: Update Manager status is performing update, current update is RACBzo1WgvaiJD, queue size is 3 Possible values are: Value offline Meaning The updater is not doing anything. This state is used internally by updaters. PLM00021 J Appearance Configuration Guide 3-15

70 Chapter 3 Running the Update Manager Value pre-initializing initializing idle idle, after success idle, after failure performing another update querying database processing primary queue entry stopping recycling ng clearing locks waiting for controller to start waiting for controller to login waiting for controller to stop unused Meaning An updater has started, has connected to the supervisor, and is allocated a slot in the supervisor s updater list. The updater is logging on. The supervisor or updater are not doing anything The updater has successfully completed its task. The updater has failed its task doing secondary packages. The updater is retrying a previously failed secondary package. The controller is checking the queues. The controller is processing a primary package. The updater is shutting down. The updater is shutting down, but will restart. The updater is sending an . The controller is running the clearlocks command. The supervisor is waiting for the controller to start up. The nextstate box tells you what the supervisor will do it after is started. The supervisor is waiting for the controller to log in. The nextstate box tells you what the supervisor will do after it is started. The supervisor is waiting for the controller to stop. It will then start a new controller. The nextstate box tells you what the new controller will do after it is started. May be seen anywhere in nextstate box if there is no planned next state. Option 2 Query specific update package Displays the processing state of a single update package. You are prompted to enter the UID of the package, which you can obtain from the output of the primary queue (the UID is the first string output for each package on the queue), for example: Enter update package s POM uid (or exit to return to menu): RACBzo1WgvaiJD Update RACBzo1WgvaiJD is processing, queued on :24:32, currently at position 0 in queue Option 3 Show specific update package Displays information about a single update package. You are prompted to enter the UID, which you can obtain from the output of the primary queue (the UID is the first string output for each package on the queue), for example: Enter package s POM uid (or exit to return to menu): RACBzo1WgvaiJD ApprUpdChangedRevsPkg: queued on 19-Feb :24:32, (no run date), processing (1), blocked Release Status: (00000e0b = BoBBzo1WgvaiJD) Released on 19-Feb :24: Appearance Configuration Guide PLM00021 J

71 Running the Update Manager 0 Effectivities (no cloned-for AppearanceRoot) 0 secondary package(s) 1 changed ItemRevision(s): (00000e0c = w7bbzo1wgvaijd) HAP-A200/E-Second Level Assembly owned by your name Note The log strings are tags and you can ignore their values. Option 4 Show primary queue Lists details of the primary queue. The following example shows a very small queue; a larger queue would show several entries for several unprocessed packages. Primary queue (1 packages): [0] (AO941bxBgvaiJD) ApprUpdChangedRevsPkg: queued on 28-Feb :30:57, (no run date), unprocessed (0), unblocked Release Status: (00000b36 = AC141bxBgvaiJD) Released on 28-Feb :30:57 by your name 0 Effectivities 0 secondary package(s) 0 filtered-by AppearanceRoot(s) 1 changed ItemRevision(s): (00000b37 = gm64lhmrgvaijd) SD1-A300/D-Spatial - Second level assembly owned by your name Option 5 Show secondary queue Lists details of the secondary queue. A secondary queue has one package for each appearance root in which the changed item revision is used. There is typically one appearance root, unless it is used in several products or has several appearance sets with different revision rules, for example, Production (with History) and Historyless. For example: Secondary queue (1 packages): [0] (Q5x41nc7gvaiJD) ApprUpdByApprRootRevPkg: unblocked corruption-threshold = 0 1 aurvir: aurvir 0 (00000b9f = Qt341nc7gvaiJD) AurvirForChangedRev AppearanceRoot: (00000ba0 = wmy0yxoggvaijd) Item ID: SD1-A1000 (View: view) Revision Rule: Appearance Test - Release Date (with spatial data, active, never fixed, never checked, last updated 28-Feb :06:48, with 8 appearances) View: (00000b9b = Au803jYYgvaiJD) view Changed ItemRevision: (00000b37 = gm64lhmrgvaijd) SD1-A300/D-Spatial - Second level assembly owned by your name 1 Parent Appearance (00000ba1 = Qh30Yxt3gvaiJD) Item: SD1-A300-Spatial - Second level assembly Release Date: 28-Feb :30:57 Option 6 Log system status Dumps the status of the Update Manager into the supervisor log file, including queue size and status of each updater (processing the primary and secondary packages), for example: System Status Overall state: updating Next state: unused Updates processed by current controller: 52 (number of primary packages processed) Current update: Estimated queue states:-( = Primary Queue) Queued update requests: 2 (how many packages awaiting processing) Sets affected by current update: 0(= Appr. Sets -> no of sec d packages) Completed sets: 0 (= secondary packages completed) Total packages: 0 Highest simultaneous clients: 1 Current clients: 1 (the console or tcserver to check Primary queue ) fd 9 from sdlsol10.cbr.ugs.com connected at Fri Sep 27 12:03: Launched (but not connected) updaters: 0 Last updater launch: Wed Sep 25 16:14: Stalled updaters: 2 (should be 0, indicates an error, these will re-start if error overcome. If not, the UM will shut down) Current uninitialized updater connections: 0 Current updaters: 1 (controller + updaters) Process connected from sdlsol10.cbr.ugs.com on fd 6 is currently idle (controller) Process connected from sdlsol10.cbr.ugs.com on fd PLM00021 J Appearance Configuration Guide 3-17

72 Chapter 3 Running the Update Manager 7 is currently idle (appearance updater 1 Process connected from sdlsol10.cbr.ugs.com on fd 8 is currently idle (appearance updater 2) Option 7 Query log file name Returns the location of the supervisor log file, for example: Supervisor log file is "/tmp//appr_update_supervisor28295.log" on sdlsol10 Option 8 Change logging level The current level is shown at the top of the supervisor log file. Enter the appropriate numeric value to set a new logging level, for example: 1. Logging levels: 0 = none, 1 = errors, 2 = full 2. Enter new logging level (or 9 to return to menu): Option 9 Clear log file This clears the supervisor log file, if the system is running without problems. You can also set a maximum size limit for the supervisor log file with the admin.log.size preference in the configuration file. When the set limit is exceeded, Teamcenter clears the log file. Option r Restart update manager The supervisor shuts down when the current primary update is complete and then restarts, that is, it runs the appr_update_manager script. The Update Manager restarts as soon as possible. Option R Restart update manager now The supervisor stops immediately and then restart automatically, that is, the supervisor executable is restarted inside the appr_update_manager script. Any currently active updater processes continue, but others shutdown immediately. When the supervisor restarts, it cannot identify currently active updater processes, so locks may occur. If so, you see errors in the supervisor log file until the system corrects the problem. No manual remedial action is required. Option s Shutdown update manager The supervisor shuts down when the current primary update is complete. The Update Manager shuts down as soon as possible. Option S Shutdown update manager now The supervisor stops immediately. Any currently active updater processes continue, but other processes shut down immediately. This option is not generally recommended. Option 0 Exit See Information in the supervisor log file Appearance Configuration Guide PLM00021 J

73 Running the Update Manager Information in the supervisor log file The supervisor log file contains the status of all the updater processes, allowing you to quickly identify any problems with the Update Manager. The file is located in your temp directory, not the Teamcenter system log directory. The header contains the settings in the.appr_update_env configuration file and allows you to confirm Teamcenter environment variable settings, for example: Appearance Update Supervisor Log opened: Wed April 2 10:44: Program: /pim/sites/v2007/hpp/bin/appr_update_supervisor Process id: 1651 Host: sdlhpp2 Configuration File: /pim/sites/v2007/hpp/tcdata/.appr_update_env TC TC_DB_CONNECT: infodba:tbwiabd@v81 TC_ROOT: /pim/sites/v2007/hpp TC_DATA: /pim/sites/v2007/hpp/tcdata TC_BIN: /pim/sites/v2007/hpp/bin TC_TMP_DIR: undefined Administration Logging level: 2 Log file size limit: unlimited level: 3 address: jimi;neil;mark charset: ISO SMTP server: camntx Supervisor Polling period: undefined AutoShutdown: never Client Port: 1700 Max connections: 50 Timeout: 10 Updater Port: 1710 Max active: 2 Max connections: 50 Startup timeout: 300 Init timeout: 10 Max stalls: 10 Failure limit: 10 Launch command: /pim/sites/v81/sol/bin/appearance_updater Valid hosts: Local host only Controller Is updater: No Idle timeout: -1 Failure limit (restart): 3 Failure limit (abort): 5 Recycle threshold: 0 Max init retries: 11 Init retries before back off: 3 Init back off period: 3600 Logged data: [Wed Sep 25 13:03: ] Validating updater "/pim/sites/v81/sol/bin/appearance_updater -validate" [Wed Sep 25 13:03: ] Updater validated [Wed Sep 25 13:03: ] Supervisor ready listening for clients on port [Wed Sep 25 13:03: ] Supervisor ready listening for updaters on port [Wed Sep 25 13:03: ] Spawning controller, before entering state querying database [Wed Sep 25 13:03: ] Spawning updater "/pim/sites/v81/sol/bin/appearance_updater -supervisor=sdlsol10,1710,1700" [Wed Sep 25 13:03: ] Local connection from sdlsol10.cbr.ugs.com [ ] [Wed Sep 25 13:03: ] Connection from Updater at sdlsol10.cbr.ugs.com on fd 6 accepted [Wed Sep 25 13:03: ] Message connectrequestmsg received from uninitialized Updater on fd 6, current system state: waiting for controller to start [Wed Sep 25 13:03: ] Updater at sdlsol10.cbr.ugs.com on fd 6 has been accepted [Wed Sep 25 13:03: ] Updater at sdlsol10.cbr.ugs.com on fd 6 nominated as Controller [Wed Sep 25 13:03: ] Message updaterstatusmsg received from Updater on fd 6, current system state: waiting for controller to start [Wed Sep 25 13:03: ] Updater on fd 6 has status: initializing [Wed Sep 25 13:03: ] Message updaterstatusmsg received from Updater on fd 6, current system state: waiting for controller to login [Wed Sep 25 13:03: ] Updater on fd 6 has status: idle [Wed Sep 25 13:03: ] Querying state of queues [Wed Sep 25 13:03: ] Message updaterstatusmsg received from Updater on fd 6, current system state: querying database [Wed Sep 25 13:03: ] Updater on fd 6 has status: querying database [Wed Sep 25 13:03: ] Message generalreplymsg received from Updater on fd 6, current system state: querying database [Wed Sep 25 13:03: ] Recycling controller from queryingstate [Wed Sep 25 13:04: ] General Query result: knownupdaterequests = 1 apprsetsinupdate = 0 PLM00021 J Appearance Configuration Guide 3-19

74 Chapter 3 Running the Update Manager completedsets = 0 unallocatedsets = 0 totalpackages = 0 unprocessedpackages = 0 The first section of the logged data lists all the processes. When the state of the queue changes, Teamcenter performs a query. In the example, a new request arrived. You can control the format of the first section by setting the admin.logging level preference in the configuration file. An example of the error section of the log file follows. If there are errors in any of the updater processes, they are reported in this section. [Fri Sep 27 12:05: ] Controller has failed to process primary queue entry Error : "Appearance code currently disabled (either by licensing, or by preference)." ADVICE: Check log files for updater process on sdlsol10.cbr.ugs.com In this example, you would look for details of a problem in the appearance_updater29550.syslog file located in your temp directory. Run the find_appearances utility Use the find_appearances utility to query the database for information about appearances. It is also called when you perform an interactive search in Structure Manager. However, the manual search provided by this utility includes additional functionality and can be useful when inspecting appearances. You can specify arguments to determine the search scope as follows: Set a specific appearance set. Alternatively you can search for all appearance sets. Set a date or unit number for the search. Search for the appearance of a specific part (component) by item ID or other attributes. Configure the output to print effectivity values. Command syntax: find_appearances h Appearance root arguments Arguments [-item_id=item_id ] [-config_rule=config-rule ] [-view_type=view-type ] [-root_only] Description Find appearances for the appearance roots tracking the specified item. Find appearances for the appearance roots tracking against the specified configuration rule. Find appearances for the appearance roots tracking against the specified view type. List only the appearance roots not the appearances Appearance Configuration Guide PLM00021 J

75 Running the Update Manager Configuration arguments Arguments [-date=date now today] Description Configured at the specified date, where: date format is: yyyy MM dd hh mm ss. now means right now. [-unit_no=unit-no] today means midnight first thing this morning. Configured for the specified unit number. Appearance filtering arguments Arguments [-component_item_id= component-item-id] [-query=saved-query [-query_entries=entry=value [,entry=value,...] ] ] Description Corresponding to the specified component item. With item or item revision satisfying the specified query, either: -ics="class[,class,...]" or: -ics"=class.attr-id:value-clause [,.attr-id:value-clause,...]" ] With item or item revision satisfying the specified Classification data mapped_attrs=name, operator, value[,name, operator, value,...] ] where operator is one of =,!=, >, >=, < or <=) with the given mapped attribute values. Output arguments Arguments [-list ] [-verbose ] [-print_cols=all col[,col...] ] ] Description List the appearances in a simple list. List the appearances in an indented list. With -verbose) specify columns to display, where column IDs are: comp,dates,unit_nos,occ, parent,creation_date Precise or - to indicate the preciseness of appearances. PLM00021 J Appearance Configuration Guide 3-21

76 Chapter 3 Running the Update Manager Arguments [-history ] [-attrs ] [-single_line ] [-no_transform ] [-print_queue ] [-timing ] Description Use with -verbose) to print appearance history. Use with -verbose) to print mapped attributes. Use with -attrs) to output mapped attributes on same line as main appearance attributes. Use with -attrs) but do not print the transform matrix. Print information about all the primary queue entries affecting the appearance root, including the processed entries. Print timing information. Action arguments Arguments [-validate] [-check ] [-queue_check] Description Compare the appearances with the actual product structure. You must also supply one or both of -date= and -unit number=, depending on the revision rule. Check each appearance for duplication. Put entries on the queue to check the appearance root. Examples Examples of successful find_appearances utility sessions follow. In the first example, you want to find details of the appearances for a specific appearance root and specify the attributes to print out using -verbose -print_cols=comp,unit_nos arguments. For example: find_appearances -item_id=ap verbose -print_cols=comp,unit_nos In this example, there are two appearance roots for item AP3-000 as there are two appearances sets tracking different revision rules. The first uses mixed mode effectivity (ERCT) with unit and date. The second is configured by release date, so the In Unit and Out Unit columns are unpopulated (the dates attribute would be more appropriate). Found 2 AppearanceRoots AppearanceRoot[0] = 00000b2a = Bxx41WtBgvaiJD (Item ID: AP3-000 (View: view) Revision Rule: AP3 - Mixed Mode (with spatial data, active, never fixed, never checked, last updated 25-Feb :13:45, with 39 appearances)), ok at :13:29 n_appearances = 39 Appearance Component Item (View) In Unit Out Unit --> wsw41amegvaijd AP3-000-AP3-Product (view) > w8z41qqfgvaijd AP Main Module (NMA) (view) > AJy41qQfgvaiJD AP Valve Module (NMA) (view) > AR841qQfgvaiJD AP3-900-Gate Valve, J Series (view) > Qt_41qQfgvaiJD AP3-815-Stud > Qpw41qQfgvaiJD AP3-815-Stud > Qp$41qQfgvaiJD AP3-815-Stud > Qlx41qQfgvaiJD AP3-815-Stud > A9741qQfgvaiJD AP3-812-Nut > A9741qQfgvaiJD AP3-813-New Nut > gh741qqfgvaijd AP3-300-Bonnet Assy (NMA) (view) > g1$41qqfgvaijd AP3-378-Flange > g9241qqfgvaijd AP3-361-Stem (1) > g9241qqfgvaijd AP3-362-Stem (2) > wny41qqfgvaijd AP3-400-Seal Assy (view) Appearance Configuration Guide PLM00021 J

77 Running the Update Manager --> wl741qqfgvaijd AP3-414-V-Ring, Corrosive > wl_41qqfgvaijd AP3-422-Lip Seal, High Etc AppearanceRoot[1] = 00000b29 = Bx441WtBgvaiJD (Item ID: AP3-000 (View: view) Revision Rule: Appearance Test - Release Date (with spatial data, active, never fixed, never checked, last updated 25-Feb :13:36, with 39 appearances)), ok at :13:29 n_appearances = 39 Appearance Component Item (View) In Unit Out Unit --> wo_41a7rgvaijd AP3-000-AP3-Product (view) > AFz41qQbgvaiJD AP Main Module (NMA) (view) NULL NULL --> AR941qQbgvaiJD AP Valve Module (NMA) (view) NULL NULL --> AZ641qQbgvaiJD AP3-900-Gate Valve, J Series (view) NULL NULL --> Qlx41qQbgvaiJD AP3-815-Stud NULL NULL --> Qd341qQbgvaiJD AP3-815-Stud NULL NULL etc The second example narrows the search to one revision rule by specifying the -config_rule=ap3 - Mixed Mode argument and also a specific unit number of -unit_no=1. The mapped attributes of tracked occurrence notes are also output using -attrs. You would typically use the -single_line argument to display the attributes on the same line for readability (not shown in the following example), and also the -no_transform argument to prevent the transform being output. For example: find_appearances -item_id=ap config_rule=ap3 - Mixed Mode -unit_no=1 -verbose -print_cols=comp,unit_nos attrs -no_transform (-single_line) This generates the following output: Found 1 AppearanceRoot AppearanceRoot[0] = 00000b2f = Bxx41WtBgvaiJD (Item ID: AP3-000 (View: view) Revision Rule: AP3 - Mixed Mode (with spatial data, active, never fixed, never checked, last updated 25-Feb :02:16, with 39 appearances)), ok at :13:29 n_appearances = 39 Appearance Component Item (View) In Unit Out Unit --> wsw41amegvaijd AP3-000-AP3-Product (view) > w4941qr5gvaijd AP Main Module (NMA) (view) ATA2="10", ATA5="001", ATA3="10", ATA4="10", ATA1="10" --> AF841qR5gvaiJD AP Valve Module (NMA) (view) ATA2="20", ATA5="001", ATA3="10", ATA4="10", ATA1="10" --> AR241qR5gvaiJD AP3-900-Gate Valve, J Series (view) ATA2="30", ATA5="001", ATA3="10", ATA4="01", ATA1="10" --> Qt441qR5gvaiJD AP3-815-Stud ATA2="30", ATA5="004", ATA3="10", ATA4="02", ATA1="10" --> Ql641qR5gvaiJD AP3-815-Stud ATA2="30", ATA5="004", ATA3="10", ATA4="02", ATA1="10" etc Run the appearance_updater utility The appearance_updater utility allows you to run the updater manually and perform the following tasks: Query packages in the database This action performs a more complete query of the state of the packages and queues than the console commands (the console only reports on the data loaded in memory by the supervisor, which has no link to the database). Perform updates Normally the Update Manager performs this task under the control of the supervisor. You would only run the utility to perform this task if there is a problem with the Update Manager. appearance_updater utility Use the following table to determine how to set the appearance_updater utility arguments. Command syntax: PLM00021 J Appearance Configuration Guide 3-23

78 Chapter 3 Running the Update Manager appearance_updater -h Note You can also execute several of these commands directly from the console. Arguments Usage: appearance_updater -login -validate -quiet -nolog -supervisor -task Description [ ( -u=user -p=password-g=group ) -login=type ] [ -quiet ] [ -nolog ] [ -supervisor=host,port1,port2 ] [ -task=cmd[,cmd...] ] Set to 0 or omitted to automatically log in. Set to 1 to read login arguments from the.appr_update_info file. Use the usual -u, -p and -g arguments for manual launches. Starts the updater, then terminates with return code 99. Do not write messages to stdout. Do not write messages to the log file. Identifies that the supervisor provides tasks. Manually invoke the following tasks: cmd may be one or more of: query_update Outputs the current update. query_primary_size Outputs the size of the primary queue. query_sets Outputs the number of appearance sets, updated sets and unallocated (not in process) sets. query_packages Outputs the number of packages in the secondary queue. query_unprocessed_packages Outputs the number of unprocessed packages in the secondary queue for the currently processing primary. To run the updater manually, see Starting and stopping the Update Manager. o process_primary 3-24 Appearance Configuration Guide PLM00021 J

79 Running the Update Manager Arguments Description Processes the next primary queue entry. This command fails if the secondary queue is not empty. o o o o finish_primary Checks for primary completion and, if complete, marks it as Done. process_secondary Processes updates for a single appearance set in the secondary queue. process_all_secondary Processes updates for every unlocked appearance set. process_all_entries Repeats the sequence { process_primary, process_all_secondary, finish_primary } until the primary queue is empty. The following options apply to the dump_primary and dump_secondary commands: Arguments -show_uids -show_blocked -since="yyyy MM dd hh mm ss" -item_id=item-id Description Include tag and UID information, which is not displayed by default. Include information about blocked packages as well as unblocked packages. Include information about all packages since the specified date, whether unprocessed or processed. Show only those packages relevant to the release of any revision of the specified item. Only available if you also specify the -since= argument. PLM00021 J Appearance Configuration Guide 3-25

80

81 Chapter 4 Using the Appearance Configuration application Using the Appearance Configuration application Add a new revision rule (column) Add a new root item (row) Find set contexts Set flags Create an appearance attribute Map an occurrence note to appearance attributes Define how appearance sets are tracked Destroy an appearance set Stop tracking an appearance set PLM00021 J Appearance Configuration Guide

82

83 Chapter 4 Using the Appearance Configuration application Using the Appearance Configuration application Use the Appearance Configuration application to: 1. Define the appearance sets for which you want to track appearances. Appearance sets are combinations of root item, view, and context revision rule. 2. Configure the mapping of occurrence notes to appearance attributes, if you want to track occurrence note data with changes. The occurrence notes must already exist in Structure Manager. Detailed information about how to create and configure appearances is in Creating and updating appearances. The Appearance Configuration application is available only if the appropriate Context Management license is installed on your system. Note If the Appearance Configuration button is not visible, log on to another application as a user with administrative privileges and check if the button is now visible. Add a new revision rule (column) 1. Click the top right Add button in the Appearance Sets pane and Teamcenter displays the Create New Context dialog box containing all contexts and details. 2. In the dialog box, select the required revision rule and click OK. Teamcenter adds the new context column to the Appearance Sets table. 3. Click Save at the bottom of the box to save the context to the database. Add a new root item (row) 1. Click the lower right Add button and Teamcenter displays the Create New Appearance Set dialog box. 2. In the dialog box, use the following options to add a new root item to the list in the Appearance Sets pane. PLM00021 J Appearance Configuration Guide 4-1

84 Chapter 4 Using the Appearance Configuration application Option Item ID Name View Type Entry Enter the item ID. Entered automatically. Enter the BOM view revision (BVR) associated with the root item, for example, Design View. Click Search to find the item ID or name. Wildcards are accepted. 3. If you did not use the search option, press the enter key, then click OK to enter the item. If you used the search option, double-click the required result in the Search dialog box, then click OK to enter the item. Teamcenter adds the item to the list in the Appearance Sets pane. 4. Click Save at the bottom of the dialog box to save the root item to the database. 5. If you are managing spatial search data, you can optionally add icons indicating that spatial data is applied to the Revision Rule (context) column. Find set contexts If there are many context columns, you can find all set contexts for a selected row: 1. Right-click one of the column labels (Root Item or View). Teamcenter displays a dialog box listing the currently set contexts, that is, columns having flags set and appearance roots defined. 2. In the dialog box, select one of the contexts to scroll the view to display the relevant context column. The last item in the dialog box is More or Less. Choose the More option (default) to expand the list and add all relevant currently unset columns that could have appearance roots defined for the currently selected row. For example, you could add contexts that have end item effectivities with the same end item as the root item for the row. When the list includes all contexts, the last entry is Less and you can choose this option to remove all the unset contexts from the displayed list. Set flags You may have to set the appropriate flags in the correct cell (Root Item and Context) to create the initial bootstrap appearance. 4-2 Appearance Configuration Guide PLM00021 J

85 Using the Appearance Configuration application Create an appearance attribute 1. Select the occurrence note type that you want to map to the new appearance attribute and click the lower Add button. Teamcenter displays the Name dialog box. 2. In the dialog box, type a name for the new appearance attribute. Use a similar name to the occurrence note type. Note You can define, extend, or modify an attribute mapping after the appearance set is created, but any changes are only tracked from that point. Map an occurrence note to appearance attributes 1. Select the occurrence note. 2. Select one or more appearance attributes to map to the occurrence note. 3. Click the Add button in the upper pane to create the mapping. 4. Click Save and Teamcenter displays the Save Appearance Attributes dialog box. 5. Click Yes to save the new mapping in the database. Teamcenter also updates the mapping list in the top of the Appearance Attribute Mapping pane with the new mapping. Note You can map a single occurrence note to more than one appearance attribute. This allows you to search by different fields within a single note type. To use this mapping, write a user exit that splits the text in the note into the appropriate fields to map to each appearance attribute. You set the flag when adding the mapping to indicate that there is a user exit to call. For an example of such a user exit, see Configuring user exits. Define how appearance sets are tracked 1. Right-click the cell and Teamcenter displays the Set Attribute Flags dialog box. Alternatively, if there is a large number of context columns, right-click the required Root Item or View column and Teamcenter displays the Context dialog box. Choose a context entry in the dialog box and Teamcenter scrolls the context columns to the required column then, if an appearance set is not already defined for the cell, it displays the Set Attribute Flags dialog box. 2. In the dialog box, set any of the following flags: Spatial to track spatial data. By default, spatial data is not tracked. Historyless if you want to track historyless appearances. By default, appearances are tracked with history. Published. This option is available only if you have configured Multi-Site Collaboration with appearances. It allows you to publish the appearance root and make appearances searches of remote databases possible. For details of PLM00021 J Appearance Configuration Guide 4-3

86 Chapter 4 Using the Appearance Configuration application how to configure this functionality, see Configure a Multi-Site Collaboration environment. 3. Click OK and Teamcenter refreshes the cell contents with the new flags. Alternatively, you can click Cancel to leave the cell unchanged. To close the dialog box without making changes, click the X button in the top right-hand corner. 4. Save changes to the flags in the database by clicking the Save button in the Appearance Sets pane. Destroy an appearance set If you destroy an appearance set, you remove all appearances in the appearance set from the database. 1. Right-click the corresponding cell and Teamcenter displays a shortcut menu. Warning Verify you have selected the correct cell to avoid unintended loss of data. 2. Choose Destroy from the shortcut menu. 3. Click Save and Teamcenter prompts for confirmation. 4. Click Yes to destroy the appearance set. Stop tracking an appearance set Right-click the corresponding cell and choose Stop Tracking. 4-4 Appearance Configuration Guide PLM00021 J

87 Chapter 5 Creating and updating appearances Creating and updating appearances Creating a bootstrap appearance set Create a baseline appearance set Create an appearance root Checking system operation Check the Update Manager is running Check the state of the queues Check the appearance set is created Releasing the product Updating appearances PLM00021 J Appearance Configuration Guide

88

89 Chapter 5 Creating and updating appearances Creating and updating appearances You create appearances in two stages: 1. Create the bootstrap appearance sets. The Teamcenter administrator creates bootstrap appearance sets for the products you want to track with the Appearance Configuration application. You also create attribute mappings for those occurrence notes whose changed values you want to track. You must have system administrator privileges to perform these actions. 2. Update the appearance sets. End users release assemblies with the appropriate release process, attaching the appropriate release status to each assembly. This process initiates the Appr-update-from-targets handler, which generates appearance update packages for the Update Manager to process offline. The generation process runs in the background, users should be unaware of it. Creating a bootstrap appearance set To create a bootstrap appearance set, the Teamcenter administrator must create a baseline appearance set and an appearance root. For more information about how to use the Appearance Configuration application for these activities, see Using the Appearance Configuration application. Create a baseline appearance set 1. If you want to track occurrence note changes with appearance sets, ensure the note types to track are mapped to appearance attributes. Caution Tracking changes to notes in this way can adversely affect performance. Do not track changes to note types whose values change frequently, if you are not interested in searching against them, as this generates unnecessary appearance updates. 2. If you want the appearance sets to track spatial data, define spatial data on all piece parts with solid geometry. This spatial data may be TruShape files with named references to UGMaster datasets or DirectModel datasets. PLM00021 J Appearance Configuration Guide 5-1

90 Chapter 5 Creating and updating appearances For details about how to define this data, see Configuring NX and Lifecycle Visualization. 3. If you work in mixed effectivity mode, user exits may be implemented to switch attribute values such as the item type. Ensure they are working correctly or the appearances are not generated. Examples of these user exits include: USER_appr_item_is_above_ERCT USER_update_end_item_search_results USER_bomline_is_preferred_ancestor Create an appearance root To create a new appearance root, use the Appearance Sets pane of the Appearance Configuration application to specify the following parameters, as described in Add a new revision rule (column) and Add a new root item (row). Configuration To Be Tracked If necessary, add a column to specifying the name of the revision rule and associated release status of the configuration to track. This rule may only contain Has Status entries. In addition, you must include an End Item entry for product structures configured by unit effectivity. Typically, the End Item is the same as the root item, but this is not mandatory. Product To Be Tracked Add a row to specify the item ID of the root item at the top level Item of the product structure. Spatial Data Tracking In the cell at the intersection of the row and column, set spatial data tracking On or Off as required. Do not change this value once a bootstrap appearance set is created. Historyless Appearance Set Set to without if you do not want to retain this history of the appearance set. Remote Searching If you want to make the appearance set available for searching from remote databases, publish it by setting the Published flag. After you complete the previous steps, make a final check of the selections and click Save. Teamcenter places a bootstrap update package in the queue for the Update Manager to process and thus creates the bootstrap appearance set. This may take some time to complete for a large structure, for example, up to 2 hours for a 10,000 line structure. Checking system operation After creating the bootstrap appearance set, perform the following checks to verify the system is running correctly. If you identify problems, see Solving problems. 5-2 Appearance Configuration Guide PLM00021 J

91 Creating and updating appearances Check the Update Manager is running 1. Start the console by entering the following command: appr_update_console 2. Choose option 1 (Query general status) by entering the value 1 and pressing the Enter key. Teamcenter returns the state of the Update Manager, which is Processing if the Update Manager is running. If the Update Manager is not running, Teamcenter returns: Failed to query status, ifail = The following errors occurred: Error 82150: Socket error "Connection refused" while communicating with Appearances Update Manager 3. If the Update Manager is not running, restart it with the console s option r (Restart update manager). For more information, see Stop and restart the Update Manager. Check the state of the queues Enter in turn the console options 3 (Show primary queue) and 4 (Show secondary queue). Teamcenter displays details of the primary packages and you should verify there is an ApprUpdBootstrapPkg bootstrap package on the primary queue. Check the appearance set is created 1. Load the top-level item of the structure into Structure Manager, and set the same revision rule as used in the appearance root. Check that the Search button is active. 2. Search for a component in the structure by item ID and check that the item is found. 3. If you are managing spatial data with appearances, select a component and do a spatial search by proximity. If the searches are successful, the appearance set exists. You can also use the find_appearances utility to verify if the appearance set exists, by entering the following command: find_appearances -item_id=root Item-ID Teamcenter returns the number of available appearances created. Releasing the product You may release all parts in the product before creating the bootstrap appearance set. Alternatively, you may create the bootstrap appearance set, then release the parts. If you use mixed unit effectivity and date released configuration, parts below the effectivity release configuration transition (ERCT) line are configured by release date and must not share the same release status as those above, which are configured by PLM00021 J Appearance Configuration Guide 5-3

92 Chapter 5 Creating and updating appearances unit effectivity. Thus you must release them with a separate process, unless your site has implemented custom handlers for this purpose. For very large structures, bootstrap appearances take several hours to generate. For structures with more 130,000 lines, you may encounter memory issues. In this case, a UNIX server has a higher memory limit than a Microsoft Windows server. To observe progress of appearance creation, use the find_appearances utility. However, appearances are not saved to the database until the complete structure is processed, so there may be a delay in the utilities report. Tip For very large structures, create a snapshot folder to contain one revision of each component and release the contents of this folder. Updating appearances Take care when you release changed assemblies that update the appearance cache. To avoid update failures and data inconsistencies, Siemens PLM Software recommends that you implement rule handlers or manual procedures to: Ensure spatial data is present on all parts with geometry. Verify the correct Workflow process is used with the Appr-update-from-targets handler when attaching status. Caution You must use a release process that includes the Appr-update-from-targets handler. If you use a Workflow process that adds the release status in an appearance root but does not run the handler, the appearance set cannot be updated. You cannot revise or re-release the assembly in this situation, but must save it with a new item ID. Check all Workflow processes and ensure the Appr-update-from-targets handler is added wherever necessary. You can remove a release status with the release_man utility, but you should not make this utility available for general use, as there are data integrity and security issues. To update appearances for a modified assembly, release the changes with a workflow process that runs the Appr-update-from-targets handler. Ensure you save any changes in Structure Manager before you release the modified structure, otherwise the appearances may assume an inconsistent state. Ensure any new parts are released or Teamcenter does not create appearances for them. You can release these parts separately before the assembly. The same release process may be used with the Appr-update-from-targets handler, but it does not perform any updates. If you maintain working appearances, run the appr_working_scheduler update scheduler. This utility places an appearance working package (ApprUpdWorkingPkg) on the primary update queue at an interval you specify. 5-4 Appearance Configuration Guide PLM00021 J

93 Creating and updating appearances You can release the new item revision for the changed assembly as part of an engineering change, or directly with a simple or complex workflow process, providing it runs the Appr-update-from-targets handler. If the appearance update does not complete successfully, the administrator receives a warning . To manually verify if the update was successful, search for the revised assembly in Structure Manager: Set Date/Unit Number to the current date or a unit number. The search should successfully return new components in the revised assembly. (It is not necessary to set End Item as this is embedded in the revision rule.) If you set a previous date and search for the revised assembly, the search should not return the new components in the revised assembly. There may be some delay before search results are returned if a large number of appearance packages are being processed. You can check the queue status with the console. For details of how to perform appearance searches, see the Structure Manager Guide. PLM00021 J Appearance Configuration Guide 5-5

94

95 Chapter 6 Solving problems Solving problems Frequently asked questions Locating appearance sets General usage Configuration and setup questions Detecting and repairing inconsistencies Detecting inconsistencies Validating appearances automatically Preventing searches of an inconsistent appearance root Interpreting appearance root attributes Validating appearances manually Repairing inconsistencies with the fix_appearances utility Using diagnostic tools Log and configuration files Log file appr_update_supervisor.log Locating the log file Example of supervisor log file header Example of supervisor log file with error Associated appearance_updater syslog Identifying the Workflow process or item revisions that failed to update the appearance cache Log file appearance_updater.syslog Configuration file.appr_update_env Examples of s sent if an Update Manager error occurs Configuration file.appr_update_info Utilities Console find_appearances appearance_updater Starting and stopping the Update Manager Checking the Update Manager environment Troubleshooting License problems Appearance bootstrap problems Checking the terminal from which the supervisor process is running Perform an appearances search with the find_appearances utility Delete an appearance set and restart Bootstrap appearance set does not create Appearances not created in mixed mode configuration PLM00021 J Appearance Configuration Guide

96 Appearance update problems No connection between the supervisor and appearance_updater processes Console is not talking to the supervisor Supervisor is not running as the intended user (dba group member) appearance_updater process cannot access the license file New revision is released, but search does not find new parts Update Manager is not running when setting effectivity on a release status Spatial update problems Verifying that spatial data files are created and accessible Using mixed units Mixed mode (ERCT) not working Search problems Search for item ID returns no result Spatial searches not working Spatial search not updating Spatial search results incorrect Spatial search takes a long time Changes to piece part geometry not tracked Appearance Configuration Guide PLM00021 J

97 Chapter 6 Solving problems Solving problems If you encounter a problem with appearance searches or the updating of appearance sets, you should identify the symptoms of the problem, then locate its source using the troubleshooting tools provided. Frequently asked questions If you have problems locating appearance sets or using appearances, refer to the appropriate group of frequently asked questions and answers. Locating appearance sets If you have problems locating appearance sets, review the following questions. Question When I create a baseline appearance set, which revision of the top-level item is used? What revision rule is used for configuring the other items in the assembly? How does a nonadministrative user find out what appearance sets are available? Answer The revisions are configured by the revision rule associated with the appearance root. Use the Appearance Configuration application described in Using the Appearance Configuration application. This is accessible to all users, but only system administrators can make changes. Look at the Appearance Sets pane and note the table of tracked and root item IDs for the structures tracked by appearances. Note the cells with icons to identify the configurations by which the structure is tracked and if spatial data is tracked. Empty cells indicate that the combination is untracked. PLM00021 J Appearance Configuration Guide 6-1

98 Chapter 6 Solving problems Question For a given item, how does a nonadministrative user find out the revision rules that have corresponding appearance sets? How can I identify the appearance set to which a particular line in the product structure belongs? Answer Use the Appearance Configuration application described in Using the Appearance Configuration application. The column headers for the table in the Appearance Sets pane display the names of the revision rules that are used to track appearances. View details of the revision rule in the tool tip that appears when you place the cursor over the column header. In Structure Manager, add the bl_appearance and bl_appearance_path property columns, as described in the Structure Manager Guide. These lines show the identification tags assigned by the appearance system to the appearance and appearance path node corresponding to each line. You can locate the corresponding IDs in the appearances logs. General usage For assistance with general usage problems, review the following questions. Question After I release a change, how do I know when the applicable appearance sets are updated to incorporate my newly released change? How can I identify the appearance sets affected by my change? What do I do if I suspect that an appearance set is damaged? How can I delete an appearance set? How can I tell if an update package failed? Answer You can achieve this indirectly by running appearance_updater -task=dump_primary and looking for the IDs of item that are released. If none are present, the package has been processed, and the appearances should be updated. Use the appearance_updater -task= dump_primary,dump_secondary -since=yyyy MM dd hh mm ss command, entering a time just before your update package was processed. You can then choose your primary package from the list. This also shows the list of secondary packages representing the affected appearance sets. Run the fix_appearances utility. For details, see Repairing inconsistencies with the fix_appearances utility. Use the Appearance Configuration application described in Using the Appearance Configuration application. Select a cell and click the X (delete) button in the lower left corner of the Appearance Sets pane. Click Save and Teamcenter deletes the appearance set. The administrator receives an . You can also check for errors in the supervisor log file. 6-2 Appearance Configuration Guide PLM00021 J

99 Solving problems Question How can I tell which update packages are waiting to be processed? How can I tell which update packages have already been processed? How can I determine what user event triggered an update package and who initiated it? How can I find out the size (number of appearances or bytes) in an appearance set? How can I tell if the Update Manager is running? How can I determine the resources (memory or CPU) consumed by a particular update package? What kind of sanity checkers are available? How do I enable them? How do I interpret the results? Answer Run the appearance_updater -task=dump_primary command. Run the appearance_updater -dump_primary -since= yyyy MM dd hh mm ss command. Run the appearance_updater -task=dump_primary,dump_secondary command to print user-related information, for example, the owner and date of the release status associated with the release of an item revision that triggered the creation of an update package. The find_appearances utility lists the number of appearances for each appearance root. The size of each appearance depends on the number of mapped attributes: an appearance with no mapped attribute occupies about 1 KByte; each mapped attribute adds about 270 bytes. Run the console by entering appr_update_console and select the query option. If it fails with a Connection refused socket error, the Update Manager is not running. It returns the Update Manager s status if it is running. Check $TC_TMP_DIR/appearance_updater*.* files. You may need to modify your Teamcenter journaling settings. The find_appearances -verbose command with date or unit number arguments prints a structure it deduces from the appearances. This may be inspected visually. The find_appearances -validate command compares the structure represented in the appearance cache with the actual structure for a given configuration date or unit. Configuration and setup questions For assistance with configuration and setup issues, review the following questions. PLM00021 J Appearance Configuration Guide 6-3

100 Chapter 6 Solving problems Question Can I have more than one Update Manager running on the same machine or on different machine? Are there limitations on where the Update Manager can be run? What access privileges are required by the Update Manager and by the updater itself? What log files are created? If any are optional, how do I turn them on? Where are the log files stored? What useful information can I find in them? Answer Running more than one Update Manager against a single database may corrupt the appearance cache. However, you can have multiple Update Managers on a single machine, if each is operating against a different database and they are allocated different port numbers (that is, different client and updater socket connections are defined in the.appr_update_env configuration file. There is no benefit in running multiple Update Managers against the same database. No. Always run the Update Manager as a member of the dba group to allow spatial data to be updated properly. The Update Manager supervisor prints a log file ($TC_TMP_DIR/appr_update_ supervisor*.log). The level of reporting is controlled by the admin.logging setting in the $TC_DATA/.appr_update_env file. Teamcenter creates one supervisor log file that exists for the duration of the supervisor process. This file can become very large. The updater produces Teamcenter system log and journal files $TC_TMP_DIR/appearance_updater*.* according to the Teamcenter environment variables. There is an updater system log file for each updater process that runs. Detecting and repairing inconsistencies Teamcenter includes internal checking routines that validate if the appearances created for fast searches are consistent with the structure configured in Structure Manager when applying the appropriate revision rule. Appearances are generated as a cumulative cache of all changes that are made for a structure. If the cache becomes inconsistent with the full representation of the structure for any reason, Teamcenter detects the problem and warns system administrators and end users. Such inconsistencies may not be obvious to users until they observe incorrect results, which may be difficult if there are large structures with many changes. 6-4 Appearance Configuration Guide PLM00021 J

101 Solving problems Detecting inconsistencies Teamcenter detects inconsistencies by comparing the structure as it would be configured with the appropriate revision rule in Structure Manager with the corresponding appearances in the cache. This check may be initiated automatically or manually: Automatic initiation To validate appearances according to their frequency of use, you must generate query audit and appearance checker packages as described in subsequent sections. Manual initiation Validate specific appearances by running the find_appearances utility with the -validate argument to specify the appearances. If any checks fail, Teamcenter marks the appearance root as inconsistent and generates an error to the administrator. You can fix the inconsistency by running the fix_appearances utility. If an appearance root is marked as inconsistent, no further appearances can be generated for that root. In addition, users may be prevented from performing a search. Validating appearances automatically Validating appearances is a time-consuming process as Teamcenter needs to compare a large number of permutations of dates or unit numbers. To optimize performance, Teamcenter retains data about the most frequently searched configurations and biases the appearance validation accordingly, ignoring those configurations that are no longer active. During automatic validation, Teamcenter creates the following: Audit records Audit records (ApprQueryAudit objects in the database) whenever a user performs a Structure Manager Search. Audit records have attributes that indicate how often the appearance root is searched, as follows: o Validation_worthiness a value that increases each time a search is performed. o o For the date the audit record was last updated, Last_worthiness_update_date a date. A date and unit number range to which the audit record applies. These attributes in the audit record are updated by the query audit and appearance checker packages. The most commonly searched appearances are then validated by the appearance checker packages, according to the attributes on the audit record. Each appearance root may have several audit records with different date or unit ranges. Query audit packages PLM00021 J Appearance Configuration Guide 6-5

102 Chapter 6 Solving problems Teamcenter generates a query audit package whenever you perform a Structure Manager search. It uses the package to create an audit record, if one does not already exist, with the same unit number or date in the date or unit range attributes of the audit record. The package always updates the validation_worthiness attribute of the audit record. Set the TC_allow_appr_query_auditing preference to true to activate the generation of query audit packages. You can also set the following preferences to control the ranges of the date and/or unit numbers for a particular audit record: o o TC_aqa_date_range specifies the number of days in the range. Must always be an integer. Default value is 3. TC_aqa_unit_no_range specifies the number of units in the range. Must always be an integer. Default value is 5. The audit record is not created or updated immediately. Teamcenter places an audit checker package in the update queue with the other packages (for example, primary and secondary update packages) for later processing. This minimizes the effect of auditing on the normal user. The statistics are provided in the form of histograms, for example, N queries have been performed (on a given AppearanceRoot) for a date between D1 and D2 and/or a unit-no between U1 and U2. The width of each histogram block (D2-D1) and (U2-U1) is specified with the preferences described previously. You should not change the default values of the other preferences associated with this functionality. Appearance checker packages Teamcenter generates appearance checker packages at regular intervals and validates appearances according to information in the audit records, if you configure validations as follows: 1. Set the TC_allow_appr_checking preference to true to activate the generation of appearance checker packages. 2. Set the TC_appr_checking_interval preference to define how often (in hours) Teamcenter performs a validation, that is, how frequently it processes the next appearance checker package on the queue. You should configure validation frequently enough to prevent a backlog of appearance checker packages, but not so often as to interfere with the processing of appearance update packages. The default value is 2 hours. 3. For an appearance root, configure the structure for the corresponding root item, revision rule, and date or unit number effectivity, as specified in an audit record. 4. Search the database for the appearances that correspond to this configured structure. Teamcenter builds another structure from those appearances and confirms the two BOMs match. 6-6 Appearance Configuration Guide PLM00021 J

103 Solving problems If they do not match, the package marks the appearance root as inconsistent by setting the corruption_status attribute to 4. It sends an to the administrator, advising that the fix_appearances utility is run. If they do match, it sets the ok_date attribute attribute on the appearance root with the date the validation took place. In addition, it resets the validation_worthiness attribute on the audit record to 0 to avoid redundant validations. Preventing searches of an inconsistent appearance root You can prevent users from performing Structure Manager searches of an appearance root marked as inconsistent by setting the TC_prevent_appr_query_on_corrupt_root preference to true. In this way, you are alerted immediately if there is a problem. However, depending on the severity of the problem, you may want to permit searches by setting this preference to false. Interpreting appearance root attributes The appearance root can have any of the following attributes: Corrupt status The appearance root has a corruption-status attribute for validation purpose that can have the following values: o o o o o 0 = OK. 1 = Adjusting after item revision import (for Multi-Site Collaboration appearances). 2 = Being fixed by the fix_appearances utility. 3 = Unprocessable (processing of some package failing consistently). 4 = Inconsistent. The attribute starts as 0 and remains at this value unless an appearance checker package detects an inconsistency. In that case, it is set to 3 or 4. When you run the fix_appearances utility, the value is set to 2, as it may take some time for the process to complete. Once the inconsistency is successfully fixed, the utility resets the value back to 0. ok_date the last date the appearance was OK. last_fix_date the last date the appearance set was fixed. last_check_date the last date the appearance set was checked by a checker package. PLM00021 J Appearance Configuration Guide 6-7

104 Chapter 6 Solving problems Validating appearances manually You can validate appearances manually at any time by entering the find_appearances -validate command. For further information on this utility, see Run the find_appearances utility. The find_appearances utility does not mark the appearance root as inconsistent. To do this, you must enable automatic appearance validation, as a result of which Teamcenter marks the appearance root as inconsistent if it detects a problem. To repair appearances after a manual check, run the fix_appearances utility with the -force option, as described in Repairing inconsistencies with the fix_appearances utility. Repairing inconsistencies with the fix_appearances utility The fix_appearances utility rolls back and deletes appearances to the last point at which the appearance root was marked as consistent, that is, the corruption_status attribute was 0. It also requeues the relevant update packages. When the packages are reprocessed, Teamcenter creates a new set of appearances that more accurately represent the actual structure. This is effectively a partial rollback and does not force recreation of the complete appearance set. The fix_appearances utility takes the following arguments: -ok_date=date -force -item_id=item_id -config_rule=config-rule -view_type=view-type By default, the fix_appearances utility uses the date of the ok_date attribute of the appearance root, that is the date at which the last successful automatic validation took place. If validation never took place, the ok_date is the same as the appearance root s creation date. However, you can specify a date for roll back with the ok_date argument. This date may be earlier than the last ok-date on the appearance root. If you run find_appearances -verbose -item_id=id, the utility dumps the last ok-date of the appearance root. You can then take this date and run fix_appearances with the ok-date value immediately before it. The -force argument is required because of differences between the automatic and the manual checking processes. The error message tells you whether you need to use the -force argument. Additional arguments define the appearance root to attempt to repair and are optional, that is, you can process more than one appearance set at a time. It is not necessary to enable appearance checking to repair appearances; the checking merely alerts the administrator of any problem. 6-8 Appearance Configuration Guide PLM00021 J

105 Solving problems Using diagnostic tools Although the appearance system is complex, it is well instrumented with tools that allow you to see what is happening and log files that record events and errors. To effectively diagnose problems, you should understand the overall process flow and the operation of the Update Manager, as described in Running the Update Manager. Log and configuration files The following figure shows the log files associated with the main processes and configuration files. Location of log files You can view these log files using a text editor or similar tool. Use the log and configuration files to obtain diagnostic information as follows: PLM00021 J Appearance Configuration Guide 6-9