PTC Integrity Upgrading Guidesupported by the database repository, you must migrate to a supported...

PTC Integritytrade UpgradingGuide

PTC Integrity 109

Copyright copy 2016 PTC Inc andor Its Subsidiary Companies All Rights Reserved

User and training guides and related documentation from PTC Inc and its subsidiary companies (collectivelyPTC) are subject to the copyright laws of the United States and other countries and are provided under alicense agreement that restricts copying disclosure and use of such documentation PTC hereby grants to thelicensed software user the right to make copies in printed form of this documentation if provided on softwaremedia but only for internalpersonal use and in accordance with the license agreement under which theapplicable software is licensed Any copy made shall include the PTC copyright notice and any otherproprietary notice provided by PTC Training materials may not be copied without the express written consentof PTC This documentation may not be disclosed transferred modified or reduced to any form includingelectronic media or transmitted or made publicly available by any means without the prior written consent ofPTC and no authorization is granted to make copies for such purposes Information described herein isfurnished for general information only is subject to change without notice and should not be construed as awarranty or commitment by 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 license agreement contains valuable tradesecrets and proprietary information and is protected by the copyright laws of the United States and othercountries It may not be copied or distributed in any form or medium disclosed to third parties or used in anymanner not provided for in the software licenses agreement except with written prior approval from PTC

UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVILDAMAGES AND CRIMINAL PROSECUTION

PTC regards software piracy as the crime it is and we view offenders accordingly We do not tolerate thepiracy of PTC software products and we pursue (both civilly and criminally) those who do so using all legalmeans available including public and private surveillance resources As part of these efforts PTC uses datamonitoring and scouring technologies to obtain and transmit data on users of illegal copies of our softwareThis data collection is not performed on users of legally licensed software from PTC and its authorizeddistributors If you are using an illegal copy of our software and do not consent to the collection andtransmission of such data (including to the United States) cease using the illegal version and contact PTC toobtain a legally licensed copy

Important Copyright Trademark Patent and Licensing Information See the About Box or copyrightnotice of your PTC software

UNITED STATES GOVERNMENT RIGHTS

PTC software products and software documentation are ldquocommercial itemsrdquo as that term is defined at 48 CFR 2101 Pursuant to Federal Acquisition Regulation (FAR) 12212 (a)-(b) (Computer Software) (MAY 2014)for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 2277202-1(a)(Policy) and 2277202-3 (a) (Rights in commercial computer software or commercial computer softwaredocumentation) (FEB 2014) for the Department of Defense PTC software products and softwaredocumentation are provided to the US Government under the PTC commercial license agreement Useduplication or disclosure by the US Government is subject solely to the terms and conditions set forth in theapplicable PTC software license agreement

PTC Inc 140 Kendrick Street Needham MA 02494 USA

Contents

Upgrading to Integrity 109 7Your Upgrade Path10Before You Start10Compatibility Support 43Supported Databases46Database Migration 46Integrations Support47Getting Ready to Upgrade 48Upgrading for UNIX Users 49Upgrading to Integrity 10950Installing Integrity 109 Server 53

Command Line Interface Changes 63Command Line Information64im Command Options64integrity Command Options65si Command Options65tm Command Options66ACL Permissions 66

5

1Upgrading to Integrity 109

Your Upgrade Path 10Before You Start 10Compatibility Support 43Supported Databases 46Database Migration 46Integrations Support 47Getting Ready to Upgrade48Upgrading for UNIX Users49Upgrading to Integrity 109 50Installing Integrity 109 Server 53

This document contains information that you want to know before upgrading toIntegrity 109 The information is relevant for upgrades from Integrity 2009 SP7and Integrity 100 through 109

7

Notebull Integrity 2009 SP7 is the minimum supported version when upgrading a

source-only database to Integrity 109 that contains no Integrityrelationship data

bull Integrity 107 is the minimum supported version that you can upgradeautomatically (including database migration) to Integrity 109 Integrityservers before release 107 cannot be upgraded automatically If yourversion of Integrity is earlier than 107 contact PTC - Integrity Support forassistance

bull Integrity 106 extended localization support on the client and server fromEnglish and Japanese to three additional languages German ChineseSimplified and Chinese Traditional However PTC does not currentlysupport or recommend changing the server language For example youcannot change the server language from English to Chinese Simplified

bull Integrity 108 introduces a capability for the administrator to localize theirconfiguration and add translation strings for the display name anddescription attributes of the administrative objects Fields Test ResultFields Types and States During an upgrade of an existing server toIntegrity 108 and later the display name and description of theadministrative objects (standard set and custom created) are stored in theserver locale The server locale cannot be changed during an upgrade Forexample if an administrator installs an Integrity 107 server and earlierusing English as the installer locale then during an upgrade to Integrity108 and later the display name and description attributes of theadministrative objects Fields Test Result Fields Types and States arestored in the English locale

For detailed information about Configuring Localization see the PTCIntegrity Server Administration Guide

For the most up-to-date upgrading information made available to you since thepublication of this document see article CS229118 in the Integrity SupportCenterFor the most current product platform support information go to httpwwwptccompartnershardwarecurrentsupporthtmFor the most current Knowledge Base articles go to httpwwwptccomsupportintegrityhtmFor detailed information about configuring the supported databases for theIntegrity server see the PTC Integrity Server Administration Guide

8 PTC Integritytrade Upgrading Guide

For detailed information about new features general notes fixed issues andknown issues in Integrity 109 see the PTC Integrity Release Notes

Upgrading to Integrity 109 9

Your Upgrade PathBefore upgrading PTC recommends reviewing this entire guide Depending onyour current version of Integrity your upgrade path may require a full installusing an executable or you may be able to upgrade using a service pack installIf you are upgrading to Integrity 109 you must upgrade using the full installexecutable Prior to upgrading to Integrity 109 the relationship data from the oldrelationship table must already have been migrated to the new relationship tableusing a 107 or 108 Integrity server For more information see DatabaseConsiderations on page 41A full install using the executable is required when upgrading to Integrity 109from the following product versions

bull Integrity 2009 SP7bull Integrity 100bull Integrity 101bull Integrity 102bull Integrity 103bull Integrity 104bull Integrity 105bull Integrity 106bull Integrity 108This guide describes the process for installing using the full install executable

Before You StartBefore you begin your upgrade to Integrity 109 review the following importantinformationGeneral Considerations on page 10Integrity Product Version Considerations on page 12Document Versioning Considerations on page 26Database Considerations on page 41

General ConsiderationsHave a backup plan

Develop a plan to use in case an upgrade fails By retaining the previousversion of the server you reduce downtime if the upgrade fails Retaining the


previous version of the server allows you to restore the database and thencontact PTC - Integrity Support for assistance

Backup and verify your databasePerform a full database backup and keep the backup on site until it isdetermined that the upgrade is successful Verify the database backup toensure it can be restored if required

Consider integrated componentsConsider the dependencies between integrated components when upgradingBoth Integrity and Implementer can refer to items and change packages thatare stored in Integrity You must keep the Integrity data in sync forIntegrityand Implementer data to accommodate these dependenciesFor example if upgrading problems cause you to restore Integrity from aweekly backupIntegrity and Implementer could end up referring to items thatdo not exist or contain out-of-date information

Do not reuse backed up configuration filesIf you upgrade using the full install executable note that old configurationfiles cannot be reused with the new release Copying and pasting files from theold installation into the new server directory causes problems if configurationproperties have been renamed or new variables added A utility is provided formigrating configuration filesIn addition many properties are now contained in the database Onceproperties are successfully migrated to the database with the isutil utilitythey can be further modified in the Integrity Administration Client GUI orfrom the CLI using the integrity setproperty si setpropertyim setproperty and aa setproperty commands or im diag and sidiag commands

NoteThe documentation files pointed to indocumentationlistproperties andinstallationlistproperties must be manually updated fromthe installation DVD and their locations manually updated in those filesFor more information see the PTC Integrity Server Administration Guide

Plan to migrate Custom CertificatesIf you upgrade using the full install executable note that custom CA Rootcertificates stored in the cacerts keystore are not migrated during theupgrade You must plan to import such certificates manually after the upgrade


If you do not migrate the certificates the Integrity server can fail to start dueto an inability to establish the proper certificate trust

Always stop the Integrity server service before installing the upgradeStop the Integrity server service but do not uninstall the Integrity server untilafter the new server is installed Retaining the old installation ensures that arollback is possible if you run into difficulties with the upgrade

Integrity Product Version ConsiderationsNew installation directories

For Integrity server 10 product versions the default installation directory isinstalldirIntegrityIntegrityServer10

In addition the installer prevents you from installing the server in an existinginstallation directoryFor the Integrity client the default installation directory isinstalldirIntegrityIntegrityClient10

PTC recommends reviewing and updating any scripts you use that referencethe installation directories

RCS repository is no longer supported in Integrity 100 and later versionsAs of Integrity 100 the legacy RCS repository is no longer supported forconfiguration management To support a more robust repository type forconfiguration managementIntegrity exclusively supports the databaserepository For more information see the PTC Integrity Server AdministrationGuide

Notebull If you are currently using an RCS repository for configuration

management you must migrate to a database repository in Integrity 2009SP7 before upgrading to Integrity 100 and later versions

bull If you are currently using a database platform that was supported by theRCS repository in previous releases of Integrity but is not currentlysupported by the database repository you must migrate to a supporteddatabase platform

bull If a database migration is not an option or you require assistance contactPTC - Integrity Support


CautionIf you are upgrading an Integrity server that was originally configured forthe RCS repository ensure that your new database is configured as casesensitive Contact PTC - Integrity Support for assistance

With the mandatory use of the database repository the property formksisbackend=db is now required on the Integrity server Themksisbackend property is configured in the following properties file onthe serverinstalldirconfigpropertiesisproperties

If mksisbackend is missing or incorrectly set the Integrity server doesnot start and an error occurs (MKS141153 The RCS repository is no longersupported for Source) To resolve the error the administrator must addmksisbackend=db to the isproperties fileFor more information on configuring properties in the isproperties filesee the PTC Integrity Server Administration Guide

Integrity 108 and later does not support PTC System Monitor 30Integrity 108 and later is only compatible with PTC System Monitor (PSM)40 It is not supported with PSM 30 and earlier PSM releases This is due toan incompatibility with the version of Java that is used with both productsThis incompatibility does not allow the Integrity server to start If you arecurrently running PSM 30 and earlier you must upgrade to 40 beforeupgrading to Integrity 108 and later

