item_relink

Replaces the external references for a duplicate item and its corresponding replica in a Multi-Site Collaboration environment. The item_relink utility works in conjunction with the item_rename utility. The Bypass option enables or disables special bypass object protections for Teamcenter administrators, allowing you to freely access any object in the database to perform maintenance. When running this utility, you must use the Bypass option, the user ID must be infodba, and the OS user account must have read-access to the NX part files to comply with the rules stated in Bypass UG Part File Verification. Caution The item_relink utility is used only with Multi-Site Collaboration to process production data. Siemens Digital Industries Software recommends that a full backup of your database be performed before running this utility. This allows you to restore the database if the data becomes corrupted. Naming pattern Because the item_relink utility works in conjunction with the item_rename utility, the same naming pattern must be used in both utilities. Bypass NX part file verification Each NX part file that is attached to a duplicate is checked against the corresponding NX part file that is attached to the replica. The item_relink utility compares the UID strings in the NX part files. The ug_inspect utility retrieves the UID strings from the part files. Therefore, it is very important to run the item_relink utility using the OS account that has read access to the part files. Usually, the Teamcenter user account, such as infodba, is used to run the utility. If UIDs are not the same, the relink process for the duplicate fails. If you are confident about the part files being reconciled, you can use the -bypass_ugpart command line argument to bypass this check. The -bypass_ugpart argument is ignored if the item_relink utility is run in verify mode. Matching criteria To find the corresponding replica, construct the replica item ID based on the duplicate item ID and renaming pattern and then search the database for the replica. To find the corresponding item revision, match the revision ID. To find the corresponding BOM view, match the view type name. To find the corresponding BOM view revision, match the view type name. To find the corresponding secondary object, match the object name, object type, and relation type. Matching results For each object that is attached to a duplicate item or duplicate item revision, if more than one object with the same object name, object type, and relation type are found in its corresponding replica item or replica item revision, the first occurrence is used. If objects attached to a duplicate do not have corresponding objects found in replica, use the -verify switch to generate a report that lists any discrepancies. In this case, perform a detailed examination and make the necessary corrections and/or ownership change for the duplicate. If any discrepancies are detected during the relink process, the duplicate is not replaced. Instead, the duplicate is placed in the exception folder. An error message is logged on the report file for review. Exception If unexpected Teamcenter internal errors occur or the duplicate contains objects not found in its corresponding replica, the utility stops processing the duplicate that has a problem, logs an error message to the report file, and then processes the next duplicate in the replacement folder. All duplicates that are not reconciled are placed in the Item_ID_ConsolidationEXP exception folder so you can further examine these duplicates. Syntax item_relink [-u=user-id {-p=password | -pf=password-file} -g=group] -replace=folder-name -refile=folder-name -update | -verify [-prefix=prefix-removed-from-item-id | -suffix=suffix-removed-from-item-id | -f=file-name] [-bypass_ugpart ] [-ignore_attachments] [-relink_to_latest_rev] -report | -report=file-name [-h] Arguments -u Specifies the user ID. This is a user with Teamcenter administration privileges. If Security Services single sign-on (SSO) is enabled for your server, the -u and -p arguments are authenticated externally through SSO rather than being authenticated against the Teamcenter database. If you do not supply these arguments, the utility attempts to join an existing SSO session. If no session is found, you are prompted to enter a user ID and password. -p Specifies the password. This argument is mutually exclusive with the -pf argument. -pf Specifies the password file. For more information about managing password files, see Manage password files. This argument is mutually exclusive with the -p argument. -g Specifies the group associated with the user. If used without a value, the user's default group is assumed. -replace Specifies the name of the folder that holds items that are currently duplicates but should be replicas. This must be the same folder used by the item_rename utility. -verify Requests verification of compatibility between duplicates and replicas. -update Performs the link replacement. -prefix Specifies the prefix removed from the item ID of duplicates to form the new item IDs for replicas. This must be the same prefix used by the item_rename utility. See restriction 5. -suffix Specifies the suffix removed from the item ID of duplicates to form the new item IDs for replicas. This must be the same suffix used by the item_rename utility. See restriction 5. -f Specifies the file containing item ID cross reference records. The cross reference contains the duplicate item ID and the renamed duplicate item ID for each duplicate item ID. This data is contained in a single 80-byte line in the file. The item_rename utility also uses this file. See restriction 5. -bypass_ugpart Indicates whether NX part files are verified. If this switch is specified, no verification is performed. This switch is ignored if the -verify argument is specified. -ignore_attachments Prohibits linking of secondary objects (attachments). Use this argument when the replacement item already has links to all required attachments. -relink_to_latest_rev Links all revisions of a duplicate item to latest revision of the replica item. Ignores secondary objects (attachments) to avoid incorrect attachments. This argument cannot be specified for items with multiple views. -report Generates a report. Outputs the report to standard output if the file name is not supplied. -h Displays help for this utility. Environment As specified in Setting up a Teamcenter command-line environment. Files As specified in Log files produced by Teamcenter. Restrictions The following restrictions must be understood and adhered to when using the item_relink utility: Must be run with the Bypass option, and the user ID must be infodba. The OS user account must have read-access to the NX part files to comply with the rules stated in Bypass UG Part File Verification. The -replace and -refile arguments must be supplied. Either the -rename or -verify arguments must be supplied. A default naming pattern is used if the -prefix, -suffix, or -f argument is not supplied. Examples The best practice is to run the item_relink utility with the -verify argument to do a comparison to find discrepancies between duplicates and replicas. If any exist, examine the discrepancies and make the necessary corrections. To ensure data integrity, Multi-Site Collaboration imposes strict rules on object replication. One of these rules is that only the primary object can be modified. The replicated object must never be checked out for modification or submitted for release. Therefore, if the duplicates contain objects that have no corresponding replicas, the relink process for these duplicates is not performed. However, if the replicated objects have increased with more attachments, the duplicates are overwritten. To verify the items in the replacement folder and generate a report called relink.rpt, enter the following command on a single line. The naming pattern must be the same as that used by the item_rename utility. Copy Item_relink -u=infodba -p=infodba -replace=replacement -refile=assm_refile -prefix=AAA -verify -report=relink.rpt After generating a replacement report, you may need to correct duplicates or change ownership. To replace the links, enter the following command on a single line: Copy Item_relink -u=infodba -p=infodba -replace=replacement -refile=assm_refile -prefix=AAA -update -report=relink.rpt Related Topics TC XML and PLM XML Configuration for Data Import and Export Multi-Site Collaboration