Migration to 4.0.0+ (Nexeed IAS 2024.01.00.xx)

Manual change needed for Influx retention policies

Because of a bug in previous versions (before 4.0.0 or 3.0.3(hotfix release)), the automatic configuration of retention policy durations for the Influx DB, which is created by non-admin user, was not correct. All configured retentions use the same from duration from rp_msm_raw. With the update to version 4.0.0 the automatic configuration has been fixed, but this does not affect already existing Influx DBs. In order to change the retention policy durations some manual effort is necessary.

Details about what needs to be done manually to change the retention policies, can be found influx retention policies chapter.

Service account role provided by Condition Monitoring is changed

"Machine Data Sender" application role is added to Condition Monitoring to enable actors, like the Information Router, to send measurement and machine messages via HTTP to CM. That is why the "Condition Monitoring Administrator" needs to be removed from Information Router (called Nexeed Direct Data Link in MACMA) in all tenants and "Machine Data Sender" needs to be assigned instead.

Merging Rule Management into Condition Monitoring module

Starting with release 4.0.0 Rule Management was merged into Condition Monitoring module.

Please note:

All previously configured permissions for Rule Management (fine-grained access, role assignments to users) will not have any effect any longer and need to be reconfigured in Condition Monitoring module.
In version 3.x the Function Configuration Admin, Function Configuration Expert and Function Configuration User roles were available. In version 4.0.0 the resources of these roles are assigned to the Rule Management Administrator, Rule Management Expert and Rule Management User roles.
From version 4.0.1 a new static resource of type urn:com:bosch:bci:cm:rm:superAdmin is available which is assigned to Rule Management Administrator and Condition Monitoring Administrator as well. It allows access to all Rule Management resources.
Rule management api path is changed from {URL}/rm/xx → {URL}/cm/rm/xx

The following manual steps are required to perform the migration:

Stop Rules Management services (in "rm" namespace) and remove "rm" helm section to avoid data changes.
Add old Rules Management (rm) configurations like Kafka, Database etc. to Condition Monitoring (cm) in inventory. Search rm: and replace it with cm: in the inventory file. The old Rule Management Database needs to be added as second database so that the customer data remains. In this case, no migration is needed. Please check an example configuration with two database user and other configurations of rule management(e.g. local variable override) which needs to be added below:

global:
    cm:
      enabled: true
      ruleManagementLightEnabled: false // needs to be added
      databases:
        cm:
          type: ORACLE
          oracleSchema: CM_INT11
          name: xxx
          userName: CM_INT11
          password: xxx
        rm: // needs to be added
          type: ORACLE
          oracleSchema: RM_INT11
          name: xxx
          userName: RM_INT11
          password: xxx
        influxcm:
          userName: ias_int11_cm
          name: ias_int11_cm
          password: xxxx
          serverInstance: externalinflux
      messaging: // needs to be added, when rule management extended mode is activated
        kafkarm:
          serverInstance: externalkafka
cm:
  local:
    kafkaClientSSLKeyPassword: "kafka123"
    kafkaClientSSLKeystorePassword: "kafka123"
    kafkaTopicPrefix: "bci-int11."
    kafkaTopicPartitions: "3"
    kafkaTopicAutoCreation: false

Deploy Condition Monitoring, which is including Rules Management services.
Create new macma contract to provide the new Rule Management application roles (under Condition Monitoring) to the all tenants.
For version 4.0.0 it is necessary to run MDM sync in Rules Management for each tenant (see Reload MDM for RM). From version 4.0.1 this is not necessary anymore as dynamic resource creation is done automatically.
Assign Rule Management dynamic resources to the already defined organization roles:
- Search in MACMA Access Management all organization roles and filter privileges by selecting module 'Rule Management' and entering the type 'urn:com:bosch:bci:rm:rule-service:rules' in the search field. Note the defined resources with their privileges e.g. by creating a screenshot. You will need this information to reconfigure the roles in Condition Monitoring.
- Select the module 'Condition Monitoring' and add all resources with the same privileges from your note to the organization roles.
In case the "Rules Management" navigation item is not available, see failure handling: portal.
In case Rules Management roles are not available under Condition Monitoring module, restart macma-configuration-operator in "aops" namespace.
When everything is working, delete the "old" Rules Management module from MACMA and Portal (see next sections).

Deleting Rules Management from MACMA

It’s recommended to delete Rules Management module from MACMA to not have deprecated roles and resources in the system. This can be done by deleting all relevant contracts and the module registration. This can be done in the section "Access Management / Contracts" and "Access Management / Modules". Please conduct the MACMA user documentation for more details.

Deleting Rules Management from Web Portal

As the roles and resources have been removed from MACMA users will not see the Rules Management entry in the navigation bar anymore. Nevertheless, the module is registered in Portal and caused by this, visible in the integration status.

To unregister Rules Management from the Portal an HTTP API is used. More details can be found in the Operations Manual of the IAS Portal, section 'Removing / Deregister / Unregister a Module'.

Rolling back to a version prior to 4.0.0

As the liquibase upgrade which was introduced with version 4.0.0 is not backwards compatible, the generated checksums in the databases have to be reset manually.

Set the values of column "MD5SUM" to NULL for all rows in the tables:

CM_CORE_DATABASECHANGELOG (in CM db)
RM_DATABASECHANGELOG (in RM db)

Afterward start the old version of Condition Monitoring and Rules Management.

Migration of static range rules from CPM to CM Rules Management

As mentioned in cpm-to-rm-relational-db-migration, the static range function was not available in CM version 3.0.x, that is why the CPM static range rules were not migrated to CM Rules Management. As static range function is available in CM from beginning version 4.0.0, the migration (beginning version 4.0.1) will be done automatically via liquibase at rule-service-app startup when the old CPM Rules table are still existing in RM Database, which needs to be retained as mentioned in cpm-to-rm-relational-db-migration.

In case one of CPM Rules tables is not existing in the RM database, the migration will not be done automatically and you will see an error in the log: "db/changelog/db.rm-changelog-master.xml : Table RS01_RULE does not exist". In this case, the CPM Rules tables need to be cloned and either rule-service-app can be restarted to do migration automatically or the migration needs to be done manually via scripts located in \\rb-repobci.de.bosch.com\InternalShare\IAS\IAS2024.01\MigrationCPMToCM\RM.

In case the migration is not successful because of other reasons (e.g., data inconsistency), and you see exception in the logs like: "ChangeSet db/changelog/changelogs/20_add_static_range_function.xml::20_2_migrate_static_range_function::BCI/ESW2 encountered an exception", the following steps need to be performed manually:

Check the exception in detail to understand why the migration failed.
After fixing the problems, run the migration scripts manually according to database (oracle or sqlserver) that is located in \\rb-repobci.de.bosch.com\InternalShare\IAS\IAS2024.01\MigrationCPMToCM\RM
- First run the script "migrate-ppm-staticRangeFunction-sqlserver.sql" and when Rule Management Light (RULE_MANAGEMENT_LIGHT_ENABLED=true) is enabled, then run "remove-static-range-timebased-rules-when-rules-light-enabled-sqlserver.sql" in the RM database.