Project files are now in client-side databaseAs of Integrity 108 and later project information is stored in a client-sidedatabase and consequently there are no pj files in Sandboxes Project filesstill display as virtual project files (with the pj file extension) in Integrityinterfaces Instead of project files project information is stored in a client-sidedatabase in the mks directory of the system on which the Integrity client isinstalled The location of the mks directory is specified by the MKS_IC_INSTANCE_DIR environment variable By default on Windows the mksdirectory can be located in the home directory of the user


NoteAn Integrity userrsquos mks directory must have sufficient space available tofit three copies of the client-side database The amount of space neededdepends on how many Sandboxes the user has and a minimum of 50 MBavailable space is recommended

Large amounts of Test Results data in Oracle databases can increaseIntegrity 106 upgrade time (275480 950629)

If you are using an Oracle database that contains a large amount of TestResults data the database migration step of the Integrity server upgrade cantake a long time During the upgrade a message warning of this appears andprovides instructions to look for status updates in the migration log(dbinstalllog) found in the server installation log directory

Java Garbage Collector default change (142919 943799)As of Integrity 105 and later the Java garbage collector default for theIntegrity server has changed to concurrent mark sweep collector (CMS) Ifyour implementation of Integrity uses custom changes to the garbage collectorsettings it is recommended that you test the new Integrity server installation ina test environment before upgrading the Integrity server used in the productionenvironment

Upgrading database to Integrity 103 can take additional time (740029807473)

In Integrity 103 three new columns have been added to the Issues tableDuring the database migration step of the Integrity upgrade for each existingitem (issue) a value is assigned to one of the columns possibly increasingupgrade time The columns have been added for future use

Trigger bean updates to support deactivating and activating developmentpaths (1010427 1071406)

In Integrity 108 and later the following updates have been made

bull The following new trigger bean classes are availableScriptActivateVariantArgumentsBean andScriptDeactivateVariantArgumentsBean These classes makethe variant name being activated available to script authors

bull For the ScriptProjectBean class the following new methods areavailable deactivateVariant and activateVariant Thesemethods deactivate and activate variant projects

bull For the ScriptProjectBean class the getVariants method hasbeen updated to return both active and inactive variants If you only want


active variants to be returned you must update your scripts to usegetActiveVariants instead

bull getActiveVariants getInactiveVariantsFor more information see the Javadocs

Methods in ScriptCopyTreeResultBean deprecated (631048 203946)As of Integrity 101 and later the following methods in theScriptCopyTreeResultBean are deprecated and should no longer beusedbull getResultMap()

bull getResultingIssue()

Instead use the following methodsbull getResultMapV2()

bull getResultingIssues()

For more information on using ScriptCopyTreeResultBean methodssee the Event Trigger Java Documentation documentation link on theIntegrity server Homepage

Change to Document ID Field Definition (494359 517828)With Integrity 101 and later the definition of the Document ID field is noteditable by Integrity administrators If your implementation of Integrity has achange from the default field definition the field is changed to the defaultduring the database migration step of the upgrade with a warning in themigration log file installdirlogdbinstalllogAn example of a warning followsThe computation definition of the ldquoDocument IDrdquo field is incorrectlyset to ldquoisMeaningful()rdquo it has been changed to ldquoDocumentID()rdquo Thehow to run computation attribute of the ldquoDocument IDrdquo field isincorrectly set to ldquostaticrdquo it has been changed to ldquodynamicrdquo Thestore to history attribute of the ldquoDocument IDrdquo field is incorrectlyset to ldquoweeklyrdquo it has been changed to ldquoneverrdquoFor further assistance contact PTC Integrity Support

Document model enforced when using event triggers (412912 496076)Integrity 102 introduces the following changes that enforce the documentmodel for change triggers

bull A branch of the backing shared item is caused by a change trigger edit toeither the Author or Reuse node of any shared item that is one of thefollowing

Referenced either by an Author node and at least one Reuse node


