Appearance Config PDF

Teamcenter 10.
Appearance Configuration Guide
Publication Number
PLM00021 J
Proprietary and restricted rights notice
This software and related documentation are proprietary to Siemens Product

Lifecycle Management Software Inc.
© 2013 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

Contents
Proprietary and restricted rights notice . . . . . . . . . . . . . . . . . . . . . . . . . 2
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Getting started with appearance configuration . . . . . . . . . . . . . . . . . . . . . . . 1-1
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Configuring appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Appearance Configuration interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Basic concepts for using appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Basic tasks using appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Unsupported functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Syntax conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Configuring for appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Configuring Teamcenter for appearances . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Setting Teamcenter preferences . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Set environment variables . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Configuring user exits . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Configuring Workflow processes . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Editing effectivity . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Creating saved queries . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Creating revision rules . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Creating appearance attribute mappings . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Creating Classification searches . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Configuring NX and Lifecycle Visualization . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Configuring optional functionality . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Choosing a functionality level . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Running the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Running the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Update Manager processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Working with Update Manager packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Processing structure changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Configuring the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Start the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Stop and restart the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Running the Update Manager utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Using the Appearance Configuration application . . . . . . . . . . . . . . . . . 4-1

Using the Appearance Configuration application . . . . . . . . . . . . . . . . . . . . . . 4-1
Add a new revision rule (column) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Add a new root item (row) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Find set contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Set flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Create an appearance attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
PLM00021 J Appearance Configuration Guide 3

Contents
Define how appearance sets are tracked . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Creating and updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Creating and updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Creating a bootstrap appearance set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Checking system operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Releasing the product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Solving problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Solving problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Detecting and repairing inconsistencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Using diagnostic tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Command reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1
Figures
Appearance update mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

Historyless appearances mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Creating a published appearance set . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Performing a remote appearance search . . . . . . . . . . . . . . . . . . . . . . . 1-18
Modifying a structure at a remote site . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Sequence of events following structure change . . . . . . . . . . . . . . . . . . . 3-6
Structure changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Location of log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
4 Appearance Configuration Guide PLM00021 J

Chapter
1 Getting started
Getting started with appearance configuration . . . . . . . . . . . . . . . . . . . . . . . 1-1
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Configuring appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Appearance Configuration interface . . . ... . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Appearance Sets pane . . . . . . . . . . ... . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Appearance Attribute Mapping pane .. . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Rich client perspectives and views . ... . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Basic concepts for using appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Working with appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Understanding occurrence and appearance threads . . . . . . . . . . . . . . . . . 1-7
Creating appearance searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Making appearances searches in Structure Manager . . . . . . . . . . . . . 1-8
Using historyless appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Execute an all history search in Structure Manager . . . . . . . . . . . . . . 1-9
Clear all-history lines in Structure Manager . . . . . . . . . . . . . . . . . . . 1-9
Enhancing searches with other attributes . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Creating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Creating appearance searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Enhancing searches with other attributes . . . . . . . . . . . . . . . . . . . . . 1-10
Updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Creating a spatial cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Generating a spatial cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Updating the spatial cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Performing a spatial query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Configuring appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12
Release date only mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Unit effectivity only and date effectivity only modes . . . . . . . . . . . 1-13
Unit effectivity plus release date mode . . . . . . . . . . . . . . . . . . . . 1-13
Updating appearances for precise assemblies . . . . . . . . . . . . . . . . . . . 1-14
Updating appearances with incremental change . . . . . . . . . . . . . . . . . . . 1-14
Creating historyless appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Using Multi-Site Collaboration with appearances . . . . . . . . . . . . . . . . . . 1-15
Basic tasks using appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Unsupported functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Syntax conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
PLM00021 J Appearance Configuration Guide

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 345234, 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 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.
Enable Before using this capability, you must create appearances, as
Appearance described in Creating and updating appearances.
Configuration
The Appearance Configuration application does not need to be
enabled before you use it.
PLM00021 J Appearance Configuration Guide 1-1

Chapter 1 Getting started
Configure There are additional steps you must perform before you can
Appearance configure appearances.
Configuration
For more information, see Configuring appearances.
Start the
Appearance Click Appearance Configuration in the navigation pane.
Configuration
application
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

Getting started
Appearance Configuration interface

The Appearance Configuration application user interface comprises two panes,
Appearance Sets and Appearance Attribute Mapping.
Appearance Sets pane

Item Function
Root Item list Top-level (root) item tracked by the appearance set.
View list Views being tracked. Ensure you select the required
view type (BOM view) when multiple views are
present.
Revision Rule list 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)

–
Untracked appearances have a blank cell.

Top Add button Displays the Create New Context dialog box allowing
you to create a new revision rule column.
Top Delete button Deletes a selected revision rule column.
Bottom Add button Displays the Create New Appearance Set dialog box
allowing you to add a new row for a new tracked root
item.
Bottom Delete button Deletes a root item and any appearance sets tracked
on it. The appearance set is not deleted (destroyed)
until you click Save.
Save button Saves any changes in the database.

Item Function
Restore button Retrieves previous appearance sets from the
database. Any changes are lost.
Refresh button 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 Appearance Attribute Mapping pane

Mapping list Displays the appearance attributes to
occurrence note mappings.
Use the arrow to sort the list in ascending or
descending alphanumeric order.
Occurrence Note Types box 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.
Appearance Attributes box Lists the created appearance attributes.
Add and Delete buttons Creates or deletes an appearance attribute.
Save and Restore buttons 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 F1.

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 Purpose
Appearance 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
2007. In addition, an appearance stores the absolute
transform and values of occurrence notes to track.
Appearance root An object in the database containing the set of
parameters that define an appearance set—the root item,
configuration context, and view.
Appearance set (cache) 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.

Element Purpose
Bootstrap appearance The initial appearance set created for a product for a
set specified appearance root. It defines the root item and
configuration context that are tracked.
Configuration context 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.
You can group entries when appropriate.

ERCT 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.
Historyless appearance An appearance set that does not record history. Its status
set differs from the status of the production appearance set,
for example, Pre-released.
Mapped attributes Occurrence notes that are mapped to appearance
attributes so that changes in their values can be tracked.
Root item 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.
Spatial data 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

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 2005. 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.

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.

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

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.

Getting started
Update
Workflow Handler Affected appearance sets are updated

triggers update
seat/C-seat assy (view)

steering/G (view) Item: X200 Item: X200 Item: X300
ski-left/AE (view)
ski-right/A (view) Context: Effective Unit Context: Pending Context: Effective Unit
skid-frame/A (view)
Newly released
item revisions
Appearance Set Appearance Set Appearance Set
Source Source Source

Description Description 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.

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

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

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

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.
Pre- Pre- Pre-

History-less Released Released Released
Appearance set
(no effectivity) B1 B2 B3
1-Up Revise Revise Revise 10-Up

Released Released
Revise Save Save Release
P123A /B /B /B P123B
Working revision which is being changed and
Production saved with periodic baseline revisions created
Appearance Set Revision B is approved and
over time.
released with status Released,
(with effectivity effectivity set and production
and history) 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

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

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.

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.

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 P50.
3. 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.

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.

Getting started
The combinations of functionality listed in the following table are not supported
with appearances.
Incremental
Incremental change with Multi-Site
Effectivity Historyless change intents Precise Collaboration
Release Yes Yes Yes No Yes Yes
date
Effectivity — No Yes No No Yes
Historyless — — No No Yes Yes
Incremental — — — — No No
change
Incremental — — — — No No
change
with
intents
Precise — — — — — Yes
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

Chapter
2 Configuring for appearances
Configuring Teamcenter for appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Setting Teamcenter preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Set spatial data preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Set appearance preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Enable automatic appearance validation . . . . . . . . . . . . . . . . . . . . . . 2-2
Prevent searches of inconsistent appearance sets . . . . . . . . . . . . . . . . 2-2
Release historyless appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Process spatial data in separate update package . . . . . . . . . . . . . . . . 2-2
Limit number of appearances processed . . . . . . . . . . . . . . . . . . . . . . 2-3
Set viewer preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Set mail preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Set environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Configuring user exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Set the appearance attribute mapper with USER_ps_update_appr_attr . . . 2-5
Set ERCT with USER_appr_item_is_above_ERCT . . . . . . . . . . . . . . . . . . 2-5
Set Structure Manager search granularity with
USER_appr_update_end_item_search_results . . . . . . . . . . . . . . . . . . . 2-6
Set preferred ancestor with USER_bomline_is_preferred_ancestor . . . . . . 2-6
Configuring Workflow processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Editing effectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Creating saved queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Creating revision rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

Configure by release date only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Configure with mixed effectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Creating appearance attribute mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Creating Classification searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Configuring NX and Lifecycle Visualization . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Configuring optional functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

Managing historyless appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Configure a historyless appearance set . . . . . . . . . . . . . . . . . . . . . . . 2-13
Update a historyless appearance set . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Purge old revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

Creating appearances for precise and imprecise structures . . . . . . . . . . . . 2-15
Configure precise structures with appearances . . . . . . . . . . . . . . . . . . 2-15
Configuring appearances with incremental change . . . . . . . . . . . . . . . . . . 2-16
Configure a Multi-Site Collaboration environment . . . . . . . . . . . . . . . . . . 2-17
Choosing a functionality level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18

Minimal setup process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18
Full setup process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
Appearance Configuration Guide PLM00021 J

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

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

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

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, e-mail 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 Make the following entry

Obtain any custom user exits 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.
Retain Teamcenter or NX By default, system logs are deleted if no errors
system logs are found. To retain these for debugging
purposes, enter:
NX_KEEP_SYSTEM_LOG=ON
TC_KEEP_SYSTEM_LOG=ON

To Make the following entry

Ensure the temp directory is set TC_TMP_DIR=C:\temp (or appropriate
directory).
The correct setting is important for the
generation of spatial data.
Ignore any available TSO data IGNORE_TSO_DATA
and only use JT 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.

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.

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.

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 Entry

AT-Date Released 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.

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.

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 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.
• Choosing units
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 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.
o 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.
o The units of the spatial cache are metres, regardless of the units of the input
TSO or JT files.
o 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.

• 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 Looks for a UGMASTER dataset and a .tso named reference. If one exists,
Teamcenter uses it to update the occupancy cache.
o 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 Typical settings

Assemblies_TrueShapeCellSize 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.
Assemblies_TrueShapeCellSizeUnits English or metric
Assemblies_TrueShapeGenerate Yes
Assemblies_ModelReferenceSet REFSOLID

Default Typical settings

Assemblies_AdditionalModelRefSets 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.
NXMGR_StructureUpdateOnLoad On1
NXMGR_StructureUpdateOnSave On
• Generate Lifecycle Visualization data

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.
• 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.

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:

• 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.

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.

• 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

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:
Transfer Transfer
Privilege ® Publish Export Import out in
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
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:

• 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.

• 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 Value
Assemblies_TrueShapeCellSize: 0.2
Assemblies_TrueShapeCellSizeUnits: English
Assemblies_TrueShapeGenerate: Yes
2. Set the following NX customer default for DirectModel dataset (JT file)
generation:
Control Value
Assemblies_ModelReferenceSet: SOLID
3. Set the following NX customer defaults to ensure large assemblies load without
problems:
Control Value
NXMGR_StructureUpdateOnLoad: Off
NXMGR_StructureUpdateOnSave: 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.email.address=admin@mycompany.com enter address of
users to be emailed on errors
b. Create a file named .appr_update_info under tcdata containing the

following entries:
-u=infodba
-p=infodba
-g=dba

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 Preference setting

Do you check TC_allow_appr_checking=true
appearances?
Do you audit the querying TC_allow_appr_query_auditing=true
of appearances?
How often (in hours) do TC_appr_checking_interval=10
you check appearances?
Do you allow the querying TC_prevent_appr_query_on_corrupt_root=true
of appearances associated
with a corrupt appearance
root?


To ensure JT files display JT_File_Priority_Refsets=
correctly.
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]


JT_File_OverrideChildren_Refsets=
• SIMPLE
• MONOLITHIC
To allow users to edit WSOM_only_edit_effectivity_in_ecm=yes
effectivity outside change
management.
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:

6. Start the console by entering:

%TC_BIN%\appr_update_console

Chapter
3 Running the Update Manager
Running the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Update Manager processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Working with Update Manager packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Primary package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Secondary package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Primary queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Secondary queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Updating working appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Understanding update package states . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Understanding update package types . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Understanding checker packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Update package information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Processing structure changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Configuring the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8

Setting preferences in the .appr_update_env file . . . . . . . . . . . . . . . . . . . 3-8
Setting supervisor preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Setting the updater preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Setting the updater controller preferences . . . . . . . . . . . . . . . . . . . . . . . . 3-10
Setting retry preferences for Update Manager failures . . . . . . . . . . . . . . . 3-11
Setting administrator preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Configuring the .appr_update_info file . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
Start the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Stop and restart the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Running the Update Manager utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14

Using the console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Option 1 – Query general status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Option 2 – Query specific update package . . . . . . . . . . . . . . . . . . . . . 3-16
Option 3 – Show specific update package . . . . . . . . . . . . . . . . . . . . . . 3-16
Option 4 – Show primary queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Option 5 – Show secondary queue . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Option 6 – Log system status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17
Option 7 – Query log file name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Option 8 – Change logging level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Option 9 – Clear log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Option r – Restart update manager . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Option R – Restart update manager now . . . . . . . . . . . . . . . . . . . . . . 3-18

Option s – Shutdown update manager . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Option S – Shutdown update manager now . . . . . . . . . . . . . . . . . . . . 3-18
Option 0 – Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Information in the supervisor log file . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
Run the find_appearances utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
Appearance root arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
Configuration arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21
Appearance filtering arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21
Output arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21
Action arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Run the appearance_updater utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
appearance_updater utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23

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 Splitting a primary update package into secondary update packages, one per
appearance set.
o 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

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.

• 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)

• 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 e-mail 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.

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.

TC Database
(Appearance Queues & Package +
Appearance Cache)
Primary
Packages
There is only one
primary and secondary Primary Queue
appr_update_manager queue in the database.
Update Manager (script that runs Supervisor) The primary queue Prim. Package 1
Mark primary package has only one active
as processed processing package State = Processed
Ordered
and associated
9 secondary packages.
Updater Process
(controller) 4 Prim. Package 2
appearance-updater Query primary State = Processing

queue and fetch
primary package
Prim. Package 3
3
State = Unprocessed
Message to
request
next primary
5b Secondary
package 5b Packages
Updates report
Describe success/failure
secondary to Supervisor Secondary
queue to 5b Queue
supervisor 8 Updater
Process 7 Sec. Package 1 Appr Root 1
Spawn
updaters (A100/C, A500/C) (RB-X1000)
Supervisor Process
appr_update_supervisor 6 Simultaneous
updates
7 Sec. Package 2 Appr Root 2
(A500/C) (RB-Y500)
Updater
7
8 Process
Appearance
7 Appr. Set 2 - Appearances Cache
Inform supervisor that A600 P33 (*)
new primary package 2b Create primary
has been placed package and A500
on primary queue. place on Appr. Set 1 - Appearances
primary queue 2a A100 P10 (-) P33 (+) P11 (*)
Client 1 TC
Release changes
Process
Workflow & add status
APPR_update_from_targets_AH
Targets
Appearance Update Manager
A100C System Flow
A600C
Sequence of events following structure change

The following figure shows the structure changes that triggered these events.

Structure changes
The sequence of events is as follows:
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-Y500.
6. 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.

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.

Module Preferences control

Updaters • Updater logon.
• Communications port.
• Maximum number of updaters.
Updater controller • Time-outs.
Administrator • Who receives e-mail 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 Preference and settings

Where is the supervisor run? (Mandatory) supervisor.host = hostname or
IP-address
How does the supervisor You can run the supervisor in one of three modes:
find new update packages on
the queue? • 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.

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.

How do updaters begin to Mandatory. updater.login
log into the Teamcenter
database? 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.
How many updaters updater.max
(including the controller)
can the supervisor support? 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.


How many updates can you controller.limit.updates
perform before restarting the
controller? 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.
How long (in seconds) does an controller.idle.timeout
idle system maintain a running
controller? 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 Preference
How many times can a specific controller fail controller.restart.failures
to process a specific primary update package
before the system terminates the controller
and tries another one?
How many times can Teamcenter fail to controller.limit.failures
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 updater.limit.failures
secondary update package before Teamcenter
gives a fatal error?
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.

Function Preference
Who should be e-mailed in the event of admin.email.address =
a serious error? You can enter multiple admin@mycompany.com
administrative address, separating entries
with a semicolon as separator.
Which SMTP server should Teamcenter use to admin.email.server =
send this e-mail? Leave this entry commented smtp_server.mycompany.com
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 e-mail through an SMTP server
on the local machine.
How much e-mail should the administrator admin.email.level = 3
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 admin.logging = 2
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 admin.log.size = 100000
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.
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).

• 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:
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.

• 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 appr_update_manager
o appr_update_supervisor
o 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:
appr_update_console -u=infodba -p=password -g=dba - shutdown
Warning 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

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 = 82150
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 Meaning
offline The updater is not doing anything. This state is
used internally by updaters.

Value Meaning
pre-initializing An updater has started, has connected to the
supervisor, and is allocated a slot in the supervisor’s
updater list.
initializing The updater is logging on.
idle The supervisor or updater are not doing anything
idle, after success The updater has successfully completed its task.
idle, after failure The updater has failed its task doing secondary
packages.
performing another The updater is retrying a previously failed
update secondary package.
querying database The controller is checking the queues.
processing primary queue The controller is processing a primary package.
entry
stopping The updater is shutting down.
recycling The updater is shutting down, but will restart.
emailng The updater is sending an e-mail.
clearing locks The controller is running the clearlocks command.
waiting for controller to The supervisor is waiting for the controller to start
start up. The nextState box tells you what the supervisor
will do it after is started.
waiting for controller to The supervisor is waiting for the controller to log
login in. The nextState box tells you what the supervisor
will do after it is started.
waiting for controller to The supervisor is waiting for the controller to stop.
stop It will then start a new controller. The nextState
box tells you what the new controller will do after
it is started.
unused 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 2004-02-19 17: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-2004 17:24:32, (no run date), processing (1), blocked
Release Status: (00000e0b = BoBBzo1WgvaiJD) Released on 19-Feb-2004 17:24:32

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-2003 17:30:57, (no run date), unprocessed (0), unblocked
Release Status: (00000b36 = AC141bxBgvaiJD)
Released on 28-Feb-2003 17:30:57 by ’your name’
0 Effectivities
0 filtered-by AppearanceRoot(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-2003 17: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-2003 17: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:57 2002
Launched (but not connected) updaters: 0
Last updater launch: Wed Sep 25 16:14:36 2002
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 29550 connected from sdlsol10.cbr.ugs.com on fd
6 is currently idle (controller)

7 is currently idle (appearance updater 1

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.

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:53 2003
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
Email level: 3
Email address: jimi;neil;mark
Email charset: ISO-8859-1
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:31 2002] Validating updater
"/pim/sites/v81/sol/bin/appearance_updater -validate"
[Wed Sep 25 13:03:34 2002] Updater validated
[Wed Sep 25 13:03:34 2002] Supervisor ready listening for clients on port 1700...
[Wed Sep 25 13:03:34 2002] Supervisor ready listening for updaters on port 1710...
[Wed Sep 25 13:03:34 2002] Spawning controller, before entering state ’querying database’
[Wed Sep 25 13:03:34 2002] Spawning updater "/pim/sites/v81/sol/bin/appearance_updater
-supervisor=sdlsol10,1710,1700"
[Wed Sep 25 13:03:37 2002] Local connection from sdlsol10.cbr.ugs.com [134.244.154.103]
[Wed Sep 25 13:03:37 2002] Connection from Updater at sdlsol10.cbr.ugs.com on fd 6 accepted
[Wed Sep 25 13:03:37 2002] Message connectRequestMsg received from uninitialized
Updater on fd 6, current system state: waiting for controller to start
[Wed Sep 25 13:03:37 2002] Updater at sdlsol10.cbr.ugs.com on fd 6 has been accepted
[Wed Sep 25 13:03:37 2002] Updater at sdlsol10.cbr.ugs.com on fd 6 nominated as Controller
[Wed Sep 25 13:03:37 2002] Message updaterStatusMsg received from Updater on fd 6,
current system state: waiting for controller to start
[Wed Sep 25 13:03:37 2002] Updater on fd 6 has status: initializing
current system state: waiting for controller to login
[Wed Sep 25 13:03:50 2002] Updater on fd 6 has status: idle
[Wed Sep 25 13:03:50 2002] Querying state of queues
current system state: querying database
[Wed Sep 25 13:03:50 2002] Updater on fd 6 has status: querying database
[Wed Sep 25 13:03:50 2002] Message generalReplyMsg received from Updater on fd 6,
current system state: querying database
[Wed Sep 25 13:03:50 2002] Recycling controller from queryingState
[Wed Sep 25 13:04:39 2002] General Query result:
knownUpdateRequests = 1
apprSetsInUpdate = 0

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:35 2002] Controller has failed to process primary queue entry
Error 82018 : "Appearance code currently disabled (either by licensing, or by preference)."
ADVICE: Check log files for updater process 29550 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 Description
[-item_id=item_id ] Find appearances for the appearance roots
tracking the specified item.
[-config_rule=config-rule ] Find appearances for the appearance roots
tracking against the specified configuration
rule.
[-view_type=view-type ] Find appearances for the appearance roots
tracking against the specified view type.
[-root_only] List only the appearance roots not the
appearances.

