WindchillWindchill UpgradeUpgrade GuideGuide -...

WindchillWindchill UpgradeUpgrade GuideGuideReleaseRelease 9.9.xx toto ReleaseRelease 10.110.1

Windchill®Windchill® 10.110.1 M020M020MayMay 20132013

CopyrightCopyrightCopyrightCopyright ©© 20122012 ParametricParametric TechnologyTechnology CorporationCorporation and/and/oror ItsItsSubsidiarySubsidiary Companies.Companies. AllAll RightsRights Reserved.Reserved.

User and training guides and related documentation from Parametric TechnologyCorporation and its subsidiary companies (collectively "PTC") are subject to thecopyright laws of the United States and other countries and are provided under alicense agreement that restricts copying, disclosure, and use of suchdocumentation. PTC hereby grants to the licensed software user the right to makecopies in printed form of this documentation if provided on software media, butonly for internal/personal use and in accordance with the license agreement underwhich the applicable software is licensed. Any copy made shall include the PTCcopyright notice and any other proprietary notice provided by PTC. Trainingmaterials may not be copied without the express written consent of PTC. Thisdocumentation may not be disclosed, transferred, modified, or reduced to anyform, including electronic media, or transmitted or made publicly available by anymeans without the prior written consent of PTC and no authorization is granted tomake copies for such purposes.

Information described herein is furnished for general information only, is subject tochange without notice, and should not be construed as a warranty or commitmentby PTC. PTC assumes no responsibility or liability for any errors or inaccuraciesthat may appear in this document.

The software described in this document is provided under written licenseagreement, contains valuable trade secrets and proprietary information, and isprotected by the copyright laws of the United States and other countries. It may notbe copied or distributed in any form or medium, disclosed to third parties, or usedin any manner not provided for in the software licenses agreement except withwritten prior approval from PTC.

UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CANRESULT IN CIVIL DAMAGES AND CRIMINAL PROSECUTION. PTCregards software piracy as the crime it is, and we view offenders accordingly. Wedo not tolerate the piracy of PTC software products, and we pursue (both civillyand criminally) those who do so using all legal means available, including publicand private surveillance resources. As part of these efforts, PTC uses datamonitoring and scouring technologies to obtain and transmit data on users ofillegal copies of our software. This data collection is not performed on users oflegally licensed software from PTC and its authorized distributors. If you are usingan illegal copy of our software and do not consent to the collection andtransmission of such data (including to the United States), cease using the illegalversion, and contact PTC to obtain a legally licensed copy.

Important Copyright, Trademark, Patent, and Licensing Information: See theAbout Box, or copyright notice, of your PTC software.

UNITEDUNITED STATESSTATES GOVERNMENTGOVERNMENT RESTRICTEDRESTRICTED RIGHTSRIGHTS LEGENDLEGEND

2 Windchill Upgrade Guide

This document and the software described herein are Commercial ComputerDocumentation and Software, pursuant to FAR 12.212(a)-(b) (OCT’95) or DFARS227.7202-1(a) and 227.7202-3(a) (JUN’95), and are provided to the USGovernment under a limited commercial license only. For procurements predatingthe above clauses, use, duplication, or disclosure by the Government is subject tothe restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Dataand Computer Software Clause at DFARS 252.227-7013 (OCT’88) or CommercialComputer Software-Restricted Rights at FAR 52.227-19(c)(1)-(2) (JUN’87), asapplicable. 01012012

ParametricParametric TechnologyTechnology Corporation,Corporation, 140140 KendrickKendrick Street,Street, Needham,Needham,MAMA 0249402494 USAUSA

3

ContentsContents

Copyright .............................................................................................................2Change Record ....................................................................................................6About This Guide ..................................................................................................6

Before Upgrading ........................................................................................................9Upgrade Overview ..............................................................................................10Supported Upgrade Paths ...................................................................................10Supported Scenarios........................................................................................... 11Unsupported Scenarios ....................................................................................... 11Installing Multiple PTC Products...........................................................................12Accessing Legacy Audit Data After Upgrading.......................................................12Windchill Index Search Upgrade Overview............................................................13

The Windchill Upgrade Procedure...............................................................................15Create a Work Instruction Document ....................................................................16Executing WinDU Diagnostic Tasks on the Source System.....................................16Gather Vault Information ......................................................................................16Preparing Windchill Business Reporting for Upgrade .............................................18Export the Database and LDAP............................................................................19Migrating to Windchill Directory Server..................................................................20Back Up Windchill Vaults .....................................................................................32Setting Up the Target System for Upgrade.............................................................32Prepare the Source System for Upgrade...............................................................45Stage the Source Data for the Upgrade.................................................................46Using the Upgrade Manager ................................................................................53Execute Final Upgrade Steps...............................................................................64

Verify the Upgraded Solution ......................................................................................71

(Optional) Run the System Health Check WinDU Tasks ................................................73

Appendix A.Migrating ECAD InterComm Representations and Markups.........................75

5

ChangeChange RecordRecord

ChangesChanges forfor 10.110.1 M020M020

ChapterChapter DescriptionDescription

Supported Scenarioson page 11

Added the section Upgrading to SQLServer 2012on page

Execute Final Upgrade Steps on page64

Added the section Update theTablespaceon page 64.

ChangesChanges forfor 10.110.1 F000F000

ChapterChapter DescriptionDescription

Windchill Upgrade Guide New for 10.1

AboutAbout ThisThis GuideGuideThe Windchill Upgrade Guide describes how to upgrade the database schema onan existing Windchill installation to a new release, and then migrate its persistentdata. This guide is intended for the upgrade team that performs the site’s upgrade.For more information on the necessary team roles, see Planning an Upgrade inWindchill Upgrade Planning.

This guide does not define upgrade-specific terminology. For a glossary ofupgrade-related terms, see the Windchill Upgrade Reference Guide.

RelatedRelated DocumentationDocumentationThe following documentation may be helpful:

• Windchill Upgrade Reference Guide

• Windchill Changes For This Release

• Windchill Installation and Configuration Guide

• Windchill Basic Administration Guide

• Windchill Specialized Administration Guide

• Windchill Rehost Guide

• Windchill Customization Guide

• Windchill Diagnostic Utility Guide


https://www.ptc.com/view?im_dbkey=99360

TechnicalTechnical SupportSupportContact PTC Technical Support through the PTC website, or by phone, email, orfax if you encounter problems using this product or the product documentation.

For complete details, see the PTC Customer Service Guide. You can find this guideunder Contacting Technical SupportContacting Technical Support on the PTC Technical Support page:

http://www.ptc.com/support/index.htm

You must have a Service Contract Number (SCN) before you can receive technicalsupport. If you do not have an SCN, contact the PTC Maintenance Departmentusing the instructions found in the PTC Customer Service Guide or on the PTCTechnical Support page.

DocumentationDocumentation forfor PTCPTC ProductsProductsYou can access PTC documentation using the following resources:

• Windchill Help CenterWindchill Help Center—The Windchill Help Center is an online knowledgebase that includes a comprehensive index of all Windchill documentation. Youcan browse the entire Windchill documentation set, or use the search capabilityto perform a keyword search. To access the help center, you can:

○ Click any help icon in Windchill○ Select HelpHelp ▶▶ Windchill Help CenterWindchill Help Center from the Quick LinksQuick Links menu at the top

right of any Windchill page

○ Use the following link to access all PTC help centers:https://www.ptc.com/appserver/cs/help/help.jsp

• Reference Documents WebsiteReference Documents Website—The Reference Documents website is a libraryof all PTC guides:

http://www.ptc.com/appserver/cs/doc/refdoc.jsp

A Service Contract Number (SCN) is required to access the PTC documentationfrom the Reference Documents website. For more information on SCNs, see thePTC Technical Support page:

http://www.ptc.com/support/index.htm

7

http://www.ptc.com/support/support.htmhttps://www.ptc.com/appserver/cs/help/help.jsphttp://www.ptc.com/appserver/cs/doc/refdoc.jsphttp://www.ptc.com/support/support.htm

CommentsCommentsPTC welcomes your suggestions and comments on its documentation. To submityour feedback, you can:

• Send an email to [email protected]. Include the name of the applicationand its release number with your comments. If your comments are about aspecific help topic or book, include the title.

• Click the PTC help center feedback icon in the upper right of a Windchill HelpCenter topic and complete the feedback form. The help topic title isautomatically included with your feedback.


11BeforeBefore UpgradingUpgrading

Upgrade Overview.....................................................................................................10Supported Upgrade Paths ..........................................................................................10Supported Scenarios ................................................................................................. 11Unsupported Scenarios.............................................................................................. 11Installing Multiple PTC Products .................................................................................12Accessing Legacy Audit Data After Upgrading .............................................................12Windchill Index Search Upgrade Overview ..................................................................13

This section contains information you will need prior to starting the upgradeprocedure.

9