Referenced by two or more Reuse nodes (no Author is required in thissecond case

bull Change triggers cannot perform a significant edit on a node in Share modeIf an attempt is made the following error is returned

Changes are not permitted when the Reference Mode field is setto Sharen n Trigger script 0 invoked by trigger 1attempted to modify field 2 of item 3 Please notify theIntegrity Administrator about this errorEnsure that your implementation of change triggers does not rely on theprevious behavior

Change to command output for im viewfield (404859 735922)With Integrity 102 the output for the im viewfield command has changedto include system managed fields Scripts that use this command requireupdating

New Integrity server property enabled by default (683801)With Integrity 102 the following Integrity server property is introduced andenabled by default mksisincludeIntegrityGUILinks For moreinformation see entry 683801 in the Integrity Release Notes and the PTCIntegrity Server Administration Guide

Method in ScriptSourceTraceBean deprecated (727249)As of Integrity 103 the getFileName() method in theScriptSourceTraceBean is deprecated Although the method currentlyfunctions it will no longer be actively supported in future product releasesFor full support it is recommended that you use the following methodsinstead

bull getMemberName()

bull getSubprojectName()

bull getProject()

For information on using ScriptSourceTraceBean methods includingthe limitations of the getFileName() method see the Event Trigger JavaDocumentation documentation link on the Integrity server Homepage

Removed methods in commksapiIntegrationPointFactory class (919859)In Integrity 104 the following methods are removed from thecommksapiIntegrationPointFactory class in Integrity JavaAPI 412

bull public static String getAPIVersion()

bull public IntegrationPointcreateLocalIntegrationPoint() throws APIException


bull public IntegrationPointcreateIntegrationPoint(String host int port) throwsAPIException

bull public IntegrationPointcreateIntegrationPoint(String host int portboolean secure) throws APIException

In releases before Integrity 104 these methods were deprecated andinstructions were provided to migrate to other methods where you would berequired to explicitly request an API version If you currently use thesemethods in a custom integration PTC recommends reviewing the Java docsfor Integrity Java API 412 and updating your integration code accordinglyIf you currently use these methods in any trigger scripts the scripts do notwork with Integrity 104 and later PTC recommends reviewing your triggerscripts for any use of the Java APIrsquos IntegrationPointFactoryConsider revising your scripts to use the triggerrsquosScriptEnvironmentBeancreateAPISessionBean instead ofdirectly using the Java API within your scripts

NoteFor further information and instructions see article CS135671 in theIntegrity Support Center at httpwwwptccomsupportintegrityhtm

Support for Integrity client 103 (and later) Help when the Integrity server isupgraded (826302)

If your implementation of Integrity includes Integrity 103 (and later) Integrityclients connecting to newer version Integrity servers PTC recommendsconsidering one of the configuration options in the Integrity Help BackwardCompatibility topic in the PTC Integrity Server Administration Guide

Installing FlexNet and a Java Runtime EnvironmentTo control the use of Integrity components FlexNet Publisher License Server11101 is distributed with Integrity 102 and later This version of the FlexNetPublisher License Server installer does not include a Java RuntimeEnvironment (JRE)You must install JRE 15 or higher before installing FlexNet Download theJRE from httpwwwjavacom For more information refer to the FlexNetPublisher documentation included with the FlexNet installer


Clients connecting to a proxy server can view Item Presentation Templateimages residing behind a firewall (775983 912068)

In Integrity 105 and later an Integrity client connecting to a proxy Integrityserver can now view Item Presentation Template (IPT) images residing on themain Integrity server or a network location that is inaccessible by clients dueto network restrictions such as a firewall To transfer IPT images across thefirewall images are cached on the proxy server and Java Remote MethodInvocation (RMI) calls are performed between the client proxy server andmain serverIf you use Integrity clients 104 and earlier to connect to proxy and mainIntegrity servers 105 and later the IPT images display as broken image iconsTo resolve this issue contact PTC - Integrity Support

Move Subproject command supports changing the path name case on a case-insensitive database (109145 669648)

When moving a subproject on a case-insensitive database Integrity clients105 and later can now change the path name case For example Testprojectpj can be changed to testprojectpjThis functionality is not available for Integrity clients 104 and earlierHowever earlier clients can pick up path name case changes made by 105 andlater clients To pick up a path name case change with earlier clients do thefollowing1 Resynchronize the affected Sandbox2 Manually change the case of the subproject path name on the file systemIf users do not make these changes the affected project name in wizard panelsand title bars can be rendered incorrectlyFor Integrity clients 105 and later PTC recommends resynchronizing theaffected changes in your Sandbox before performing additional operationsThis ensures that you are working with the latest changes and reducespotential configuration errors

NoteUsers cannot change the case of the subproject path name withtransactional change packages or Change Package Reviews enabled Iftransactional change packages or Change Package Reviews are enabledusers must drop the subproject in a change package manually change thecase of the subproject path name and then use a new change package toadd the subproject as a shared subproject


Updated ScriptAPISessionBean uses Integrity API 411 for local andremote API calls (939795)

Before Integrity 105 the ScriptAPISessionBean used the most currentversion of the Integrity API In Integrity 105 and later if theScriptAPISessionBean is used for an API call within the local server orfor remote API sessions the ScriptAPISessionBean now uses IntegrityAPI 411 This allows a 105 and earlier server to make local and remote APIcalls through the ScriptAPISessionBean in event triggers into 106servers and later Using the same Integrity API version for local and remoteAPI sessions also ensures that trigger script authors can create trigger scriptsthat do not need to account for multiple versions of the Integrity APIresponses When working with event triggers and the API PTC recommendsmaking note of the API version differenceFor more information refer to the Java docs and the PTC IntegrityIntegrations Builder Guide

Test result metadata fields of the Date data type represented in the API as adatetime value (939795)

Before Integrity 105 the API representation of a test result metadata fieldincorrectly returned a string value instead of a datetime value for theDate data type In Integrity 105 and later all versions of the Integrity APIcorrectly return a datetime value

Compatibility of Item Presentation Templates in Integrity 106 and later(966764)

If you open an Integrity 105 and earlier item presentation template (IPT) in anIntegrity 106 and later release Integrity adds a header populated with theItem Created Information and Item Modified Informationread-only fields If there is a logo in the IPT it is placed in the header basedon the logo alignment property Integrity also applies the default text style tofields in the headerIf you open an Integrity 106 and later IPT in Integrity 105 and earlierIntegrity ignores the read-only fields in the header and moves any customfields to the first tab in the IPT As of Integrity 106 Integrity no longerinclude a logo property for IPTs because header layout can be customized justlike the layout of any tab This allows you to add more than one imageanywhere in the header

Enhanced project visibility for project administrators (961444)To provide enhanced project security project administrators can only view andedit the projects to which they are assigned For example visible projectsdisplay in the Integrity Administration Client GUI gt Projects node and whenusing the im projects command


To reflect this enhancement from the CLI the im dynamicgroups and imeditdynamicgroupscommands contain the following added options andupdated option behavior

bull im dynamicgroups --fields=membership displays only theprojects to which the project administrator is assigned

To indicate that a project does not have any groups and users as membersof the dynamic group specify the new nomembers keyword Forexample specify --membership= Project=nomembersPreviously a blank space indicated that a project did not have any groupsand users as members of the dynamic group For example the followingwas previously acceptable--membership= Project=

CautionIf you are a project administrator the im dynamicgroups--fields=membership command displays a subset of the projects in your Integrityconfiguration If a super administrator uses that list of projects whenspecifying im editdynamicgroup--membership the membershipfor the projects that the project administrator does not have permission toview are removed

bull im editdynamicgroups --membership processes only the projectsto which the project administrator is assigned

To indicate that a project does not have any groups and users as membersof the dynamic group specify the new nomembers keyword Forexample specify --membership= Project=nomembersPreviously a blank space indicated that a project did not have any groupsand users as members of the dynamic group For example the followingwas previously acceptable --membership= Project=

To inherit the membership from the parent project to the dynamic groupspecify the inherit keyword For example specify--membership=Project=inherit Previously a membership listwas specified

To allow a project administrator to set membership for a specific project towhich he or she is assigned use the --projectMembership=project=inherit|nomembers|per-project-membership option


where

per-project-membership is in the form user-list|group-list|user-listgroup-list

where

user-list is in the form u=username[username] group-list is in the form g=groupname[groupname]

inherit specifies that the membership for the parent project is tobe inherited by the dynamic group

nomembers specifies that the project does not have any groupsand users as members of the dynamic group

NoteSpecifying users but no groups removes any existing groupsSimilarly specifying groups but no users removes any existingusers

To correctly work with dynamic groups PTC recommends using the optionsprovided with these commands For more information see the 106 and laterversion of the CLI man pagesIf a project administrator is using a 105 and earlier Integrity AdministrationClient the GUI and CLI commands return results based on 105 and earlierbehavior

Configuration Options For Non-Build Subprojects When Creating aDevelopment Path (972187 972193)

When creating a development path from a project that contains non-buildsubprojects (normal or variant subprojects) the options are configurable fromthe Integrity client However an administrator can override and enforce aspecific option on the Integrity serverIf one of these options is enforced on a 106 and later Integrity server and a105 and earlier Integrity client creates a development path the defaultbehavior is enforced All subprojects that are configured differently from theparent project retain their existing configuration

Improperly using im dynamicgroups or im editdynamicgroup canresult in lost membership data (96020 148955 976751)

The --fields=membership and --membership options were designedso that a script could update project membership for a dynamic group byretrieving the membership for all projects with im dynamicgroups


--fields=membership making changes to the list and then returningthe list to im editdynamicgroup --membershipIn Integrity 106 and later the im dynamicgroups --fields=membership and im editdynamicgroup --membership commandshave been changed so that they only return or edit the memberships forprojects that the project administrator has rights to administer For example ifa user is a project administrator the list of members returned from imdynamicgroups --fields=membership only includes the projectsthat the project administrator is allowed to administer Similarly if a projectadministrator attempts to edit membership using im editdynamicgroup--membership Integrity only updates those projects that the projectadministrator can administerWith these changes in Integrity 106 and later scripts should not call imdynamicgroups --fields=membership as a project administrator andthen use the returned list to call im editdynamicgroup --membershipas a different project administrator If a project is missing from the list passedto im editdynamicgroup --membership Integrity sets that projectrsquosmembership to inherit its parent projectrsquos membership This means that usingthese two commands with different project administrators causes thememberships for some projects to inherit from their parent project losing theirmembership data if the two project administrators administer a different set ofprojects

Revision description audit tags in text files (976757)In Integrity 106 and later revision annotation --- Added comment ---tags are replaced with - Added comment - tags As a result users can seeadditional differences when differencing files from a Sandbox that containsthe $Log IntUpgradeGuideStartProdVersiondita $ keywordThese differences that contains the Revision 126 20150724205910IST Flett David (dflett) keyword These differencesthat contains the keyword These differences that contains the $Revision140 $ keyword These differences that contains the keyword Thesedifferences are resolved by updating the working file in the Sandbox Newtags use the format - Added comment - Users do not see additionaldifferences

Creating viewing editing copying and deleting configuration managementpolicies from the CLI (949198)

From the CLI administrators can create view edit copy and deleteconfiguration management policies using the following commands

bull si copypolicysection

bull si deletepolicysection

bull si setpolicysection


bull si viewpolicysection

bull si viewpolicysections

NoteThe si setpolicysection command replaces the sicreatepolicysection command (a previously unsupportedcommand that was removed in Integrity 106) To create and edit policiesuse the si setpolicysection command and modify any existingscripts that refer to the si createpolicysection command

These commands are also published commands supported by PTC for use withthe Integrity Java API For more information see the PTC IntegrityIntegrations Builder GuideUsing scripts or the Integrity Java API administrators can automate the setupof configuration management policies For more information on CLIcommands see the CLI man pages

NoteTo manage your configuration management policies PTC recommendsusing the Integrity Administration Client

Manually disable and lock global Change Package Description Templateconfiguration management policy following an upgrade to Integrity 107 andlater (1003803)

Following an upgrade to Integrity 107 and later administrators who do notintend to configure Change Package Description templates should considerglobally disabling and locking the Change Package Description Templatepolicy to ensure optimal performance The policy can be disabled and lockedthrough the Integrity Administration Client policy editor For moreinformation on modifying server configuration management policies see thePTC Integrity Server Administration Guide

Deprecated options for the im editissue command (976630)When using the im editissue command in Integrity 106 and later thefollowing options are deprecated and should no longer be used

bull --addRelationships=valuebull --removeRelationships=valueInstead use the newer options


bull --addFieldValues=valuebull --removeFieldValues=valueIn addition the --addRelationships=value option is deprecated in theim createissue and im copyissue commands Instead use the newer--addFieldValues=value optionAlthough the deprecated options continue to work PTC does not recommendusing them for new scripts because they will be removed in a future releaseExisting scripts using the deprecated options should use the new options

New method added to ScriptDynamicGroupBean (917243)To check the user membership of a dynamic group based on the project theisUserMemberOf method was added to ScriptDynamicGroupBean inIntegrity 106 This updated method can be used in an event trigger to restrictthe following

bull creating an itembull editing a project on an item (cannot change to specific projects)bull recording time entriesbull editing test resultsbull label operations on itemsFor more information see the Event Trigger Java Documentationdocumentation link on the Integrity server Homepage

Referencing checkpoints in unregistered configuration management projects(982628)

In Integrity 106 and later project paths are referenced using the repositorylocation This allows you to reference checkpoints in unregistered (dropped)configuration management projects If a checkpoint is currently referenced andthe corresponding project is later dropped the checkpoint remains accessibleas read-only For example you can continue to open the referenced checkpointfrom an SI project field or create a build Sandbox from the checkpoint forauditing purposes


Before upgrading note the followingbull Although no existing data is migrated when you upgrade to Integrity 106

and later project paths are referenced using the repository location whichcan affect existing scripts and triggers PTC recommends reviewing anyexisting scripts and triggers

bull Integrity 105 and earlier clients cannot view metrics links for SI Projectfields that reference build projects created with Integrity 106 and later

bull If you are using different versions of the Integrity client and Integrityserver and dedicated servers the behavior is dependent on the version ofthe Integrity server dedicated to configuration management For anIntegrity server 105 and earlier that is dedicated to configurationmanagement a flat path is stored for build projects

Custom integrations can possibly require extra steps for Integrity upgrade(999628)

If you are upgrading to Integrity 109 from 107 or 108 the followingadditional upgrade steps are not required However if you are upgrading toIntegrity 109 from an earlier Integrity version other than 108 or 107 and youhave a custom integration additional steps for updating your integration canbe necessary You must perform these extra steps if all of the following criteriaapply

bull Your environment uses a private copy of the Integrity C APIbull Your environment uses the Integrity server as the integration pointbull SSL is used for secure communication with the server integration pointIf your environment meets all of these criteria you must update your copy ofthe Integrity C API to the version provided with Integrity 109 If you areusing a Microsoft Excel or Project integration you must also update to thecurrently supported version of the integration software For supportedversions see the latest Integrations document on the PTC website If you donot upgrade the Integrity C API the integration is unable to connect to thesecure port of the Integrity server

Shared Sandboxes not supported as of Integrity 108Shared Sandboxes are not supported for Integrity 108 and later After theIntegrity client upgrade only the owner of the Sandbox continues to haveaccess to the Sandbox through the Integrity client Other users who weresharing the Sandbox can no longer access that Sandbox

Sandboxes used for the Staging and Deploy functionality no longer supportedas of Integrity 108

In Integrity 108 and later the Sandboxes used for the Staging and Deployfunctionality are no longer supported The migration of such Sandboxes from


earlier versions of Integrity to Integrity 108 and later is also no longersupported

Applying Integrity 108 service pack prevents restart of Integrity Agent 107The Staging and Deploy functionality is no longer supported in Integrity 108and later If the Staging and Deploy functionality is enabled(mksagentstartupsd=true) in the agentproperties file theIntegrity Agent fails to start A FATAL category log message in theagentlog and FATALlog files is also logged The log message indicatesthat the Staging and Deploy functionality is no longer supported Applying theIntegrity 108 service pack to Integrity Agent 107 disables the Staging andDeploy functionality by updating an existing mksagentstartupsd=true property to mksagentstartupsd=false in theagentproperties file This automatic disabling of Staging and Deployfunctionality on the Integrity Agent is required to support remote automatedpatching

Backup files generated by Integrity 108 during multiple-row editing are notcompatible with Integrity 109

During multiple-row editing of a document unsaved changes are stored in abackup file so that these changes can be recovered if an unexpected shutdownof the Integrity client occurs The backup files generated by Integrity 108which introduced a beta version of multiple-row editing cannot be opened byIntegrity 109 Before upgrading an Integrity client from 108 to 109 youwant to ensure that all documents are saved or closed successfully Otherwiseafter the client is upgraded you are unable to recover changes from a 108backup file Backwards compatibility is planned for releases subsequent to109 For example an Integrity 110 client will be able to open backup filesfrom Integrity 109 Future releases will also support recovering pendingimports which are new in Integrity 109

Document Versioning ConsiderationsIntegrity 105 introduced enhanced document versioning capabilitiesIf you are upgrading from Integrity 104 and earlier to Integrity 109 consider thefollowing

Integrity client support for document versioning (930902)If you are working with document versions using an earlier Integrity client itis possible for item operations not to work or to produce unexpected behaviorTo make full use of the document versioning capabilities introduced inIntegrity 108 PTC recommends upgrading your Integrity client to 108 andlater


Hyperlinks in the Item Details view (930902)Integrity 104 an earlier do not display hyperlinks to document or contentversion information in the header and History tab of the Item Details viewEarlier clients display Created by and Modified by information only

Searching for live and versioned documents using the Document ID field(935528)

In the Integrity client GUI the Document ID field supports searching for liveand versioned documents For example typing 184 returns the contents of thelive document Typing 184ndash12 returns the contents of the versioneddocumentIntegrity clients 104 and earlier do not support searching for versioneddocuments using the Document ID field

New item query filters (916659)From the Items query filter in the GUI and Web interface two new sub-filtersare available Is versioned and Is live From the CLI the sub-filters areitemversioned and itemliveAfter upgrading existing queries display all items (versioned and live) Todisplay live items only (pre-upgrade query behavior) modify the queries toinclude the Item is live filter

NoteAs a best practice PTC recommends including the Item is live filter in allqueries for live items This improves the accuracy of query results

New item ID query filters (933679)For item ID query filters you can specify the following conditions to displaylive and versioned items by item ID

bull Display a specific live item only For example ID = 123 and Is live returnslive item 123

bull Display a live item and all versions of the item For example ID = 123and include versions returns 123 123-10 123-11 and 123-12


bull Display a range of live items For example ID gt 123 and lt 128 and Is livereturns 124 125 126 and 127

bull Display a specific versioned item For example ID = 123-10 returns123ndash10

NoteYou cannot display a range of versioned item For example you cannotdisplay ID gt 123-10 and lt 123-20

Queries containing versioned item IDs the Is live query filter or the includeversions query filter are not visible in Integrity clients 104 and earlier Inaddition charts reports and dashboards containing those queries are notvisible in earlier clients

New document ID query filters (935528)For document ID query filters in the GUI and Web interface you can specifythe following conditions to display content that is included in live andversioned documents

bull Display the contents of a live document For example Document ID = 123and Is live returns content that is included in live document 123

bull Display the content from a range of live documents For exampleDocument ID gt 123 and lt 128 and Is live returns content that is includedin live documents 124 125 126 and 127

bull Display the contents of a versioned document For example Document ID= 123-10 returns content that is included in versioned document123ndash10

NoteYou cannot display the content from a range of versioned documents Forexample you cannot display content from Document ID gt 123-10 and lt123-20

Queries containing versioned document IDs or the Is live query filter are notvisible in Integrity clients 104 and earlier In addition charts reports anddashboards containing those queries are not visible in earlier clients


Updated document query filters and computed expressions (934500)From the Items query filter in the GUI or Web interface the following sub-filters are updated

bull Is a document node returns all items (live and versioned) that are adocument model node type

bull Is a content node returns all items (live and versioned) containingreferences to shared items

From the CLI the sub-filters are itemnode and itemcontentAfter upgrading existing queries display all items (versioned and live) Todisplay live items only (pre-upgrade query behavior) modify the queries toinclude the Item is live filterFor computed expressions the following item functions are updatedbull IsNode() returns true if the items (live and versioned) are a document

model node typebull IsContent() returns true if the items (live and versioned) contain

references to shared itemsExisting computed expressions include all items (versioned and live) Toinclude live items only (pre-upgrade behavior) modify the computedexpressions to include the IsLive() function

NoteAs a best practice PTC recommends including the IsLive() function inall computed expressions for live items This improves the accuracy ofcomputations

Updating fields in versioned items (922959 929457)Although a document version represents a record of a document at a specificpoint in the documents history some fields in individual versioned items cancontinue to update based on the field definition These are known as livefields indicated by the live field icon The following fields always update based on the field definitionbull item backed picklist fieldsbull query backed relationship fields


bull range fields (An icon displays if the referenced field is configured toupdate based on the field definition)

bull field value attribute fields (An icon displays if the referenced field isconfigured to update based on the field definition which can include anyof the above fields a field on a live item or where the backing relationshipis editable)

NoteThe asterisk () icon displays based on the current field configuration notthe field configuration at the time of versioning For example changing afield configuration to be editable or allow updates after versioning displaysan asterisk () icon in all item versions

When creating or editing computed fields an available option specifies howvalues are computed in versioned items Allow Computation Updates onVersioned Items (GUI) and[no]allowComputationUpdatesOnVersion (CLI) By defaultcomputation values on versioned items continue to update based on thecomputed field definition To record computation values at the time ofversioning and prevent further updates clear the Allow Computation Updateson Versioned Items checkboxFor existing computed fields this checkbox is selected Select or clear it basedon your requirements

NoteBefore versioning a document containing a computed field PTCrecommends carefully considering whether you want the computed field toAllow Computation Updates on Versioned Items If you change the optionafter versioning the document it is possible for historical views ofversioned items to not display the expected field value

New item functions for computed expressions (938099)For computed expressions the following item functions are available

bull IsLive() returns true if item type node or segment is livebull IsVersioned() returns true if item type node or segment is

versionedAfter upgrading existing computed expressions include all items (versionedand live) To include live items only (pre-upgrade behavior) modify thecomputed expressions to include the IsLive() function


For example to include live items only in the following existing computedexpressionaggregate(ALM_Documented By sum(IsSegment() 1 0))

add the IsLive() functionaggregate(ALM_Documented By sum(IsSegment() and IsLive() 1 0))


Displaying live or versioned items in reports (931016)In report recipes you can specify the following report tags to filter by live orversioned items

bull ltfiltergt(item is live)ltendfiltergt filters by live itemsbull ltfiltergt(item is versioned)ltendfiltergt filters by

versioned itemsAfter upgrading existing reports display all items (versioned and live) Todisplay live items only (pre-upgrade report recipe behavior) modify the reportrecipes to include the live items report tag filterFor example to include live items only in a report recipe similar to Detail -HTML Column Relationships modify the beginrelationshipsdetailline toltbeginrelationshipsdetail amprelationshipsdetailfieldsgtltfiltergt(item is live)ltendfiltergt

NoteIf a report recipe does not include the appropriate filter users can modifythe backing query to include a query filter that displays live or versioneditems

Report recipes containing report tag filters for live and versioned item IDsdisplay an error message in Integrity clients 104 and earlier


NoteAs a best practice PTC recommends including the (item is live)filter in all report recipes for live items This improves the accuracy ofreports

Displaying live fields and ambiguous computed fields in reports (939682)The Integrity client GUI and Web interface include icons to indicate live fields( ) and ambiguous computed fields ( ) in versioned items However reportscannot display these icons To indicate whether field values in a report are liveor ambiguous the following report tags are available

Report Tag Descriptionampfieldislive Displays true or false to indicate

whether the field is liveampfieldisambiguous Displays true or false to indicate

whether the field is an ambiguouscomputation

amprelationshipfieldislive Displays true or false to indicatewhether the relationship field is live

amprelationshipfieldisambiguous

Displays true or false to indicatewhether the relationship field is anambiguous computation

ltislivegtfieldnameltendislivegt

Instead of displaying the field namedisplays true or false to indicatewhether the field is live

ltisambiguousgtfieldnameltendisambiguousgt

Instead of displaying the field namedisplays true or false to indicatewhether the field is an ambiguouscomputation

ltrelationshipisliveLgtfieldnameltendrelationshipisliveLgt

Displays true or false to indicatewhether the field is live for the itemat the specified relationship level

ltrelationshipisambiguousLgtfieldnameltendrelationshipisambiguousLgt

Displays true or false to indicatewhether the field is an ambiguouscomputation for the item at thespecified relationship level

ampfieldgroupcomputeislive If a field contains a defined groupcomputed field displays true orfalse to indicate whether the


Report Tag Descriptioncomputation is live

NoteIf there is no group computedfield for the field an empty stringdisplays

ampfieldgroupcomputeisambiguous

If a field contains a defined groupcomputed field displays true orfalse to indicate whether thecomputation is ambiguous


ltgroupcomputeisambiguousgt

Used within theltiterategroupcomputegtreport tag displays true or falseto indicate if the associatedltgroupcomputegt isambiguous

ltgroupcomputeislivegt Used within theltiterategroupcomputegtreport tag displays true or falseto indicate if the associatedltgroupcomputegt is live

After upgrading existing reports containing ambiguous computed fields donot display any data for the ambiguous computed fields Live fields continueto display data for the live fields Modify existing reports as needed to displayappropriate dataIntegrity clients 104 and earlier ignore the new report tags in report recipes

Report recipes that include the item ID field in JavaScript code (944738)If document versioning is enabled and you have an existing report recipe thatincludes the item ID field in JavaScript code you must put quotes around theitem ID fieldFor exampleltscript type=textjavascriptgtif(REPORT_ISSUES == ) REPORT_ISSUES = ltltbuiltin IDgtgtelse REPORT_ISSUES = REPORT_ISSUES++ltltbuiltin IDgtgtsection = new Array()level = 0


ReportID = ltltbuiltin IDgtgtltscriptgt

Modify toltscript type=textjavascriptgtif(REPORT_ISSUES == ) REPORT_ISSUES = ltltbuiltin IDgtgtelse REPORT_ISSUES = REPORT_ISSUES++ltltbuiltin IDgtgtsection = new Array()level = 0ReportID = ltltbuiltin IDgtgtltscriptgt

Defining rules for live and versioned items (945966 938098)When defining rules in Integrity you can specify conditions for live andversioned document model items For example you can create an event triggerrule to run on versioned items only or an e-mail notification rule that sends ane-mail when a user edits a specific live itemWith items you can

bull define a rule to match live items only For example Item is live matcheslive items only

bull define a rule to match versioned items only For example Item is versionedmatches versioned items only

After upgrading existing rules display all items (versioned and live) Todisplay live items only (pre-upgrade behavior) modify the rules to include theItem is live condition

NoteAs a best practice PTC recommends including the Item is live condition inall rules for live items This improves the accuracy of rules

With item IDs you can

bull define a rule using a live item ID to match a single live item For exampleID= 123 and Item is live match 123

bull define a rule using a versioned item ID to match a single versioned itemFor example ID= 123ndash10 matches 123ndash10


Notebull You cannot define a rule using a live item ID to match the live item and all

versions of the itembull You cannot define a rule using live or versioned item IDs to match a range

of live or versioned items For example you cannot use IDgt 123ndash10 andlt 123-20 to match of range of live or versioned items

With document IDs you can

bull define a rule using a live document ID to match a single live documentFor example Document ID= 123 and Item is live match content that isincluded in live document 123

bull define a rule using a versioned document ID to match a single versioneddocument For example Document ID= 123ndash10 matches content that isincluded in versioned document 123ndash10

NoteYou cannot define a rule using live or versioned document IDs to match arange of live or versioned documents For example you cannot useDocument IDgt 123-10 and lt 123-20 to match a range of live orversioned documents

When defining a new rule with live or versioned item conditions from theIntegrity Administration Client a message displays that Integrity clientsearlier than 105 cannot evaluate this rule correctly potentially resulting inunexpected behavior

Integrity API updates to computed field values in workflows and documentsitems (939795)

Integrity API 413 (introduced in Integrity 105) includes support fordistinguishing literal null values from null values returned by ambiguouscomputed field values in workflows and documents itemsWhen viewing a workflows and documents item in previous Integrity releasesthe API representation for a computed field value matched the representationof a non-computed field value for the same workflows and documents fielddata type In Integrity API 413 computed field values are now represented byan API item of imComputation model type containing the following APIfields


bull value indicates the computation valuebull isAmbiguous indicates the boolean value of whether the computation is

ambiguousbull isDynamic indicates the boolean value of whether the computation is

dynamic or static

NoteWith this update earlier versions of the Integrity API can return nullvalues with no context for simple data types

For more information on ambiguous computations see the PTC IntegrityServer Administration Guide

Changes toLocalTriggerManagerScriptIssueDeltaBeanrevision method(941478)

With the introduction of document versioning functionality the trigger methodScriptIssueDeltaBeanrevision has been modified to perform acheck-in operation The following changes have been made to the associatedparameters

bull The conditionalSignificantEdit parameter is ignored andinternally set to true Document model items are only checked in whenthey contain significant changes

bull The conditionalModified parameter is ignored and internally set tofalse Document model items are only checked in when they containsignificant changes

bull The recurseInclude parameter is ignored and internally set to trueAll included documents are automatically checked in

bull The recurseReference parameter is ignored and internally set to trueAll referenced documents are automatically checked in

bull The recurse parameter applies only to content items If the selection is asegment or a node that points to a segment the option is ignored andinternally set to true

If you have any trigger scripts that currently use theScriptIssueDeltaBeanrevision method PTC recommends thatyou review those scripts and update them as required

Changes to LocalTriggerManagerScriptServerBean class (945403)With the introduction of document versioning functionality theLocalTriggerManagerScriptServerBean class has been modified


to include the following new methods to look up the new versioning-relatedfields

bull getLiveItemIDFieldBean for the Live Item ID fieldbull getMajorVersionIDFieldBean for the Major Version ID fieldbull getMinorVersionIDFieldBean for the Minor Version ID fieldIf you have any trigger scripts that currently use theLocalTriggerManagerScriptServerBean class PTC recommendsthat you review those scripts and update them as required

Computed fields and ambiguous computations (939364 944630)With document versioning a computed field containing an ambiguouscomputation returns an empty value If a computed field can contain anambiguous computation as a best practice PTC recommends wrapping theexpression in the IsEmpty() function This ensures that any emptycomputed field values stored to history are as a result of an ambiguouscomputed expressionFrom the CLI the decorator indicates that a computed field contains anambiguous computation To toggle the display of the decorator specify the--[no]showDecorators option for the following commands

bull im exportissues

bull im issues

bull im viewissue

By default --showDecorators is specified for im viewissue and--noshowDecorators is specified for im issuesimexportissues If you have any scripts that use these commands PTCrecommends that you review those scripts and update as required

Creating editing and viewing hyperlinks to versioned items (940895)Integrity clients 104 and earlier cannot create edit or view (click) hyperlinksto versioned items in the Item Details view

Custom integrations and versioned item data (941917)If you use the Integrity API to develop custom integrations note the followingabout how API versions handle versioned item data

bull Integrity API 413 and later can include versioned items as specified by anIntegrity 105 and later query definition

bull Integrity API 412 and earlier excludes versioned items by default Theclientcommand removes versioned items from the query results There isno change to operation of the query on the server and there is nomodification to the query definition sent to the server


When you write new integrations or upgrade existing integrations PTCrecommends that you upgrade the API version to 413 and specify if you wantto include versioned items by using an appropriate query definition Thisensures that your integrations use the appropriate item data

Charts and ambiguous computed expressions (940753)Charts do not display ambiguous computed expression values in versionedcontent item data If a chart contains an ambiguous computed expression anerror message displaysAfter upgrading backing queries in existing charts display all items (versionedand live) Modify backing queries in existing charts as needed to displayappropriate data If you choose to include versioned content item data incharts modify the chart definition to exclude computed expressions that referto document context (Document ID Contains Contained By fields or theAggregate ByDocument() function) If you do not exclude thesecomputed expressions they can return ambiguous results preventing the chartfrom running

Changes to the LocalTriggerManagerScriptIssueBean andLocalTriggerManagerScriptIssueDeltaBean classes (946348)

With the introduction of document versioning functionality theLocalTriggerManagerScriptIssueBean andLocalTriggerManagerScriptIssueDeltaBean classes weremodified to include the isFieldValueAmbiguous(StringfieldName) method to determine if a computed field value (in the contextof a versioned item) is ambiguousisFieldValueAmbiguous(String fieldName) returns true if (in thecontext of a versioned item) the stored value for the provided computed fieldis null because of an ambiguous computationIf you have any trigger scripts that currently use theLocalTriggerManagerScriptIssueBean orLocalTriggerManagerScriptIssueDeltaBean classes to inspectfield values PTC recommends reviewing and updating the scripts whereappropriate to account for ambiguous computations

Changes to the LocalTriggerManagerScriptIssueBean classScriptIssueBeantoString()method andScriptIssueDeltaBeantoString() method (946174)

With the introduction of document versioning functionality theLocalTriggerManagerScriptIssueBeanclassScriptIssueBeantoString() andScriptIssueDeltaBeantoString() methods were updated tosupport e-mail notifications containing versioned items


The LocalTriggerManagerScriptIssueBean class was modifiedto add the getIssueIDString() method to retrieve the versioned item IDfrom an itemThe ScriptIssueBeantoString() andScriptIssueDeltaBeantoString() methods for issue beans weremodified to include the versioned item IDTo use these new methods the following trigger scripts included with Integrity105 and later were updatedbull emailjs

bull signatureRequiredjs

bull postLinkedIssuejs

bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs

bull emailAdvancedjs

bull dependentStatusjs

If you have any trigger scripts that currently use these methods or you arecurrently using the trigger scripts that were updated in Integrity 105 and laterPTC recommends reviewing and updating your scripts where appropriate

Document versioning and the ALM solution (945333)If you have an existing solution installed such as the ALM solution enablingdocument versioning can affect fields and admin objects in the solution Forexample it is possible for certain reports or triggers in the ALM solution notto work or to produce unexpected behavior

NoteWith the release of Integrity 106 and later the ALM solution download isno longer maintained or available for download from the Integrity SupportCenter Contact your PTC Account Representative to learn more aboutavailable ALM solution offerings from PTC

For more information on known issues browse the Knowledge Base athttpwwwptccomsupportintegrityhtmSome Knowledge Base articles indicate potential workarounds or fixes thatcan be made to correct known issues


Specifying and Displaying Versioned Item IDs (926736)Versioned item IDs cannot be specified or displayed for the following

Integrity Component Affected AreaRelationships View When loading a branch in the

Relationships view (GUI) theversioned item ID does not displayAfter the branch is loaded theversioned item ID displays

Viewing and Editing Items Computed fields and range fields (ifusing an FVA to ID) do not displayversioned item IDs

Export Items to Microsoft Excel im exportissues (CLI) andExport Items to Excel (GUIWeb) donot export versioned item IDs

CLI Commands You cannot specify versioned itemIDs with the following CLIcommandsbull im printissue

bull im propagatetraces

bull im branchsegmentndashinsertLocationndashparentID

bull im issues ndashfocusIssueID

bull im viewsegmentndashfocusIssueIDndashsessionID

bull im viewduplicatesVisual Studio and EclipseIntegrations

Versioned items are not returned inthe integrations

Integrity Web Services You cannot specify versioned itemIDs for input and output does notdisplay versioned item IDs

Document Read and ReviewApplication

You cannot specify versioned itemIDs


Logging bull Audit log does not displayversioned item IDs

bull Client and server logs displaysome versioned item IDs

E-mail Notification Relationship field values do notdisplay versioned item IDs

Database ConsiderationsMigrate relationship data to new database table prior to upgrade

Integrity 107 introduced a new database storage model and table forrelationship data Prior to upgrading to Integrity 109 the relationship datafrom the old relationship table must already have been migrated to the newrelationship table using a 107 or 108 Integrity server

NoteIf the migration has not occurred prior to attempting an upgrade toIntegrity 109 the upgrade does not succeed but the database is still usableto run the original version of Integrity If you are performing a silentinstall the following error is logged in dbinstalllog

ERROR(0) Database migration aborted The migrationto the IIDeltaMap table must be performed prior toupgrading to Integrity 109 (and later) For migrationinformation see the Integrity 108 version of the PTCIntegrity Upgrading Guide

The new relationship table is more compact and grows at a significantlyslower rate than the relationship table that it replaces For more information onmigrating relationship data consult the 108 version of the PTC IntegrityUpgrading Guide

Grant SELECT_CATALOG_ROLE to the Oracle database userFor Oracle databases PTC recommends granting SELECT_CATALOG_ROLEto the database user to ensure that the correct SQL logging and query planretrieval permissions are available

Case-sensitive collation for Microsoft SQL server databasesIf you are using Microsoft SQL Server as your database the Integrity serverrequires a case-sensitive collation For example you can use SQL_Latin1_General_CP1_CS_AS


Oracle error in Document viewWhen working in the Integrity Document view an error can occur afterapplying a field filter for a full-text field The error(javasqlSQLSyntaxErrorException ORA-00918 column ambiguouslydefined) occurs only when the Integrity server is running on an Oracledatabase version earlier than 11201 The Integrity client erroneously showsthat the failed field filter is active when it is notThe underlying cause of the error is related to a known Oracle issue (Doc ID57024338 Bug 5702433 ldquoORA-918 from ANSI join with a CONTAINSclauserdquo) The defect is addressed in the base version of Oracle 11g Release 2(11201)

Duration of an Integrity 2009 database migrationMigrating an Integrity 2009 database to Integrity 10 can require several hoursdepending on certain factors During this time the installer can appear to havemade little progress You can check the progress of the upgrade by viewing thedbinstalllog file located in the following directory on the serverinstalldirlogdbinstalllog

For more information on factors that increase migration time contact PTC -Integrity Support

Duration of database migrationDatabase migrations can take longer than normal if the backing database isMicrosoft SQL Server and the IssueDeltas and IssueDeltaAtomstables contain a large amount of data (where either one of the tables is large orboth tables are large collectively) The duration of the migration is dependenton the speed of your database server and the size of your data so a testmigration is recommended as part of planning the upgrade window

SQL Server transaction log affects disk size allocationIf your implementation of Integrity is backed by a Microsoft SQL Server andthe IssueDeltaAtoms and IssueDeltas contain a large amount ofdata then a large amount of disk space is needed for the SQL Servertransaction logs Prior to the upgrade test the upgrade on test servers todetermine the size of the disk space that is needed for the SQL Servertransaction logs Then use that information to set the maximum size of thedatabase transaction log Also ensure that there is sufficient hard disk spacesize allocated where the transaction log resides

Error when using Oracle 12c with Integrity 108If your Integrity server is running on an Oracle 12c database the ORA-01792 maximum number of columns in a table or view is 1000error may occur This error is related to a known Oracle 12c issue (Doc ID


19516891 Bug 17376322 ldquoSelect Statement Throws ORA-01792 Errorrdquo)This defect is addressed by the Oracle patch 19509982

Compatibility SupportThe next several topics provide information about compatibilitybull Integrity Client and Server Compatibility on page 43bull Configuration Management Repository Compatibility on page 44bull Dedicated Integrity Server Compatibility on page 44bull Integrity Server and Integrity Agent Compatibility on page 45bull Integrity API Compatibility on page 45bull Implementer and Integrity Server Compatibility on page 45

Integrity Client and Server CompatibilityIntegrity server 109 supports connections from Integrity client 2009 SP7 and 100through 109If you are currently using an FSA-enabled proxy server and upgrading from anearlier release to Integrity 109 you do not have to perform the upgrade all atonce Integrity server 109 supports connections from a proxy Integrity server2009 SP7 and an Integrity server for 100 through 109Note the following

bull Upgrade the components of the system in the following order

1 Workflows and Documents and Test Management-enabled servers2 Configuration Management-enabled servers3 FSA proxy servers4 Clients

bull By default the servicepackpolicy file specifies the minimum Integrityclient version and service pack that can connect to Integrity server 109However you can configure these values as new service packs are releasedFor more information on configuring the servicepackpolicy file referto the PTC Integrity Server Administration Guide

bull Integrity supports the installation of multiple Integrity clients on a singlemachine For example a 109 client and a 108 client This is useful foraccessing functionality available in specific releases and connecting todifferent versions of the Integrity server For more information see the PTCIntegrity Server Administration Guide

bull The Web interface version does not depend on the client version


bull ViewSets edited with a new Integrity client may be unusable on older clientsand will have an adverse impact on your users if those ViewSets areconfigured to be mandatory For example a ViewSet edited with a 109Integrity Administration Client and published to a 109 server may only beusable for 109 clients Older clients will continue to be able to use existingViewSets that have not been edited by an 109 Integrity client Particular careshould be taken when working with mandatory ViewSets in a mixed versionenvironment A mandatory ViewSet edited with a new Integrity client maycause the older client to become unusable due to new functionality introducedin newer releases

bull If some users who are working within a project will be using an older Integrityclient ensure that you do not deactivate development paths in those projectsOlder clients do not interact correctly with deactivated development paths

bull Ensure the Integrity Administration Client and Integrity server versions matchAdministrative operations are not supported when using an IntegrityAdministration Client that is a different version than the Integrity serverversion

bull Integrity 109 (and later) includes the Ignore Keywords policy that preventskeywords from being expanded and unexpanded in text files worked on byusers of configuration management functionality For Integrity 108 (andearlier) clients this policy works for Member Check In and Member Rename operations For all other operations that have keyword settings thosekeyword settings apply even when the policy is set

Configuration Management RepositoryCompatibilityUpdates of earlier versions of the configuration management database repositoryto later versions are handled automatically by the Integrity server installer in thesame manner that configuration management repositories are automaticallyupdatedThe RCS-Style repository is no longer supported as of Integrity 100 and later

Dedicated Integrity Server CompatibilityYou can have multiple Integrity servers in your environment each dedicated tospecific functionality A common practice is to have one server dedicated toWorkflows and Documents functionality and one or more servers dedicated toConfiguration Management functionality


The Workflows and Documents server is the central server and runs the currentIntegrity version Any number of Configuration Management servers can beconnected to the central Workflows and Documents server ConnectedConfiguration Management servers can run any mix of Integrity versions from2009 SP7 through the current version

Integrity Server and Integrity Agent CompatibilityIntegrity server 109 supports connections from Integrity Agent 2009 SP7 andIntegrity 100 through 109 If you are upgrading from an earlier release toIntegrity Agent 109 you do not have to perform the upgrading all at once

Integrity API CompatibilityIntegrity provides an Application Program Interface (API) for integrating third-party products with Integrity The API provides a framework to invoke Integritycommands and receive responses Command compatibility via the API isconstrained by the commands that are supported for the API and by the commandchanges if any that affect compatibilityThe following table identifies the supported compatibility configurations for APIlanguage bindings with Integrity integration points

API Language API Version Released in IntegrityVersion

Integrity JavaC API 416 108415 107414 106413 105412 104411 100410 2009

Integrity Web ServicesAPI

102 10210 10097 2009 SP790 2009 SP6

Implementer and Integrity Server CompatibilityImplementer integrates with Integrity to provide functionality for workflows anddocuments configuration management or both


Supported DatabasesSupported DatabasesYou can find information about supported databases in Integrity ProductPlatforms

Dropped DatabaseThe following database versions are no longer supported in Integrity 101 andlaterbull Microsoft SQL Server 2005 1

bull Oracle 10g R2bull Oracle 11g R12

bull IBM DB2 for Linux Unix and Windows (all versions)bull IBM DB2 iSeries (all versions)

CautionEnsure database upgrades are performed before upgrading the Integrity server

Database MigrationDatabase schema migrations are automatically handled during the installationprocess when you upgrade using the full install executable During theinstallation you select your database type and database connection informationYou are then prompted to migrate the database schema you used with the existingIntegrity for use in this release For more information see the PTC IntegrityServer Administration Guide


1 Integrity 101 supports a minimum of Microsoft SQL Server 2008 SP3 or Microsoft SQLServer 2008 R2 SP1

2 Oracle 11g R1 is no longer supported in Integrity 108 and later

Notebull The installer does not permit you to create new tables if it detects any existing

Integrity tables If there are existing data your choices are to migrate the dataor exit the installation

bull For Oracle databases ORA-01555 errors can occur if you do not havesufficiently large rollback segments Consult your Oracle productdocumentation for more information

bull The database migration eliminates duplicate ACLs in the following way

If the ACL is a complete duplicate (same ACL name same principalsame permission name and same grantdeny value) then the duplicateACL is deleted

If the ACL is a partial duplicate such as conflicting values of grantdenythen the ACL with the deny value wins

If the migration fails you must resolve the error restore the database and thenattempt the migration again

NoteIf the migration fails due to a Database Transaction Log SizeExceeded error you can correct the problem and then rerun the migrationwithout first restoring the database

Debugging and Diagnosing Database IssuesDuring the installation the following file is created for debugging and diagnosticpurposes when a database is upgradedinstalldirlogdbinstalllog

where installdir is the path to the directory where you installed the Integrityserver

Integrations SupportSupported IntegrationsFor current information on supported integrations for Integrity go to


httpwwwptccompartnershardwarecurrentsupporthtm

Implementer IntegrationWhen upgrading your Integrity server specific issues with Implementerintegrations can occur If you are upgrading an Implementer integration contactPTC - Integrity Support for assistance and consult the documentation forImplementer

Getting Ready to UpgradeWhen to UpgradePTC provides an alert system that publishes Integrity Alerts for all new HotFixesas well as other pertinent product information (such as deprecated support foroperating systems databases and releases) You can select the criteria of interestto you and sign up for e-mail notifications to alert you to the relevant updates Youcan also review and search all existing alerts For more information go to theIntegrity Support Center athttpwwwptccomsupportintegrityhtmTo avoid disruption in service to your users perform the upgrade in off hours Ifthat is not possible remember to inform your users that you are performing anupgrade and that the Integrity is to be temporarily unavailable

Information Required for UpgradeBe ready with your customer information since the installation program promptsyou to provide this during upgrading Information is saved in the installdirconfigproperties isproperties file and is automatically displayedon the Integrity server Homepage

Backing UpBacking Up Your DatabaseYou cannot roll back without an existing database backup It is essential that youback up your existing database before starting the upgradePerforming regular backups of your database should already be part of yournormal operations


Notebull Always stop the Integrity server before performing any database maintenancebull If you changed the default location of the server database files make sure the

files that you are copying are from this new location

Backing Up Integrity Server DirectoryYou want to back up the installdir directory before running the installation Abackup of this directory allows you to restore the Integrity server directory if theneed arises

NoteTo ensure the database is not in use during a backup stop the Integrity serverbefore creating any backups

Performing a Trial RunBecause Integrity is a mission-critical application for your enterprise it isrecommended that you perform a test of the upgrade in the form of a trial runbefore installing live on the production server

Upgrading for UNIX UsersThe upgrading instructions in the next sections apply to both Windows and UNIXusers except as follows for UNIX systems

bull Make sure the environment variable $DISPLAY is set if necessarybull References to ldquoservicesrdquo do not apply to UNIXbull Install the Integrity server in a new location on UNIX without uninstalling the

existing (previous) serverbull Ensure that the new server replacing the existing server has been installed

configured tested and is performing as needed Then uninstall the existing(previous) server by running the following file

installdiruninstallIntegrityServerUninstall

For more information on stopping the server see the PTC Integrity ServerAdministration Guide


PTC recommends that you stop the Integrity server before installing Thisensures that the previous Integrity server is not running while upgrading yourdatabase

Upgrading to Integrity 109If you are upgrading to Integrity 109 from 108 you must upgrade using the fullinstall executableA full install using the executable is required when upgrading to Integrity 109from supported versions other than 107 For more information see Your UpgradePath on page 10This guide describes the process for installing using the full install executable

Single ServerThe following is a high-level description for upgrading a single server

1 Stop the existing Integrity2 Install 109 to a different directory than the one in which the existing Integrity

server resides3 Migrate the server configuration files such as properties policies reports and

triggers Make manual adjustments to configuration files as required4 Upgrade Integrity clients5 Uninstall the existing (previous) Integrity server

Multiple ServersThe following is a high-level description for upgrading multiple servers

1 Plan your upgrade sequence determining how to minimize downtime for eachserver The recommended upgrade sequence follows

a Workflows and Documents and Test Management-enabled serversb Configuration Management-enabled serversc FSA proxy serversd Clients

2 Implement your upgrade sequence For each server

a Stop the existing Integrity serverb Install Integrity server 109 to a different directory than the one in which

the existing Integrity resides


c Migrate server configuration files such as properties policies reports andtriggers Make manual adjustments to configuration files as required

3 Upgrade Integrity clients4 Uninstall all existing (previous) Integrity servers

Using Admin Staging to Upgrade Multiple ServersAs a best practice to avoid losing any in progress changes while upgrading PTCrecommends a three-tiered admin staging configuration for upgrading staging andproduction serversConsider the following admin staging configurationDevelopment (staging server) gt Test (staging server) gt Production (productionserver)This configuration reduces the risk of losing any in progress changes on theDevelopment and Test servers when the upgrade occurs

1 Migrate all of the changes you want to retain from Development to Test andfrom Test to Production

2 Ensure you have reliable backups of all of the servers in your admin stagingconfiguration

3 Ensure you have a rollback plan4 On the Development server

a From the command line run mksis stop to stop the serverb To uninstall the Windows service for your server run mksis remove

This removes the service only it does not uninstall the program filesc Install the new server using the Upgrade of an existing server option

Specify the Development servers database as the database to upgrade andpoint to the existing Integrity server install directory as the server toupgrade As part of this process the Windows service is installed

d From the new New_ServerInstallbin run isutil -cmigrateServerConfig Existing_ServerInstall

where New_Server_install is the new Integrity server 109 directory andExisting_ServerInstall is the existing (previous) Integrity server directory

This creates a very large amount of output including files that were notmigrated because of a conflict This output does not appear in theserverMigrationlog directory

e Manually migrate the customized contents of any of the followingExisting_ServerInstall directories datapublic_html datatriggers datagateway


5 On the Test server

a From the command line run mksis stop to stop your serverb To uninstall the Windows service for your server run mksis remove


Specify the Test servers database as the database to upgrade and point tothe existing Integrity server install directory as the server to upgrade Aspart of this process the Windows service is installed

d From New_ServerInstallbin run isutil -cmigrateServerConfig Existing_ServerInstall

where New_ServerInstall is the new Integrity server 109 directory andExisting_ServerInstall is the existing (previous) Integrity server directory



6 On the Production server



Specify this servers database as the database to upgrade and point to theexisting Integrity server install directory as the server to upgrade As partof this process the Windows service is installed

d From the New_ServerInstallbin run isutil -cmigrateServerConfig Existing_ServerInstall




7 Restart the Production server


8 Restart the Test server9 Restart the Development server10 To confirm that the Test server is functioning properly start the Admin

Migration Wizard on the Test server11 To confirm that the Development server is functioning properly start the

Admin Migration Wizard on the Development server

Installing Integrity 109 ServerThis section contains instructions for installing the Integrity server from the fullinstall executable

Determining the Correct licensedat FileAs you prepare to install Integrity 109 you must determine the correctlicensedat file to useIf you are upgrading an existing server you can continue to use the samelicensedat file On the existing server check the Existing_ServerInstallconfigpropertiesisproperties file andsearch for the mksislicensePath property which lists the path to thelicensedat file Existing_ServerInstall is the existing Integrity serverdirectoryIf you are moving the FlexNet server to new hardware PTC recommends usingthe PTC Licensing Tool (httpswwwptccomappslicenseManagerauthsslindexjsp) to get a license transfer This is not necessary if the Integrity server ismoving to new hardware but the FlexNet server is not movingYou can also use the PTC Licensing Tool to get a fresh copy of the license file

NoteIf you are upgrading to Integrity server 109 from an Integrity server earlierthan 101 determine the correct licensedat file before the upgrade Thisfile includes information customer information such as PTC_Customer_Number and PTC_Contract_Numbers


Step 1 Stop Existing Integrity ServerBefore attempting to install Integrity server 109 stop the existing Integrity serverAlways stop the server using the mksis stop command Stopping the serverusing this method ensures that the service is also stopped this is a requirementbefore installing a new Integrity server

CautionNever perform a hard stop of the Integrity server Archives can becomecorrupted if a checkin operation is being performed when a hard stop is usedto stop the Integrity server

For more information on stopping the existing Integrity server see the PTCIntegrity Server Administration Guide for that release

NoteThis release installs the service named Integrity 10 You need to uninstallthe service from the previous Integrity server release before installing Integrityserver 109 For information on installing and uninstalling the service see thePTC Integrity Server Administration Guide

Step 2 Install Integrity 109 ServerAs part of the installation and upgrade you must also perform the following tasks

1 Specify the installation type (server host or proxy only)2 Specify a suitable installation directory3 Specify the appropriate server host name and port number for Integrity server

1094 Upgrade your existing database5 Migrate the server configuration files and admin objects6 Identify changes to ACL Permissions in this release and upgrade your ACLs

accordinglyFor detailed information on configuring and starting the Integrity server or forinformation on administering the Integrity server see the PTC Integrity ServerAdministration Guide


Server Installation TypeThe Integrity server installer prompts you to specify an installation type

bull If you are installing a new server click New serverbull If you are upgrading an existing server click Upgrade of an existing server

To upgrade an existing server

NoteIf you do not follow this procedure you must manually put the IPTs into thedatabase after the server starts If you have RM 07 IPTs none of the existingRM field names that are built-in fields in Integrity are mapped to theappropriate fields in the IPTs This requires that you manually update the IPTs

1 Run the Integrity installation2 When the installer prompts you for the type of installation click Upgrade of an

existing server and then click Next3 Type the path or browse to the location of the existing server install directory

and then click Next

The installer copies any existing IPTs and stores them in the Integrity serverdatabase

4 Continue the server installation

Server Repository TypeIntegrity supports the database repository only The selected server repository isthe location where configuration management information (including revision andproject information) is stored

Installation DirectoryIf you are migrating server files you must install the Integrity server to a differentdirectory than the previous installation

Set Server Hostname and Port NumberThe Integrity server uses the fully qualified host name of the server machineHowever when upgrading to this release you want to retain the same host nameand port number used by the previous Integrity server installation


Upgrade Your DatabaseDuring the installation you select your database type and database connectioninformation You are then prompted to migrate the database schema you used withthe existing Integrity server for use in Integrity 109 For more information seethe PTC Integrity Server Administration Guide

Notebull The server installer does not permit you to create new tables if it detects any

existing Integrity tables If there are existing data your choices are to migratethe data or exit the installation



NoteIf the migration fails due to a Database Transaction Log Size Exceeded erroryou can correct the problem and then rerun the migration without firstrestoring the database

Upgrade ACL PermissionsThe Access Control Lists (ACLs) use a set of database tables to store securityconfiguration and administrative information for the IntegrityPermissions added since the last release are set to deny For more information seethe PTC Integrity Server Administration Guide

Step 3 Migrate Server Configuration FilesIn this release certain properties are now contained in the database If you haveexisting properties you want to retain Integrity provides the means to migrateserver properties and configuration files automatically However the source filesyou are migrating must be located in the original directory structureIf you intend to manually transfer server configuration file information instead ofusing the utility provided see the section entitled ldquoManually Transferring ServerConfiguration Filesrdquo


To migrate server settings and configuration files use themigrateServerConfig command for the isutil utilityOnce the properties are successfully migrated to the database they can be furthermodified in the Integrity Administration Client GUI or from the CLI using theintegrity setproperty im setproperty and si setpropertycommands and the im diag and si diag commands

Migrating Using the isutil UtilityThe migrateServerConfig command for the isutil utility migrates

bull properties

NoteThe migrateServerConfig command converts security settings aspart of the properties file migration

bull policiesbull trigger scripts

Script files that do not exist in the destination location are copied to thedestination location and retain their original file names All other script filenames have an appropriate file extension appended and are copied to thedestination location

A file extension of 10 is appended for Integrity versions 100-104 A file extension of 11 is appended for Integrity 105 A file extension of 13 is appended for Integrity 106

No merging of script contents is performed by the utility You must manuallymodify script file contents

Similarly the globalevents file is copied and renamed

It is renamed to globalevents10 on Integrity versions 100-104 It is renamed to globalevents11 on Integrity 105 It is renamed to globalevents13 on Integrity 106


NoteIf the scripts are located outside of the standard directory the utilitydoes not copy them You must manually move them to the desiredlocation

NoteAs of Integrity 106 Japanese versions of the trigger scripts are nolonger installed with Integrity server

bull reports and report resources

NoteIn the event of an upgrade conflict (a report file was edited by the user andwas also updated by PTC since the last release) the existing reports in thedestination location (installdirdatareports)are retained withtheir original filenames and the new files have a number appended to theirfilenames For Integrity 106 and later the included report files supportlocalization (see the documentation for localizing reports in the PTCIntegrity Server Administration Guide) If you are using included reportsfrom an Integrity release 105 and earlier you can continue to use thosereports if there is no localization requirement To make use of thelocalization features of reports manually update the reports as needed

After you run this utility to upgrade to Integrity 106 and later theinstalldirdata reportsja folder will be present on theupgraded server However PTC Integrity no longer supports language-based folder so you can delete this folder Manually copy your pre-106report recipes (English and non-English) to installdirdatareportsrecipes

bull Java properties from installdirconfigmksserviceconf

Memory (only if they are larger in the previous release than the latestrelease) -Xms and -Xmx -Xss

Garbage collection (if they do not currently exist)-XX+PrintGCTimeStamps


-XX+PrintTenuringDistribution and-XX+PrintGCDetails

bull change package reviewer rulesbull sitenoteshtml (if the file does not exist in the target directory)bull information about shared Visual Studio solutions and projects in

installdirdatavsi vsibindingproperties

NoteAs of Integrity 106 this utility no longer migrates files that are not part of theIntegrity version to which you are updating If you wish to use existing fileson your system that were dropped or deprecated you must manually copythem from the source server (that is the one you are migrating from) todestination server (that is the one you are migrating to)

The isutil utility is installed with Integrity 10 in the following locationinstalldirbinisutilexe

where installdir is the installation directory for Integrity server 10The syntax for the command isisutil ndashc migrateServerConfig ldquoinstalldirrdquo

where installdir is the installation directory for the source Integrity server you aremigrating from

CautionThere is no undo mechanism in place to undo a migration To restore Integrityserver 10 files see the section entitled ldquoMigration Backup Filesrdquo

For the purposes of this procedure only the migrateServerConfigcommand is documented and intended to be used For more information on theavailable commands for the isutil utility see the PTC Integrity ServerAdministration GuideUpon completion the command outputs a message to the console describing thesuccess or failure of the migration If the command fails details are printed to theconsole only requiring you to analyze and save the output If there are script filesyou need to manually merge them at this time


NotePasswords in migrated files are never displayed in messages to the console orthe log file Each character in the password is replaced with ldquoXrdquo

Migration Backup FilesThe migrateServerConfig command for the isutil utility creates abackup of every file in the Integrity server 10 installation directory that it changesFiles are backed up into the following locationinstalldirbackup

where installdir is the Integrity server 10 installation directoryThe backup directory contents mimic the target server directory structure Thebackup root directories are versioned such that rerunning the migration neveroverwrites existing backup files For example running the migration a secondtime creates an additional folder backup1 and running a third time backup2

Migration LogThe migrateServerConfig command for the isutil utility generates thefollowing loginstalldirlogserverMigrationlog

where installdir is the Integrity server 10 installation directoryThe serverMigrationlog file contains

bull The date and time the migration occurredbull The absolute path to the source directory used for example the installation

directory for Integrity server 10bull The name of each file changed by the utility and the name of the backup file

created to represent the original (see the section entitled ldquoMigration BackupFilesrdquo)

bull A description of how the file was changed stating

if the file was deleted if the file is an exact copy from the old installation (including the name of

the source file copied and its new name) what settings were changed moved or removed (including the setting

name its original value and its new value)


Migrating Agent PropertiesThe Integrity Agent AgentUtilsexe utility migrates Integrity Agentproperties This utility is run on each agent and must be pointed at the previousinstalled version of the Integrity AgentThe utility also migrates the following Java properties from installdirconfigmksserviceconf

bull Memory (only if they are larger in the previous release than in the latestrelease) -Xms -Xmx - Xss

bull Garbage collection (if they do not currently exist)-XX+PrintGCTimeStamps -XX+PrintTenuringDistribution and -XX+PrintGCDetails

bull The Integrity Agent 10 target directory must be located in a different locationthan the original Integrity Agent 2009 installation location

The utility is installed with Integrity Agent 10 in the following locationinstalldirbinAgentUtilsexe

where installdir is the directory Integrity Agent is migrated toThe syntax for the command isagentutil ndashc migrateAgentConfig Integrity Agent installdir

where Integrity Agent installdir is the current Integrity Agent target directoryOn completion the command outputs a message to the console describing thesuccess or failure of the migration If the command fails details are printed to theconsole only requiring you to analyze and save the output


Step 4 Start Integrity 109 ServerTo start the new Integrity server use the mksis start commandFor complete details on running the Integrity server see the server installationdocumentation in thePTC Integrity Server Administration Guide or the IntegrityHelp CenterEnsure that users can connect to the Integrity server by checking the server log file(and verifying an entry for GENERAL(0) Listening on port nnnn) orby connecting through an Integrity client


Step 5 Uninstall Existing Integrity Server

NoteBefore uninstalling the existing Integrity server ensure that the Integrityserver replacing it has been installed configured tested and is performing asrequired

For more information on uninstalling the existing Integrity server (the previousinstallation you are upgrading from) refer to the documentation that wasoriginally issued for the release version you installedWhen uninstalling Integrity server on Windows you should always use thefollowing fileinstalldiruninstallIntegrityServerUninstallexe

After the server is stopped the IntegrityServerUninstallexe fileremoves the Integrity service and launches the application that performs the serveruninstallIf the server is running as a service make note of the user the service is running asbefore uninstalling In most cases this is ldquosystemrdquo If you use the operatingsystemrsquos uninstall feature or the uninstall shortcut in the Integrity server programgroup you must manually remove the service

NoteWhen you are ready migrate your relationship data to the new table introduced inthis release For more information see the next section


2Command Line Interface Changes

Command Line Information 64im Command Options 64integrity Command Options65si Command Options 65tm Command Options66ACL Permissions66

This release includes changes that affect the command line interface (CLI)

NoteAs part of any upgrade PTC recommends that you review and update anyscripts you use with the CLI

This document summarizes the key changes for the command line interfaces thathave changes in this release of Integrity

63

Command Line InformationFor detailed information on all commands and options see the CLI man pages

im Command Optionsim Command Changesim copyissue New command options

ndashcustomFieldDefinition

ndashcustomFieldValueim createcontent New command option

ndashcustomFieldValue=valueim createfield New value for ndashtype

ierim createissue New command options


ndashcustomFieldValueim createsegment New command option

ndashcustomFieldValue=valueim editfield New command options

ndashierDefaultColumns

ndashierThingName

New value for ndashremoveOverrideierThingName

Deprecated value forndashremoveOverride

ierRelativeURIim editissue New command options

ndashremoveCustomFieldDefinition


ndashcustomFieldValue

ndash[no|confirm]removeCustomFieldDefinitions

ndash[no|confirm]removeCustomFieldPickValues


im Command Changes

ndash[no|confirm]removeCustomFieldValues

im fields New values for ndashfieldsierDefaultColumns

ierThingNameim importcontent New command option

ndashcustomFieldValueim importissue New command options


ndashcustomFieldValueim importsegment New command option

ndashcustomFieldValueim viewissue New command option

ndash[no]showIncomingExternalReferences

im viewpendingimports New commandim viewsegment New command option

ndashperspective

integrity Command OptionsThere are no changes to integrity commands for this release

si Command Optionssi Command Changessi createdevpath Deprecated command option

ndashresultingSubprojectConfiguration

New command optionsndashcreationMethod

ndashonLiveConfigurationsi extenddevpath Deprecated command option

ndashprojectRevision

Command Line Interface Changes 65

tm Command Optionstm Command Changestm resultfields New values for ndashfields

ierDefaultColumns

ierThingName

ACL PermissionsThere are no changes to the Access Control Lists (ACLs) for this release


Upgrading to Integrity 109

Your Upgrade Path

Before You Start

General Considerations

Integrity Product Version Considerations

Document Versioning Considerations

Database Considerations

Compatibility Support

Integrity Client and Server Compatibility

Configuration Management Repository Compatibility

Dedicated Integrity Server Compatibility

Integrity Server and Integrity Agent Compatibility

Integrity API Compatibility

Implementer and Integrity Server Compatibility

Supported Databases

Database Migration

Debugging and Diagnosing Database Issues

Integrations Support

Getting Ready to Upgrade

Backing Up

Performing a Trial Run

Upgrading for UNIX Users


Single Server

Multiple Servers

Using Admin Staging to Upgrade Multiple Servers

Installing Integrity 109 Server

Determining the Correct licensedat File

Step 1 Stop Existing Integrity Server

Step 2 Install Integrity 109 Server

Step 3 Migrate Server Configuration Files

Step 4 Start Integrity 109 Server


Command Line Interface Changes

Command Line Information

im Command Options

integrity Command Options

si Command Options

tm Command Options

ACL Permissions

Copyright copy 2016 PTC Inc andor Its Subsidiary Companies All Rights Reserved

User and training guides and related documentation from PTC Inc and its subsidiary companies (collectivelyPTC) are subject to the copyright laws of the United States and other countries and are provided under alicense agreement that restricts copying disclosure and use of such documentation PTC hereby grants to thelicensed software user the right to make copies in printed form of this documentation if provided on softwaremedia but only for internalpersonal use and in accordance with the license agreement under which theapplicable software is licensed Any copy made shall include the PTC copyright notice and any otherproprietary notice provided by PTC Training materials may not be copied without the express written consentof PTC This documentation may not be disclosed transferred modified or reduced to any form includingelectronic media or transmitted or made publicly available by any means without the prior written consent ofPTC and no authorization is granted to make copies for such purposes Information described herein isfurnished for general information only is subject to change without notice and should not be construed as awarranty or commitment by 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 license agreement contains valuable tradesecrets and proprietary information and is protected by the copyright laws of the United States and othercountries It may not be copied or distributed in any form or medium disclosed to third parties or used in anymanner not provided for in the software licenses agreement except with written prior approval from PTC

UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVILDAMAGES AND CRIMINAL PROSECUTION

PTC regards software piracy as the crime it is and we view offenders accordingly We do not tolerate thepiracy of PTC software products and we pursue (both civilly and criminally) those who do so using all legalmeans available including public and private surveillance resources As part of these efforts PTC uses datamonitoring and scouring technologies to obtain and transmit data on users of illegal copies of our softwareThis data collection is not performed on users of legally licensed software from PTC and its authorizeddistributors If you are using an illegal copy of our software and do not consent to the collection andtransmission of such data (including to the United States) cease using the illegal version and contact PTC toobtain a legally licensed copy

Important Copyright Trademark Patent and Licensing Information See the About Box or copyrightnotice of your PTC software

UNITED STATES GOVERNMENT RIGHTS

PTC software products and software documentation are ldquocommercial itemsrdquo as that term is defined at 48 CFR 2101 Pursuant to Federal Acquisition Regulation (FAR) 12212 (a)-(b) (Computer Software) (MAY 2014)for civilian agencies or the Defense Federal Acquisition Regulation Supplement (DFARS) at 2277202-1(a)(Policy) and 2277202-3 (a) (Rights in commercial computer software or commercial computer softwaredocumentation) (FEB 2014) for the Department of Defense PTC software products and softwaredocumentation are provided to the US Government under the PTC commercial license agreement Useduplication or disclosure by the US Government is subject solely to the terms and conditions set forth in theapplicable PTC software license agreement

PTC Inc 140 Kendrick Street Needham MA 02494 USA

Contents



5




7










































































bull getProject()





































where


where

























































































































































dynamic or static

















bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions

Contents



5




7










































































bull getProject()





































where


where

























































































































































dynamic or static

















bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions




7










































































bull getProject()





































where


where

























































































































































dynamic or static

















bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions










































































bull getProject()





































where


where

























































































































































dynamic or static

















bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions
































where


where

























































































































































dynamic or static

















bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions















































































































































dynamic or static

















bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions





bull im issues

bull im viewissue

















bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions











bull PromoteIssuejs

bull javamailjs

bull hellojs

bull escalatejs
































































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions

























































102 10210 10097 2009 SP790 2009 SP6













































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions











































































































and then click Next


















bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions












bull properties






























































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions






















































63











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions











ndashierThingName










im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions

im Command Changes










ndashperspective









ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions


ierDefaultColumns

ierThingName




Your Upgrade Path

Before You Start












Supported Databases

Database Migration




Backing Up




Single Server

Multiple Servers











im Command Options


si Command Options

tm Command Options

ACL Permissions

PTC Integrity Upgrading Guidesupported by the database repository, you must migrate to a supported...

Documents

Transcript of PTC Integrity Upgrading Guidesupported by the database repository, you must migrate to a supported...