Configuration arguments
[-date=date|now|today] Configured at the specified date, where:
• date format is: yyyy MM dd hh mm ss.
• now means right now.
• today means midnight first thing this

morning.
[-unit_no=unit-no] Configured for the specified unit number.
Appearance filtering arguments
[-component_item_id= Corresponding to the specified component
component-item-id] item.
[-query=saved-query With item or item revision satisfying the
[-query_entries=entry=value specified query, either:
[,entry=value,...] ] ]
• -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
[-list ] List the appearances in a simple list.
[-verbose ] List the appearances in an indented list.
[-print_cols=all|col[,col...] ] ] 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.

[-history ] Use with -verbose) to print appearance history.
[-attrs ] Use with -verbose) to print mapped attributes.
[-single_line ] Use with -attrs) to output mapped attributes
on same line as main appearance attributes.
[-no_transform ] Use with -attrs) but do not print the transform
matrix.
[-print_queue ] Print information about all the primary queue
entries affecting the appearance root, including
the processed entries.
[-timing ] Print timing information.
Action arguments
[-validate] 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 ] Check each appearance for duplication.
[-queue_check] 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=AP3-000 -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-2003 13:13:45,
with 39 appearances)), ok at 2003-02-25 13:13:29
n_appearances = 39
Appearance Component Item (View) In Unit Out Unit
--> wsw41aMEgvaiJD AP3-000-AP3-Product (view) 1 2147483647
--> w8z41qQfgvaiJD AP3-1000-Main Module (NMA) (view) 1 2147483647
--> AJy41qQfgvaiJD AP3-2000-Valve Module (NMA) (view) 1 2147483647
--> AR841qQfgvaiJD AP3-900-Gate Valve, J Series (view) 1 2147483647
--> Qt_41qQfgvaiJD AP3-815-Stud 1 2147483647
--> Qpw41qQfgvaiJD AP3-815-Stud 1 2147483647
--> Qp$41qQfgvaiJD AP3-815-Stud 1 2147483647
--> Qlx41qQfgvaiJD AP3-815-Stud 1 2147483647
--> A9741qQfgvaiJD AP3-812-Nut 1 10
--> A9741qQfgvaiJD AP3-813-New Nut 10 2147483647
--> gh741qQfgvaiJD AP3-300-Bonnet Assy (NMA) (view) 1 2147483647
--> g1$41qQfgvaiJD AP3-378-Flange 1 2147483647
--> g9241qQfgvaiJD AP3-361-Stem (1) 1 20
--> g9241qQfgvaiJD AP3-362-Stem (2) 20 2147483647
--> wNy41qQfgvaiJD AP3-400-Seal Assy (view) 1 2147483647

--> wl741qQfgvaiJD AP3-414-V-Ring, Corrosive 1 2147483647

--> wl_41qQfgvaiJD AP3-422-Lip Seal, High 1 2147483647
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-2003 13:13:36,
n_appearances = 39
--> wo_41a7rgvaiJD AP3-000-AP3-Product (view) 1 2147483647
--> AFz41qQbgvaiJD AP3-1000-Main Module (NMA) (view) NULL NULL
--> AR941qQbgvaiJD AP3-2000-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=AP3-000 -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-2003 17:02:16,
n_appearances = 39
--> wsw41aMEgvaiJD AP3-000-AP3-Product (view) 1 2147483647
--> w4941qR5gvaiJD AP3-1000-Main Module (NMA) (view) 1 2147483647
ATA2="10", ATA5="001", ATA3="10", ATA4="10", ATA1="10"
--> AF841qR5gvaiJD AP3-2000-Valve Module (NMA) (view) 1 2147483647
--> AR241qR5gvaiJD AP3-900-Gate Valve, J Series (view) 1 2147483647
--> Qt441qR5gvaiJD AP3-815-Stud 1 2147483647
--> Ql641qR5gvaiJD AP3-815-Stud 1 2147483647
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:

appearance_updater -h
Note You can also execute several of these commands directly from the console.
Usage: [ ( -u=user -p=password-g=group ) | -login=type ] [
appearance_updater -quiet ] [ -nolog ] [ -supervisor=host,port1,port2
] [ -task=cmd[,cmd...] ]
-login 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.
-validate Starts the updater, then terminates with return code
99.
-quiet Do not write messages to stdout.
-nolog Do not write messages to the log file.
-supervisor Identifies that the supervisor provides tasks.
-task 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

Processes the next primary queue entry. This

command fails if the secondary queue is not
empty.
o finish_primary
Checks for primary completion and, if
complete, marks it as Done.
o process_secondary
Processes updates for a single appearance set
in the secondary queue.
o process_all_secondary
Processes updates for every unlocked
appearance set.
o 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:
-show_uids Include tag and UID information, which is
not displayed by default.
-show_blocked Include information about blocked packages
as well as unblocked packages.
-since="yyyy MM dd hh mm ss" Include information about all packages since
the specified date, whether unprocessed or
processed.
-item_id=item-id Show only those packages relevant to the
release of any revision of the specified item.
Only available if you also specify the -since=
argument.

Chapter
4 Using the Appearance

Configuration application
Using the Appearance Configuration application . . . . . . . . . . . . . . . . . . . . . . 4-1
Add a new revision rule (column) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Add a new root item (row) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Find set contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Set flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Create an appearance attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Map an occurrence note to appearance attributes . . . . . . . . . . . . . . . . . . . 4-3
Define how appearance sets are tracked . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Destroy an appearance set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Stop tracking an appearance set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4

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.

Chapter 4 Using the Appearance Configuration application
Option Entry
Item ID Enter the item ID.
Name Entered automatically.
View Type 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.

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

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.

Chapter
5 Creating and updating

appearances
Creating and updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Creating a bootstrap appearance set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Create a baseline appearance set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Create an appearance root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Checking system operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Check the Update Manager is running . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Check the state of the queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Check the appearance set is created . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Releasing the product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

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.

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.

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 = 82150
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

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.

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 e-mail.
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.

Chapter
6 Solving problems
Solving problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Locating appearance sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
General usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Configuration and setup questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Detecting and repairing inconsistencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

Detecting inconsistencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Validating appearances automatically . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Preventing searches of an inconsistent appearance root . . . . . . . . . . . . . . 6-7
Interpreting appearance root attributes . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Validating appearances manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Repairing inconsistencies with the fix_appearances utility . . . . . . . . . . . . 6-8
Using diagnostic tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9

Log and configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Log file appr_update_supervisor.log . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Locating the log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Example of supervisor log file header . . . . . . . . . . . . . . . . . . . . . . 6-10
Example of supervisor log file with error . . . . . . . . . . . . . . . . . . . 6-11
Associated appearance_updater syslog . . . . . . . . . . . . . . . . . . . . . 6-11
Identifying the Workflow process or item revisions that failed to update
the appearance cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Log file appearance_updater.syslog . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Configuration file .appr_update_env . . . . . . . . . . . . . . . . . . . . . . . . . 6-13
Examples of e-mails sent if an Update Manager error occurs . . . . . 6-14
Configuration file .appr_update_info . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
find_appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15
appearance_updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16
Starting and stopping the Update Manager . . . . . . . . . . . . . . . . . . . . 6-16
Checking the Update Manager environment . . . . . . . . . . . . . . . . . . . 6-16
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
License problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Appearance bootstrap problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Checking the terminal from which the supervisor process is running . . 6-17
Perform an appearances search with the find_appearances utility . . . . 6-17
Delete an appearance set and restart . . . . . . . . . . . . . . . . . . . . . . . . 6-18
Bootstrap appearance set does not create . . . . . . . . . . . . . . . . . . . . . . 6-18
Appearances not created in mixed mode configuration . . . . . . . . . . . . 6-19

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

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 Answer
When I create a baseline The revisions are configured by the revision rule
appearance set, which revision associated with the appearance root.
of the top-level item is used?
What revision rule is used for
configuring the other items in
the assembly?
How does a nonadministrative Use the Appearance Configuration application
user find out what appearance described in Using the Appearance Configuration
sets are available? 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.

Chapter 6 Solving problems
Question Answer
For a given item, how does a Use the Appearance Configuration application
nonadministrative user find out described in Using the Appearance Configuration
the revision rules that have application. The column headers for the table in
corresponding appearance sets? 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.
How can I identify the In Structure Manager, add the bl_appearance
appearance set to which a and bl_appearance_path property columns,
particular line in the product as described in the Structure Manager Guide.
structure belongs? 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 Answer
After I release a change, how You can achieve this indirectly by running
do I know when the applicable appearance_updater -task=dump_primary
appearance sets are updated to and looking for the IDs of item that are released.
incorporate my newly released If none are present, the package has been
change? processed, and the appearances should be
updated.
How can I identify the Use the appearance_updater -task=
appearance sets affected by dump_primary,dump_secondary
my change? -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.
What do I do if I suspect that an Run the fix_appearances utility. For
appearance set is damaged? details, see Repairing inconsistencies with the
fix_appearances utility.
How can I delete an appearance Use the Appearance Configuration application
set? 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.
How can I tell if an update The administrator receives an e-mail. You can
package failed? also check for errors in the supervisor log file.

Solving problems
Question Answer
How can I tell which update Run the appearance_updater
packages are waiting to be -task=dump_primary command.
processed?
How can I tell which update Run the appearance_updater
packages have already been -dump_primary -since=’yyyy MM dd hh
processed? mm ss’ command.
How can I determine what Run the appearance_updater
user event triggered an update -task=dump_primary,dump_secondary
package and who initiated it? 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.
How can I find out the size The find_appearances utility lists the number
(number of appearances or of appearances for each appearance root. The
bytes) in an appearance set? 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.
How can I tell if the Update Run the console by entering
Manager is running? 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.
How can I determine the Check
resources (memory or CPU) $TC_TMP_DIR/appearance_updater*.* files.
consumed by a particular You may need to modify your Teamcenter
update package? journaling settings.
What kind of sanity checkers The find_appearances -verbose command
are available? How do I enable with date or unit number arguments prints a
them? How do I interpret the structure it deduces from the appearances. This
results? 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.

Question Answer
Can I have more than one Running more than one Update Manager against
Update Manager running on the a single database may corrupt the appearance
same machine or on different cache. However, you can have multiple Update
machine? 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.
Are there limitations on where No.
the Update Manager can be
run?
What access privileges are Always run the Update Manager as a member
required by the Update of the dba group to allow spatial data to be
Manager and by the updater updated properly.
itself?
What log files are created? The Update Manager supervisor prints a
If any are optional, how do I log file ($TC_TMP_DIR/appr_update_
turn them on? Where are the supervisor*.log). The level of reporting
log files stored? What useful is controlled by the admin.logging setting
information can I find in them? 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.

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 For the date the audit record was last updated,

Last_worthiness_update_date – a date.
o 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

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 TC_aqa_date_range specifies the number of days in the range. Must
always be an integer. Default value is 3.
o 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.

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 e-mail 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 0 = OK.
o 1 = Adjusting after item revision import (for Multi-Site Collaboration

appearances).
o 2 = Being fixed by the fix_appearances utility.
o 3 = Unprocessable (processing of some package failing consistently).
o 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.

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.

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:

Log file appr_update_supervisor.log

Use the appr_update_supervisor_nnnn.log log file as the initial point of entry
when diagnosing problems. Teamcenter creates one of these log files each time the
supervisor is started. The log file contains a cumulative record of all the events that
the Update Manager supervisor has processed. Any errors are also listed in this file,
although specific details are given in the appropriate appearance_updater.syslog
file.
The start of the file contains the parameters set in the .appr_update_env
configuration file, as described in Configuring the Update Manager.
Locating the log file

Use the console to locate the appr_update_supervisor.log file by entering:
7 – Query log file name
This option gives you the path and the machine name, as the Update Manager
may be running on a different machine. This is typically in the $TC_TMP_DIR
preference in the .appr_update_env configuration file.
This log file tells you if any appearance_ updater process has failed. If you set
the admin.logging level to 2, the supervisor writes every action it takes in the log
file with a time stamp. You can then search for Error or ADVICE to see if there
is a problem.
If the problem occurred in an appearance_updater process, rather than the
supervisor process, the error report is usually followed by an ADVICE line. You can
then check the specific appearance_updater_nnnn.syslog, and the machine it is
on (typically $TC_TMP_DIR directory on the machine on which the supervisor is
running).
Example of supervisor log file header

The header of the supervisor log file contains a useful dump of settings in the
.appr_update_env configuration file, as shown in the following example. It also
lists some other key data and Teamcenter environment variables.
General configuration information

Appearance Update Supervisor
Log opened: Wed Apr 2 10:44:53 2008
System Configuration
Program: /pim/sites/v2008/hpp/bin/appr_update_supervisor
Process id: 1651
Host: sdlhpp2
Config File: /pim/sites/v2008/hpp/tcdata/.appr_update_env
Preferences set in .appr_update_env config file

TC
TC_DB_CONNECT: infodba:tbwiabd@v2008
TC_ROOT: /pim/sites/v2008/hpp
TC_DATA: /pim/sites/v2008/hpp/tcdata
TC_BIN: /pim/sites/v2008/hpp/bin
TC_TMP_DIR: <undefined>
Admin
· Logging level: 2
· Log file size limit: unlimited
· Email level: 3
· Email address: jimi;neil;mark
· Email charset: ISO-8859-1
· SMTP server: camntx
Supervisor
· Polling period: undefined

Solving problems
· 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/v2008/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
Example of supervisor log file with error

File name: appr_update_supervisor4622.log
[Thu Nov 27 18:52:17 2007] Secondary failure #9 of current primary update
(retry limit = 10)
[Thu Nov 27 18:52:17 2008] Starting new updater
[Thu Nov 27 18:52:18 2008] Spawning updater "C:\Teamcenter8\bin\appearance_updater
-supervisor=CBRLTPC6,1712,1701 -login=1"
[Thu Nov 27 18:52:18 2008] Updater 3372 at CBRLTPC6 on fd 576 has been accepted
[Thu Nov 27 18:52:19 2008] Updater 3468 at CBRLTPC6 on fd 568 reports syslog as
C:\DOCUME~1\JIMD\LOCALS~1\Temp\appearance_updater93540c20.syslog
[Thu Nov 27 18:52:19 2008] Updater 3468 at CBRLTPC6 on fd 568 has selected
secondary package Atw8sRnagvaiJD [ApprUpdByApprRootRevPkg]
Log files: C:\DOCUME~1\JIMD\LOCALS~1\Temp\appearance_updater93540c20.syslog, .log, and .jnl
[Thu Nov 27 18:52:21 2008] Updater 3372 at CBRLTPC6 on fd 576 reports syslog as
C:\DOCUME~1\JIMD\LOCALS~1\Temp\appearance_updater94f84640.syslog
[Thu Nov 27 18:52:22 2008] Updater 3372 at CBRLTPC6 on fd 576 has selected secondary
package Aty8sRnagvaiJD [ApprUpdByApprRootRevPkg]
Log files: C:\DOCUME~1\JIMD\LOCALS~1\Temp\appearance_updater94f84640.syslog, .log, and .jnl
[Thu Nov 27 18:52:24 2007] Updater 3468 at CBRLTPC6 on fd 568 failed during secondary
update Atw8sRnagvaiJD [ApprUpdByApprRootRevPkg]
[Thu Nov 27 18:52:24 2008] Error 82032 : "An Appearance callback function failed:"
ADVICE: Check log files for updater process 3468 on CBRLTPC6
Log files: C:\DOCUME~1\JIMD\LOCALS~1\Temp\appearance_updater93540c20.syslog, .log, and .jnl
Associated appearance_updater syslog

This log tells you the error that is causing the problem. In the following example,
Teamcenter is failing to create the bootstrap package, as the named references
for spatial data cannot be attached to the dataset. The most likely cause of this
problem is that the appearance_update process does not have write access to the
Spatial_data dataset. Alternatively, there may a be problem with unit selection
(metric or English).
UNDO error catcher caught something
***** Error was in UNDO handler set by routine appearance_updater! 00000000 *******
>>>> Calling ERROR_longjump to go to "UNDO_could_i_go_to_markpoint"
errno=2
*** ERROR code 904 in line 135 of d:\nx2qrm\sandbox\src\syss\sm\ind\sm_init.c
at Thu Nov 27 18:51:51 2008 GMT Standard Time
+++ Attempt to free already free block at &03051940
[ 1] 77E989D1 RaiseException +0x37 (KERNEL32)
[ 2] 20FB15FA ERROR_trace_back +0x8a (libsyss)
[ 3] 20FAE7F1 ERROR_ask_signal_handler +0x71 (libsyss)
[ 4] 20FAF78D ERROR_vraise +0x4d (libsyss)
[ 5] 20FAF9BC ERROR_raise +0x1c (libsyss)
[ 6] 2103825D SM_ask_top_allocators +0x2dd (libsyss)
[ 7] 2103701D SM_free_in_area +0x5d (libsyss)
[ 8] 210373BE SM_free +0xe (libsyss)
[ 9] 2104FB56 UNDO_sure_to_go_to_markpoint +0x3b6 (libsyss)
[10] 21051361 UNDO_could_i_go_to_markpoint +0x191 (libsyss)
[11] 21051466 UNDO_to_markpoint +0x16 (libsyss)
[12] 10092AE1 DMS_loaded_object_of_tag +0x37ab (libpom)
[13] 10107122 POM_roll_to_markpoint +0x188 (libpom)
[14] 002F0248 AppearanceRoot::doBootStrap +0x140 (libappr)
[15] 0035205A ApprUpdByApprRootRevPkg::execute +0x59e (libappr)
[16] 004060DB (appearance_updater)

[17] 00405D06 (appearance_updater)

[18] 004021FE (appearance_updater)
[19] 00401DFA (appearance_updater)
[20] 004013F4 (appearance_updater)
[21] 00409A71 (appearance_updater)
[22] 77E8D326 CreateProcessW +0x900 (KERNEL32)
UNDO error catcher caught something
***** Error was in UNDO handler set by routine appearance_updater! 00000000 *******
>>>> Calling ERROR_longjump to go to "UNDO_could_i_go_to_markpoint"
--------------------------------------------------------------------------------
Updater error stack:
9160: Cannot insert dataset named reference, dataset
Another Top Level_Appearance Te, type Spatial_Data, reference Index_File
9161: Cannot replace dataset named reference Another Top Level_Appearance Te
85210: error_85210
85228: error_85228
82032: An Appearance callback function failed:
Updater call stack:
[ 1] 77E989D1 RaiseException +0x37 (KERNEL32)
[ 2] 20FB15FA ERROR_trace_back +0x8a (libsyss)
[ 3] 0040331C (appearance_updater)
[ 4] 0040621D (appearance_updater)
[ 5] 00405D06 (appearance_updater)
[ 6] 004021FE (appearance_updater)
[ 7] 00401DFA (appearance_updater)
[ 8] 004013F4 (appearance_updater)
[ 9] 00409A71 (appearance_updater)
[10] 77E8D326 CreateProcessW +0x900 (KERNEL32)
----------------------------------------------------------
Identifying the Workflow process or item revisions that failed to update the
appearance cache
The appearance_updater system log identifies the failure, but not the job and
associated item revisions that failed to update.
If there is an error, it is likely the supervisor was unable to complete processing of
a secondary package—the package that actually updates the appearance cache.
Hence, the associated parent primary package will be in an unprocessed state.
You can use the console to identify the currently processing package by entering:
4 – Show primary queue
This option displays information about the current primary package, which lists
details of the item revisions, who submitted the workflow, and so on. The example
below shows a regular update (changed revisions package) of a single target
assembly SD1-A300 rev D.
[0] (AO941bxBgvaiJD) ApprUpdChangedRevsPkg:
queued on 28-Feb-2008 17:30:57, (no run date), unprocessed (0), unblocked
Release Status: (00000b36 = AC141bxBgvaiJD) Released on 28-Feb-2008 17:30:57
by jimd (Jim Doe)
0 Effectivities
0 filtered-by AppearanceRoot(s)
(00000b37 = gm64lHmRgvaiJD) SD1-A300/D-Spatial - Second level assy
owned by jimd (Jim Doe)
Log file appearance_updater.syslog