UpgradeUpgrade OverviewOverviewThis section gives an overview of the upgrade process. It is intended to give theperson who is performing the upgrade a high-level perspective of the stepsrequired to upgrade a Windchill solution.

The following steps summarize the Windchill upgrade process:

1. Run upgrade-mandatory Windchill Diagnostic Utility (WinDU) tasks on thesource system and fix all reported issues.

2. Export the database and LDAP1. Exports should be taken at the same time.

3. If your upgrade includes vaults, copy the vaults for the master site as well asfor any remote sites from the source server to the target server.

4. Set up the target system and verify that the target system is fully functional.

5. Convert customizations from Rational Rose to Annotations and apply on thetarget system.

6. If your source system uses Aphelion, migrate from Aphelion to WindchillDirectory Server.

7. Import the database and LDAP taken in step 2.

8. Run the Upgrade Manager.

9. Execute final upgrade tasks.

10. Validate the upgraded solution.

PTC has consolidated all online resources for customers upgrading Windchill atthe Windchill Upgrade and Migration Resource Page, including the latest tools andpatches for the Windchill upgrade process. You can also find documentation for theWindchill Diagnostic Utility at http://www.ptc.com/support/windu.htm. Click thelink for the Windchill Diagnostic Utility and download the latest documentationfrom that page.

Prior to starting your upgrade project, PTC recommends that you visit theWindchill Upgrade and Migration Resource Page. Call Technical Support if youhave any questions about the upgrade.

Also, for any source system temporary patches, investigate any SPRs in the webtools to see if they are resolved.

SupportedSupported UpgradeUpgrade PathsPathsFor information on supported upgrade paths, refer to the Windchill SupportedUpgrade Paths document available from the PTC Reference Documents site. Fromthe drop-down menus, select the following:

ProductProduct:


1. This step only applies to test upgrades or sites using new hardware.

http://www.ptc.com/view?im_dbkey=96752http://www.ptc.com/appserver/cs/doc/refdoc.jsphttp://www.ptc.com/appserver/cs/doc/refdoc.jsp

Reported ReleaseReported Release:

Document TypeDocument Type: Upgrade GuideUpgrade Guide

User RoleUser Role: All User RolesAll User Roles

SupportedSupported ScenariosScenariosThere are numerous support scenarios for upgrading a Windchill solution. Thissection is intended to highlight the most common supported scenarios.

ChangingChanging PlatformsPlatformsPTC now supports changing hardware during the upgrade, but with the limitationthat sites stay on the same operating system (OS) platform (for example, MicrosoftWindows on both new and old hardware, or UNIX on both the new and oldhardware. PTC will not support switching from Windows on the old hardware toUNIX on the new hardware). If an OS platform change is needed, you must firstrehost your source system to the new OS platform and then perform the upgrade.

UnsupportedUnsupported ScenariosScenariosThere are numerous unsupported scenarios for upgrading a Windchill solution.This section is intended to highlight the most common unsupported scenarios.

ReconfigureReconfigure OracleOracle RACRAC PriorPrior toto UpgradeUpgradeUpgrades to release 10.x are not supported using Oracle RAC.

Using Oracle RAC causes a significant performance issue for any data set that hashigh volumes of insert/update/delete’s due to cluster locks for block comparisons.It is required, for performance reasons, that upgrade not be done with RACenabled. Use the same RAC connection string, but narrow it down to just a singlenode or use the standard JDBC short syntax. On the Oracle side you must disableall of the RAC nodes in the cluster with the exception of the one that Windchill ispointing at. Failure to properly disable the RAC cluster will result in RAC nodeevictions.

MachinesMachines inin DifferentDifferent DomainsDomainsPTC does not support upgrading when the target system is configured on adifferent domain than the source system.

Before Upgrading 11

SolutionsSolutions IncludingIncluding WindchillWindchill SocialLinkSocialLinkUpgrading a Windchill solution that includes Windchill SocialLink to a targetsystem that does not include Windchill SocialLink is not supported. However, youstill can upgrade the Windchill solution without the Windchill SocialLinkfunctionality.

InstallingInstalling MultipleMultiple PTCPTC ProductsProductsPTC supports the installation of interoperable products. This includes having asystem with interoperable Windchill PDMLink and Windchill ProjectLink.However, if you are upgrading, the products on your source and target systemshould be the same. For example, if you have Windchill PDMLink on your sourcesystem and you want to add Windchill ProjectLink, you must first upgrade yourWindchill PDMLink system and, after the upgrade is complete, add WindchillProjectLink.

AccessingAccessing LegacyLegacy AuditAudit DataData AfterAfterUpgradingUpgradingStarting in Windchill 10.0, the link to Windchill 7.0/8.0 Security Audit Reportingwhich was available in Windchill 9.0 and 9.1 systems on the Site and OrganizationUtilities tabs, will no longer be available. This link was enabled by setting the wt.audit.EnableLegacyAuditUI property to true. Audit data created prior to Windchill9.0 will not be deleted on upgrade, but this data will no longer be viewable oraccessible on a Windchill 10.0 system. Before upgrading to Windchill 10.0, youmay wish to archive audit data created prior to Windchill 9.0 by creating thenecessary Windchill 8.0 audit reports and saving them to files, as documented inthe online help. Audit data created at Windchill 9.0 and later releases is in the newformat and can still be accessed by reports using the new audit reportingcapabilities.

The following tables were used for audit data prior to Windchill 9.0. If after savingany audit data created prior to Windchill 9.0, you may choose to manually deletethese obsolete tables:

• ACCESSRULEEVENTINFO

• ACTIONITEMEVENTINFO

• ADHOCEVENTINFO

• CUSTOMEVENTINFO

• EXECOBJECTEVENTINFO

• GROUPEVENTINFO

• NOTAUTHORIZEDEVENTINFO

• ORGANIZATIONROLEEVENTINFO


• PROJECTEVENTINFO

• TEAMEVENTROLEPOOLINFO

• TEAMEVENTROLEPRINCIPALINFO

• WFVARIABLEEVENTINFO

The following tables were used in the audit framework prior to Windchill 9.0 andwill become obsolete in a subsequent Windchill release:

• RENAMEEVENTINFO

• LOCATIONCHANGEEVENTINFO

• PROJECTAUDITEVENT

• LASTAUDITEVENT

• AUDITEVENT

WindchillWindchill IndexIndex SearchSearch UpgradeUpgradeOverviewOverviewIndexing is the process of extracting text strings of attribute names and attributevalues from Windchill objects and sending them to a search engine that buildsindices optimized for searching. This enables users to efficiently search for datastored in a Windchill database, without having to know anything about the internalobject model. Windchill solutions provide the option of installing Windchill IndexSearch to help with indexing.

The Windchill Index Search system provides the ability to search for keywordswithin the meta data and content of Windchill database objects. The oversight of asystem administrator is required to maintain the efficiency and usefulness of thesearch system as it changes over time.

BulkBulk IndexingIndexing

You can use the Bulk Index Tool to load all the objects that belong in the WindchillIndex Search libraries. This utility sends objects to a search engine to be indexedaccording to their domain’s indexing policy. You can perform the following taskswith this utility:

• Start and stop the bulk indexing process. Because loading indexes can take asignificant amount of time, it may be necessary to stop the operation for somelength of time. State is maintained in the IndexStatus table, which is used bythis too, so the process can be stopped and restarted without having to re-indexobjects that have already been indexed.

• Schedule the process to start and stop at specified times.

• Check on the status of the overall bulk indexing process.

Before Upgrading 13

• Attempt the re-index objects that have failed the indexing process.

• Maintain a detailed log of the indexing process.

NoteNoteThe Bulk Index Tool can only be used to load Windchill Index Search libraries.

InstallingInstalling WindchillWindchill IndexIndex SearchSearch

For information on installing Windchill Index Search and bulk indexing see:

• The Windchill Installation and Configuration Guide

UsingUsing WindchillWindchill IndexIndex SearchSearch DuringDuring anan UpgradeUpgrade

For more information on using Windchill Index Search and bulk indexing duringan upgrade see:

• Execute Steps for Windchill Index Search on page 65

AdministeringAdministering WindchillWindchill IndexIndex SearchSearch

For information on configuring and administering Windchill Index Search andbulk indexing see:

• The Windchill Administration - Configuring Your Windchill Environment


22TheThe WindchillWindchill UpgradeUpgrade ProcedureProcedure

Create a Work Instruction Document ...........................................................................16Executing WinDU Diagnostic Tasks on the Source System ...........................................16Gather Vault Information.............................................................................................16Preparing Windchill Business Reporting for Upgrade ....................................................18Export the Database and LDAP ..................................................................................19Migrating to Windchill Directory Server ........................................................................20Back Up Windchill Vaults............................................................................................32Setting Up the Target System for Upgrade ...................................................................32Prepare the Source System for Upgrade .....................................................................45Stage the Source Data for the Upgrade .......................................................................46Using the Upgrade Manager.......................................................................................53Execute Final Upgrade Steps .....................................................................................64

