Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
262:upgrade_from_712 [2026/09/28 19:26] – created - external edit 127.0.0.1262:upgrade_from_712 [2026/11/19 15:55] (current) – Goetz, Sebastian
Line 1: Line 1:
-===== How to upgrade to version 26.1 =====+====== How to upgrade from Stages 7.12 to version 26.2 ======
  
-**Version 26.1 is currently only available on Stages Managed Service instances. **On-premise usage will be made available later this year.+An upgrade from Stages 7.12 to 26.2 is a major version step. This page is divided into two parts:
  
-Please [[[email protected]|contact our customer care team]] to request an upgrade of your Stages Managed Service instance.+  * **[[#part_1plan_the_upgrade|Part 1 – Plan the upgrade]]** describes the organizational preparation and testing. It is relevant for **all customers**. 
 +  * **[[#part_2conduct_the_upgrade|Part 2 – Conduct the upgrade]]** describes the technical installation steps. It is relevant for **administrators of on-premise installations**. For Stages Managed Service instances, these steps are performed by UL.
  
-If you use a customized metamodel on your Stages Managed Service instance, it needs to be adapted to v26 by your Stages product consultant first.+===== Before you start: availability and limitations =====
  
-//Note: all process release automations have to be finished before an upgrade can be performed.// +**Version 26.2 is currently only available on Stages Managed Service instances. On-premise usage will be made available later this year.**
-(see Report [[reports:start#running-process-release-automations|Running Process Release Automations]])+
  
-//Note: An existing SAML connection needs to be reestablished, by registering new URLs at the IDP server.//+**Integrations with PTC products are not yet available for 26.2.**
  
-===== Upgrade your system to at least Stages 7.12.5.0 =====+**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
  
-**Only** Stages databases of Stages **7.12.5.0 or newer** can be upgraded to Stages 26.1. Therefore upgrade to this version first if not yet done.+===== Part 1: Plan the upgrade =====
  
-===== Ensure consistent data =====+To ensure a smooth transition without disrupting your productive process work, we strongly recommend the following procedure.
  
-To minimize the chance for issues during the upgrade it is recommended to execute ''ensureDatabaseIntegrity.bat|sh'' before upgrading to Stages 26.1.+==== 1. Check the prerequisites ====
  
-To minimize the runtime of ''ensureDatabaseIntegrity'' add the following config properties to config.xml to skip those steps:+**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. 
 + 
 +==== 2. Update customized Stages extensions ==== 
 + 
 +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) 
 + 
 +==== 3. Review functional changes ==== 
 + 
 +The following changes require preparation on your side: 
 + 
 +  * **Workspace collections replace Group and Common Elements** \\ The workspace settings **Group** and **Common Elements** no longer exist in 26.2. Their functionality now has to be modeled via **workspace collections**. Plan which collections you need before the upgrade. For details and examples see [[262:collectionmigration|Migrate process interface handling to workspace collections]]. 
 +  * **SAML connection** \\ An existing SAML connection needs to be re-established by registering the new URLs at the IdP server. Coordinate this with the team responsible for your identity provider. 
 + 
 +==== 4. Set up a test system ==== 
 + 
 +Always perform the upgrade 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** 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. 
 + 
 +Then upgrade the test system as described in [[#part_2conduct_the_upgrade|Part 2 – Conduct the upgrade]]. 
 + 
 +==== 5. Test the upgrade ==== 
 + 
 +After the test system has been upgraded, perform a thorough test. 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 
 + 
 +==== 6. Schedule the productive upgrade ==== 
 + 
 +Only when all tests have been completed successfully, the productive system may be upgraded. 
 + 
 +  * **Stages Managed Service:** Please [[[email protected]|contact our customer care team]] to request the upgrade of your instance. 
 +  * **On-premise:** Upgrade the productive system as described in [[#part_2conduct_the_upgrade|Part 2 – Conduct the upgrade]]. 
 + 
 +===== Part 2: Conduct the upgrade ===== 
 + 
 +Perform the following steps **first on the test system** and – after all tests have been completed successfully – **on the productive system**. 
 + 
 +==== 1. Finish running process release automations ==== 
 + 
 +All process release automations have to be finished before an upgrade can be performed (see report [[reports:start#running-process-release-automations|Running Process Release Automations]]). 
 + 
 +==== 2. 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:
  
 <code xml config.xml> <code xml config.xml>
Line 27: Line 102:
 </code> </code>
  
-Note: Stages should be stopped while ensureDatabaseIntegrity is running.+//Note: Stages should be stopped while ''ensureDatabaseIntegrity'' is running.//
  
-===== Create Backups Before Upgrading =====+==== 3. Create backups ====
  
-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.+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 =====+==== 4. Install Java 25 ====
  
-===== Install Stages 26.1 =====+==== 5. Install Stages 26.2 ====
  
-===== Execute Manual Actions =====+==== 6. Execute manual actions ====
  
 === server.xml migration === === server.xml migration ===
  
-Remove the following lines from ''$STAGES_CONF/server.xml''+Remove the following lines from ''$STAGES_CONF/server.xml'':
  
 <code xml> <code xml>
-<Realm className="org.apache.catalina.realm.CombinedRealm" >  +<Realm className="org.apache.catalina.realm.CombinedRealm" > 
-    <Realm className="de.methodpark.stages.containerauth.SSLAuthenticatorRealm" roles="pki_user"/>  +    <Realm className="de.methodpark.stages.containerauth.SSLAuthenticatorRealm" roles="pki_user"/> 
-    <Realm className="de.methodpark.stages.containerauth.SimpleAuthenticationRealm" roles="StagesUser" />  +    <Realm className="de.methodpark.stages.containerauth.SimpleAuthenticationRealm" roles="StagesUser" /> 
-</Realm> +</Realm>
 </code> </code>
  
Line 56: Line 132:
 </code> </code>
  
-remove the Context elements with path="/stages" and path="/reporting":+Remove the ''Context'' elements with ''path="/stages"'' and ''path="/reporting"'':
  
 <code xml> <code xml>
Line 67: Line 143:
 </code> </code>
  
-In case one of the Connectors are configured to use protocol "org.apache.coyote.http11.Http11Nio**2**Protocol" replace that by "org.apache.coyote.http11.Http11NioProtocol"+In case one of the connectors is configured to use protocol ''org.apache.coyote.http11.Http11Nio**2**Protocol'', replace it by ''org.apache.coyote.http11.Http11NioProtocol'':
  
 <code xml> <code xml>
 <Connector port="[...]" <Connector port="[...]"
-protocol="org.apache.coyote.http11.Http11NioProtocol" +    protocol="org.apache.coyote.http11.Http11NioProtocol" 
-[...]+    [...]
 /> />
 </code> </code>
Line 78: Line 154:
 === Authentication method configuration migration === === Authentication method configuration migration ===
  
->//In case SAML SSO is enabled please ensure the idp-metadata.xml file is available in ''$CONF_STAGES''.//+> //In case SAML SSO is enabled, please ensure the ''idp-metadata.xml'' file is available in ''$CONF_STAGES''.//
  
-The ACS URLs changed and because of that the information about Stages in the IDP must be updated. Best case is to take the sp-metadata.xml file and import it on the IDP. Certificates should stay the same.+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 as the ''idp-metadata.xml'' file from the SAML IDP.+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.1.xml''.+The original ''config.xml'' will be backed up as ''config.before-26.2.xml''.
  
-<code bash>+<code>
 $STAGES_ROOT/bin/upgradeConfigXml.sh|bat $STAGES_ROOT/bin/upgradeConfigXml.sh|bat
 </code> </code>
Line 98: Line 174:
 database.jdbc.url= database.jdbc.url=
 </code> </code>
-They are similar to these properties from conf/database.properties: torque.database.default.driver, torque.database.default.url+ 
 +These correspond to the properties ''torque.database.default.driver'' and ''torque.database.default.url'' from ''conf/database.properties''.
  
 <code properties secret.properties> <code properties secret.properties>
Line 104: Line 181:
 database.password= database.password=
 </code> </code>
-and those are the like torque.database.default.username, and torque.database.default.password. 
  
->Add rewriteBatchedStatements=true as parameter to database.jdbc.url if you are using MySQL.+These correspond to ''torque.database.default.username'' and ''torque.database.default.password''. 
 + 
 +> Add ''rewriteBatchedStatements=true'' as parameter to ''database.jdbc.url'' if you are using MySQL. 
 + 
 +==== 7. After the upgrade ====
  
 +  * **Set up workspace collections** via ''Administration > Workspaces > Collections'' as planned in [[#review_functional_changes|Part 1, step 3]]. Then check via the [[262:remoteassociations|Process Interfaces]] menu that process interfaces are created as expected (see [[262:collectionmigration|Migrate process interface handling to workspace collections]]).
 +  * **Update the IdP:** If SAML SSO is used, make sure the new Stages URLs are registered at the IdP (see [[#authentication_method_configuration_migration|Authentication method configuration migration]]).
 +  * **Test:** On the test system, continue with [[#test_the_upgrade|Part 1, step 5 – Test the upgrade]].