Known issues and limitations for IBM Match 360

The following known issues and limitations apply to IBM Match 360.

For information about known issues and limitations that apply to backup, restore, or other platform-level operations, see Known issues and limitations for IBM Software Hub.

For additional solutions to help you to resolve common problems that you might encounter with IBM Match 360, see Troubleshooting IBM Match 360.

Installation, upgrade, and setup
General
Limitations

Installation, upgrade, and setup

The following known issues apply to installations, upgrades, and other setup or configuration scenarios.

When the internal TLS secret used by the IBM Match 360 service is refreshed, the corresponding Neo4j TLS does not get automatically refreshed

Applies to: 5.2.0 and later

The secret mdm-<INSTANCE-ID>-neo4j-tls is created by using data from the internal-tls secret. However, when internal-tls-certificate is refreshed due to certificate expiry or any other reason, the Neo4j TLS (mdm-<INSTANCE-ID>-neo4j-tls) does not automatically get updated to reflect the changes from the regenerated internal-tls secret.

Resolving the problem
To resolve this issue, trigger the Neo4j TLS secret to regenerate itself:
  1. Delete the mdm-<INSTANCE-ID>-neo4j-tls secret.
    oc delete secret mdm-<INSTANCE-ID>-neo4j-tls -n ${PROJECT_CPD_INST_OPERANDS}
  2. Perform a redundant update on the IBM Match 360 (mdm-cr) to cause the MDM operator to reconcile. 
    oc patch mdm mdm-cr --type=merge -p '{"spec":{"onboard":{"timeout_seconds": "800" }}}'
    Wait for mdm-<INSTANCE-ID>-neo4j-tls to be recreated.
  3. Refresh the IBM Match 360 service pods by deleting them.
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-data
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-data
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-matching
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-matching
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-model
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-model
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-configuration
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-configuration
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-job
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-job
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-em-ui
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-em-ui
    oc delete pods --wait -lapp.kubernetes.io/component=mdm-config-ui
    oc wait --for=condition=ready --timeout=30s pod -lapp.kubernetes.io/component=mdm-config-ui
    Wait for the pods to be recreated.

After an IBM Match 360 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 Match 360 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 Match 360 instance:
    1. From the IBM Software Hub home page, go to Services > Instances.
    2. Click the link for the IBM Match 360 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 Match 360, Redis operands are at a lower level than the Redis operator

Applies to: 5.2.0 and later

After completing an upgrade of the IBM Match 360 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 Match 360 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 Match 360 service is ready to use.

General

The following known issues apply to scenarios that do not fall into one of the other categories in this topic.

After shutting down IBM Match 360, the OpenSearch cluster continues running

Applies to: 5.2.2

After shutting down the IBM Match 360 service by using the cpd-cli manage shutdown command, the associated OpenSearch cluster (mdm-index-store-os) remains available. The OpenSearch cluster continues in an available state after the IBM Match 360 CR (mdm-cr) enters a shutdown state.

After the service shuts down, the mdm-index-store-os cluster should be in Quiesced state.

Resolving the problem

To work around this problem, patch the OpenSearch cluster to manually quiesce mdm-index-store-os.

Required role: To complete this task, you must be a cluster administrator.
  1. Get the full name, including the instance ID, of the mdm-index-store-os cluster:
    oc get cluster -n ${PROJECT_CPD_INST_OPERANDS}
  2. Using the full cluster name and instance ID gathered in the previous step, run the following command to quiesce mdm-index-store-os-<INSTANCE-ID>: 
    oc patch cluster mdm-index-store-os-<INSTANCE-ID>  --type merge --patch '{"spec": {"quiesce": true}}' -n ${PROJECT_CPD_INST_OPERANDS}

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

Applies to: 5.2.0 and later

If you navigate to the IBM Match 360 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 Match 360 operations

Applies to: 5.2.0 and later

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 Match 360 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

For entity types that include a filter to select which records to use for matching, the total number of records might be incorrectly reported

Applies to: 5.2.0 and later

When configuring an entity type's match settings (Master data > Match setup > Match settings), you can optionally configure record selection filters that define which records to use for matching. If record selection is enabled, then you can see incorrect Total records statistics in your matching summary, match setup overview page, and anywhere else that entity and record statistics are reported.

There is currently no workaround available to resolve this issue.

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

Applies to: 5.2.0 and later

Due to a change in the way IBM Match 360 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 Match 360 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 Match 360

When you search for entity data in IBM Match 360 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 Match 360 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 Match 360 SDK can change without warning

Applies to: 5.2.0 and later

When the IBM Match 360 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 Match 360 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 Match 360 service. Where possible, these items provide instructions about how to work around the limitations.

In some IBM Match 360 API responses, an incorrect record number can be returned

Applies to: 5.2.0 and later

Some IBM Match 360 API responses include the record_number field of a given record, often along with other record attributes. Each record in IBM Match 360 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 Match 360 master data event streaming capability

Applies to: 5.2.0 and later

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

The master data event streaming capability has the following limitations:
  • The event streaming capability uses a static cache for data subscriptions. This means that if any changes are made to subscriptions at runtime, the IBM Match 360 Matching microservice pods must be restarted for the changes to take effect. To minimize the effects of this limitation, ensure that all required subscriptions are created and configured before using this feature in a production environment and minimize the amount of changes made to subscriptions afterward. Any time a subscription is updated, manually restart the IBM Match 360 matching-ms pods.
  • IBM Match 360 generates record change and entity change events before the corresponding data change is persisted to the database. This can have two possible effects:
    • Early message processing. Event processing can receive event notifications and attempt to retrieve the data before the data is successfully committed. To minimize the impact of this possibility, configure a delay before running the getEntity API for each message.
    • Incorrect message ordering. The sequence of events can be wrong, meaning that an update entity message can arrive, for example, before a related create entity message for the same entity.

      To work around this issue, configure the IBM Match 360 custom resource (mdm-cr) so that the events are single-threaded:

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

      1. Update mdm-cr with the following parameters:
        mdm_matching:
  rabbitmq:
    listener:
      data:
        consumer_count: 1
      2. Wait for the mdm-cr to resolve so that the pods can pick up your configuration change.
      3. To verify that this configuration is set correctly, go to a matching-ms pod, open the following YAML file: /usr/mdm-matching/conf/rabbitmq/rabbit-mq.yaml. Ensure that the MatchingDataListener's consumerCount value is set to 1.
        
- listener: MatchingDataListener
  enable: True
  queueName: matching-data-queue-default
  exclusive: False
  durable: True
  autoDelete: False
  consumerCount: 1