Migration to 1.16.0

There will be migration steps and checks necessary. See Migration from MACMA Classic to MACMA Core for mostly automated steps.

Kubernetes Configuration change: NEXEED_MACMA_DATABASE_MASTERDATA_PASSWORD was renamed to NEXEED_MACMA_DATABASE_CORE_PASSWORD. This needs to be updated in all kubernetes inventories.

HTTPS (or a secure context as defined by the browsers like localhost) is required to be able to log in into MACMA.

As of MACMA 1.16 there is NO support to create a tenant (with a random UUID) and then assigning a different UUID. (As previously done by renaming the tenant in Keycloak UI and creating a new tenant relation). Technically this is no longer sufficient and there is no replacement process at this time.

However, there is a feature in progress ( SCPF-5678 - Allow to enter UUID while creating a tenant in order to support migration scenarios Closed ) that lets you select an unused UUID at the creation time of a tenant.

Migration from MACMA Classic to MACMA Core

The migration is fully automated (ansible scripts). In case of an error manual rework is needed.

Requirements for the migration:

The token of MACMA’s client is required to trigger the migration.
There is only one instance of MACMA Core running.
Data stored in MACMA cannot be changed during the migration → therefore all changing requests are blocked for the duration of the migration and will return status code 503.
The migration was not executed successfully → the execution of the migration can be enforced by setting the query parameter "forceRepeat" to true.

The migration includes the following steps:

Step 0: Check your installation for MACMA readiness using the following SQL statements

Clients with same name in different tenants:

Dial into the Keycloak schema of your system’s database and execute the following SQL. If it lists entries - you are affected.

select clients with same name in different tenants (MSSQL)

select count(*) cnt,CLIENT_ID,STRING_AGG(ra.VALUE,', ') as realm_name from CLIENT c join REALM_ATTRIBUTE ra on ra.REALM_ID=c.REALM_ID
where CLIENT_ID not in (
    select c.CLIENT_ID from client c join CLIENT_ATTRIBUTES ca on c.id = ca.CLIENT_ID
    where ca.name = 'macma.client.providedByTenant'
)
and ra.NAME='displayName'
and c.PUBLIC_CLIENT = 0
and CLIENT_ID not in ('account','account-console','admin-cli','broker','security-admin-console','realm-management')
group by CLIENT_ID having count(1) > 1 order by cnt desc;

select clients with same name in different tenants (Oracle)

select count(*) cnt,CLIENT_ID,LISTAGG(ra.VALUE,', ') as realm_name from CLIENT c join REALM_ATTRIBUTE ra on ra.REALM_ID=c.REALM_ID
where CLIENT_ID not in (
    select c.CLIENT_ID from client c join CLIENT_ATTRIBUTES ca on c.id = ca.CLIENT_ID
    where ca.name = 'macma.client.providedByTenant'
)
and ra.NAME='displayName'
and c.PUBLIC_CLIENT = 0
and CLIENT_ID not in ('account','account-console','admin-cli','broker','security-admin-console','realm-management')
group by CLIENT_ID having count(1) > 1 order by cnt desc;

Actions to take

This is most likely caused by a shared application not being marked as one and needs to be fixed using Postman to directly access Keycloak
If this is NOT the case and multiple clients with same name have been created in multiple tenants (most likely directly using Keycloak) these need to be removed or renamed.
Contact MACMA 3rd level support for help.

Multiple Application roles (or resources) with the same name/displayname

Dial into the Keycloak schema of your system’s database and execute the following SQL. If it lists entries - you are affected.

The excluded roles ("NOT IN") are already cleaned up in the ansible script for the MACMA migration.

select roles with duplicated displayName (MSSQL)

select count(1) c, STRING_AGG(b.NAME,' ,'), a.value,b.REALM_ID,b.CLIENT from ROLE_ATTRIBUTE a, KEYCLOAK_ROLE b
where a.name = 'displayName' and a.ROLE_ID=b.ID
and (b.NAME not in (
  'BCI_DAIS_PLANT_ADMIN','BCI_DAIS_PLANT_USER','BCI_DBS_ADMIN','BCI_DBS_EXPERT',
  'BCI_DBS_USER','BCI_NIS_ADMIN','BCI_NIS_EXPERT','BCI_NIS_USER','BCI_PS_ADMIN',
  'BCI_PS_EXPERT','BCI_PS_USER')
)
group by a.value,b.REALM_ID,b.client
having count(1) > 1
order by b.client;

select roles with duplicated displayName (Oracle)