This section contains the procedure to upgrade your Windchill solution.

15

CreateCreate aa WorkWork InstructionInstruction DocumentDocumentThis step-by-step process for upgrading the Windchill system covers steps thatmust always be done; however, there may be unique steps that are specific to yoursite that should be recorded in a work instructions document. For example, youmay want to extrapolate upon some instructions to include details such as machinenames, database names, and file locations that are specific to your upgrade. Keepthe work instructions document updated so that it can be a repeatable process forsubsequent test upgrades and production upgrades.

ExecutingExecuting WinDUWinDU DiagnosticDiagnostic TasksTasks onon thetheSourceSource SystemSystemRun the upgrade-mandatory Windchill Diagnostic Utility (WinDU) tasks and fixall issues that are reported. You will need to use the latest WinDU patch from theweb site.

For more information on each WinDU task, refer to the Windchill DiagnosticUtility Guide. You can download the latest WinDU patch and the guide from thefollowing location:

http://www.ptc.com/support/windu.htm

GatherGather VaultVault InformationInformationIdentify the file vault directory structure that will be used for future upgrade steps.Open the External Storage AdministratorExternal Storage Administrator by selecting SiteSite ▶▶ UtilitiesUtilities ▶▶ ExternalExternalStorage AdministratorStorage Administrator on the source system and record the mount points it listsunder the local master site. If you are performing an upgrade that includes remoteFile Server sites, then you should also record the Vault/folder/mount informationfor the remote sites.

UpgradeUpgrade VaultsVaults andand FileFile ServersServersBefore running upgrade, you must decide how to handle vaults during the upgrade.Even if Windchill has not been configured to use Vaults, it uses a default cachevault which might contain content that has not been re-vaulted. The UpgradeManager provides three options to handle vaults during upgrade:

1. Configure different file vault host information

2. Keep existing file vault host information from source database

3. Do Not Update File Vault Data

Option 1 is the default option. To use this option, you must copy the directoriescontaining vaulted file content from the source system to another system. Toidentify the directories that must be copied, open the Vault ConfigurationVault Configuration window


on the source system and record the folders it lists under the local master site.When copying the folders and their contents to the new host, make sure that theexact same folder structure from the source system is used on the other system towhich you copied the content. The new host must be able to access the vaultcontent using existing vault/folder mounts. PTC recommends using FTP in binarymode to copy the file content. See the External File Vaults section of the WindchillEnterprise Administration Guide on your source system for assistance.

When this option is selected, the existing vault information will be displayed andyou will be prompted to enter the new hostname, where the vault content has beencopied to, for each existing hostname. You cannot proceed away from the phaseuntil you have entered values for each host that needs updating. This is therecommended option for test upgrades.

Option 2 should only be selected for production upgrade, because vaulted contentwould be updated during upgrade. If this option is used during a test upgrade, thereis a risk of production vault data being updated. When this option is selected,existing vault information will be displayed and no other action is required fromthe user.

Option 3 disables Vaults. This option may be used during test upgrades whenvaulted data is not available. Selecting this option means that only the metadatawill be upgraded, therefore it is not recommended because necessary updates tovaulted data will not occur. This option should not be used for productionupgrades. For more information, see Vaults and File Servers on page 59.

The Upgrade Manager provides the following options to handle File servers duringupgrade:

• Update File Server configuration

When this option is selected, the existing File Server URLs and host nameswill be displayed under each replica configured on the source server and theuser will be prompted to enter the new File Server URLs and host names. Thenew URLs and host names should point to the new File Servers where thetarget release has been installed. The user must enter values for each FileServer URL and host name before proceeding.

NoteNoteMake sure that you do not provide production File server host names andURLs for test upgrades. This might result in data corruption on the productionsystem. This option requires you to install File Server sites before starting themaster site upgrade.

• Manually Configure File Servers Post Upgrade

This option is available if File Servers have not been configured beforeupgrade. Choose this option if the source windchill system has no File serverconfigured. If source system has file servers configured, choosing this optionrequires the File Servers to be updated and configured manually after the

The Windchill Upgrade Procedure 17

Master Site has been upgraded. When this option is selected, File server URLsand host names are set to invalid names to avoid production File Server accessduring test upgrades. If you are upgrading a 9.x solution, this option is notavailable if one or more File servers have master vaults and you select UpdateUpdateFile Vault dataFile Vault data in Vault Mode. This is because certain tasks in the upgradeprocess require access to file content on a replica master vault.

• Keep existing File Server Configuration -

This option is provided for production upgrades when target File Servers areinstalled on the same host machines where source File Servers existed.

UseUse Auto-Auto-mountedmounted FoldersFolders forfor VaultsVaults (UNIX(UNIX Only)Only)If your site is upgrading on UNIX and uses auto-mounted folders for vaults, set thefollowing property:

com.ptc.windchill.upgrade.automountPatterns

This property should be set to the prefix that is used for auto-mounted folders. Thedefault value of this property iscom.ptc.windchill.upgrade.automountPatterns=/net. It is amulti-value property that is comma-delimited. For example, com.ptc.windchill.upgrade.automountPatterns=/net,/mnt. The Windchill Upgrade Manager will checkthis property in the Vaults and File Servers on page 59 step.

PreparingPreparing WindchillWindchill BusinessBusiness ReportingReportingforfor UpgradeUpgradeUpgrading Windchill Business Reporting requires some preparatory steps forCognos. Perform the following:

1. Take a dump of the Cognos schema from the source server.

2. Import the Cognos dump into a new Oracle SID or SQL Server instance.

3. Export the Cognos configuration setting from the source system.

a. Open the IBM Cognos configuration tool on the source system.

b. From FileFile ▶▶ Export AsExport As and save it as cogstartup.xml.

CautionCautionThe exported cogstartup.xml file contains unencrypted passwords, so ensurethat the location you save the file to is secure.


ExportExport thethe DatabaseDatabase andand LDAPLDAPExport the database and LDAP at the same time. The following section includesinstructions for exporting either from Windchill Directory Server or Aphelion.

ExportingExporting thethe DatabaseDatabase

PTC recommends that you export the database using the recommended proceduresin the documentation for your supported database.

ExportingExporting LDAPLDAP fromfrom WindchillWindchill DirectoryDirectory ServerServer

NoteNote• If the source and target installations already use same Windchill Directory

Server, then these steps are not needed.

• If your site uses an enterprise, corporate LDAP, you should export the LDIFfile, mentioned below, from that corporate LDAP.

The export command exports the entire LDAP structure, including all top levelnodes and their children. Once the exported LDIF file is created, it is placed in thesame directory path mentioned in the command (For example, \server\bat\PTCLdap_database\sourceLdap.ldif)

WindowsWindows

\server\bat\export-ldif.bat --backendID userRoot --ldifFile \server\bat\PTCLdap_database\sourceLdap.ldif

UNIXUNIX

/opt/ptc/windchillds/server/bin/export-ldif --backendIDuserRoot --ldifFile /opt/ptc/windchillds/server/bat/PTCLdap_database/sourceLdap.ldif

ForFor example:example:

C:\WindchillDS\server\bat\export-ldif.bat --backendIDuserRoot --ldifFile C:\WindchillDS\server\bat\PTCLdap_database\sourceLdap.ldif

ExportingExporting LDAPLDAP fromfrom AphelionAphelion

Export the source LDAP data.

WindowsWindows

1. Open a command prompt.

2. Change the directory to the virtual drive for Aphelion. The default is R.

3. Change the directory to R:\usr\var\lde\PTCLdap.


4. Execute the following:

R:\usr\sbin\lde\export -c "root" -o -fR:\usr\var\lde\PTCLdap\PTCLdap_lde.conf

5. Open the Aphelion lde.log.general file from the following location:

R:\usr\var\lde\PTCLdap\PTCLdap_logs\lde.log.general

Verify that the export completed properly by locating the following message inthe lde.log.general file: "Export of all requested databases completed."

6. If the export was successful, the export command will create the file under R:\usr\var\lde\PTCLdap. Place it on the target system.

UNIXUNIX

1. Change the directory to /opt/lde/var/PTCLdap.

2. Run the following command:

/usr/sbin/lde/export -c "root" -o -f/var/lde/PTCLdap/PTCLdap_lde.conf -l

3. Open the Aphelion lde.log.general file from the following location:

/opt/lde/var/PTCLdap/PTCLdap_logs/lde.log.general

Verify that the export completed properly by locating the following message inthe lde.log.general file: "Export of all requested databases completed."

4. If the export was successful, the export command will create the file under /var/lde/PTCLdap. Place it on the target system.

NoteNoteThe goal of this procedure is to have the source and target Base DNs on the sameLDAP server. This is necessary because at the end of the upgrade process, thetarget installation will be using the target Base DN, but its LDAP adapters will bepointing to the ou=people node that exists under source Base DN.

MigratingMigrating toto WindchillWindchill DirectoryDirectory ServerServerIf you are upgrading from a release of 9.x that supported Aphelion LDAP Server,you must migrate to Windchill Directory Server prior to upgrading your solution.

InstallingInstalling thethe WindchillWindchill DirectoryDirectory ServerServerUse the following procedure to install the Windchill Directory Server when you aremigrating from the Aphelion Directory Server to Windchill Directory Server orwhen you are updating an existing Windchill Directory Server to the latest version.


If you are installing the Windchill Directory Server as part of a new Windchillinstallation, you can select to install and configure Windchill Directory Server asone of the platform components. For installation details, see the WindchillInstallation and Configuration Guide.

NoteNoteBefore installing the Windchill Directory Server, ensure that there is no existinginstance of the server installed in the installation file path you are going to use forthe Windchill Directory Server. You cannot install over an existing instance;uninstall the existing instance or rename the installation directory before installingthe Windchill Directory Server. Before uninstalling an existing instance orrenaming the installation directory, be sure to stop the server, disable it as aWindows service (on Windows platforms), and close any Windchill DirectoryServer control panel windows. For details on how to uninstall a Windchill Direc-tory Server, see the Windchill Directory Server Administrator’s Guide.

If you are installing the Windchill Directory Server as part of migrating fromAphelion to Windchill Directory Server, follow the steps laid out in the Migratingfrom Aphelion to Windchill Directory Server on page 24; do not go directly to thesteps in this procedure. Following the steps in the migration process ensures thatthe installation of Windchill Directory Server is completed at the correct point inthe process.

Install the Windchill Directory Server using the PTC Solution Installer (PSI).

NoteNoteOn UNIX systems, only the user who installed the Windchill Directory Server ispermitted to use the control-panel or other Windchill Directory Serveradministrative functions. Therefore, carefully consider which identity to use whenperforming the Windchill Directory Server installation.

1. Examine the PTCLdap_lde.conf file to determine the port number, the LDAPadministrative user name, and the administrative password.

This file specifies the configuration information Aphelion uses when it starts,and PTC recommends that the same information be used when installing theWindchill Directory Server.

The following are typical file paths for the PTCLdap_lde.conf file:

• WindowsWindows

R:\usr\var\PTCLdap\PTCLdap_lde.conf

• UNIXUNIX

/usr/var/PTCLdap/PTCLdap_lde.conf

a. Open the PTCLdap_lde.conf file in a text editor.

b. Locate the port number. For example:

port 389


Use the same port number when you install the Windchill Directory Serverusing PTC Solution Installer (PSI).

c. Under the "lde database definitions" heading, locate the rootdn and therootpw. For example:

rootdn “cn=Manager”

rootpw password

When installing the Windchill Directory Server, put the rootdn value in theLDAPLDAP ServerServer AdministratorAdministrator DistinguishedDistinguished NameName field and the rootpw valuein the LDAP Server Administrator PasswordLDAP Server Administrator Password and the Confirm LDAP ServerConfirm LDAP ServerAdministratorAdministrator PasswordPassword fields.

If you decide that the Windchill Directory Server needs to be installed on adifferent host or port, or with a different LDAP administrator or password, youcan complete the migration procedure as documented using whatever host,port, or LDAP administrator you want, but you must also complete additionalsteps to reconfigure Windchill. See Manually Reconfiguring WindchillDirectory Server on page 27.

2. Select the SolutionSolution installation type option. Then select Standalone Product orStandalone Product orComponentComponent.

3. Choose Windchill Directory ServerWindchill Directory Server and Java Software Development KitJava Software Development Kit (JSDK).

NoteNoteWhen installing Windchill Directory Server as a standalone component,Windchill Directory Server should be installed outside the base installationdirectory (by default, the base installation directory is \ptc\Windchill_10 on Windows) and, it requires a JSDK that is separate from theWindchill solution’s JSDK.

4. As you enter the information to define the settings required for installing Wind-chill Directory Server, be aware of the following:

• Do not specify a Uniform Naming Convention (UNC) path name (such as\\host\path\to\JDK) for either the Java SDK or the Windchill Direc-tory Server installation directory file paths. Additionally, if you specify amapped or SUBST drive in the file path for the Windchill Directory Server,you cannot run the server as a Windows service.

• In the LDAP Base DNLDAP Base DN field, be sure to replace “o=ptc” with the Base DNthat was used with Aphelion or with an earlier version of the Windchill Di-rectory Server.

5. Complete the remaining installation steps as directed by PSI.

For additional details on using PSI to install the Windchill Directory Server,see the Windchill Installation and Configuration Guide.


NoteNoteOn Windows 2008 servers, you cannot start or stop the Windchill Directory Serverwhen the User Account Control (UAC) feature is enabled. Although you can openthe Control Panel, you also cannot authenticate and therefore, cannot view ormodify directory entries. Complete the following steps to disable UAC:

1. From your Windows 2008 Control Panel, click User AccountsUser Accounts.

2. In the User AccountsUser Accounts window, click User AccountsUser Accounts (skip this step is you areusing the classic Control Panel view).

3. Click Turn User Account Control on or offTurn User Account Control on or off.

4. Clear the Use User Account Control (UAC) to help protect your computerUse User Account Control (UAC) to help protect your computer checkbox and click OKOK.

5. If the User Account ControlUser Account Control window displays, click ContinueContinue.

6. Click Restart NowRestart Now or Restart LaterRestart Later and close the User AccountsUser Accounts window.

You must restart your system to disable UAC.

VerifyingVerifying thethe WindchillWindchill DirectoryDirectory ServerServer InstallationInstallationYou must verify that your Windchill Directory Server installation was successful.To do so, follow these steps:

1. Verify that the Windchill Directory Server control panel is running. If thecontrol panel is not running, start it. For more information, see the WindchillDirectory Server Administrator’s Guide.

NoteNoteYou can use the control panel Manage EntriesManage Entries option to verify that the Wind-chill Directory Server is running and that it contains the same entries asAphelion (if you are migrating from Aphelion) or an earlier version of theWindchill Directory Server (if you are updating the Windchill Directory Serv-er). However, this does not verify correct operation with Windchill.

2. Start your Windchill solution and verify correct operation. If Windchill startsand users can log in, then the Windchill Directory Server installed correctly.


MigratingMigrating fromfrom AphelionAphelion toto WindchillWindchill DirectoryDirectoryServerServerIf you are upgrading from a previous release of Windchill that used Aphelion as itsLDAP directory, you must migrate your LDAP information to the Windchill Direc-tory Server.

NoteNoteIf you are upgrading from a previous Windchill release and are using Aphelion,review this chapter before upgrading Windchill or installing the Windchill Direc-tory Server. In particular, note that the Windchill Directory Server must not beinstalled as part of the Windchill upgrade process.

ImportingImporting ExportedExported DataData intointo thethe WindchillWindchill DirectoryDirectoryServerServerAfter the Aphelion data has been exported from Aphelion and cleaned up toremove Aphelion-specific information, you can import the resulting LDIF file intothe Windchill Directory Server.

NoteNoteBefore importing data, ensure that you have all required Base DNs created in theWindchill Directory Server. One Base DN is defined during the installation.Additional Base DNs must be manually created. If you need to create additionalBase DNs, see the section titled Creating Additional Base DNs in the WindchillDirectory Server Administrator’s Guide.

Use the following steps to import the exported data:

1. Start the Windchill Directory Server control panel by running the followingcommand. Log in as the directory administrator.

• WindowsWindows

\server\bat\control-panel.bat

• UNIXUNIX

/server/bin/control-panel

2. Import the Aphelion LDAP directory entries into the Windchill Directory Serv-er by completing the following steps:

a. Select Directory DataDirectory Data ▶▶ Import LDIFImport LDIF in the control panel.

b. Ensure that the BackendBackend drop-down list is set to userRootuserRoot.

c. In the File to ImportFile to Import field, enter the location of the migrated LDIF file froma previous task.


d. For Import TypeImport Type, use the default (Overwrite Any Existing DataOverwrite Any Existing Data) whenimporting data that was exported from Aphelion into a new Windchill Di-rectory Server.

If you have existing data that you do not want replaced, you can selectAppend to Existing DataAppend to Existing Data; however, you can also select Replace Entries thatReplace Entries thathave Matching DN’s with Imported Valueshave Matching DN’s with Imported Values if you want the imported data tooverwrite any entries that are duplicated by the imported data.

e. Select Write Rejected Entries to a FileWrite Rejected Entries to a File and browse to select a file path. Thefile path should be a full file path.

f. Select Write Skipped Entries to a FileWrite Skipped Entries to a File and enter a file path. The file pathshould be a full file path.

g. To perform the import, click OKOK.

