Known issues and limitations for IBM Match 360 with Watson
The following known issues and limitations apply to IBM Match 360 with Watson™.
- Installation, upgrade, and setup
- IBM Match 360 connection
- General
- Limitations
- Resolved
- See the Resolved section to view the resolved issues.
For information about known issues and limitations that apply to backup, restore, or other platform-level operations, see Known issues and limitations for IBM Cloud Pak® for Data.
For additional solutions to help you to resolve common problems that you might encounter with IBM Match 360, see Troubleshooting IBM Match 360 with Watson.
Installation, upgrade, and setup
After upgrading IBM Match 360, some Redis pods are not refreshed
After completing an upgrade of the IBM Match 360 service, old versions of some Redis resources still show even though Redis has been updated to a newer version.
Applies to: 4.7.4
- 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.
- Run the following command to delete the StatefulSet associated with your
mdm-redis
instances:
Replace <INSTANCE-ID> with the instance ID of theoc delete sts c-mdm-redis-<INSTANCE-ID> c-mdm-redis-<INSTANCE-ID> -n ${PROJECT_CPD_INST_OPERATORS}
mdm-redis
resource instance. - Wait for the Redis pods to refresh. When
the status is
Synced successfully
, the IBM Match 360 service is ready to use.
- Run the following command to delete the StatefulSet associated with your
After upgrading IBM Match 360, Redis operands are at a lower level than the Redis operator
Applies to: 4.7.0 and later
After completing an upgrade of the IBM Match 360 service, you might 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.
- Run the following command to back up the
redissentinnel
custom resource.
Replace REDIS-CR-NAME with the name of the Redis custom resource.oc get redissentinels REDIS-CR-NAME -o yaml > mdm-redissentinels.yaml
- On the upgraded deployment instance, run the following command to delete the
redissentinnel
custom resource.
Replace REDIS-CR-NAME with the name of the Redis custom resource.oc delete redissentinel REDIS-CR-NAME
- Wait for the Redis pods to refresh. When
the status is
Synced successfully
, the IBM Match 360 service is ready to use.
- Run the following command to back up the
After upgrading from Cloud Pak for Data 4.5, IBM Match 360 shutdown operations will not work unless you manually delete Elasticsearch jobs
Applies to: Upgrades from 4.5.x to 4.7.0 and later
For instances of the IBM Match 360 service that have been upgraded from Cloud Pak for Data 4.5, the service shutdown operations will not work unless you manually delete all existing Elasticsearch jobs.
- Resolving the problem
-
After completing an upgrade from Cloud Pak for Data 4.5, manually delete all existing Elasticsearch jobs before starting to use the IBM Match 360 service.
Required role: To complete this task, you must be a cluster administrator.
Run the following command to delete the existing Elasticsearch jobs:oc delete pod mdm-INSTANCE_ID-ibm-elasticsearch-create-snapshot -n ${PROJECT_CPD_INST_OPERATORS} oc delete job mdm-INSTANCE_ID-ibm-elasticsearch-create-snapshot-repo-job -n ${PROJECT_CPD_INST_OPERATORS}
IBM Match 360 connection
Data Refinery jobs can fail when they use an IBM Match 360 connection as the source and a CSV file as the target
Applies to: 4.7.0 and later
You cannot import master data from an IBM Match 360 connection into a CSV file by using a Data Refinery job. The Data Refinery job fails.
- Resolving the problem
-
Depending on your installed services and user permissions, you can work around this limitation in more than one way:
- To export IBM Match
360 data to a CSV or TSV
file, use the IBM Match
360 service's
export capability. For more information, see Exporting master data from IBM Match
360.
Required role: To complete this task, you must have IBM Match 360 data steward or data engineer permissions.
- If you do not have access to the IBM Match
360
service, use the IBM Match
360 connection with the
DataStage® service to create a job that
exports your master data to the required file format. For more information, see Exporting master
data by using DataStage and the IBM Match
360 connection.Required role: To complete this task, you must have:
- IBM Match 360
- DataStage
- Permissions to create a DataStage job
- To export IBM Match
360 data to a CSV or TSV
file, use the IBM Match
360 service's
export capability. For more information, see Exporting master data from IBM Match
360.
General
The IBM Match 360 configuration UI can fail to detect the status of completed matching process
Applies to: 4.7.0 and later
Infrequently, after matching completes, the user interface is unable to correctly detect the completion status of the matching process. This can occur regardless of whether the matching process was successful or failed.
When this issue occurs, you cannot start a new matching process from the configuration UI because it appears, incorrectly, that the previous process is still incomplete.
- Resolving the problem
-
To resolve this issue, check the matching job statuses and then use the API to override the incorrect job status in the project metadata.
Required role: To complete this task, you must have IBM Match 360 data engineer permissions.
- Click the IBM Match 360 navigation menu and select Master data home to open the master data home page. Select the Jobs tab.
- Check the status of the most recent matching job. Matching jobs are of different job types that
all start with the
match-
prefix. - Manually update the job status in the project metadata using the
PATCH
configuration metadata API.- Get the project metadata name by running the GET project metadata API
command:
Note the project metadata name for the next step.GET project metadata
- Update the job status in the project metadata using the PATCH configuration metadata
API
PATCH /mdm/v1/configuration_metadata
Sample body:{ "name": "<PROJECT_METADATA_NAME>", "matching_status": { "person": { "person_entity": { "status": "Error", "message": "Matching failed.", "process_count": "0" } } } }
The following are valid statuses for a matching job:- In-progress_bulkderive
- In-progress_bulkmatch
- In-progress_persistentity
- In-progress_exportlink
- In-progress_bulkreport
- Complete
- Error
- Get the project metadata name by running the GET project metadata API
command:
The order of parameters in the IBM Match 360 SDK can change without warning
Applies to: 4.7.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 theconstructor
method that includes multiple parameters. Because the order of the parameters cannot be guaranteed, using theconstructor
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.
Limitations of the IBM Match 360 master data event streaming capability
Applies to: 4.7.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 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.
- Update
mdm-cr
with the following parameters:mdm_matching: rabbitmq: listener: data: consumer_count: 1
- Wait for the
mdm-cr
to resolve so that the pods can pick up your configuration change. - To verify that this configuration is set correctly, go to a a
matching-ms
pod, open the following YAML file: /usr/mdm-matching/conf/rabbitmq/rabbit-mq.yaml. Ensure that theMatchingDataListener
'sconsumerCount
value is set to 1.- listener: MatchingDataListener enable: True queueName: matching-data-queue-default exclusive: False durable: True autoDelete: False consumerCount: 1
- Update
- 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
The default Elasticsearch configuration supports data volumes up to 5,000,000 entities
Applies to: All releases of IBM Match 360
By default, the Elasticsearch cluster that is installed with IBM Match 360 is configured to support data volumes up to 5,000,000 entities. This configuration does not limit the core IBM Match 360 load, derive, match, or report jobs in any way.
- Resolving the problem
-
If your enterprise requires support for a higher data volume, edit the value of the
search.max_buckets
parameter in the Elasticsearch cluster configuration. For example:name: search.max_buckets value: "5000000"
Required role: To complete this task, you must be a cluster administrator.
Resolved
- Resolved in 4.7.4
-
- When you activate an IBM Match 360 configuration snapshot that includes a data model, the draft version of the data model does not get updated
- IBM Match 360 requires special configuration to load data from MDM Publisher
- After restoring IBM Match 360 from backup, the associated Aspera pods can fail to initialize
- After restoring IBM Match
360 from an online backup, Redis pods can enter a
CrashLoopBackOff
state - After restoring IBM Match
360 from an offline backup, Redis pods can enter a
CrashLoopBackOff
state
- Resolved in Cloud Pak for Data 4.7.1
-
- When viewing master data in an IBM Match 360 connection asset, row filter masking rules do not work
- While upgrading IBM Match
360, Elasticsearch pods can remain in a
1/2 Running
state, causing IBM Match 360 to remain in anInProgress
state - When exporting record or entity data from IBM Match 360 by using the master data explorer UI, the export fails if the resulting file is larger than 512 MB
- When exporting record or entity data from IBM Match 360 by using the API, the export fails if the resulting file is in ZIP format and larger than 4 GB
- A timeout error can occur in successful offline backup and restore operations
- IBM Match 360 connections do not support secrets from vaults
- Resolved in Cloud Pak for Data 4.7.0
The following items describe resolved known issues and limitations.
When you activate an IBM Match 360 configuration snapshot that includes a data model, the draft version of the data model does not get updated
Fixed in: 4.7.4
Applied to: 4.7.1, 4.7.2, and 4.7.3
- The published data model that is used by the system
- The draft data model that data engineer users can view and edit within the master data configuration UI
- Resolving the problem
-
After activating a configuration snapshot that includes a data model, use the IBM Match 360 API to manually update the draft data model with the data model from the snapshot.
Required role: To complete this task, you must have IBM Match 360 data engineer permissions.
Update the draft data model using the following API command. Provide the data model JSON in the message body.PUT /mdm/v1/config_data_model
For more information about the API, see the IBM Match 360 API reference documentation.
IBM Match 360 requires special configuration to load data from MDM Publisher
Fixed in: 4.7.4
Applied to: 4.7.0, 4.7.1, 4.7.2, and 4.7.3
Without special configuration, IBM Match 360 is unable to load master data sent through an InfoSphere® MDM Publisher ongoing subscription or bulk load. When using the default configuration, the high speed transfer service between MDM Publisher and IBM Match 360 does not function in Cloud Pak for Data 4.7.0 and later.
After restoring IBM Match 360 from an online backup, the associated Aspera pods can fail to initialize
When you restore IBM Match 360 from backup, the associated Aspera pods can fail to come up properly.
Fixed in: 4.7.4
Applied to: 4.7.1, 4.7.2, and 4.7.3
- Resolving the problem
-
To fix this problem, complete the following steps to remove and recreate the Aspera pods:
Required role: To complete this task, you must be a cluster administrator.
- Run the following commands to clean up the stuck
pods:
oc delete CatalogSource ibm-operator-catalog oc -n ${PROJECT_CPD_INST_OPERANDS} delete deployment ibm-aspera-hsts-operator --ignore-not-found=true oc delete og cpd-aspera-operatorgroup oc -n ${PROJECT_CPD_INST_OPERANDS} delete csv $(oc get csv -n ${PROJECT_CPD_INST_OPERANDS} | awk '{ print $1 }' | grep ibm-cloud-databases-redis.v ) --ignore-not-found=true oc -n ${PROJECT_CPD_INST_OPERANDS} delete csv $(oc get csv -n ${PROJECT_CPD_INST_OPERANDS} | awk '{ print $1 }' | grep ibm-aspera-hsts-operator.v ) --ignore-not-found=true oc -n ${PROJECT_CPD_INST_OPERANDS} delete subscription $(oc get subscription -n ${PROJECT_CPD_INST_OPERANDS} | awk '{ print $1 }' | grep ibm-cloud-databases-redis-operator-v ) --ignore-not-found=true oc delete sub aspera-hsts-operator oc get svc -n ${PROJECT_CPD_INST_OPERANDS} | grep aspera | awk '{ print $1 }' | xargs oc delete svc -n ${PROJECT_CPD_INST_OPERANDS} oc get cm -n ${PROJECT_CPD_INST_OPERANDS} | grep aspera | awk '{ print $1 }' | xargs oc delete cm -n ${PROJECT_CPD_INST_OPERANDS} oc get secret -n ${PROJECT_CPD_INST_OPERANDS} | grep aspera | awk '{ print $1 }' | xargs oc delete secret -n ${PROJECT_CPD_INST_OPERANDS} oc get role -n ${PROJECT_CPD_INST_OPERANDS} | grep aspera | awk '{ print $1 }' | xargs oc delete role -n ${PROJECT_CPD_INST_OPERANDS} oc get rolebinding -n ${PROJECT_CPD_INST_OPERANDS} | grep aspera | awk '{ print $1 }' | xargs oc delete rolebinding -n ${PROJECT_CPD_INST_OPERANDS} oc get networkpolicy -n ${PROJECT_CPD_INST_OPERANDS} | grep aspera | awk '{ print $1 }' | xargs oc delete networkpolicy -n ${PROJECT_CPD_INST_OPERANDS}
- Wait for the pods to be recreated and returned to a running state.
- Run the following commands to clean up the stuck
pods:
After restoring IBM Match
360 from an
online backup, the associated Redis pods can
enter a CrashLoopBackOff
state
Fixed in: 4.7.4
Applied to: 4.7.1, 4.7.2, and 4.7.3
When you restore IBM Match
360 from backup, the
associated Redis pods can fail to come up,
showing a status of CrashLoopBackOff
.
- Resolving the problem
-
To fix this problem, complete the following steps to clean up the Redis pods:
Required role: To complete this task, you must be a cluster administrator.
- Get all of the Redis recipes in the
current
namespace:
oc get recipes.redis.databases.cloud.ibm.com -n ${PROJECT_CPD_INST_OPERANDS}
- Delete each of the listed
recipes:
oc delete recipes.redis.databases.cloud.ibm.com <RECIPE_NAME> -n ${PROJECT_CPD_INST_OPERANDS}
- Get the Redis CR name:
oc get redissentinel -n ${PROJECT_CPD_INST_OPERANDS}
- Back up the Redis CR and name it
redissentinels.yaml:
oc get redissentinels <CR_NAME> -o yaml > redissentinels.yaml
- Delete the current Redis CR:
oc delete redissentinels <CR_NAME>
- Restore the Redis CR from the backup that
you just created:
oc apply -f redissentinels.yaml
- Wait for reconciliation to complete. The Redis pods should now up and enter a running state.
- Refresh the IBM Match
360 configuration UI pod
(
mdm-config-ui
) to restore its Redis connection.- Get the name of the
mdm-config-ui
pod:oc get pod -n ${PROJECT_CPD_INST_OPERANDS} | grep mdm-config-ui
- Delete the
mdm-config-ui
pod using the name you retrieved in the previous step.oc delete pod <CONFIG-UI-POD-NAME> -n ${PROJECT_CPD_INST_OPERANDS}
- Wait for the
mdm-config-ui
pod to be recreated and in a running state.
- Get the name of the
- Get all of the Redis recipes in the
current
namespace:
After restoring IBM Match
360 from an
offline backup, Redis pods can enter a
CrashLoopBackOff
state
Fixed in: 4.7.4
Applied to: 4.7.0, 4.7.1, 4.7.2, and 4.7.3
After you restore the IBM Match
360 service
from an offline backup, the corresponding Redis pods can go into a CrashLoopBackOff
state.
- Resolving the problem
-
To fix this problem, run the following command to delete and refresh the Redis pods:
oc get pod -n ${PROJECT_CPD_INST_OPERANDS} | grep mdm-redis | awk '{ print $1 }' | xargs oc delete pod -n ${PROJECT_CPD_INST_OPERANDS}
When viewing master data in an IBM Match 360 connection asset, row filter masking rules do not work
Fixed in: 4.7.1
Applied to: 4.7.0
Row filter masking does not occur when you view data that was exported from IBM Match 360 using a IBM Match 360 connection. This means that Cloud Pak for Data data protection rules that include row filter masking cannot be properly implemented on IBM Match 360 connection assets.
There is no workaround for this problem.
While upgrading IBM Match
360, Elasticsearch pods can remain in a 1/2
Running
state, causing IBM Match
360 to
remain in an InProgress
state
Fixed in: 4.7.1
Applied to: Upgrades to 4.7.0
During an upgrade of the IBM Match
360 service,
its underlying Elasticsearch pods can remain in a
1/2 Running
state. When this happens, the IBM Match
360 custom resource (mdm-cr
)
status shows as InProgress
until the underlying issue gets resolved.
- Resolving the problem
-
After completing an upgrade, manually delete the Elasticsearch pods before starting to use the IBM Match 360 service.
Required role: To complete this task, you must be a cluster administrator.
- List the
mdm-elasticsearch
pods:oc get pods -l app.kubernetes.io/part-of=mdm-elasticsearch
- Take note of the pod names.
- Run the following command to delete each of the Elasticsearch pods:
Replace POD-NAME with the name of the pod to delete.oc delete pod POD-NAME -n PROJECT_CPD_INST_OPERATORS
After the Elasticsearch pods are removed they will refresh, allowing the IBM Match 360 CR to enter a
Complete
state. - List the
When exporting record or entity data from IBM Match 360 by using the master data explorer UI, the export fails if the resulting file is larger than 512 MB
Fixed in: 4.7.1
Applied to: 4.7.0
When you use the IBM Match 360 master data explorer user interface to export record or entity data, the export fails if the size is 512 MB or larger.
- Resolving the problem
-
To export files larger than 512 MB, use the IBM Match 360 API to export the data using a file compression format such as TAR or TGZ. For information about using the API, see the IBM Match 360 API reference documentation.Note: Due to a separate known issue, you must export files larger than 4 GB in a compression format other than ZIP. For more information, see When exporting record or entity data from IBM Match 360 by using the API, the export fails if the resulting file is in ZIP format and larger than 4 GB.
When exporting record or entity data from IBM Match 360 by using the API, the export fails if the resulting file is in ZIP format and larger than 4 GB
Fixed in: 4.7.1
Applied to: 4.7.0
When you use the IBM Match 360 API to export record or entity data in ZIP format, the export fails if the output format is ZIP and the size is 4 GB or larger.
- Resolving the problem
-
To export files larger than 4 GB, use the IBM Match 360 API to export the data using another file compression format, such as TAR or TGZ. For information about using the API, see the IBM Match 360 API reference documentation
A timeout error can occur in successful offline backup and restore operations
Fixed in: 4.7.1
Applied to: 4.6.3, 4.6.4, 4.6.5, 4.6.6, and 4.7.0
During offline backup and restore operations, timeout errors can appear in the logs. These timeout errors are inconsequential and do not affect the success of the backup or restore operations. For example:
time=2023-02-07T23:20:15.126981Z level=info msg=resource: mdm.cpd.ibm.com/v1, Resource=masterdatamanagements mdm-cr, mdmStatus: InMaintenance time=2023-02-07T23:20:15.127038Z level=error msg=failed to wait for resource status mdmStatus: timed out waiting for the condition time=2023-02-07T23:20:15.127063Z level=info msg=exit executeBuiltin time=2023-02-07T23:20:15.127069Z level=error msg=1 error occurred: * timed out waiting for the condition
No workaround is required. You can safely ignore the timeout errors.
- Resolving the problem
-
After completing an upgrade from Cloud Pak for Data 4.5, manually delete all existing Elasticsearch jobs before starting to use the IBM Match 360 service.
Required role: To complete this task, you must be a cluster administrator.
Run the following command:oc delete pod mdm-INSTANCE_ID-ibm-elasticsearch-create-snapshot -n ${PROJECT_CPD_INST_OPERATORS} oc delete job mdm-INSTANCE_ID-ibm-elasticsearch-create-snapshot-repo-job -n ${PROJECT_CPD_INST_OPERATORS}
IBM Match 360 connections do not support secrets from vaults
Fixed in: 4.7.1
Applied to: 4.7.0 and earlier
When you create a IBM Match 360 platform connection, you cannot use secrets from vaults to specify the required credentials for the connection. IBM Match 360 connections do not support secrets from vaults.
Exported IBM Match 360 relationship data is missing some columns
Fixed in: 4.7.0
Applied to: 4.6.4, 4.6.5, and 4.6.6
When you export IBM Match 360 relationship data by using DataStage or Data Refinery, certain columns are missing from the exported data. This occurs even though the export job appears to be successful.
created_user
relationship_number
to_record_number
from_record_number
relationship_type
last_updated_user
created_date
last_updated_date
- Resolving the problem
-
To work around this problem, remove the empty columns by using Data Refinery.
- Open the data asset in Data Refinery.
- Click Prepare data. Wait while Data Refinery reads and processes a sample of the data.
- Create a Data Refineryjob to remove the
columns.
- Select one of the empty columns, then click the overflow menu in the column header. Select Remove column to add the Remove column step to your Data Refinery job.
- Repeat this step for each of the empty columns:
created_user
relationship_number
to_record_number
from_record_number
relationship_type
last_updated_user
created_date
last_updated_date
- Click the Jobs icon, then select Save and create a job. Define your job details and configure the job including optional schedules and notifications, then click Create and run.
Required role: To complete this task, you must have the Admin or Editor role to create and run the Data Refinery job.
IBM Match 360 operations can fail due to an Elasticsearch connection timeout issue
Fixed in: 4.7.0
Applied to: 4.6.5 and 4.6.6
You can encounter failures from IBM Match
360
jobs and operations that involve data and matching. The root cause of these failures is an issue
that causes Elasticsearch instances on some clusters to perform slower than usual. This slowness can
result in connection timeout errors between IBM Match
360 and Elasticsearch. In this scenario, you
might see an error message such as failed to connect to ES with error
.
- Onboarding and deboarding
- Most operations and jobs that involve the Data microservice
- Most operations and jobs that involve the Matching microservice
- Resolving the problem
-
There is no confirmed workaround for this issue. If you encounter this problem, retry the failed operation.
After upgrading from Cloud Pak for Data 4.6.0 to 4.6.4, the RabbitMQ pod can enter an error state
Fixed in: 4.7.0
Applied to: Upgrades from 4.6.0, 4.6.1, 4.6.2, 4.6.3, or 4.6.4
For instances of the IBM Match 360 service that have been upgraded from Cloud Pak for Data 4.6.0 directly to 4.6.4, the RabbitMQ pod can enter an error state. By deleting the pod, you can force RabbitMQ to get recreated so that IBM Match 360 can function correctly.
- Resolving the problem
-
After completing an upgrade from Cloud Pak for Data 4.6.0, manually delete the RabbitMQ pod.
Required role: To complete this task, you must be a cluster administrator.
- Run the following commands to remove the RabbitMQ pod:
mdm_rabbitmq_name=$(kubectl get rabbitmqcluster -n $PROJECT_CPD_INST_OPERATORS -l app.kubernetes.io/component=mdm-rabbitmq -o jsonpath='{.items[0].metadata.name}') mdm_rabbitmq_helm_secrets=$(kubectl get secrets -n $PROJECT_CPD_INST_OPERATORS | grep -E "sh.helm.release.v[0-9]+.${mdm_rabbitmq_name}.v[0-9]+" | awk '{printf $1 " "}') kubectl delete secrets ${mdm_rabbitmq_helm_secrets} -n $PROJECT_CPD_INST_OPERATORS kubectl delete RabbitMQCluster ${mdm_rabbitmq_name} -n $PROJECT_CPD_INST_OPERATORS
- Wait for the pod to be recreated before starting to use the IBM Match 360 service.
- Run the following commands to remove the RabbitMQ pod: