Known issues and limitations for IBM Master Data Management

Installation, upgrade, and setup

After upgrading IBM Master Data Management, the ibm-mdm service account keeps its privileges even if the upgrade is done with lesser privileges

Applies to: 5.4.0

When you upgrade the IBM Master Data Management service with a user who has minimum RBAC permissions, the ibm-mdm service account user keeps the same permissions as were configured in the pre-upgraded service.

This issue does not negatively impact installation or upgrade, but it can provide the IBM Master Data Management service account with more privileges than intended.

Resolving the problem

To resolve this issue, delete the ibm-mdm role created by the Namespacescope operator:

1. Identify the role created by the Namespacescope operator that follows this naming convention: ibm-mdm-<random-identifier>.

   # oc describe role ibm-mdm-<ID> -n ${PROJECT_CPD_INST_OPERANDS}

   The role has the following labels:

   Name:         ibm-mdm-<ID>
   Labels:       app.kubernetes.io/instance=namespace-scope
                 app.kubernetes.io/managed-by=ibm-namespace-scope-operator
                 app.kubernetes.io/name=namespace-scope

2. Delete the role:

   oc delete role ibm-mdm-<ID> -n ${PROJECT_CPD_INST_OPERANDS}

On some environments, IBM Master Data Management upgrades can fail due to a Neo4j PVC expansion failure

Applies to: Upgrades to 5.4.0

When upgrading the IBM Master Data Management service on environments where the StorageClass does not have the allowVolumeExpansion flag enabled, the Persistent Volume Claim (PVC) mdm-neo4j-metrics-<INSTANCE-ID> fails with a Forbidden exception. This causes the Neo4j Custom Resource (CR) to fail, which subsequently leads to a failure of the entire IBM Master Data Management service upgrade.

Resolving the problem

To resolve this issue after you encounter it, check the failing Neo4j PVCs indicated in the Neo4j CR status. If the failure is due to a storage restriction, edit the relevant StorageClass and set allowVolumeExpansion: true. Reconcile the Neo4j and IBM Master Data Management operator pods by restarting them.

To resolve this problem:

1. Identify the storage class used by the PVC.

   oc get pvc mdm-neo-<INSTANCE-ID>-metrics -o yaml -n ${PROJECT_CPD_INST_OPERANDS}| grep storageClass

   The command will return information similar to the following:

   storageClassName: managed-nfs-storage

2. Edit the storage class to add allowVolumeExpansion: true.

   oc edit storageclass <STORAGE-CLASS-NAME>

   Add the following line:

   allowVolumeExpansion: true

   Example snippet:

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: managed-nfs-storage
   provisioner: cp4d/nfs-client
   reclaimPolicy: Delete
   volumeBindingMode: Immediate
   allowVolumeExpansion: true

3. Restart the Neo4j and IBM Master Data Management operator pods to apply the changes and resolve the PVC issue.

When you scale down the IBM Master Data Management service, the CR becomes stuck in an InProgress state

Applies to: 5.4.0

When you scale down IBM Master Data Management, the service enters a disrupted state and its status shows as InProgress. This occurs because Persistent Volume Claims (PVCs) cannot shrink to lower values due to a Kubernetes limitation. This results in disruption in the Neo4j CR, which eventually makes the IBM Master Data Management service unstable.

Resolving the problem

To resolve this issue after you encounter it, check the IBM Master Data Management CR (mdm-cr) status to determine if any PVCs are in an error state. Edit the mdm-cr for those PVCs with values that match the previous (scaled up) size.

To resolve this problem:

1. Check the status of the Neo4j CR.

   oc get neo4j <MDM-NEO4J-CR-NAME> -n ${PROJECT_CPD_INST_OPERANDS} -o yaml

2. From the YAML output, identify PVCs that are in an error state. In the YAML, these PVCs are in the volumes section. Typically, you will see the following PVC types: data, logs, backup, metrics, plugins and others.
3. Get the PVC sizes for each of the volumes.

   oc get pvc mdm-neo-<INSTANCE-ID>-<PVC-NAME> -n ${PROJECT_CPD_INST_OPERANDS}

   For example, for the metrics volume, run the following command:

   oc get pvc mdm-neo-<INSTANCE-ID>-metrics -n ${PROJECT_CPD_INST_OPERANDS}

   The result will be similar to the following example:

   NAME                                          STATUS  VOLUME                                     CAPACITY  ACCESS MODES  STORAGECLASS         AGE
   mdm-neo-<INSTANCE-ID>-metrics                 Bound   pvc-a5bf89ef-fb48-4b1a-8172-22e6a603144f    5Gi       RWX          managed-nfs-storage  18d