select count(1) c, STRING_AGG(b.NAME,' ,'), a.value,b.REALM_ID,b.CLIENT from ROLE_ATTRIBUTE a, KEYCLOAK_ROLE b
where a.name = 'displayName' and a.ROLE_ID=b.ID
and (b.NAME not in (
  'BCI_DAIS_PLANT_ADMIN','BCI_DAIS_PLANT_USER','BCI_DBS_ADMIN','BCI_DBS_EXPERT',
  'BCI_DBS_USER','BCI_NIS_ADMIN','BCI_NIS_EXPERT','BCI_NIS_USER','BCI_PS_ADMIN',
  'BCI_PS_EXPERT','BCI_PS_USER')
)
group by a.value,b.REALM_ID,b.client
having count(1) > 1
order by b.client;

Actions to take

Cleanup for this problem needs to be done before the final contract synchronisation (i.e. before the deployment of MACMA 1.16 starts). This needs to be cleaned up in cooperation with the application developers. Most plausible cause is a migration of roles (i.e. a change of the technical role id). In that case a new role is created in MACMA < 1.16 (possibly with the same displayName) and if the previous one is not deleted, this error occurs.

Roles with too long names

Dial into the Keycloak schema of your system’s database and execute the following SQL. If it lists entries - you are affected.

select Roles with too long names (MSSQL)

select rr.REALM_ID,ra.VALUE as REALM_NAME, rr.NAME from KEYCLOAK_ROLE rr join REALM_ATTRIBUTE ra on  ra.REALM_ID=rr.REALM_ID where ra.NAME='displayName' and len(rr.name) > 200

select Roles with too long names (Oracle)

select rr.REALM_ID,ra.VALUE as REALM_NAME, rr.NAME from KEYCLOAK_ROLE rr join REALM_ATTRIBUTE ra on  ra.REALM_ID=rr.REALM_ID where ra.NAME='displayName' and length(rr.name) > 200

Actions to take

The name must be shortened. Contact support for clarification before the deployment of MACMA 1.16 is started.

Step 1 Premare MACMA Classic

In order to prepare MACMA Classic the following actions are executed:

Read all contracts and extract the contract ids:
GET {host}/maintenance/v1/contracts
Synchronize contracts:
POST {host}/maintenance/v1/contracts/{contractId}/synchronize
Stop MACMA Master Data and Ambassador Keycloak.

Step 2: Start MACMA Core to trigger the migration

For the migration itself the following actions are executed :

Deploy MACMA Core
Trigger the migration which is then executed asynchronously:

POST {host}/migration-management/v1/migrate?logLevel={logLevel}

Options for the loglevel: DEBUG, INFO, ERROR

Only read endpoints can be accessed during the migration. All other endpoints are blocked.
Get the result of the migration:

GET {host}/migration-management/v1/results

Since the migration is executed asynchronously it might be necessary to wait some time till the migration is finished and the result can be requested.

Error handling

In case the migration did not run successfully the following actions need to be executed manually:

Get a token for MACMA

POST {host}/auth/realms/7311ea8c-5d48-43fe-acf9-980eedf24b6c/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=macma&client_secret={macma-client-secret}

Request the result from MACMA or check the logs of the ansible job to get information about why the migration failed:
```
GET {host}/migration-management/v1/results
```
Fix the cause for the failed migration. More information about the error can be found in the Potential Errors section.
Trigger the migration again:
```
POST {host}/migration-management/v1/migrate?logLevel={logLevel}
```
The execution of the migration can be enforced by setting the query parameter "forceRepeat" to true (needed e.g. if the migration was already executed successfully and should be retriggered).
Get the result of the migration to ensure that the migration was now executed successfully:
```
GET {host}/migration-management/v1/results
```

Since the migration is executed asynchronously it might be necessary to wait some time till the migration is finished and the result can be requested.

Potential status codes

API	HTTP_STATUS	meaning
/migration-management/v1/migrate	OK	migration is already done OR the migration is not required
	ACCEPTED	migration is triggered (by this request)
	CONFLICT	migration was started by another request and is currently running

/migration-management/v1/results	OK	migration was executed successfully OR migration has not been started or is not required
	ACCEPTED	Migration is still running
	CONFLICT	migration failed
	INTERNAL SERVER ERROR	unforeseen error

API

HTTP_STATUS

meaning

/migration-management/v1/migrate

migration is already done OR
the migration is not required

ACCEPTED

migration is triggered (by this request)

CONFLICT

migration was started by another request and is currently running

/migration-management/v1/results

migration was executed successfully OR
migration has not been started or is not required

ACCEPTED

Migration is still running

CONFLICT

migration failed

INTERNAL SERVER ERROR

unforeseen error