h. Check the rejected file and skipped file to determine if any entries failed toimport. Only a few entries, if any, should appear. If they are Aphelion-specific, you can ignore the entries. If they are entries for users, groups, orany other Windchill data, correct the entries and ensure that the entries areadded before continuing.

The output from the import includes a completion message and a count ofthe number of entries imported.

NoteNoteAn Aphelion LDIF file normally contains an entry withobjectclass=accessControlSubentry. This is an Aphelion-only entry and isnot valid in theWindchill Directory Server; therefore, it appears in therejected file and can be ignored.

Some sites may have created password policies which would cause entrieswith objectClass=pwdPolicy to be rejected. These rejected files can beignored during the import operation. For more information on passwordpolicies, see the Windchill Directory Server Administrator’s Guide.

If rejected entries are related to users, groups, or any other Windchill data,correct the problem in the LDIF file and repeat the steps to import it.

After the import step has succeeded, the Windchill Directory Servercontains all the data that was in the Aphelion directory, including all theentries that comprise the hierarchy in the directory information tree.

ReplacingReplacing AphelionAphelion withwith WindchillWindchill DirectoryDirectory ServerServerNoteNoteThe Aphelion installations local to the replica servers need to be updated as well asthe Master. The process for doing this is exactly the same as it is for the masterserver, as described below.


To replace Aphelion with the Windchill Directory Server, follow these steps:

1. Determine the base distinguished names (Base DNs) that must be defined inthe Windchill Directory Server.

NoteNoteThe term Base DN used here refers to the highest level entry in the hierarchy ofentries held by an LDAP server. This term is related to the LDAP term NamingContext, which refers to the set of entries, starting with the Base DN, that isheld by an LDAP server. The Base DN is sometimes called a suffix.

Use the following procedure to determine these Base DNs:

a. Open the LDAP browser.

The LDAP browser displays the ConnectConnect window.

b. Select the preferred connection name from the SessionSession list and clickConnectConnect.

The BTBT LDAPLDAP Browser/Browser/EditorEditor window opens.

c. Expand the Root DSERoot DSE folder to see the entries at the top of the directorytree and immediately below the Root entry. A Base DN must be defined inthe Windchill Directory Server for each of these entries.

NoteNoteThe cn=accessControlSubentrycn=accessControlSubentry is an Aphelion-specific entry and shouldnot be used to define the Windchill Directory Server Base DNs.

In your window, the Base DN that you are using is shown.

If multiple Base DNs must be defined, the window shows multiple entriesbelow the cn=accessControlSubentry entry.

If your window shows multiple entries below thecn=accessControlSubentry entry, you must define more than one Base DNin the Windchill Directory Server. However, only one Base DN can bedefined during installation. When installing Windchill Directory Server,specify one Base DN in the LDAP Base DNLDAP Base DN field, replacing o=ptc.

If you need to define additional Base DNs, you must manually create themafter the installation is complete. For more information on this procedure,see the Windchill Directory Server Administration Guide.

NoteNoteBe sure to create additional Base DNs before importing data.

2. Shut down Windchill and then Aphelion.


You can use the windchill command to shut down Windchill. For windchillcommand details, see the Windchill Installation and Configuration Guide.

3. The Windchill Directory Server installation includes an LDAP data migrationtool. The tool removes Aphelion proprietary attributes and decrypts userpasswords from the exported Aphelion LDIF file.

Execute the LDAP data migration tool by entering the following commandfrom a windchill shell:

java -jar /tools/MigrateLdif.jar

-input -output

where is the directory where the Windchill Directory Serv-er is installed.

Use the file created in this step in the next task.

ManuallyManually ReconfiguringReconfiguring WindchillWindchill DirectoryDirectory ServerServerNoteNoteIf you have followed the recommended migration steps that have you use the samehost, port, and LDAP administrative user that were used with Aphelion, you canskip this section. For more information, see Migration Procedure on page 24.

Windchill is configured to connect to an LDAP server. If, as part of your migrationfrom Aphelion to Windchill Directory Server, you have configured any of thefollowing settings to values that are different from the values used for Aphelion,you must manually reconfigure your Windchill system:

• Windchill Directory Server host

• Windchill Directory Server port

• LDAP administrative distinguished name (DN) or password

NoteNoteThe data content of the new Windchill Directory Server must be identical to thedata content of your existing Aphelion Directory Server. This includes thehierarchical tree structure and the contents of the entries.

To manually reconfigure your Windchill system, complete those tasks from thefollowing list that are appropriate for your Windchill system:

• Update the JNDI adapter entries in the new Windchill Directory Server thatwere imported from Aphelion. This task is required if you have changed theLDAP host or port.

See Updating JNDI Entries on page 28.

• Update Windchill properties files. This task is required if you have changed theLDAP host or port or have changed the LDAP administrative DN or password.


• Reconfigure Apache or the web server being used. This task is required if youhave changed the LDAP host or port.

See the documentation for the web server that you are using to determine thereconfiguration procedure.

For complete Apache reconfiguration information, see the WindchillInstallation and Configuration Guide.

• If you have installed other products that directly connect to the LDAP server,you may need to reconfigure these products as well.

To determine if changes are required, see the appropriate documentation forthose products. For example, if you have installed Windchill Business Report-ing, see the Windchill Installation and Configuration Guide for information onthe LDAP configuration that is required for that product. For third-partyproducts such as the Sun Java Web Server and IBM HTTP Server, see yourproduct documentation.

If your system is set up in any of the following ways, be aware that you may needto make modifications to the instructions provided in this section:

• The system uses a separate enterprise LDAP directory.

• The system has set up non-privileged LDAP access.

• The system has other Windchill configuration changes affecting your LDAPserver.

UpdatingUpdating JNDIJNDI EntriesEntriesThe JNDI adapter entries in your LDAP directory provide the attributes thatWindchill uses to access other services such as LDAP. If you change the LDAPhost or port number, you must update the appropriate Windchill JNDI adapterentries.

Typically, you need to update several JNDI adapter entries. To locate the entries,start the Windchill Directory Server control panel and browse the directory to findthe entries. The entries are located under an entry with a DN similar to:

dc=MyHostName,dc=MyCompany,dc=com,cn=configuration,cn=Windchill_10.x,

o=MyCompany

The four entries you need to modify have names similar to:

ptcServiceName=com.MyCompany.Ldap

ptcServiceName=com.MyCompany.EnterpriseLdap

ptcServiceName=com.MyCompany.MyHostName.ldap-pending

ptcServiceName=com.MyCompany.MyHostName.servlet

where com.MyCompany represents the inverted format of the fully qualifiedserver domain (such as com.acme.acmenet) and MyHostName represents the hostname of the Windchill server (such as host123). For information about identifyingdomain and host names, see the Windchill Installation and Configuration Guide.


Each of the previous entries contains a ptcProperty attribute with several values.The content of the appropriate ptcProperty value varies depending on the entry youare modifying. Modify the value of the ptcProperty attribute that contains theLDAP URL to reflect the new host name and port number. When modifying thevalue, change only the host and port number of that value.

Review the following samples to help determine the appropriate value of theptcProperty attribute for each of the above three entries on your system:

• For the ptcServiceName=com.MyCompany.Ldap entry, the value issimilar to:

com.MyCompany.Ldap.java.naming.provider.url=ldap://

:

• For the ptcServiceName=com.MyCompany.EnterpriseLdap entry,the value is similar to:

com.MyCompany.EnterpriseLdap.java.naming.provider.url=ldap://

:

• For the ptcServiceName=com.MyCompany.MyHostName.ldap-pending entry, the value is similar to:

com.MyCompany.MyHostName.ldap-pending.java.naming.provider.url=ldap://

:

• For the ptcServiceName=com.MyCompany.MyHostName.Servletentry, the value is similar to: com.MyCompany.MyHostName.servlet.administration.baseUri=ldap://:/dc=MyHostName,dc=MyCompany,dc=com,

NoteNotePort 389 is the default. If no port number is present, 389 is assumed.

Replace the existing and in the JNDI adapter entries with the new values foryour Windchill Directory Server.

Updating Windchill Properties

To reflect any changes to the LDAP host or port, or changes to the LDAPadministrative DN or password, you must update Windchill properties files.

Updating properties involves using the xconfmanager utility to update your site.xconf file. The xconfmanager commands shown have been formatted to fit thepage; enter each command on one line.

PTC recommends that you make a backup copy of your site.xconf file beforemaking any changes. Then, if you encounter problems, you can restore the originalsite.xconf file.


Review the following steps to determine how to make the required updates on yoursystem.

NoteNoteThe specific changes you need to make depend on your Windchill configurationand any changes you have made to it.

The following steps illustrate how to make updates to an out-of-the-boxinstallation:

1. Navigate to the Windchill installation directory and create a backup copy ofyour site.xconf file.

2. Start a windchill shell.

3. From the windchill shell, update the Windchill properties in the usingxconfmanager commands similar to the following:

• For changes to the port or host of the LDAP server:

