User Community Service Desk Downloads
If you can't find the product or version you're looking for, visit

MDM 14.1.0 Upgrade Notes

Migration steps

To successfully upgrade to version 14.1.0, you need to install a new Keycloak version. To do this, follow the steps described in Upgrade Guide, section Keycloak version upgrade. Skip the steps that do not apply to your MDM instance.

An upgrade template is provided to help you migrate projects to version 14.1.0 and make the necessary changes to the configuration files. Use the upgrade template as described in the MDM Upgrade Procedure.

In addition, you need to perform other steps described on this page:

  1. Define the data sources as described in Data source configuration.

  2. Follow the steps described in Drafts and Issues are now Tasks:

    1. Before the upgrade:

      1. Configure one or several task templates.

      2. Publish drafts.

      3. Close or resolve open issues.

    2. After the upgrade:

      1. Update permissions.

      2. Disable event handlers.

      3. Remove the property from

      4. Optionally, remove obsolete Issue management configuration.

  3. Follow the steps described in Custom actions configuration, if these apply to your project.

In version 14.1.0, when you log in to the MDM Webapp, the following message can appear: Could not retrieve configuration from MDM Server. It can be caused by the MDM server starting for a longer time.

Data source configuration

The MDM data sources can now be defined in or in the mdm.runtimeConfig. See Data Sources Connection for details.

The project upgrade template will extract the relevant settings from any runtimeConfig files into the <your_project> Files/etc/ subfolder as individual <name_of_runtimeconfig>.ap files.

You can then decide which data sources to keep in the runtimeConfig files and which to move to the file. We recommend moving the following sources to

  • mdc_db - The MDM persistence.

  • log_db - The logging database.

  • eh_db - The event handler database.

The Issue Tracker connection it_db is not actively used in 14.1.0 and is only needed for migration purposes.

