MDM 17.2.0 Upgrade Notes

New MDM Web App interface

The new MDM Web App interface is now the default. It is served at the /ui path, and the root URL of the MDM Web App redirects there. The legacy interface remains available at /legacy-ui. To switch to it, select the product name in the upper-left corner of the MDM Web App and choose Legacy MDM UI. Both interfaces work with the same data and tasks, so you can switch between them at any time without losing work. See Get Started.

REST API security

The REST API now requires a dedicated user role, and the nme-security.xml permissions apply to every REST API endpoint. Previously, any authenticated user or service account could call the REST API, and the operational endpoints, entity listings, statistics, and attribute overrides were available to everyone.

Work through the following steps in order. Without the new role, no REST API integration works after the upgrade. For the permission each endpoint requires, see Security and Audit > Permissions required by REST API endpoints.

Create and assign the REST API role in Keycloak

Every REST API call now requires the MDM_rest_api_access or MDM_admin user role. Without it, requests fail with a 403 Forbidden HTTP status code and an empty body, and nothing is written to the audit log.

In Keycloak, in the realm used by MDM (ataccamaone by default), create the MDM_rest_api_access role if it does not exist.
Assign it to every user and service account that calls the REST API, such as integration service accounts, ETL or scripting users, and anyone who uses Try it out in Swagger UI. Users with MDM_admin do not need it.

The required roles are defined by the new api-rest access control list properties; see Added properties. For details, see REST API > Authentication and authorization.

Update permissions in nme-security.xml

Check the roles of your REST API clients against the following changes. Roles with AllPermissions need no change.

Operational endpoints

The endpoints that manage the MDM Server, such as purge, system tasks, event handlers, stream consumers, persistence, and runtime parameters, now require the new OpsView permission for reading and OpsWrite for changes. Previously, any authenticated caller could use them, including purge.

Add OpsView to every role that reads the MDM Server state through the REST API and OpsWrite to every role that changes it. OpsWrite does not include OpsView.

Entity listings and statistics

The entity listings and record statistics now return only the entities the caller has read permission for, and the history metadata endpoints return 403 Forbidden without it. Previously, every authenticated caller received the complete list of entities and all record counts.

If a role only browses the model or reads statistics, give it a read permission such as ReadAll or ReadEntities.

Attribute overrides

The override endpoints now require read permission for GET requests and write permission for PUT and DELETE requests, the same as the record endpoints. Previously, every authenticated caller could read and set overrides on any record.

Give the roles that manage overrides the same permissions as for reading and writing records.

Indirectly changed entities

Write permission is now also checked for the entities an operation changes indirectly: the dependent entities of a SOAP processDelta service, and the child master entities and the corresponding instance entity when deleting or merging an authored master record. Previously, a WriteEntities permission that listed only the central or parent entity worked until a request changed those entities; it is now refused regardless of the request content.

Add these entities to every WriteEntities permission whose role calls processDelta or writes master records. Roles with WriteAll, WriteInstanceLayer, or WriteMasterLayer are not affected, and neither are processDelta services without an entities configuration, where all entities are autonomous.

For details, see Security and Audit > Permissions and [nme-security.xml].

Audit the operational endpoints

Requests refused for a missing permission are audited as UNAUTHORIZED events regardless of the event filters. Requests refused for the missing REST API role are not audited. To audit the operational calls themselves, add the OpsView or OpsWrite event filter to nme-security.xml and a logging rule for the OPS_VIEW or OPS_WRITE event type to nme-audit-logging.xml. See [nme-audit-logging.xml].

Update REST API clients

Review your integrations for the following changes in responses.

Write permission is checked first

Requests without write permission for an entity are now refused immediately with 403 Forbidden and Unauthorized attempt to WRITE_TYPE in detail. Previously, they were refused only when a record was written, with WRITE_RECORD in the message, or they failed validation or succeeded without doing anything. This applies to all REST API write endpoints and to the SOAP processDelta and processDeltaPreview services.

Clients that look for WRITE_RECORD in error messages must also accept WRITE_TYPE.

Identify without read permission

The identify endpoint now checks the read permission for the master entity before matching runs and returns 403 Forbidden. Previously, it returned 400 Bad Request with the same Unauthorized attempt to READ_TYPE message after matching had run.

The record conditions and column restrictions of the caller’s read permission now also apply to the returned proposals, the same as when reading master records. Previously, identify returned the matching master records without them.

Clients that look for 400 Bad Request with the message Unauthorized attempt to must expect 403 Forbidden instead.

sourceTimestamp in write requests

In instance write requests, the source timestamp field is now called sourceTimestamp, the same as in GET responses. The previous name source_timestamp is still accepted, so existing requests need no change. Previously, a request with sourceTimestamp was accepted but the value was ignored, so the record was stored without a source timestamp.

Clients that already send sourceTimestamp now store the timestamp they send.

After the upgrade, test one call per integration.

REST API

REST API error responses use RFC 7807 problem details

REST API error responses now use the RFC 7807 problem details format with the application/problem+json content type. This affects every REST API endpoint, and any client that parses REST API error bodies must be updated.

Error response before the upgrade

{
  "message": "Error",
  "exception": "com.ataccama.nme.core.NmeException: Record ... does not exist."
}

Error response after the upgrade

{
  "title": "Not Found",
  "status": 404,
  "detail": "Record ... does not exist.",
  "instance": "/api/rest/..."
}

The exception field is no longer returned, and the cause of the error is in detail. Clients that still read message or exception receive null without an error. The detail text also changed where the previous message was generic. Server error (5xx) responses include an errorId field that identifies the corresponding entry in the server error log. The HTTP status codes are unchanged.