xconfmanager -s "ie.ldap.serverHostName="

-t "codebase/WEB-INF/ieStructProperties.txt"

xconfmanager -s "ie.ldap.serverPort="

-t "codebase/WEB-INF/ieStructProperties.txt"

xconfmanager -s “wt.federation.ie.ldapServer=ldap://

:”

• For changes to the LDAP administrative DN or password:

xconfmanager -s “ie.ldap.managerPw=”

-t “codebase/WEB-INF/ieStructProperties.txt"

xconfmanager -s “ie.ldap.managerDn=”

-t “codebase/WEB-INF/ieStructProperties.txt"

Updating the ieStructProperties.txt file also updates mapcredentials valuesfor both the Ldap adapter and the MyHostName.ldap-pending adapter.

4. If you have made changes to the LDAP administrative DN or password, youalso need to use the xconfmanager to modify the mapCredentials.txt file asfollows:

• Remove an extraneous entry for the Ldap adapter by entering a commandsimilar to the following:

xconfmanager --remove "mapcredentials.admin.adapters=

com.MyCompany.Ldap^cn=OldManager^oldpassword"


-t "codebase/WEB-INF/mapCredentials.txt"

• Remove the old information for the enterprise LDAP connector and addnew information by entering commands similar to following.

NoteNoteSkip this step if you are using a separate enterprise LDAP directory server.

xconfmanager --remove "mapcredentials.admin.adapters=

com.MyCompany.EnterpriseLdap^cn=OldManager^oldpassword"


xconfmanager --add "mapcredentials.admin.adapters=

com.MyCompany.EnterpriseLdap^cn=NewManager^newpassword"


NoteNoteIn these commands, replace OldManager, NewManager, oldpassword,and newpassword with the appropriate values for your Windchill DirectoryServer. Be sure to keep the ^ character between the values.

5. Apply all of the changes you have made to the site.xconf file to thecorresponding properties files by entering the following command:

xconfmanager -p

CleaningCleaning UpUp SystemSystem FilesFiles andand UninstallingUninstalling AphelionAphelionComplete the following steps to clean up any system configuration files that wereused with Aphelion and to uninstall Aphelion:

1. If you installed the Aphelion Web Tools and are using the Apache Web server,update the Apache configuration as follows so that the Aphelion configurationfile is not referenced:

a. Locate the following Apache configuration file on the instance of Apachebeing used by Windchill and Aphelion:

/conf/extra/additions.conf

where is the Apache installation directory.

b. Open the additions.conf file in a text editor.

c. Add the comment character to the beginning of the app-aphelion.conf linein the file as follows:

#Include conf/extra/app-aphelion.conf

d. Save your changes and close the file.

Updates to the Apache additions.conf file are in effect the next time youstart Apache.


NoteNoteAfter making this change, you can no longer use the Aphelion Web Tools.

If you are using a Web server other than Apache with the Aphelion Web Tools,check your Web server configuration to ensure that any references to the webtools have been removed.

2. If you are using UNIX and have created a script that starts the Aphelion everytime you reboot your machine, disable the script.

For details on how to generate a new shell script to start, stop, and restart theWindchill Directory Server, see the Windchill Directory Server AdministrationGuide.

3. Uninstall Aphelion.

For details, see “Uninstalling Aphelion” in the Windchill Upgrade Guide: 8.xto 10.1.

NoteNoteYou may want to leave the Aphelion Directory installed for a period of time asa backup. If you choose to do so, modify the port number in the Aphelionconfiguration file, PTCLdap_lde.conf, so the Aphelion and the Windchill Di-rectory Server ports do not conflict.

BackBack UpUp WindchillWindchill VaultsVaultsBack up your Windchill vaults on the master site as well as any remote sites.

SettingSetting UpUp thethe TargetTarget SystemSystem forfor UpgradeUpgradeThis chapter describes how to set up your target system for an upgrade. For anoverview of the entire upgrade process, consult the section “Upgrade Overview.”

PreparingPreparing WindchillWindchill IntegrationsIntegrations forfor EmbeddedEmbeddedSoftwareSoftware forfor UpgradeUpgradeUpgrading Windchill Integrations for Embedded Software requires somepreparatory steps for the SCMI ClearCase adapters.

After installing the target system with Windchill Integrations for Embedded Soft-ware, you must manually create the SCMI ClearCase adapters on the targetsystem’s LDAP DN with the exact ClearCase adapter name and properties as thesource system, including the DefaultAdapter. This can be done on the target systemthrough the Software Adapters AdministrationSoftware Adapters Administration user interface by an administrator.For information regarding how to configure the properties, see the Info*EngineImplementation Guide.


InstallInstall thethe TargetTarget SystemSystemThis section provides the order in which you should install your target system. Forspecifics on installing the target system, see the Windchill Installation andConfiguration Guide.

NoteNoteThe design and implementation of the desired target Windchill architecture isdriven by customer requirements. Design your target Windchill system based onyour individual business objectives. The design will impact the following steps thatinstall the target system for upgrade.

1. PTC requires that you use the same operating system (OS) platform if it issupported. Set up your hardware using your existing OS or upgrade your OS.

2. Use a database version that is supported on the target system. If you areupgrading your database to a higher release, this is the point in the process tocomplete the database upgrade. If you are migrating from Oracle to SQLServer, see the Oracle to SQL Server Migration Guide for supported paths.

3. Install any other third party applications such as JSDK, Solr (WindchillIndexing), Cognos (Windchill Business Reporting), or TIBCO (Windchill ESI).

4. Install all of the necessary Windchill solutions and optional products. TheWindchill solution installation must include a supported web server. Thisshould also include Windchill Information Modeler if you will be deployingmodeled customizations. If your source system uses multibyte characters,select the multibyte character option when configuring the Windchill database.

When installing Windchill Directory Server, your solution should beconfigured differently based on whether you migrated from Aphelion as part ofthis upgrade:

• If you migrated from Aphelion during this upgrade, you have alreadyinstalled the target Windchill Directory Server. Use the PTC SolutionInstaller’s (PSI) option to Configure to an existing instanceConfigure to an existing instance for WindchillDirectory Server.

• If you already use Windchill Directory Server with your source system, dothe following:

○ Verify that you have exported the LDIF file. For more information, seeExport the Database and LDAP on page 19.

○ Uninstall the source system’s Windchill Directory Server.○ Use the PTC Solution Installer’s (PSI) option to Install and configureInstall and configure to

create a new instance for Windchill Directory Server.


Also, the value entered in Base Distinguished Name for Product PropertiesBase Distinguished Name for Product Properties inPSI must be different from the source DN. The LDAP Base DNLDAP Base DN is the root andcan be same for the source and target systems.

If you are not sure about your source system's Base DN, please look at thevalue of property "ie.ldap.propertyBaseDn" in your /site.xconf fileon your source Windchill installation. You also need to choose your databaseoptions. You can create a new database or use an existing database, and youmust create a new database installation user or use an existing databaseinstallation user. If you chose the former, you’ll need to create the databaseinstallation user for the target installation before running PSI.

When specifying the adminstrative settings, the value of the OrganizationOrganizationInternet Domain NameInternet Domain Name in PSI during the target Windchill installation should bethe same as the Organization Internet Domain NameOrganization Internet Domain Name of the source system. Lookat the value of the property "wt.inf.container.SiteOrganization.internetDomain"in your /site.xconf file on your source Windchill installation tofind the value.

5. Apply the latest maintenance releases and patches, if applicable. If you aredoing multiple upgrade passes, check for and install the latest maintenancereleases, if applicable, before each upgrade pass. See the Upgrade Resourceand Migration page for details.

6. If your target solution implements a cluster configuration, install and configurehardware cluster nodes. For more information on cluster configurations, see theWindchill Advanced Deployment Guide.

NoteNoteYou would need to convert the cluster to a monolithic configuration at a laterstep. For more information, see Converting to a Single Server System on page44.

7. If the system you are upgrading uses Windchill File Server, you must install theWindchill File Server software on the remote servers before the upgrade. Wheninstalling the target system with the PTC Solution Installer, select the optionEnableEnable RemoteRemote FileFile ServerServer SupportSupport. After the upgrade is complete, theWindchill server will re-broadcast out to the remote Windchill file servers andreplication and vaulting will work as it did prior to the upgrade. For a testupgrade, cloning of a remote file server is recommended, but not requiredunless your test upgrade has content mastered on File Server sites and youwould like to upgrade vault content during the upgrade. Follow the steps belowto install and configure file servers before the upgrade. This set up is required ifyou want to update File Server Configuration during upgrade by selectingUpdate File Server ConfigurationUpdate File Server Configuration for the File Server drop down in the GatherUpgrade properties phase in the Upgrade Manager.


a. Install File Servers. See Set Up File Servers on page 35 for moreinformation.