4. Edit the IBM Master Data Management CR (mdm-cr).

   oc edit mdm-cr -n ${PROJECT_CPD_INST_OPERANDS}

5. In mdm-cr, locate the volumes configuration for Neo4j and update the storage sizes for the volume types that you identified as being in an error state. Provide values that match the previous (scaled up) size.

   neo4j:
     volumes:
       metrics:  # data or logs, backup, etc.
         volumeClaimTemplate:
           resources:
             requests:
               storage: "10Gi"  # Update to required size

6. Save your changes to mdm-cr and wait for the operator to reconcile.
7. To confirm that your changes resolved this issue, monitor the statuses of both the Neo4j CR and IBM Master Data Management CR:

   oc get mdm && oc get neo4j -w ${PROJECT_CPD_INST_OPERANDS}

After an IBM Master Data Management service upgrade, you cannot see any results when you search your master data

Applies to: Upgrades from 5.1.0 and later where the database is Neo4j

After completing an upgrade of the IBM Master Data Management service, you cannot successfully search your master data from the Master data > Search screen. The search results are empty.

This issue only occurs when the service is using Neo4j as its database.

Resolving the problem

To fix this issue, reindex your master data for searching:

1. Get the IBM Software Hub cluster host URL:

   oc get routes

2. Get the ID of the IBM Master Data Management instance:
   1. From the IBM Software Hub home page, go to Services > Instances.
   2. Click the link for the IBM Master Data Management instance.
   3. Copy the value after mdm- in the URL.

      For example, if the end of the URL is mdm-1234567891123456, the instance ID is 1234567891123456.

3. Run the following command to start a reindex job:

   curl --request POST \
     --url https://<SOFTWARE-HUB-URL>/<MDM-INSTANCE-ID>/mdm/v1/reindex \
     --header 'Authorization: <BEARER-TOKEN>' \
     --header 'accept: application/json' 

After upgrading IBM Master Data Management, Redis operands are at a lower level than the Redis operator

Applies to: 5.4.0

After completing an upgrade of the IBM Master Data Management service, you can encounter an issue where the corresponding Redis pods are upgraded incompletely. In this scenario, the Redis operator is upgraded to the latest version, but the Redis operands are at a lower version level.

Resolving the problem

After upgrading the IBM Master Data Management service, complete the following steps:

Required role: To complete this task, you must be a cluster administrator.

1. Run the following command to back up the redissentinnel custom resource.

   oc get redissentinels REDIS-CR-NAME -o yaml > mdm-redissentinels.yaml

   Replace REDIS-CR-NAME with the name of the Redis custom resource.
2. On the upgraded deployment instance, run the following command to delete the redissentinnel custom resource.

   oc delete redissentinel REDIS-CR-NAME

   Replace REDIS-CR-NAME with the name of the Redis custom resource.
3. Wait for the Redis pods to refresh. When the status is Synced successfully, the IBM Master Data Management service is ready to use.

General

After running matching, even when successful, you can see a 400 error notification

Applies to: 5.4.0

After the IBM Master Data Management matching process completes, you can get a 400 error notification with the message Missing required parameters.

Resolving the problem

There is no workaround required to resolve this problem. The error can safely be ignored and dismissed with no impact to your workflow.

Clicking Data types in the breadcrumb navigation bar might open a 404 error page

Applies to: 5.4.0

If you navigate to the IBM Master Data Management data types screen from your project's configuration assets page, then clicking Data types in the breadcrumb navigation bar opens a 404 error page instead of returning you to the main data types screen. You can also encounter this error when you right-click on Data types in the breadcrumb navigation to open a new tab.

Resolving the problem

To work around this problem, avoid clicking the Data types link in the breadcrumb navigation bar. Instead, open the Master data navigation menu, then click Data types to open the main data types configuration page.

To open the data types screen in a new tab, copy the URL into a new tab.

Neo4j databases might enter quarantine mode, preventing normal IBM Master Data Management operations

Applies to: 5.4.0