To do this, follow these steps for each data source:

  1. Open the mdm.runtimeConfig file.

  2. Find the data source whose configuration you want to move. You will use the same parameters in the configuration file.

    The data source definition looks like this:

    mdm.runtimeConfig` example (before 14.1.0)
    <dataSource driverclassName=.postgresql. name="mdc_db" user="mdc" password="mdc" url="jdbc:postgresql://localhost:5432/mdc" />
  3. Open the file and add the following properties: example (14.1.0 and later)<data_source_name>.url=<data_source_name>.waiting.timeout=5m<data_source_name>.waiting.interval=5s<data_source_name>.username=<data_source_name>.password=
  4. Replace the data source name depending on the data source that you are specifying and copy the data source connection string, username, and password from the mdm.runtimeConfig file.

    For example, the new configuration for the mdc_db data source should look like this: example (14.1.0 and later)
  5. Remove the data source configuration from the mdm.runtimeConfig file.

    One data source can only be defined once, either in a runtimeConfig file or in
  6. Once you are finished editing, save changes to both files.

Drafts and Issues are now Tasks

Although the issues and drafts storage is preserved, currently it is not possible to migrate issues and drafts from older versions. Before the upgrade:

  • Configure the generic task template (see Configuring Tasks). You can configure more task templates if needed.

  • Make sure all drafts are published. Keep in mind that the history will not be migrated.

  • Make sure all issues are either closed or resolved. Alternatively, you can create new tasks directly from MDM Webapp:

    • Data quality issues: Filter out the records that should be fixed and create bulk record change tasks (for details, see Tasks Overview).

    • Matching proposals issues: All matching proposal issues can be now accessed from the Matching proposals listing tab.

Tasks configuration

Once you run the upgrade template, the following is done automatically:

  • The configuration is transformed.

  • The event handlers that were used for creating matching proposal issues are disabled.

In addition to this, you need to perform several changes manually:

  • Update the createIssue permissions to createTask permissions. This cannot be automated due to differences in granularity: the createIssue permissions are defined per entity, while the createTask permissions are defined per role. See Update CreateIssue permissions.

  • Disable all event handlers used for issue management (see Disable event handlers).

  • Remove the following issue management property as it is no longer used: The property is located in the file (see MDM Server Application Properties, section MDM solution configuration).

  • Remove the issue management configuration files stored in etc/issue_management as these are no longer used.

Update CreateIssue permissions

The definition of the createIssue permissions in the mda-permissions.gen.xml file looks as follows:

mda-permissions.gen.xml example
<entity createIssue="true" export="false" name="address">
<entity createIssue="true" export="false" name="contact">

To update the permissions follow these steps:

  1. Under GUI Configuration, go to the Permissions tab.

  2. Clear Default permissions and select Custom permissions.

  3. Open Custom Permissions Settings by clicking the composite element link.

  4. For each role, specify if it can create tasks and manage AI Matching. Confirm your choice.

  5. Now you need to generate the project to save the changes. Right-click GUI Configuration and select Generate. The mda-permissions.gen.xml file is now updated with the new configuration. The definition of the createTask and AI Matching permissions now looks as follows:

    mda-permissions.gen.xml example (version 14.1.0 and later)
        <role aiMatching="false" createTask="false" name="MDM_viewer">
        <role aiMatching="true" createTask="true" name="MDM_user">
        <role aiMatching="true" createTask="true" name="MDM_admin">
When upgrading from 13.9.x to 14.1.0, createTask permissions and AI permissions are granted to all roles by default.

Disable event handlers

To disable event handlers that were used for issue management:

  1. In the MDM project, go to Output Interfaces and open the Event Handlers list.

  2. Find the event handlers that were used to send issues to the Issue Tracker (in the MDM Example Project, they have _dq_issue in the name).

  3. Double-click the name of the event handler and clear Enable in the tab that opens. Repeat for all event handlers.


    Alternatively, double-click the parent folder, go to the Publishers tab and clear Enable for all event handlers you need.

  4. Now you need to generate the project to save the changes. Right-click Event Handlers and select Generate. The project is now updated with the new configuration.


DQIT importer/exporter step is not part of the MDM server package.

Custom actions configuration

If you are using eng_sources_system column in the custom action configuration, you need to edit the expression. To upgrade custom actions that use the eng_sources_system column:

  1. In the MDM project, go to Files > engine > custom actions.

  2. Double-click the custom action to open the plan.

  3. Double-click the custom step with an error. In the window that opens, select Edit.

  4. In the expression editor that opens, change eng_system to eng_source_system and confirm.


AI Matching

Note that migrating the AI Matching persistence database deletes all AI Matching models.

Configuration changelog

This section provides the information about the changes in the configuration files that need to be taken into account when upgrading the solution. In certain cases, the newly introduced default is used or some configuration is required.

The following table lists the configuration files that were added, changed, or removed.

Added files Changed files Removed files


  • MDM server

  • MDM webApp


  • etc/nme-config.xml

  • etc/mda-config.xml

  • etc/xxx.serverConfig

  • etc/xxx.runtimeConfig

Files generated by MDM model project are not listed here.

  • etc/mda-workflow.gen.xml

  • etc/issue_management/*

The following table lists the changes in the files: added, changed, and removed properties.

Configuration file Added properties Changed properties Removed properties

MDM server

Disabled by default:

Enabled with default values:

Action is required:

  • MDM features - the default value changed from true to false



When a related property contains URL for given module, default is overriden to true (backward compatible change).

  • - You can remove all related configuration files.

MDM webApp



  • nme.match.rematchIf.removeManualMatch - the default value is false, for details see Runtime Parameters, section Process Control. Keep in mind that upgrading from versions 13.6.0-13.9.1 might change the rematchIfChanged behavior (due to a known issue in these versions).




  • <taskConfigFile>nme-task.gen.xml</taskConfigFile> - the reference to the new Task management functionality. The property is added automatically by the upgrade template.






  • <workflow>mda-workflow.gen.xml</workflow> - the content is now placed in nme-task.gen.xml. The property is removed automatically by the upgrade template.







The following data sources should be moved to (for details, see Data source configuration):

  • mdc_db - the MDM persistence

  • log_db - the logging database

  • eh_db - the event handler database


Was this page useful?