NoteNoteYou can choose to install the target File server on the same host where theproduction (source) File server is installed for a production upgrade.However, for a test upgrade, install the target File server on a different hostthan the production File server host as content will be modified during theupgrade and you do not want to modify production content during a testupgrade.

b. Get the public key from the source server found at \codebase\CCSTools\key.

c. Copy the public key found in the previous step to the target master site at\codebase\CCSTools\key.

d. Copy the public key to all the File Server sites in the location specified bythe following property in the wt.properties file on File Server:

wt.intersvrcom.masterSite.1=masterurl,

The key needs to be copied to the location indicated by

e. Copy vault content as described in Copy Vaults Content to New Hardwareon page 51.

f. Verify that the method server is running on the File servers before youbegin the upgrade on the master site.

8. Run the windchill version to confirm that all the required components arereported as installed.

9. Verify the installation was successful by checking the method server log forany errors or warnings.

InstallInstall WindchillWindchill PartsLinkPartsLinkIf your source server includes Windchill PartsLink, perform the following:

1. Install the Windchill PartsLink Client using the same Windchill schema(Database User).

2. Install the Windchill PartsLink Server outside of the Windchill load point forthe target release and make sure it uses a database schema other than theWindchill database schema.

SetSet UpUp FileFile ServersServersPerform the following steps to set up your file servers:


1. Install the File Server sites so they are all at the same release level with themaster site.

The locations of the File Server folders must not be changed during theupgrade. The files that are stored there are user-uploaded content referencedfrom the master site. These files were accessible to Windchill before theupgrade and must be accessible after the upgrade. When File Server starts, itwill ask the master site for the local storage locations. The master site willprovide the locations, which will still be correct, unless the folders were movedduring the upgrade.

2. Start up the sites and make sure that the master site is able to broadcastconfigurations to the File Server sites. For detailed broadcast instructions, seethe Windchill Installation and Configuration Guide.

IncorporateIncorporate CustomizationsCustomizations intointo thethe TargetTarget SystemSystemThis section describes the process of incorporating customizations into the targetsystem.

CustomizedCustomized PropertiesPropertiesIf you have added or customized any properties in your source system, you shouldhave done so using site.xconf as recommended in the Windchill CustomizationGuide. To incorporate these into your target system, perform the following steps:

• Review the entries in your source site.xconf file and add or update the targetsite.xconf file. The default values of your customized properties may have beenchanged in the target system. If you have customized the property values on thesource system by modifying the source defaults, then you want to do the samemodifications on target instead of just copying the tag from sourcesite.xconf to target site.xconf.

• Copy any XCONF files that you added to your source system, and put them intheir equivalent locations in your target system. After copying the XCONF fileover to the target system, review all of the properties in these files to make surethat they are valid and updated for the target system.

ModelModel andand SourceSource CodeCode CustomizationsCustomizations

IntroductionIntroduction

This document describes the process required to bring forward modeledcustomizations to the Windchill 10 release. Modeled customizations consist of themodels (*.cat and *.mData files) and generated Java source files (*.java) initiallydiagrammed in Rational Rose and generated via Windchill’s system generationtools. This document covers the conversion process specifically and does notaddress issues pertaining to the use of deprecated classes and APIs (that may have


been removed in Windchill 10.0), client refactorings (and redesigns) that may benecessary to incorporate customizations into the new user interface, or adjustmentsthat may be necessary due to extending defunct classes (like WTProduct, forexample).

Windchill 10 no longer utilizes Rational Rose to model persistent (and other)classes; persistent classes are now described via Java annotations. Similarly,Windchill 10 no longer relies on system generation to generate the model;annotation processors within the Java compiler itself process the annotations andgenerate the appropriate logic.

Modeled customizations are brought forward by augmenting the existing Javasource files of persistent classes with annotations equivalent to that of the Rosemodels and by removing from these source files source that will be handled byannotations processors. The result is a completely user-managed source file withnone of the familiar preservation markers. These source files will extendcompletely compiler-generated “_” class files. Modeled classes that did notcontribute to schema will have the preservation markers stripped, but will,otherwise, be unchanged.

PrerequisitesPrerequisites

The conversion itself requires that the existing customization be available and inworking order. A common mistake when bringing a modeled customizationforward is to assume that it’s sufficient to simply regenerate (from *.cat and *.mData files) new source in the new release. This approach generally appears towork (compile), but the new source files will be missing any user-preserved code.This causes upgrades and basic functionality to break, something people who trythis approach tend not to discover until they’re in the middle of an upgrade and itaborts.

Also required from the pre-Windchil 10 system are the Rose models themselves(the “Module” directory), and various properties files. These files will be used to“bootstrap” an environment sufficient to execute system generation. It is systemgeneration itself that unmodels customization and adds annotations.

The conversion itself is in executed in a Windchill 10 environment and requiresInfoModeler. It is preferable to install the same solutions into the Windchill 10environment as were installed in the pre-Windchill 10 customization environment.The Windchill 10 installation includes everything needed to run the conversion(there are no additional tools to download).

The wt_home_pre location used in the following steps must, at a minimum,contain these files from the pre-Windchill 10 source system:

• The entire src tree that was used to develop the customizations

• The entire Module folder

• The (optional) wtCustom folder

• The properties files in the root of codebase


If you are changing hardware or operating systems, see Changing Platforms onpage 11 for supported scenarios.

NotesNotes

The conversion consists of the execution of a set of commands in a commandprompt. Bash is assumed for UNIX variants (including Linux) and the standardDOS command prompt on Windows. Both Windows and UNIX commands will bedemonstrated where they deviate; if they’re equivalent, a single command will beshown.

The document assumes customizations in “Windchill/src” (load_point/src).Customizations utilizing a modular structure will require that the source be presentin the module location and will necessitate (minorly) tweaking the commandsspecified.

Commands are executed in a Windchill shell. The Windchill shell willautomatically assign the “WT_HOME” environment variable. Since files will becopied from the location of the “source” (pre-Windchill 10) system, it must beaccessible locally (if the pre-Windchill 10 system is installed on a different host,share the location to make it accessible to the current host).

All commands are assumed to be executed within the WT_HOME directory.Furthermore, commands are preceded by a letter/dot (“a.”, “b.”). The letter/dot isnot part of the command, however each letter/dot command is a single (one-line)command regardless of word wrapping.

InstructionsInstructions

1. Start a Windchill shell.

NoteNote“load_point” is the location of the Windchill 10 installation (For example, /opt/ptc/Windchill on UNIX or C:\ptc\Windchill on Windows).

a. cd load_point

b. bin/windchill shell

2. Execute the following command:

NoteNoteThis step can be performed repeatedly, since it will start with the java files fromthe source_load_point each time it runs. It will copy everything required fromthe source system, perform the conversion, and remove obsolete model andjava files from the target. To see the individual targets that are run, run theconvert_source_to_target.help target with the same options.


ant -f /utilities/RoseModelConverter/RoseModelConverter.xml convert_source_to_target-Dcust_pkg=-Dwt_home_pre=

The is the location of the pre-Windchill 10 systemcontaining the files referenced previously (For example, /opt/ ptc/Windchill9.0). The is the top-level package of the customization(For example, ext.acme).

3. Verify that the files have been converted. Rose preserve markers should beremoved from all files and modeled files should contain annotations.

CautionCautionDo not proceed until it is clear that the source has been converted!

4. Optional:

Convert resource bundles (rbInfo files) of type StringResourceInfo to Javasource files. It is recommended to execute this step if developing using IDEs,as Java-based bundles are much more IDE-friendly than rbInfo-based bundles.

ant -f bin/tools.xml bundle_convert -Dbundle_convert.path=

5. If you have any StringResourceInfo rbInfo files representing text tailoring ofout-of-the-box Windchill strings in your wtCustom folder, perform thefollowing:

a. See the section Converting Customized User Interface Messages on page41 before building your customizations.

b. Return to this point in the process and continue.

6. Build all customizations:

ant -f bin/tools.xml customer_build

This compiles all bundles and java classes, generate sql scripts, and applliesany column and bundle customizations that have been made. To see theindividual targets that are run, execute the customer_build.help target.

NoteNoteRead the section titled “Compile Notes” that follows this section for importantinformation about this command.

7. Load the schema generated by the previous step. The actual commands willvary based on the database used.

8. Start Windchill and verify the customization.


CompileCompile NotesNotes

The Rose to annotations conversion script, executed in step 6, addresses most ofthe necessary changes. There are, nonetheless, aspects of the conversion which willneed to be handled manually.

initialValueinitialValue

The initialValue annotation member is assigned to a string that’s directlysubstituted as the assigned initial value for the field generated for the givenproperty. For example, @GeneratedProperty(name=”anInt”, type=int.class,initialValue=”42”) will generate the declaration int anInt = 42;. This works untilthe initial value is something like “MyUtilClass.MY_INT_CONSTANT”, whereMyUtilClass is not in the same package as the class containing the annotation/initialValue. The reason for this is that the “_” classes contain no importstatements, making MyUtilClass unresolvable in the generated class, which willultimately manifest itself as a “cannot find symbol” compile error. Fix this byfully-qualifying the class (For example, “com.acme.util.MyUtilClass.MY_INT_CONSTANT”).

