feat: split optimize upgrade to camunda 8 & 7 versions

related to camunda/camunda-optimize#14024

optimize/self-managed/optimize-deployment/migration-update/2.4-to-2.5.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/2.4-to-2.5.md

@@ -18,7 +18,7 @@ Here you will find information about:
 
 ## Limitations
 
-If you intend to make use of the new [Multi-Tenancy-Feature](./../configuration/multi-tenancy.md), you need to perform a [full reimport](../../reimport) and may need to amend your existing reports by selecting the tenant you want the report to be based on.
+If you intend to make use of the new [Multi-Tenancy-Feature](./../../configuration/multi-tenancy.md), you need to perform a [full reimport](../../reimport) and may need to amend your existing reports by selecting the tenant you want the report to be based on.
 
 ## Known issues
 

optimize/self-managed/optimize-deployment/migration-update/2.5-to-2.6.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/2.5-to-2.6.md

@@ -48,13 +48,13 @@ Given the scenario that the user `john` owns a collection `John's Collection` th
 
 You can now grant users `Super User` permissions, which allows them to bypass the owner/collection permissions, enabling them to access all available entities. This can, for example, be useful if entities are owned by users that are not available anymore.
 
-To grant Super User permissions, see the [Authentication & Security Section](./../configuration/system-configuration.md#security).
+To grant Super User permissions, see the [Authentication & Security Section](./../../configuration/system-configuration.md#security).
 
 ## Known issues
 
 ### Rebuild your Optimize plugins
 
-With Optimize 2.6.0, the plugin system was overhauled. For your plugins to continue to work, you have to rebuild them with the latest Optimize plugin artifact as an uber jar. Refer to the updated [plugin setup guide](./../plugins/plugin-system.md#set-up-your-environment).
+With Optimize 2.6.0, the plugin system was overhauled. For your plugins to continue to work, you have to rebuild them with the latest Optimize plugin artifact as an uber jar. Refer to the updated [plugin setup guide](./../../plugins/plugin-system.md#set-up-your-environment).
 
 ### Misinterpreted cron expressions
 

optimize/self-managed/optimize-deployment/migration-update/2.6-to-2.7.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/2.6-to-2.7.md

@@ -45,12 +45,12 @@ Optimize has an identity synchronization in place that fetches all users from th
 
 If you start Optimize `2.7` and the engine is down at the time of a user synchronization, it is possible that you will lose all your collection permissions. This is due to Optimize not being able to receive the correct authorizations for the collections and as a result, all the collection roles are removed.
 
-The easiest way to recover your permissions and regain access to your collections would be to add a user ID to the `auth.superUserIds` property of your [configuration file](./../configuration/system-configuration.md#security), then re-adding the necessary permissions as this user.
+The easiest way to recover your permissions and regain access to your collections would be to add a user ID to the `auth.superUserIds` property of your [configuration file](./../../configuration/system-configuration.md#security), then re-adding the necessary permissions as this user.
 
 After you have regained the roles of your collections, you should consider one of the two next follow-up steps:
 
 - Preferred solution: Update to Optimize 3.2.0 to fix the issue.
-- Interim solution: In case you anticipate the engine being taken down, we recommend also stopping Optimize to prevent the same scenario from reoccurring. In addition, you can also change the frequency at which this collection cleanup occurs by adjusting the `import.identitySync.cronTrigger` expression in your [configuration file](./../configuration/system-configuration.md#security) to `0 0 1 * * *`, which results in executing the sync once per day at 01:00 AM.
+- Interim solution: In case you anticipate the engine being taken down, we recommend also stopping Optimize to prevent the same scenario from reoccurring. In addition, you can also change the frequency at which this collection cleanup occurs by adjusting the `import.identitySync.cronTrigger` expression in your [configuration file](./../../configuration/system-configuration.md#security) to `0 0 1 * * *`, which results in executing the sync once per day at 01:00 AM.
 
 ### Misinterpreted cron expressions
 

optimize/self-managed/optimize-deployment/migration-update/2.7-to-3.0.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/2.7-to-3.0.md

@@ -44,19 +44,19 @@ The update should now successfully complete.
 
 ### Cannot disable import from particular engine
 
-In 3.0.0, it is not possible to deactivate the import of a particular Optimize instance from a particular engine (via `engines.${engineAlias}.importEnabled`). In case your environment is using that feature for e.g. a [clustering setup](./../configuration/clustering.md), we recommend you to stay on Optimize 2.7.0 until the release of Optimize 3.1.0 (Scheduled for 14/07/2020) and then update straight to Optimize 3.1.0.
+In 3.0.0, it is not possible to deactivate the import of a particular Optimize instance from a particular engine (via `engines.${engineAlias}.importEnabled`). In case your environment is using that feature for e.g. a [clustering setup](./../../configuration/clustering.md), we recommend you to stay on Optimize 2.7.0 until the release of Optimize 3.1.0 (Scheduled for 14/07/2020) and then update straight to Optimize 3.1.0.
 
 ## Limitations
 
 ### User operation log import
 
-Optimize now imports the user operation log. Due to this, the engine user now requires engine permissions to read the user operation log, see also the [configuration documentation](./../configuration/system-configuration-platform-7.md).
+Optimize now imports the user operation log. Due to this, the engine user now requires engine permissions to read the user operation log, see also the [configuration documentation](./../../configuration/system-configuration-platform-7.md).
 
 ### Suspension filter
 
 Due to a limitation of the user operations log data retrieval in the engine API, process instance suspension states of instances suspended after Optimize has been started are not correctly imported. This leads to inaccuracies in the [Suspended Instances Only Filter](components/userguide/process-analysis/instance-state-filters.md#suspended-and-non-suspended-instances-only-filter), which will only apply to instances which were suspended before they were imported by Optimize.
 
-Furthermore, since the suspension state of process instances in Optimize is updated according to historic data logs, if you have [history cleanup](./../configuration/history-cleanup.md) enabled it is possible that the relevant data will be cleaned up before Optimize can import it, leading to inaccuracies in the state of suspended process instances which will then not appear in the appropriate filter.
+Furthermore, since the suspension state of process instances in Optimize is updated according to historic data logs, if you have [history cleanup](./../../configuration/history-cleanup.md) enabled it is possible that the relevant data will be cleaned up before Optimize can import it, leading to inaccuracies in the state of suspended process instances which will then not appear in the appropriate filter.
 
 ### Event-based processes
 

optimize/self-managed/optimize-deployment/migration-update/3.0-to-3.1.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.0-to-3.1.md

@@ -27,9 +27,9 @@ See the [Supported Environments]($docs$/reference/supported-environments) sectio
 
 ## Breaking changes
 
-With Optimize 3.1.0, the [History Cleanup](./../configuration/history-cleanup.md) configuration was restructured and needs to be adjusted accordingly.
+With Optimize 3.1.0, the [History Cleanup](./../../configuration/history-cleanup.md) configuration was restructured and needs to be adjusted accordingly.
 
-Major changes are the removal of the global feature flag `historyCleanup.enabled` in favor of entity type specific feature flags as well as a relocation of process and decision specific configuration keys. Refer to the [configuration documentation](./../configuration/system-configuration.md#history-cleanup-settings) for details.
+Major changes are the removal of the global feature flag `historyCleanup.enabled` in favor of entity type specific feature flags as well as a relocation of process and decision specific configuration keys. Refer to the [configuration documentation](./../../configuration/system-configuration.md#history-cleanup-settings) for details.
 
 With this release, Optimize now imports deployment data from the engine when importing definitions. If Optimize is importing from an authenticated engine, the configured user must now have READ permission on the `Deployment` resource.
 
@@ -60,7 +60,7 @@ _We thus recommend removing all filters used on decision reports before updating
 
 With Optimize 3.1, user and group related permissions are checked by Optimize to determine whether the current user is authorized to access other users/groups within Optimize, for example when adding new roles to a collection.
 
-Due to this, it is now required to explicitly grant users the relevant authorizations, otherwise they will not be able to see other users and groups in Optimize. More information on authorizations can be found [here](./../configuration/authorization-management.md#user-and-group-related-authorizations).
+Due to this, it is now required to explicitly grant users the relevant authorizations, otherwise they will not be able to see other users and groups in Optimize. More information on authorizations can be found [here](./../../configuration/authorization-management.md#user-and-group-related-authorizations).
 
 ### User operations log import
 

optimize/self-managed/optimize-deployment/migration-update/3.1-to-3.2.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.1-to-3.2.md

@@ -53,7 +53,7 @@ See the [Supported Environments]($docs$/reference/supported-environments) sectio
 
 With this version, Optimize now allows you to filter for process instances where a given set of flow nodes have been canceled, as well as for flow nodes or user tasks that have been canceled.
 
-However, any canceled flow nodes and user tasks already imported by Optimize before this release will not appear as canceled in Optimize so will continue to be treated the same as any other completed flow node or user task. To use these options for previously imported data, you will need to [force a reimport](../../reimport) from the engine.
+However, any canceled flow nodes and user tasks already imported by Optimize before this release will not appear as canceled in Optimize so will continue to be treated the same as any other completed flow node or user task. To use these options for previously imported data, you will need to [force a reimport](../../../reimport) from the engine.
 
 ## Limitations
 

optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.10-to-3.11.md

@@ -0,0 +1,128 @@
+---
+id: 3.10-to-3.11
+title: "Update notes (3.10 to 3.11)"
+---
+
+:::note Heads up!
+To update Optimize to version 3.11, perform the steps in the [migration and update instructions](./instructions.md).
+:::
+
+The update to 3.11 can be performed from any 3.10.x release.
+
+Here you will find information about:
+
+- Limitations
+- Known issues
+- Changes in supported environments
+- Changes in behavior (for example, due to a new feature)
+- Changes in translation resources
+
+## Known issues
+
+## Migration of Camunda 7 data for 3.11.0, 3.11.1, and 3.11.2
+
+Under some circumstances, the migration of Camunda 7 data for versions 3.11.0, 3.11.1, and 3.11.2 can cause issues with the tenant selection of report definitions and collection scopes. This only occurs if data is present in Elasticsearch with the value `zeebe` in the datasource field, which can happen if the `onboarding` dataset set is used in Optimize, for example. To avoid this issue, we recommend Camunda 7 users skip 3.11.0, 3.11.1, and 3.11.2, and instead migrate straight to Optimize version 3.11.3.
+
+## Changes in supported environments
+
+### Elasticsearch
+
+With 3.11, Optimize now supports Elasticsearch `8.8`. Elasticsearch `8.5`, `8.6` and `8.7` are no longer supported.
+Additionally, please note there are temporary changes in Optimize's Elasticsearch support as detailed below:
+
+| Optimize version                        | Elasticsearch version            |
+| --------------------------------------- | -------------------------------- |
+| Optimize 3.10.0 - Optimize 3.10.3       | 7.16.2+, 7.17.0+, 8.5.0+, 8.6.0+ |
+| Optimize 3.10.4                         | 7.16.2+, 7.17.0+, 8.7.0+, 8.8.0+ |
+| Optimize 3.10.5 - Optimize 8.3.x/3.11.x | 7.16.2+, 7.17.0+, 8.5.0+, 8.6.0+ |
+| Optimize 3.11.x                         | 8.8.0+                           |
+
+See the [supported environments]($docs$/reference/supported-environments) section for the full range of supported versions.
+
+If you need to update your Elasticsearch cluster, refer to the general [Elasticsearch update guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html). Usually, the only thing you need to do is perform a [rolling update](https://www.elastic.co/guide/en/elasticsearch/reference/current/rolling-upgrades.html).
+
+### Java
+
+With this release, the minimum version of Java that Optimize supports is now Java 17. See the [Supported Environments]($docs$/reference/supported-environments) sections for more information on supported versions.
+
+### Plugins
+
+Optimize now runs with Spring Boot 3. As a result, some plugin interfaces have been updated accordingly. More specifically, the [Engine Rest Filter Plugin](./../../plugins/engine-rest-filter-plugin.md) and the [Single-Sign-On Plugin](./../../plugins/single-sign-on.md) now import jakarta dependencies. If you use these plugins and are updating from version 3.10.3 or earlier, you will need to adjust your implementation accordingly.
+
+### Logging
+
+With the change to Spring Boot 3, Optimize's logging configuration format has also been updated. If you are updating from version 3.10.3 or earlier, please review the updated `environment-logback.xml` to make sure your configuration is valid.
+
+## Changes in behavior
+
+### Collection Role Cleanup
+
+Prior to Optimize 8.3/3.11, Optimize has performed collection role cleanup after syncing identities with the engine. From
+Optimize 8.3/3.11 onwards, this is now disabled by default. It can be reenabled by setting the
+`import.identitySync.collectionRoleCleanupEnabled` property value to `true`
+
+### API behavior
+
+Before the 7.20/8.3 release, the Optimize API would accept requests when the URI contained a trailing slash (`/`). This is no longer the case, and requests containing a trailing slash will no longer be matched to the corresponding API path.
+
+### Raw Data Report API
+
+:::caution
+These changes require you to adjust any integrations using the data mentioned below.
+:::
+
+The data structure of raw data reports has changed. For the data export API, the properties named `numberOfIncidents`, `numberOfOpenIncidents`, and `numberOfUserTasks` is now renamed to `incidents`, `openIncidents`, and `userTasks` respectively, and grouped together in a single property named `counts`.
+
+Before:
+
+```
+{
+  ...
+  results: {
+    ...
+    measures: [
+      {
+        processDefinitionKey: 'someKey',
+        numberOfIncidents: 1,
+        numberOfOpenIncidents: 0,
+        numberOfUserTasks: 1,
+        ...
+      },
+      ...
+    ]
+  }
+}
+```
+
+After:
+
+```
+{
+  ...
+  results: {
+    ...
+    measures: [
+      {
+        processDefinitionKey: 'someKey',
+        counts: {
+          incidents: 1,
+          openIncidents: 0,
+          userTasks: 1
+        },
+        ...
+      },
+      ...
+    ]
+  }
+}
+```
+
+For CSV export the properties are renamed to `count:incidents`, `count:openIncidents`, and `count:userTasks`.
+
+### Localization file
+
+The following terms have been added to or removed from the localization file `en.json` since the last release:
+
+[en.json.diff](./translation-diffs/differences_localization_310_311.diff)
+
+- Lines with a `+` in the beginning mark the addition/update of a term; lines with a `-` mark the removal of a term.

optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.11-to-3.12.md

@@ -0,0 +1,34 @@
+---
+id: 3.11-to-3.12
+title: "Update notes (3.11 to 3.12)"
+---
+
+:::note Heads up!
+To update Optimize to version 3.12, perform the steps in the [migration and update instructions](./instructions.md).
+:::
+
+The update to 3.12 can be performed from any 3.11 release.
+
+Here you will find information about:
+
+- Limitations
+- Known issues
+- Changes in supported environments
+- Changes in behavior (for example, due to a new feature)
+- Changes in translation resources
+
+## Changes in supported environments
+
+### Elasticsearch
+
+With 8.4/3.12, Optimize now supports Elasticsearch `8.9`. Elasticsearch `8.8` is no longer supported.
+
+If you need to update your Elasticsearch cluster, refer to the general [Elasticsearch update guide](https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-upgrade.html). Usually, the only thing you need to do is perform a [rolling update](https://www.elastic.co/guide/en/elasticsearch/reference/current/rolling-upgrades.html).
+
+### Localization file
+
+The following terms have been added to or removed from the localization file `en.json` since the last release:
+
+[en.json.diff](./translation-diffs/differences_localization_311_312.diff)
+
+- Lines with a `+` in the beginning mark the addition/update of a term; lines with a `-` mark the removal of a term.

optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.12-to-3.13.md

@@ -0,0 +1,35 @@
+---
+id: 3.12-to-3.13
+title: "Update notes (3.12 to 3.13)"
+---
+
+:::note Heads up!
+To update Optimize to version 3.13, perform the steps in the [migration and update instructions](./instructions.md).
+:::
+
+The update to 3.13 can be performed from any 3.12 release.
+
+Here you will find information about:
+
+- Limitations
+- Known issues
+- Changes in supported environments
+- Changes in behavior (for example, due to a new feature)
+- Changes in translation resources
+
+## Changes in supported environments
+
+### Camunda 7
+
+Optimize now supports up to `7.21.0+`.
+See the [supported environments]($docs$/reference/supported-environments/#camunda-platform-7--optimize-version-matrix) section for the full range of supported versions.
+
+## Changes in translation files
+
+### Localization file
+
+The following terms have been added to or removed from the localization file `en.json` since the last release:
+
+[en.json.diff](./translation-diffs/differences_localization_312_313.diff)
+
+- Lines with a `+` in the beginning mark the addition/update of a term; lines with a `-` mark the removal of a term.

optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.13-to-3.14.md

@@ -0,0 +1,40 @@
+---
+id: 3.13-to-3.14
+title: "Update notes (3.13 to 3.14)"
+---
+
+:::note Heads up!
+To update Optimize to version 3.14, perform the steps in the [migration and update instructions](./instructions.md).
+:::
+
+The update to 3.14 can be performed from any 3.13 release.
+
+Here you will find information about:
+
+- Limitations
+- Known issues
+- Changes in supported environments
+- Changes in behavior (for example, due to a new feature)
+- Changes in translation resources
+
+## Changes in behavior
+
+### Telemetry
+
+Optimize no longer gathers telemetry data, and this is removed from the UI and Elasticsearch. The associated key in the configuration file (`telemetry.telemetryEndpoint`) was removed.
+
+## Changes in supported environments
+
+### Camunda 7
+
+Optimize now requires at least Camunda 7 `7.20.0` and supports up to `7.22.0+`. Camunda 7 `7.19.x` is no longer supported.
+
+### Java
+
+Optimize now supports Java 21+.
+
+### Elasticsearch
+
+Optimize now supports Elasticsearch 8.13.0+.
+
+See the [supported environments]($docs$/reference/supported-environments/#component-requirements) documentation for the full range of supported versions.

optimize/self-managed/optimize-deployment/migration-update/3.3-to-3.4.md → optimize/self-managed/optimize-deployment/migration-update/camunda-7/3.3-to-3.4.md

@@ -25,4 +25,4 @@ do not fetch data that is necessary for the new feature to work. For this update
 - [Process Instance Parts]({{< ref "/user-guide/process/single-report/_index.md#process-instance-parts" >}})
 - [Canceled Instances Only Filter]({{< ref "/user-guide/process/filter/_index.md#canceled-instances-only-filter" >}})
 
-To enable this feature for your old data, follow the steps in the [engine data reimport guide](./../reimport.md).
+To enable this feature for your old data, follow the steps in the [engine data reimport guide](./../../reimport.md).