For details, see REST API > Response status codes.

Purge endpoint response change

A successful POST /api/rest/purge request now returns a 200 OK HTTP status code with a JSON body instead of 204 No Content. The routine purge returns {"result": "ok"} and the targeted purge returns the purged counts, so the endpoint no longer answers with an empty body.

The endpoint also supports targeted purge of specific instance or master records. For details, see REST API > Purge.

REST API time zone handling

The new ataccama.one.mdm.nme.rest.timezone MDM Server property controls the time zone of REST API timestamps. The default value legacy keeps the previous behavior, so existing integrations are not affected.

Setting the property to UTC, a zone ID (for example, Europe/Prague), or server switches the REST API to correct time zone offsets in responses and accepts explicit offsets in inputs. This changes every timestamp in REST API responses, so coordinate the change with all API consumers. Timestamps without a time zone in request bodies are read as server-local time on both SOAP and REST; this is unchanged. See Added properties.

Migrating from SOAP to REST API

The REST API now covers the operations that were previously available only through the SOAP native services: manual match, bulk delta imports, cleansing, targeted purge, traversal, identification in mixed style, and batch operation invocation, as well as partial updates (PATCH), related-entity changes, deletion with the hard parameter, and case-insensitive search. These additions do not affect existing REST API callers.

For details, including a SOAP to REST mapping for migrating integrations, see REST API > SOAP to REST mapping.

Basic HTTP authentication deprecated

Basic HTTP authentication for the REST API and the SOAP native services is deprecated. Authenticate with a bearer token instead. See API Requests Authentication.

Streaming Event Handler supports matching proposal entities

The Streaming Event Handler now accepts a matching proposal entity as a publisher root, in addition to instance and master entities.

A matching proposal root is always a leaf: no traversing is performed from it and it cannot be used as a related entity of an instance or master root. Because a publisher has exactly one root, each matching proposal entity needs its own publisher with its own plan file.

No configuration change is required if you do not publish matching proposal events. If you kept the Async Event Handler because of matching proposal entities, you can now migrate. See Migrating to Streaming Event Handler for the migration table and Add a Streaming Event Handler > Matching proposal root for the published columns.

Configuration changelog

This section provides 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 application.properties nme-security.xml nme-audit-logging.xml	/

Added files

Changed files

Removed files

MDM Server application.properties
nme-security.xml
nme-audit-logging.xml

The following sections list the changes in the files: added, changed, and removed properties.

MDM Server application.properties

Added properties

ataccama.authentication.http.acl.endpoints.api-rest.endpoint-filter - Path patterns of the REST API endpoints secured by the api-rest ACL group. Default: /api/rest/**.
ataccama.authentication.http.acl.endpoints.api-rest.allowed-roles - Roles allowed to call the REST API. Default: MDM_rest_api_access,MDM_admin.

See MDM Server Application Properties > API endpoint required role configuration.
ataccama.one.mdm.nme.rest.validation-file - Name of the DQ validation definition file in the MDM Server configuration folder that supplies the validations outcomes of the REST API cleanse endpoint. If the file does not exist, the exp_* explanation columns are used instead. Default: nme-validation.xml.
ataccama.one.mdm.nme.rest.timezone - Time zone of REST API timestamps: legacy, UTC, a zone ID, or server. An invalid zone ID fails server startup. Default: legacy.

See MDM Server Application Properties > MDM features.
ataccama.one.mdm.mcp.tools.proposal-rejection.enabled - Exposes the rejectMatchProposals MCP tool, which lets AI agents reject matching proposals. The caller still needs the reject permission on the proposal entity. Default: false (true in Ataccama Cloud deployments).
ataccama.one.mdm.mcp.tools.task-resolution.enabled - Exposes the resolveTask MCP tool, which lets AI agents publish the draft of any task type and resolve the task, permanently changing master data. The caller still needs the publish permission on the task’s current workflow step. Default: false (true in Ataccama Cloud deployments).

For more information, see MDM Server Application Properties and MCP Server in MDM > Autonomous resolution tools.
ataccama.one.mdm.nme.readonly - Controls whether the MDM Server node starts in read-only persistence mode. Default: false.

A value set on the node itself (this property in the node’s application.properties, a -D JVM system property, or an environment variable) takes precedence over the nme.readonly runtime parameter edited in the MDM Web App Admin Center, which serves only as a fallback for nodes without a local value.

If your installation uses read-only nodes, set ataccama.one.mdm.nme.readonly=true on each read-only node. For details, see MDM Server Application Properties > HA configuration.

nme-security.xml

Added permissions

com.ataccama.nme.engine.security.auth.permissions.OpsView - Grants permission to call the REST API endpoints that read the MDM Server state.
com.ataccama.nme.engine.security.auth.permissions.OpsWrite - Grants permission to call the REST API endpoints that change the MDM Server state.

See Security and Audit > Permissions.

Added event filters

com.ataccama.nme.engine.security.audit.filters.OpsView - Audits calls to the REST API endpoints that read the MDM Server state as OPS_VIEW events.
com.ataccama.nme.engine.security.audit.filters.OpsWrite - Audits calls to the REST API endpoints that change the MDM Server state as OPS_WRITE events.

See Security and Audit > Event filters.

nme-audit-logging.xml

Added event types

OPS_VIEW and OPS_WRITE - New audit event types for the operational REST API endpoints. Add a logging rule for them to write the operational calls to the audit log.

See Security and Audit > Writers.

Was this page useful?