Teamcenter creates a appearance_updater_nnnn.syslog file for each
appearance_updater process that runs. You can set the level of Teamcenter error
reporting and journaling in the shell from which the Update Manager script runs
with the following entries:
set TC_Journalling=ON
set TC_Journal_Modules=ALL
You may also want to set the following journaling options:

• set TC_JOURNAL=OFF/SUMMARY/FULL (OFF=no journal,
SUMMARY=writes summary at the end of the file, FULL=all known journaling

Solving problems
• set TC_TRACEBACK=ON (always on)
• set TC_SQL_DEBUG=BJTP (T=Timing, P=Profile);
• set TC_KEEP_SYSTEM_LOG=Y (keeps log files)

Note If there are no errors in the appearance_updater log, Teamcenter deletes
the system logs unless you set the TC_KEEP_SYSTEM_LOG environment
variable to Y.
You can also set these options in the tc_profilevars file.
The appearance_updater system log file tells you how the updater failed for the
particular package.
Having located and opened the relevant updater system log, you must interpret its
content. Two examples of common problems are:
• POM_inst_in_use by user X on node Y in a session started at Z
If X is the same user that is running the Update Manager (for example,
infodba), you may be running more than one Update Manager.
If X is another user, they may have an unnecessary rich client session running
that is holding a lock on the appearance root. Close unnecessary sessions and, if
necessary, run the clearlocks command.
Warning Do not run more than one Update Manager as this may cause
problems.
• Appearance validation failed

There is an inconsistency in your appearances. This error is usually accompanied
by instructions on how to use the fix_appearances utility to resolve the
problem.
Configuration file .appr_update_env

This configuration file lists the main parameters that configure the Update Manager
and appearance_updater processes. The most important parameters are:
• supervisor.host specifies the machine that the Update Manager supervisor and
the appearance_updater processes it spawns are running on.
• admin.logging = 2 sets full Update Manager logging.
• admin.email.address = admin@mycompany.com identifies one or more users

e-mailed when problems are reported.
Warning If you try to run the Update Manager on a machine that is not defined
in this configuration file, the client does not connect to the supervisor
correctly.
To make parameter changes effective, stop and restart the Update Manager by
entering the following console command:
r. Restart update manager

Check the header section in the appr_update_supervisor.log log file to ensure the
new parameters are effective.
If there are still problems, check that all Update Manager processes are stopped:
• Supervisor (appr_update_supervisor)
• Updater (appearance_updater)
• Manager (appr_update_manager)
For details of additional parameters, see Configuring the Update Manager.
Examples of e-mails sent if an Update Manager error occurs

Each e-mail lists the machine the Update Manager is running on and the
appr_update_supervisor log file to check for more details.
• Update Manager (Supervisor) is not running, must be started
The appearance update handler has failed to
contact the appearance update manager.
Can you check the appearance update manager please?
Update Manager host: sdlsol10, port: 1700
Error stack:-
82150: Socket error "Connection refused" while communicating with Appearances Update Manager
• Access problem
Access problem may occur if the user does not have read or write objects to
the necessary objects.
Appearance Update Manager has terminated due to:-
FATAL ERROR: Primary update retry limit reached
Updater error 515001: "Access denied"
Host: CBRLTPC6
Log file: C:\DOCUME~1\JIMD\LOCALS~1\Temp\\appr_update_supervisor.exe5348.log
• Locking problem
Fatal error in Appearance Update Manager [AUTOMATIC EMAIL]
Appearance Update Manager has terminated due to:-
FATAL ERROR: Primary update retry limit reached
Updater error 515109: "Instance in use"
Host: sdlsol10
Log file: /tmp//appr_update_supervisor12030.log
• Appearance inconsistency problem

Executing update package generated the following error(s):
Appearance validation failed
(COMPARE FAILED on appearance uid AJ203dlGgvaiJD because the BOM line
and I have a different number of children)
for root "Hugh (view) App Test - Unit No - A10000 (without spatial data)
(with 36 appearances)",
configured by date "05-Sep-2005 15:31:34" and unit-no "-".
You may wish to run
fix_appearances -item_id="A10000" -view="view" -config_rule="App Test -
Unit No - 150
Configuration file .appr_update_info

This file configures the Teamcenter user as which the appearance_updater process
is running. This user must be a member of a system administration dba group. This
user must have read/write access to the necessary data including:
• Revision rule used on the appearance root (read access).

Solving problems
• Items and BOM view revisions (read access).
• Spatial_Data dataset (read and write access). Use an Access Manager rule to
give system administrators write access to this dataset.
Utilities
Use the following utilities to obtain more information about the appearances system.
For a full description of these utilities, see Running the Update Manager utilities.
Console
Use the following console options to check the update packages and the state of
the queues.
• Query general status
Shows the state, typically idle or performing update. You can also check the
primary queue size and check the size of the backlog.
• Show primary queue

Provides details of the currently processing package including package type
(for example, changed revisions), the item revisions being released and who
submitted the workflow.
• Restart update manager

Allows a system administrator to restart the Update Manager supervisor.
find_appearances
The find_appearances utility allows you to query the database for information
about appearances themselves. This action creates a new appr_update_supervisor
log. For information about the packages and queues, use the controller or the
appearance_updater utility.
You can specify arguments to restrict the search, for example:
• Set a specific appearance by item ID for the appearance root or context (revision
rule).
• Set a date or unit number for the search, for example:

• Search for the appearance of a specific part (component) by item ID or other

attributes, for example:
find_appearances -component_item_id=AP3-P10
• Configure the output to print different attributes, for example, effectivity values:
find_appearances -item_id=AP3-000 -verbose -print_cols=comp,unit_nos
-verbose -print_cols=comp,unit_nos -attrs -no_transform (-single_line)
• Find help:
find_appearances -h

The find_appearances utility also provides information about appearances for

precise structures in the following columns:
• Precise
For any appearance, this may contain Precise or - (imprecise) to indicate
appearance precision.
• Component Item Rev.

Contains the revision and item ID of the component item revision if precise,
or - if imprecise.
To display these columns, use the -print_cols switch and enter the precise option.
appearance_updater
The appearance_updater utility allows you to run the updater manually and
perform any of the following tasks:
• Query the database
This option gives a more complete query of the state of the packages and queues
than the console.
• Perform updates
Normally, the Update Manager performs this task under the control of the
supervisor and you should only initiate it manually if there is a problem with
the Update Manager.
Starting and stopping the Update Manager

To stop the Update Manager, enter the following console option:
s – Shutdown update manager
To restart the Update Manager, enter the following console command:
$TC_BIN/appr_update_manager
Warning Ensure you run only one central Update Manager. Do not run local
Update Managers (on two-tier or four-tier installations), as this may
cause locking problems.
To stop or start the Update Manager, you must be logged on as the
Teamcenter infodba user, not the operating system user with the same
name.
Checking the Update Manager environment

To check the Update Manager parameters, view the
appr_update_supervisor.exexxxx.log file, where xxxx is the relevant process
identifier.
To verify environment variables, check the shell in which the supervisor process is
running. This may provide information about user exits.

Solving problems
To check Update Manager preferences (for example, for audit packages), check the
preferences in the .appr_update_env file.
Troubleshooting
If you encounter errors or other problems, perform the relevant checks to identify
the cause.
License problems
If you cannot see the Structure Manager Search button or Appearance Configuration
application, ensure that you have installed the required Context Management
licenses. If you do not have a server license, the Structure Manager search button
is not displayed and you cannot see the Appearance Configuration application. If
you do not have a client license, you cannot perform a search. For information about
license requirements, contact your Siemens PLM Software representative.
Appearance bootstrap problems

If you suspect appearance bootstrap problems, confirm that appearances are being
created in one of the following ways:
• Check the terminal from which the supervisor process is running.
• Perform an appearances search with the find_appearances utility.
• Delete an appearance set and restart.
Checking the terminal from which the supervisor process is running
You should see the following output:

processing_appearance 0001
Note These messages are only generated during spatial updates, not when
nonspatial data is updated.
Perform an appearances search with the find_appearances utility
The find_appearances utility provides a count of how many appearances are

created. When you create the initial appearance set in a bootstrap, this number is
the same as the total number of BOM lines in the completely expanded structure.
Enter the following command:
find_appearances -item_id=Root-Item-ID
If there is only one appearance, the appearance root is created but not the
appearances.

Note When you create a very large appearance set, the appearances are not saved
in the database, until they are all created in memory. It may take 2–3
hours to create several thousand appearances. Therefore, if you use the
find_appearances utility, you do not see any results until the appearances
are saved.
Delete an appearance set and restart

It may be most convenient to destroy the problematic appearance set and start
again. Be careful not to destroy an active appearance set as they cannot be recovered
without doing a complete database recovery.
1. In the Appearance Configuration application, right-click the cell that represents
the appearance root you want to delete.
Teamcenter displays a dialog box.
2. In the dialog box, click Destroy, then click the Save button at the bottom of
the pane.
Teamcenter displays a warning that appearance data will be lost.
3. Click OK to destroy the appearance. This operation should complete quickly as

there is only one appearance to delete.
4. Check other diagnostics and logs for the possible cause of the problem.
5. Recreate the appearance set.
6. Verify that the Update Manager is running and appearances are now being
created, as described previously.
Bootstrap appearance set does not create

This problem may occur if the revision rule for the appearance set is not owned by
the dba group. The default Access Manager rules for revision rules give each user
read-only access only to the revision rules they create, that is, private revision rules;
those revision rules owned by a dba group (public revision rules) can be read by all
users. Thus, if the dba group does not own the revision rule and the Update Manager
process tries to read the revision rule to update appearances, access is denied.
If the bootstrap appearance set does not create appearances, you see no
error messages, the Structure Manager Search button is inactive and the
find_appearances utility finds only one appearance. The most likely causes are:
• The top-level item revision is not released with the status specified in the active
revision rule.
• The component item revisions at all levels are not released with the status
specified in the active revision rule.
To resolve this problem, release the top-level and all component item revisions
with the release status that matches the status in the revision rule for the
context used for the appearance set. Ensure you use a process that includes the
Appr-update-from-targets handler.
You may also see the following log entries:

Solving problems
• The supervisor log file shows a 515001 : Access denied error.
• The end of appearance_updater log file displays 2010: Read access denied
on object of class RevisionRule.
This may occur if the revision rule for the appearance set is not owned by the
dba group.
To resolve this problem:
1. Search for all objects of the RevisionRule type.
2. Make sure the user running the Update Manager (as defined in the
.appr_update_info file) can read the revision rule.
3. Change the owner to any user in the dba group or as required, according to
the access rules defined in Access Manager for revision rules.
Appearances not created in mixed mode configuration
If appearances are not created or only one top-level appearance is created with the
ERCT user exit active, you see no error messages. Potential causes are:
• The user exit is not being called.
• The user exit is not coded correctly.
• The item master attribute on which the user exit switches is not set correctly so
that a revision can not be configured.
This issue is most likely to occur if a separate release status configures unit and
release date.
For more details, see Configuring user exits.
Use print statements in the user exit to verify that it is called correctly.
Appearance update problems

If you suspect appearances are not updated correctly, check for connectivity problems
and processes that are not running.
No connection between the supervisor and appearance_updater processes
The appearance_updater processes are not sharing same .appr_update_env

configuration file as the supervisor process.
Ensure that all installations share the same .appr_update_env configuration file.
• Verify that the supervisor is running on the host specified in the
.appr_update_env file for the supervisor.
• Verify that the .appr_update_env file reported in the supervisor log file is in
the correct path.

Console is not talking to the supervisor

If the appearance_updater processes are not sharing the same .appr_update_env
configuration file as the supervisor process, you see misleading results about the
state of the queues.
Check the supervisor log file and verify the location and machine returned from the
console match. Use the Query log file name.
Supervisor is not running as the intended user (dba group member)

Check the updater.login=1 parameter in the .appr_update_env file that
determines if the user specified in the .appr_update_info file is used for logon,
rather than an automatic logon. You can also check if the logon entry in the
appr_update_supervisor.log (search for login states (for example) login=1:
Spawning updater "C:\Teamcenter8\bin\appearance_updater
-supervisor=CBRLTPC6,1712,1701 -login=1"
appearance_updater process cannot access the license file

Ensure that the SPLM_LICENSE_SERVER environment variable is set. Warnings
are displayed only in the shell and not the log file, so it may not be obvious if there
is a problem.
On UNIX machines, enter:
$ export SPLM_LICENSE_SERVER=28000@machine-name-of-FlexLMlicense-server
New revision is released, but search does not find new parts
Check if the queues in the database are empty. If so, you could be connecting
to the wrong database. Check the environment is correctly set for the
appearance_updater processes.
Update Manager is not running when setting effectivity on a release status

You may see an error message indicating the Update Manager is not running when
setting effectivity on a release status, as follows:
Socket error “No connection could be made because the target machine actively
refused it” while communicating with Appearances Update Manager.
If you start the Update Manager, it should then be possible to set the effectivity.
This error should not occur at a production site as the Update Manager typically
runs constantly.
Note This initial error is unavoidable as Teamcenter determines whether an
appearance set is affected only after the primary update package is created
and processed. There is an adverse effect on performance if this check is
made before creation.
Spatial update problems

If you suspect spatial update problems, check the necessary files are configured
correctly.

Solving problems
Verifying that spatial data files are created and accessible

Spatial data information is stored in datasets of the Spatial_Data type, and the
dataset is named top_level_item_name_revrule, such as Product X_Date Released.
There are two files (named references) in this dataset:
• Index_File (.tmpi)
• Data_File (.tmpd)
There is a Spatial_Data dataset for each appearance root (that is, each active cell in
the Appearance Configuration application) that has spatial tracking. Teamcenter
creates a new version each time the appearance set is updated. It is important to
keep the dataset version purge limit to a sensible value.
Check that a Spatial_Data dataset is created at the same time the appearance
root is created.
Check for correct write access. The dataset is owned by the Teamcenter user that
the appearance_updater process was running as when the appearance set was
initially created. Subsequent appearance_updater processes must have write
access to the Spatial_Data dataset, or the appearance update fails.
Using mixed units

Siemens PLM Software does not recommend having both metric and English
appearance sets in a single database.
Mixed mode (ERCT) not working

If a search does not find the expected parts, in particular parts below the ERCT, use
find_appearances to check the Valid In/Out values; you can also display them
in Structure Manager.
Appearances for BOM lines at two levels below the ABOVE ERCT assemblies
should have a unit validity, not NULL or date effectivity.
Search problems
If you encounter search problems, check that the necessary files are available and
that configuration was completed correctly, depending on the symptoms of the
problem.
Search for item ID returns no result

Check if you can enter an item ID directly from the Search pane, without having
to use the ... button. If not, there may be a problem with the search query
(__Item_Name_Query). This issue may particularly be encountered with upgraded
databases. This query should have one entry for search criteria:
• Attribute: item_id
• User entry name: Name
If not, edit the query with Query Builder. You can use a wildcard character (for
example, * ), and this may be the leading character.

Spatial searches not working
Check if TSO files, piece parts, UGMASTER datasets, and named references were
created correctly.
Check if a Spatial_Data dataset is created and has named references to .Index_file
and .Data_file files with correct modification dates.
Spatial search not updating
There may be issues if the spatial cache is updated while a user performs a search.
If so, close the Structure Manager session and send the top-level item to Structure
Manager again after the updater is finished working on this appearance set.
Spatial search results incorrect
This may be caused by the use of incorrect units (metric rather than English, or vice
versa) during TruShape file generation. For further information, see Configuring
NX and Lifecycle Visualization.
Note Teamcenter displays the units for the proximity search and bounding box in
the Structure Manager Spatial Search dialog box.
Spatial search takes a long time
This is may be caused by incorrect size of voxels in the TSO files. For more
information, see Configuring NX and Lifecycle Visualization. You should check:
• The size of the files in the Spatial_data dataset.
• The size set for voxels in TSO files.
• The settings in the customer defaults file.
Changes to piece part geometry not tracked

If a piece part is revised and a geometry change made, the appearance cache is not
updated unless you are using precise structures with appearances. Appearances
(and hence the spatial cache) are only updated if a component is added or removed,
or if any of the occurrence data (transforms or any mapped attributes) are changed.

Appendix
A Command reference

Appendix
A Command reference
Use the following commands to configure and manage appearances.
Action Command
Start a new Update Start %TC_BIN%\appr_update_manager
Manager
Run console appr_update_console [-u=jimd-p= -g=dba]

Find appearances • find_appearances -help
• find_appearances -item_id=AP2-900®
®number
only
• find_appearances -item_id=AP2-900 -verbose

-attrs®
®attributes
• find_appearances -item_id=AP2-900 -list

-config_rule="AP2 Appr Test - Mixed Mode"
• Attribute: is_precise. Valid values will

include:false - Classic (default, "normal"), true -
Precise
Run release_man For a folder named snapshot in the user’s Home folder:
utility
• release_man -release -status=Released
-folder=snapshot -spec -u=jimd-p= -g=dba
Journal functions These cannot always be set in tc_profilevars. Set them
in the shell from which the Update Manager script runs:
• set TC_JOURNAL=OFF/SUMMARY/FULL
(OFF=no journal, SUMMARY=writes summary at
the end of the file, FULL=all known journaling
• set TC_TRACEBACK=ON (always on)
• set TC_SQL_DEBUG=BJTP (T=Timing, P=Profile)
• set TC_KEEP_SYSTEM_LOG=Y (keeps log files)

Update working appr_working_scheduler [-u=user-id -p=password
appearances -g=group] -minutes=minutes-time-interval
-hours=hour-time-interval [-h]
PLM00021 J Appearance Configuration Guide A-1

Appendix
B Glossary

Appendix
B Glossary
appearance
Sequence of occurrences that describes a unique path through an exploded structure.
An appearance corresponds to a unique instance of the component that is referenced
by the leaf node of the path within the top-level assembly. An appearance may have
spatial data associated with it, allowing spatial searches.
appearance checker package

Primary update package that validates one or more appearance sets against the
corresponding structures configured in Structure Manager. An appearance checker
package chooses what to configure and validate based on the information generated
by the audit packages.
Appearance Configuration
Teamcenter application used to configure the use of appearance:
• Defining the appearance sets for which the site tracks appearances.
• Configuring the mapping of occurrence notes into appearance attributes.
appearance root
Object in the database containing the set of parameters that define an appearance
set: root item, configuration context, and view.
appearance set
Collection of appearances created for an appearance root and updated each time a
part is released within the root product with the appropriate release status.
audit package
Primary update package that stores information in the database about how users
are using appearances. An audit package is generated when a user performs a
search in Structure Manager. When processed, it stores information in the database
about the relevant appearance root and date and unit-number configuration.
baseline appearance set

Initial appearance set created for a product for a specified appearance root. It defines
the root item and configuration context to be tracked.
bootstrap package
Primary update package created when the baseline appearance set is created.
PLM00021 J Appearance Configuration Guide B-1

Appendix B Glossary
changed effectivity package

Primary update package resulting from a user editing effectivity.
changed revisions package

Secondary update package created when the user releases a change to the product
structure by releasing new assembly item revisions.
configuration context (Appearance Configuration)

In Appearance Configuration, a revision rule used to configure the structure.
Configuration context can contain only release status entries.
effectivity release date configuration transition

Dividing line in the product structure between unit number effectivity configuration
(above the line) and date released (below the line). Parts above the line are typically
identified by some attribute on the item master form attribute.
ERCT
See effectivity release date configuration transition.
historyless appearance set

Appearance set that does not record history. Its status differs from the status of
the production appearance set.
mapped attribute
Occurrence note mapped to an appearance attribute so that changes in the values
can be tracked.
primary queue
Queue that determines the processing order of primary update packages. The queue
is stored persistently in the database and can be queried.
primary update package

Update package that exists on the primary queue and defines a set of changes that
can apply to any number of appearance sets.
root item
Top-level item of the product. Typically this is also the end item for unit effectivity.
B-2 Appearance Configuration Guide PLM00021 J

Glossary
secondary queue
Queue that contains the list of secondary update packages to be processed. The
queue is stored persistently in the database and can be queried.
secondary update package

Update package that exists on the secondary queue and defines a set of changes
that apply to one appearance set.
spatial data
Either NX true shape files or PLM visualization JT files that define the volume of
the part as a set of cubes. The cube size is set in the CAD programs defaults file. The
CAD files do not set absolute position; this is defined when the files are associated
with an appearance.
Update Manager
Multiprocess system responsible for ensuring product structure changes are
appropriately applied to appearances; includes the supervisor and updater processes.
update package
Discrete package of change information applied to appearance sets, either
primary or secondary. Typically, update packages are created by the
APPR-update-from-targets handler on the workflow process. They are also
created when the user saves the baseline appearance set or changes effectivity.
PLM00021 J Appearance Configuration Guide B-3

Index
A Creating . . . . . . . . . . . . . . . . . . . . . . 1-6
Creating searches . . . . . . . . . . . . . . 1-10
Appearance attribute Enhancing searches . . . . . . . . . . . . . 1-10
Create . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Historyless . . . . . . . . . . . . . . . . . . . 1-14
Create mapping to occurrence note . . . 4-3 Incremental change . . . . . . . . . . . . . 1-14
Appearance Attribute Mapping pane . . . 1-4 Limit number processed . . . . . . . . . . . 2-3
Appearance bootstrap problems . . . . . . 6-17 Product structure elements . . . . . . . . . 1-5
Appearance checker package . . . . . . 3-4, 6-6 Update . . . . . . . . . . . . . . . . . . . . . . . 5-4
Appearance Configuration application Updating . . . . . . . . . . . . . . . . . . . . . 1-10
Add new column . . . . . . . . . . . . . . . . 4-1 Using . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Add new row . . . . . . . . . . . . . . . . . . . 4-1 Validating manually . . . . . . . . . . . . . . 6-8
Find set contexts . . . . . . . . . . . . . . . . 4-2 APPR_allow_separate_spatial_processing
Set flags . . . . . . . . . . . . . . . . . . . . . . 4-2 preference . . . . . . . . . . . . . . . . . . . . . . 2-2
User interface . . . . . . . . . . . . . . . . . . 1-3 APPR_max_appearances_per_process
Using . . . . . . . . . . . . . . . . . . . . . . . . 4-1 preference . . . . . . . . . . . . . . . . . . . . . . 2-3
Appearance root .appr_update_env configuration file . . . 6-13
Attributes . . . . . . . . . . . . . . . . . . . . . 6-7 .appr_update_env preference file . . . . . . 3-8
Create . . . . . . . . . . . . . . . . . . . . . . . . 5-2 .appr_update_info configuration file . . . 6-14
Preventing searches of inconsistent . . . 6-7 .appr_update_info preference file . . . . . 3-12
Appearance root, purpose . . . . . . . . . . . . 1-5 .appr_update_info preference file . . . . . . 3-8
Appearance searches . . . . . . . . . . . . . . 1-11 appr_update_supervisor.log log file . . . . 6-10
Appearance set appr_working_scheduler utility . . . . . . . 3-3
Check existence . . . . . . . . . . . . . . . . . 5-3 Attribute mappings, creating . . . . . . . . . 2-9
Create baseline . . . . . . . . . . . . . . . . . 5-1 Audit package
Create historyless . . . . . . . . . . . . . . 2-13 Purpose . . . . . . . . . . . . . . . . . . . . . . . 3-4
Define tracking . . . . . . . . . . . . . . . . . 4-3
Destroying . . . . . . . . . . . . . . . . . . . . 4-4
Purpose . . . . . . . . . . . . . . . . . . . . . . . 1-5 B
Searching inconsistent . . . . . . . . . . . . 2-2 Baseline appearance sets . . . . . . . . . . . . 5-1
Stop tracking . . . . . . . . . . . . . . . . . . . 4-4 Baseline_allowed_baserev_statuses
Update historyless . . . . . . . . . . . . . . 2-14 preference . . . . . . . . . . . . . . . . . . . . . 2-13
Appearance sets . . . . . . . . . . . . . . . . . . 6-1 Baseline_release_procedures
Appearance Sets pane . . . . . . . . . . . . . . 1-3 preference . . . . . . . . . . . . . . . . . . . . . . 2-2
Appearance threads . . . . . . . . . . . . . . . 1-7 Baseline_release_procedures
Appearance update problems . . . . . . . . 6-19 preference . . . . . . . . . . . . . . . . . . . . . 2-13
Appearance updater . . . . . . . . . . . . . . 1-10 Basic concepts . . . . . . . . . . . . . . . . . . . 1-5
Commands . . . . . . . . . . . . . . . . . . . 3-23 Bootstrap appearance set, purpose . . . . . 1-6
Purpose . . . . . . . . . . . . . . . . . . . . . . 3-23
Troubleshooting with . . . . . . . . . . . . 6-16
C
Appearance, purpose . . . . . . . . . . . . . . . 1-5
appearance_updater log file . . . . . . . . . 6-11 Checker packages . . . . . . . . . . . . . . . . . 3-4
appearance_updater.syslog log file . . . . 6-12 Classification searches . . . . . . . . . . . . . . 2-9
Appearances Configuration context, purpose . . . . . . . . 1-6
Automatic validation . . . . . . . . . . 2-2, 6-5 Configuration files
Configuring . . . . . . . . . . . . . . . . . . . 1-12 .appr_update_env . . . . . . . . . . . . . . 6-13
PLM00021 J Appearance Configuration Guide Index-1

Index
.appr_update_info . . . . . . . . . . . . . . 6-14 JT_File_Priority_Refsets preference . . . . 2-4

Configure by release date only revision
rule . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 L
Configure with mixed effectivity revision
rule . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 License problems . . . . . . . . . . . . . . . . 6-17
Configuring Appearance Lifecycle Visualization
Configuration . . . . . . . . . . . . . . . . . . . 1-2 Configuring . . . . . . . . . . . . . . . . . . . . 2-9
Console Generating . . . . . . . . . . . . . . . . . . . 2-12
Commands . . . . . . . . . . . . . . . . . . . 3-15 Log files
Purpose . . . . . . . . . . . . . . . . . . . . . . 3-15 appearance_updater syslog . . . . . . . . 6-11
Troubleshooting with . . . . . . . . . . . . 6-15 appearance_updater.syslog . . . . . . . . 6-12
Context column, add . . . . . . . . . . . . . . . 4-1 appr_update_supervisor.log . . . . . . . . 6-10
Context, find set . . . . . . . . . . . . . . . . . . 4-2
Conventions, syntax definitions . . . . . . 1-21 M
mail_server_name preference . . . . . . . . . 2-4
E Mapped attributes, purpose . . . . . . . . . . 1-6
e-mails, update manager errors . . . . . . 6-14 Minimal setup process . . . . . . . . . . . . . 2-18
Effectivity, editing . . . . . . . . . . . . . . . . . 2-8 Mixed mode, resolve problems . . . . . . . 6-21
Enabling Appearance Configuration . . . . 1-1 Mixed units . . . . . . . . . . . . . . . . . . . . 6-21
Enabling appearances . . . . . . . . . . . . . . 1-5 Multi-Site Collaboration . . . . . . . 1-15, 2-17
Environment variables . . . . . . . . . . . . . 2-4
ERCT N
Purpose . . . . . . . . . . . . . . . . . . . . . . . 1-6 NX, configuring . . . . . . . . . . . . . . . . . . . 2-9
Resolve problems . . . . . . . . . . . . . . . 6-21
O
F
Occurrence note, create mapping to
find_appearances appearance attributes . . . . . . . . . . . . . 4-3
Command . . . . . . . . . . . . . . . . . . . . 3-20 Occurrences, precise occurrences . . . . . 1-14
Purpose . . . . . . . . . . . . . . . . . . . . . . 3-20
Troubleshooting with . . . . . . . . . . . . 6-15 P
fix_appearances . . . . . . . . . . . . . . . . . . 6-8
Flags, set . . . . . . . . . . . . . . . . . . . . . . . 4-2 Panes
Frequently asked questions . . . . . . . . . . 6-1 Appearance Attribute Mapping . . . . . . 1-4
Full setup checklist . . . . . . . . . . . . . . . 2-20 Appearance Sets . . . . . . . . . . . . . . . . 1-3
Perspectives
H In general . . . . . . . . . . . . . . . . . . . . . 1-4
Precise occurrences . . . . . . . . . . . . . . . 1-14
Historyless appearance set, purpose . . . . 1-6 Precise structures, creating appearances
Historyless appearances . . . . . . . . 1-8, 1-14 for . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Create appearance set . . . . . . . . . . . 2-13 Preferences
Managing . . . . . . . . . . . . . . . . . . . . 2-12 Appearances . . . . . . . . . . . . . . . . . . . 2-1
Releasing . . . . . . . . . . . . . . . . . . . . . 2-2 APPR_allow_separate_spatial_
Update appearance set . . . . . . . . . . . 2-14 processing . . . . . . . . . . . . . . . . . . 2-2
APPR_max_appearances_per_
I process . . . . . . . . . . . . . . . . . . . . . 2-3
Imprecise structures, creating appearances Automatic appearance validation . . . . 2-2
for . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 Baseline_allowed_baserev_
Inconsistencies, detecting . . . . . . . . . . . . 6-5 statuses . . . . . . . . . . . . . . . . . . . 2-13
Baseline_release_procedures . . . . 2-2, 2-13
Historyless appearances . . . . . . . . . . . 2-2
J JT_File_OverrideChildren_Refsets . . . 2-3
JT_File_OverrideChildren_Refsets JT_File_Priority_Refsets . . . . . . . . . . 2-4
preference . . . . . . . . . . . . . . . . . . . . . . 2-3 Limit appearances processed . . . . . . . . 2-3
Index-2 Appearance Configuration Guide PLM00021 J

Index
mail_server_name . . . . . . . . . . . . . . . 2-4 Spatial update problems . . . . . . . . . . . 6-20

PS_assume_legacy_transform_units . . 2-1 Starting the Appearance Configuration
PS_assume_old_transform_format . . . . 2-1 application . . . . . . . . . . . . . . . . . . . . . 1-2
Searching inconsistent sets . . . . . . . . . 2-2 Structure changes, processing . . . . . . . . 3-5
Spatial data . . . . . . . . . . . . . . . . . 2-1–2-2 Supervisor log file . . . . . . . . . . . . . . . . 3-19
TC_allow_appr_checking . . . . . . . 2-2, 6-6 Supervisor preferences . . . . . . . . . . . . . 3-9
TC_allow_appr_query_auditing . . . . . . 2-2 Syntax definition conventions . . . . . . . . 1-21
TC_appr_checking_interval . . . . . . . . . 6-6
TC_prevent_appr_query_on_ corrupt_ T
root . . . . . . . . . . . . . . . . . . . . . . . 2-2
TC_allow_appr_checking preference . . . . 2-2
Viewer . . . . . . . . . . . . . . . . . . . . . . . 2-3
TC_allow_appr_checking preference . . . . 6-6
Prerequisites for Appearance
TC_allow_appr_query_auditing
Configuration . . . . . . . . . . . . . . . . . . . 1-1
preference . . . . . . . . . . . . . . . . . . . . . . 2-2
Primary package . . . . . . . . . . . . . . . . . . 3-2
TC_appr_checking_interval . . . . . . . . . . 6-6
Primary queue . . . . . . . . . . . . . . . . . . . 3-3
TC_prevent_appr_query_on_corrupt_root
Product, releasing . . . . . . . . . . . . . . . . . 5-3
preference . . . . . . . . . . . . . . . . . . . . . . 2-2
PS_assume_legacy_transform_units
tc_profilevars script . . . . . . . . . . . . . . . . 2-4
preference . . . . . . . . . . . . . . . . . . . . . . 2-1
Troubleshooting . . . . . . . . . . . . . . . . . . 6-2
PS_assume_old_transform_format
TruShape data, generating . . . . . . . . . 2-10
preference . . . . . . . . . . . . . . . . . . . . . . 2-1
TruShape files, generating . . . . . . . . . . . 2-9
Purge old revisions . . . . . . . . . . . . . . . 2-14
purge_baselined_item_revisions
utility . . . . . . . . . . . . . . . . . . . . . . . . 2-14 U
Unsupported functionality . . . . . . . . . . 1-20
R Update appearances . . . . . . . . . . . . . . . 5-4
Update Manager
Revision rules
Administrator preferences . . . . . . . . 3-11
Add new . . . . . . . . . . . . . . . . . . . . . . 4-1
Check states . . . . . . . . . . . . . . . . . . . 5-3
Configure by release date only . . . . . . . 2-8
Checking environment . . . . . . . . . . . 6-16
Configure with mixed effectivity . . . . . 2-8
Checking status . . . . . . . . . . . . . . . . . 5-3
Creating . . . . . . . . . . . . . . . . . . . . . . 2-8
Configuring . . . . . . . . . . . . . . . . . . . . 3-8
Revisions, purge old . . . . . . . . . . . . . . 2-14
Error e-mails . . . . . . . . . . . . . . . . . . 6-14
Rich client perspectives and views . . . . . 1-4
Manager . . . . . . . . . . . . . . . . . . . . . . 3-1
Root item
Preferences . . . . . . . . . . . . . . . . 3-8, 3-12
Add . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Primary package . . . . . . . . . . . . . . . . 3-2
Purpose . . . . . . . . . . . . . . . . . . . . . . . 1-6
Primary queue . . . . . . . . . . . . . . . . . . 3-3
Row, add . . . . . . . . . . . . . . . . . . . . . . . 4-1
Processes . . . . . . . . . . . . . . . . . . . . . 3-1
Purpose . . . . . . . . . . . . . . . . . . . . . . . 3-1
S Restart . . . . . . . . . . . . . . . . . . . . . . 3-14
Saved queries, creating . . . . . . . . . . . . . 2-8 Retry preferences . . . . . . . . . . . . . . . 3-11
Search problems . . . . . . . . . . . . . . . . . 6-21 Secondary package . . . . . . . . . . . . . . . 3-2
Secondary package . . . . . . . . . . . . . . . . 3-2 Secondary queue . . . . . . . . . . . . . . . . 3-3
Secondary queue . . . . . . . . . . . . . . . . . . 3-3 Start . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Set context, find . . . . . . . . . . . . . . . . . . 4-2 Starting . . . . . . . . . . . . . . . . . . . . . 6-16
Spatial cache Stop . . . . . . . . . . . . . . . . . . . . . . . . 3-14
Creating . . . . . . . . . . . . . . . . . . . . . 1-11 Stopping . . . . . . . . . . . . . . . . . . . . . 6-16
Generating . . . . . . . . . . . . . . . . . . . 1-11 Supervisor . . . . . . . . . . . . . . . . . . . . . 3-1
Updating . . . . . . . . . . . . . . . . . . . . . 1-12 Update package . . . . . . . . . . . . . . . . . 3-2
Spatial data Update package information . . . . . . . . 3-4
Preferences . . . . . . . . .... . . . . . . . . 2-1 Update package states . . . . . . . . . . . . 3-3
Process separately . . . .... . . . . . . . . 2-2 Update package types . . . . . . . . . . . . . 3-4
Purpose . . . . . . . . . . . .... . . . . . . . . 1-6 Updater . . . . . . . . . . . . . . . . . . . . . . 3-1
Spatial query, performing ... . . . . . . . 1-12 Utilities . . . . . . . . . . . . . . . . . . . . . 3-14
Spatial searches . . . . . . .... . . . . . . . 1-11 Update package
PLM00021 J Appearance Configuration Guide Index-3

Index
Information . . . . . . . . . . . . . . . . . . . . 3-4 USER_bomline_is_preferred_ancestor user

Purpose . . . . . . . . . . . . . . . . . . . . . . . 3-2 exit . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
States . . . . . . . . . . . . . . . . . . . . . . . . 3-3 USER_ps_update_appr_attr user exit . . . 2-5
Types . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Utilities
Working data . . . . . . . . . . . . . . . . . . . 3-3 appearance_updater . . . . . . . . . 3-23, 6-16
Updater controller preferences . . . . . . . 3-10 Console . . . . . . . . . . . . . . . . . . 3-15, 6-15
Updater preferences . . . . . . . . . . . . . . 3-10 find_appearances . . . . . . . . . . . 3-20, 6-15
User exits fix_appearances . . . . . . . . . . . . . . . . . 6-8
Configuring . . . . . . . . . . . . . . . . . . . . 2-5 Update Manager . . . . . . . . . . . . . . . 3-14
USER_appr_item_is_above_ERCT . . . . 2-5
USER_appr_update_end_item_search_
results . . . . . . . . . . . . . . . . . . . . . 2-6 V
USER_bomline_is_preferred_
Visualization files, generating . . . . . . . . 2-9
ancestor . . . . . . . . . . . . . . . . . . . . 2-6
USER_ps_update_appr_attr . . . . . . . . 2-5
USER_appr_item_is_above_ERCT user W
exit . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
USER_appr_update_end_item_ search_results Workflow processes . . . . . . . . . . . . . . . . 2-7
user exit . . . . . . . . . . . . . . . . . . . . . . . 2-6
Index-4 Appearance Configuration Guide PLM00021 J

Appearance Config PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Appearance Config PDF

Hochgeladen von

Copyright:

Verfügbare Formate

Teamcenter 10.

Appearance Configuration Guide

This software and related documentation are proprietary to Siemens Product

2 Appearance Configuration Guide PLM00021 J

Proprietary and restricted rights notice . . . . . . . . . . . . . . . . . . . . . . . . . 2

Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Configuring for appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Running the Update Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Using the Appearance Configuration application . . . . . . . . . . . . . . . . . 4-1

PLM00021 J Appearance Configuration Guide 3

Define how appearance sets are tracked . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Creating and updating appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Solving problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Command reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Appearance update mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

4 Appearance Configuration Guide PLM00021 J

Getting started with appearance configuration . . . . . . . . . . . . . . . . . . . . . . . 1-1

Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Configuring appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Appearance Configuration interface . . . ... . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Basic concepts for using appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Basic tasks using appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20

Unsupported functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20

Syntax conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21

PLM00021 J Appearance Configuration Guide

Getting started with appearance configuration

Before you begin

PLM00021 J Appearance Configuration Guide 1-1

1. Set Teamcenter preferences, as described in Setting Teamcenter preferences and

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

8. Optionally, configure historyless appearances. See Managing historyless

10. Optionally, configure appearances for a Multi-Site Collaboration environment. If

1-2 Appearance Configuration Guide PLM00021 J

Appearance Configuration interface

Appearance Sets pane

• Supports remote search (published) –

• Does not support remote search (not published)

Untracked appearances have a blank cell.

PLM00021 J Appearance Configuration Guide 1-3

Appearance Attribute Mapping pane

Item Appearance Attribute Mapping pane

Rich client perspectives and views

1-4 Appearance Configuration Guide PLM00021 J

Basic concepts for using appearances

PLM00021 J Appearance Configuration Guide 1-5

• Do not mix configuration by date effectivity and by

• Do not mix configuration by date effectivity and by

You can group entries when appropriate.

Working with appearances

1-6 Appearance Configuration Guide PLM00021 J

Understanding occurrence and appearance threads

PLM00021 J Appearance Configuration Guide 1-7

Creating appearance searches

Making appearances searches in Structure Manager

Using historyless appearances

1-8 Appearance Configuration Guide PLM00021 J

Execute an all history search in Structure Manager

Clear all-history lines in Structure Manager