This is an old revision of the document!
How to upgrade from Stages 7.12 to version 26.2
Version 26.2 is currently only available on Stages Managed Service instances. On-premise usage will be made available later this year.
Integrations with PTC products are not yet available for 26.2.
The following scripts are currently not yet available for 26.2:
- Transfer Mapping script – transfers compliance mapping associations to a new reference model
- Migrate Metamodel script – adapts the process content so that it matches a new metamodel
Note: The workspace settings Group and Common Elements no longer exist in 26.2. Their functionality now has to be modeled via workspace collections. For details see Migrate process interface handling to workspace collections.
Please contact our customer care team to request an upgrade of your Stages Managed Service instance.
Note: All process release automations have to be finished before an upgrade can be performed (see report Running Process Release Automations).
Note: An existing SAML connection needs to be re-established by registering the new URLs at the IdP server.
Recommended upgrade procedure
An upgrade from Stages 7.12 to 26.2 is a major version step. To ensure a smooth transition without disrupting your productive process work, we strongly recommend the following procedure:
- Update customized stages extensions first
If you use any of the following, contact your responsible Stages product consultant before the upgrade, so that these products can be updated to Stages 26.2:- customized metamodel
- customized reports
- Admin Jobs
- other customer-specific add-ons (e.g. importers, exporters)
- Set up a dedicated test system
Always perform the installation on a separate test system first – never directly on your productive system. The test system must be connected to a mirror (copy) of the productive database, so that all tests are performed with your real customer data. - Connect all third-party systems
Connect all third-party systems to the test system that are also connected to your productive system (e.g. identity provider/SAML, CMS/file storage, ALM tools, mail server), so that these integrations can be tested as well. - Perform a thorough test
After the test system has been set up, perform a thorough test based on the test checklist below. - Upgrade the productive system
Only when all tests have been completed successfully, the productive system may be upgraded. Follow the technical steps described in the sections below.
Test checklist
We recommend testing all common actions that are performed in Stages within your organization (e.g. modeling, releasing). The following checklist serves as a general guideline and should be extended by your organization-specific use cases.
Viewing
- All visualizations render correctly (including their different parameter settings)
- All processes are displayed correctly
Modeling
- Creating elements and associations
- File upload to a connected CMS system
- Assigning users to a role
- Creating compliance mapping associations
- Creating tailoring associations
Management
- Performing module updates in an integrated workspace
- Creating a process version
- Release as valid version
- Performing tailoring (manually and via the tailoring assistant)
- Running a process release automation
Administration
- Creating workspaces and collections
- Creating test users
- Assigning permissions
- Creating participants and assigning users
Upgrade your system to at least Stages 7.12.5.0
Only Stages databases of Stages 7.12.5.0 or newer can be upgraded to Stages 26.2. Therefore upgrade to this version first if not yet done.
Ensure consistent data
To minimize the chance of issues during the upgrade, it is recommended to execute ensureDatabaseIntegrity.bat|sh before upgrading to Stages 26.2.
To minimize the runtime of ensureDatabaseIntegrity, add the following config properties to config.xml to skip these steps:
- config.xml
<property name="database.cleanup.targets" value="false"/> <property name="database.cleanup.associationAttributes" value="false"/>
Note: Stages should be stopped while ensureDatabaseIntegrity is running.
Create backups before upgrading
To be safe in case of any problems during the update, back up your database and the stages folder before the upgrade.
If the backup is running automated, please check whether the backup was created successfully.
Install Java 25
Install Stages 26.2
Execute manual actions
server.xml migration
Remove the following lines from $STAGES_CONF/server.xml:
<Realm className="org.apache.catalina.realm.CombinedRealm" > <Realm className="de.methodpark.stages.containerauth.SSLAuthenticatorRealm" roles="pki_user"/> <Realm className="de.methodpark.stages.containerauth.SimpleAuthenticationRealm" roles="StagesUser" /> </Realm>
and
<Valve className="org.apache.catalina.authenticator.SingleSignOn" />
Remove the Context elements with path=“/stages” and path=“/reporting”:
<Context path="/stages" docBase="stages" cookies="true"> [...] </Context> <Context path="/reporting" docBase="reporting" cookies="true" > [...] </Context>
In case one of the connectors is configured to use protocol org.apache.coyote.http11.Http11Nio2Protocol, replace it by org.apache.coyote.http11.Http11NioProtocol:
<Connector port="[...]" protocol="org.apache.coyote.http11.Http11NioProtocol" [...] />
Authentication method configuration migration
In case SAML SSO is enabled, please ensure theidp-metadata.xmlfile is available in$CONF_STAGES.
The ACS URLs have changed, therefore the information about Stages in the IdP must be updated. Ideally, take the sp-metadata.xml file and import it into the IdP. Certificates should stay the same.
The authentication section in the config.xml file needs to be migrated to a new format. The basic conversion can be done by the following script call. Please review the results in detail and add missing information, such as the idp-metadata.xml file from the SAML IdP.
The original config.xml will be backed up as config.before-26.2.xml.
$STAGES_ROOT/bin/upgradeConfigXml.sh|bat
Database access configuration migration
The conf/database.properties file used in Stages 7.12 and earlier is no longer in use. Database connection settings are now configured in conf/config.properties and conf/secret.properties with the following property keys:
- config.properties
database.driver.class.name= database.jdbc.url=
These correspond to the properties torque.database.default.driver and torque.database.default.url from conf/database.properties.
- secret.properties
database.username= database.password=
These correspond to torque.database.default.username and torque.database.default.password.
AddrewriteBatchedStatements=trueas parameter todatabase.jdbc.urlif you are using MySQL.