Neo4j databases can automatically move into quarantine mode for a number of reasons, such as disk space limitations or connectivity issues. When the database is quarantined, you cannot complete any database transactions.

Resolving the problem

To remove a Neo4j database from quarantine mode and return to a normal operational status, first address the underlying issues that caused the quarantine, such as low disk space or poor connectivity. After confirming that the underlying issue is resolved, complete the following steps to remove the database from quarantine:

1. Get the Neo4j connection properties from the secret.

   oc get secrets/mdm-neo4j-connection-secret-<INSTANCE-ID> -n ${PROJECT_CPD_INST_OPERANDS} --template={{.data}}|awk '{print $1}'|cut -d ':' -f 2|base64 -d

2. Exec into any of the IBM Master Data Management Neo4j server pods (mdm-neo-<INSTANCE-ID>).
3. Log in to the Neo4j cypher-shell by using bolt protocol. Provide the connection properties that you obtained in step 1.

   cypher-shell -a <neo4j-user> -p <neo4j-password> -a bolt+ssc://<neo4j-load-balancer-url>:7687 -d system

4. Get a summary of your databases to determine which databases are in a quarantined state.

   show databases;

5. Run the following procedure for each affected database to remove them from quarantine:

   CALL dbms.quarantineDatabase("<dbName>",false); 

6. Verify the database status to ensure none remain quarantined.

   show databases;

7. Restart Neo4j to refresh the nodes from the Neo4j server pod.

   neo4j restart

Performance can degrade if attribute composition is configured to allow a list of values

Applies to: 5.4.0

Due to a change in the way IBM Master Data Management determines how an entity's attribute values get selected from its member records, you can experience degraded system performance if the maximum number of values used for compositing entities is set to Single or list value, which is the default behavior. The performance issue only occurs in certain situations, and it can be resolved by changing the attribute composition settings.

Resolving the problem

To resolve this issue, change the maximum number of values used for compositing entities from Single or list value to Single value only.

Required role: To complete this task, you must have IBM Master Data Management data engineer permissions.

1. From the navigation menu, select Matching setup, then choose the Match settings tab.
2. In the sidebar, choose Attribute composition.
3. Ensure that the correct entity type from your data model is selected in the entity type selection menu.
4. In the list of attribute composition rules, locate the rule that has Entity type in the Scope column.
5. Hover your mouse over the rule and click the Edit pencil icon.
6. Under Compositing output > Set the maximum number of values, select Single value only.
7. Click Save.

Searching by using a partial entity ID does not return any matches

Applies to: All releases of IBM Master Data Management

When you search for entity data in IBM Master Data Management by using a partial entity ID as the search criteria, the search does not yield any results. This issue occurs even if you use the IBM Master Data Management search API with the conditions contains, starts_with, or ends_with.

To successfully search by entity ID, you must provide a complete entity ID value as the search criteria. Optionally, you can use comparison operators such as equal, not_equal, greater_than, greater_than_equal, less_than, or less_than_equal.

The order of parameters in the IBM Master Data Management SDK can change without warning

Applies to: 5.4.0

When the IBM Master Data Management SDK is generated, the order of parameters can change. The OpenAPI YAML content is generated in a different order each time.

Resolving the problem

If you use the IBM Master Data Management SDK, use the builder method for each parameter instead of the constructor method that includes multiple parameters. Because the order of the parameters cannot be guaranteed, using the constructor method can negatively affect backwards compatibility.

Limitations

This section describes limitations with the IBM Master Data Management service. Where possible, these items provide instructions about how to work around the limitations.

• In some IBM Master Data Management API responses, an incorrect record number can be returned
• Limitations of the IBM Master Data Management master data event streaming capability

In some IBM Master Data Management API responses, an incorrect record number can be returned

Applies to: 5.4.0

Some IBM Master Data Management API responses include the record_number field of a given record, often along with other record attributes. Each record in IBM Master Data Management has a unique, system-generated record number. Record numbers are long type values, and sometimes get parsed incorrectly when viewed in the Swagger 3.0 user interface.

This issue occurs because the Swagger UI does not correctly parse the large record_number value. This is a known problem with JavaScript, which Swagger relies on.

Limitations of the IBM Master Data Management master data event streaming capability

Applies to: 5.4.0

IBM Master Data Management can, in near real time, propagate changes in your record and entity data directly to downstream systems through a connected Apache Kafka server.