Class.Class.getDeclared*getDeclared*

Fields modeled in Rose and generated into the business class are now modeled inannotations and generated into the superclass (the “_” file/class). It was possible(to reuse the initialValue example) to reflect on Rose-generated properties, as inMyClass.class.getDeclaredField(“anInt”). Once converted to annotations, the fieldwill no longer be declared in MyClass; it will be declared in MyClass’s parent,_MyClass, breaking the reflective call. Fix this by injecting a getSuperClass() call:MyClass.class.getSuperClass().getDeclaredField(“anInt”). Do not fix this byreplacing MyClass with _MyClass: the “_” files should never show up in source!

warning:warning: [unmodeled][unmodeled]

Annotation processing adds a new warning "unmodeled" to indicate that anabstract or concrete "GenAs" class is implementing a non-GenAs (unmodeled)interface. This warning exists to highlight situations in which interfaces that werenot persistent (did not extend Persistable) are being implemented by persistentclasses. The Rose (system) generation behavior in this situation was to treat theunpersistent interface as though it were persistent and to persist its fields.Annotation conversion, however, annotates only the interfaces and classes thatextend or implement ObjectMappable, so these unpersisted interfaces areconverted as un-annotated source files, with the result being that any fields thatmay have become persisted on the interface are lost to the implementing class(es).

In the unlikely event that your customization includes classes which acquireschema from unpersisted interfaces, it is possible to detect the loss of this schemaduring conversion by comparing the new schema with the old, but this warningmakes detection much easier.


If you see this warning, determine if it matters to you. If it does not matter, simplysuppress "unmodeled" at the class level in the implementing class by adding"@SuppressWarnings("unmodeled") just prior to the class declaration. If it doesmatter, append the fully-qualified interface name to the comma-delimited list of"unpersistable" interfaces by manually adding the property wt.generation.unpersistable.interface to user.properties and reconvert (for example wt.generation.unpersistable.interface=a.b.InterfaceX,c.d.InterfaceY). Windchill will convert it asa "GenAsUnPersistable".

CustomCustom JNDIJNDI AdaptersAdapters

If there are any custom JNDI adapters on the source system, you must configureand validate those adapters on the target Windchill server before running theupgrade.

ConvertingConverting CustomizedCustomized UserUser InterfaceInterface MessagesMessagesIf you have any StringResourceInfo rbInfo files in your wtCustom folder, theyneed to be converted. This is necessary because the out-of-the-box WindchillStringResourceInfo bundles have been converted from rbInfo to java files tofacilitate IDE usage. See the Windchill Customization Guide for details oncustomizing bundles.

The rbInfo files that need to be converted are those with this as the first line:

ResourceInfo.class=wt.tools.resource.StringResourceInfo

There is a utility to perform the conversion. It requires the wtCustom files to existin the target system. If you converted Rose model customizations, the wtCustomfolder should already have been copied from the source system to the targetsystem. After ensuring the wtCustom files are available, run this target to performthe conversion:

ant -f bin/tools.xml custom_convert

Each StringResourceInfo rbInfo file will be converted to the same file name with a.converted extension and aggregated into wtCustom/wt/util/resource/resourceCustomize.rbInfo. The custom_convert target will do nothing ifresourceCustomize.rbInfo already exists. The original file will be renamed to havea .orig extension. The *.converted and *.orig files can be removed once theconversion has been verified.

Run this script to build the converted customizations:

ant -f bin/tools.xml bundle_custom -Dbundle.recurse=true

See the Windchill Customization Guide for details on verifying customizations anddeploying them for runtime.


ConvertingConverting UserUser InterfaceInterface CustomizationsCustomizationsIn addition to converting modeled customizations, if you have user interface (UI)customizations that were done using JCA architecture, then you need to redeploythese customizations on the target system. JCA architecture supports the new MVCparadigm in Windchill 10.0. If you wish to convert your existing JCAcustomizations to use these new JCA features, then you can do so after the upgradeis complete. See the Windchill Customization Guide for additional details.

ConfiguringConfiguring YourYour SeriesSeries forfor UpgradeUpgradeTo configure your series for upgrade, perform the following:

1. Verify that the wt.series.* properties in your \codebase\wt.properties are in sync with the source system’s wt.properties file.

Keep the following in mind:

• Any changes must be made in the site.xconf file and propagated to this file.

• If you wish to make a change to the target system’s series, the change mustbe done post-upgrade.

2. If your source system has file-based series, then you need to verify that the file-based series on the target system is in sync with the source system’s file-basedseries. Ensure that the versioning scheme is set up in wt.properties on the targetsystem exactly like it is on the source system.

NoteNoteIf you wish to make a change to the target system’s file-based series it must bedone post-upgrade.

3. If your source system has customized series that are not wt.properties based,then you need do one of the following:

• Move the custom series to a file-based series before upgrade. Remove anycustomizations. PTC highly recommends this to avoid upgrade issues.

• If the file-based series is not available on your source system, then thecustomizations will need to be ported to the target system before upgrade.Post-upgrade, you should move the custom series to a file-based series andremove the customizations.

4. Verify that there are object initialization rules (OIRs) for every versioned objecttype in the system and that they are using a valid series (defined in wt.properties or a file-based series). Ensure that the wt.properties has the sameseries configuration as the source system.


IncreaseIncrease thethe MethodMethod ServerServer HeapHeap SizeSize (Optional)(Optional)For some sites, migrators, WinDU tasks and other tools may fail with Out ofMemory Exceptions because of the lower heap size default setting. To preventthese errors, perform the following.

Using xconfmanager, update the site.xconf file by adding or changing thefollowing properties based on available memory on your installation:

• wt.method.maxHeap

• wt.method.minHeap

• com.ptc.windchill.upgrade.tools.java.args

CopyingCopying ContainerContainer TemplatesTemplates ContentContent FolderFolderFor Windchill ProjectLink or integral Windchill PDMLink and WindchillProjectLink, perform the following steps:

1. Back up the files located under /loadXMLFiles/content.

2. Copy the files located under /loadXMLFiles/content

to

/loadXMLFiles/content

with the directory hierarchy preserved.

StepsSteps forfor WindchillWindchill GatewayGateway forfor CadenceCadence AllegroAllegroDesignDesign WorkbenchWorkbenchThe Info*Engine adapter created on the source server will not be migrated to thetarget Info*Engine during the upgrade. You need to recreate this adapter on thetarget Info*Engine server. The Info*Engine adapter created on the target systemwill need to have the same values as the source Info*Engine adapter for: ServiceName, Host and port number, domain and guid so that parts which were in syncbetween ADWand Windchill prior to upgrade will remain so after the upgrade. Forexample:


You will also need to download the latest Windchill Gateway for Cadence AllegroDesign Workbench (ADW) Client installer and reinstall the target ADW Client:

1. From the target Windchill home page, go toQuick LinksQuick Links ▶▶ Software DownloadsSoftware Downloads.

2. Click on Cadence Allegro Design Workbench Adapter InstallationCadence Allegro Design Workbench Adapter Installation .

3. Download the installer file, and extract it on the client machine.

4. Click setup.vbs to run the installer.

VerifyVerify thethe TargetTarget SystemSystemVerify the successful operation of the target system. Exercise any use cases that areof particular importance in your usage of Windchill. If you transformed anycustomized UI configuration files, then access the corresponding user interfaces(UIs) to verify that your transformations work correctly.

ConvertingConverting toto aa SingleSingle ServerServer SystemSystemIf the system you are upgrading is using a cluster configuration, the upgraderequires that the cluster be converted to a monolithic configuration with a singlemethod server. After the upgrade, the cluster can be reconfigured.


ShutShut DownDown RemoteRemote ServersServersIf you have configured File Servers in the Setting Up the Target System forUpgrade on page 32 section, shut down the remote servers.

PreparePrepare thethe SourceSource SystemSystem forfor UpgradeUpgradePerform the following steps in setting up your production source database forupgrade:

ShutShut downdown ReplicaReplica ServersServers

If your site uses replication, this section describes the steps specific to your site forthat process.

If you do not use a replicated vault configuration, skip this section.

1. On the master site, perform the following:

a. Navigate to SiteSite ▶▶ UtilitiesUtilities ▶▶ File Server AdministratorFile Server Administrator ▶▶ ReplicationReplicationSchedule AdministratorSchedule Administrator. Note the frequency and target vault for all of thereplication schedules except the ones starting with PCS_PCS_. Schedule namesstarting with PCS_PCS_ are predictive ca

WindchillWindchill UpgradeUpgrade GuideGuide -...

Documents

Transcript of WindchillWindchill UpgradeUpgrade GuideGuide -...