Managing Master Data with MDS (V2) For Cross Environments in Dynamics 365 Business Central

Introduction

Overview

Master Data Sync or MDS (used in Managing Master Data) keeps master data consistent across Microsoft Dynamics 365 Business Central companies, environments, Azure regions and tenants. One company is the master — it issues numbers, keeps the registry of configurations, governs the data and distributes it. The other companies are subscribers — they can create and change master data, and they control which values stay local.

To get our solution, visit us on Microsoft Marketplace MDM Cross Environment 

Key Concepts

How a Change Travels

1. A user creates or changes a record in any company, on any page or through an API.

2. The change is captured automatically and written to the company’s Outbox. Several quick edits of the same record become one message.

3. A background task sends the message to the master (from a subscriber) or to all subscribers (from the master), never back to the company the change came from.

4. The receiving company stores the message in its Inbox and applies it: it matches the record by its key, applies value maps and field modes, and fills company-specific fields from its local template when the record is new.

5. Every step is logged in the Sync Log, with elapsed time and end-to-end latency.

Get Started

Prerequisites

Read the following prerequisites before you proceed:

• Business Central online, version 28 or later, in every participating environment.

• MDS Master Data Sync — MDM Cross Environment  installed in every participating environment. For configured products, also the companion configurator app.

• In sandbox environments — Allow HttpClient Requests turned on for each app (Extension Management → Configure).

• For other environments, regions or tenants — A Microsoft Entra app registration with the API.ReadWrite.All application permission for Dynamics 365 Business Central, and admin consent.

Implementation Checklist

Here is a checklist of the steps to implement Managing Master Data:

To Connect a Company in Another Environment

1. In the Azure portal, register an application in Microsoft Entra ID. Add Dynamics 365 Business Central → Application permissions → API.ReadWrite.All, grant admin consent, and create a client secret.

2. In each environment, open Microsoft Entra Applications, add the application by its client ID, set State to Enabled, and assign the permission sets MDS SYNC, D365 READ and any ISV set (for example CFG ALL), with Company left blank.

3. Open MDS Connections → New. Set Transport Type to BC API (OAuth) first.

4. Enter Environment Name, Client Id and Client Secret, then choose Select Target Company. The target environment’s companies are listed; selecting one fills Target Company Name, Company Id and, if blank, Tenant Id.

5. Choose Test Connection. The result starts with OK.

Role Center: Master Data Sync Administrator

Profile for MDS ADMINISTRATOR — Select it in My Settings > Role.

Parts

Here is a description of the parts of the Master Data Sync Administrator role center:

Tiles

This section describes the tiles on the Master Data Sync Administrator role center.

Actions

Here are the actions that can be taken.

MDS Master Data Sync Setup

This section will cover the MDS Master Data Sync Setup page, which is the main setup for each company.

This defines this company’s role and how synchronization behaves in it. Settings that differ per table (numbering series, local templates, filters) are on MDS Sync Tables.

General

Here are the general fields:

Numbering & Configured Items

Here is a description of the fields that control numbering and configured items:

Processing

Here are the processing fields:

Testing

This section describes the testing fields:

Actions

Here are actions that can be taken:

MDS Connections & MDS Connection Card

This section will discuss the MDS Connections and the MDS Connection Card.

A connection tells this company how to reach another company. The master has one connection per subscriber; each subscriber has one connection to the master.

General

These are the general fields of the MDS Connection Card:

BC API (OAuth Client Credentials)

Here are the fields for BC API (Business Central Application Programming Interface OAuth) connections:

Last Test

Here are the fields for the last test of the connection:

Actions

These are actions you can take on the MDS Connection Card:

MDS Sync Tables

The tables this company synchronizes. A company only sends and accepts changes for tables listed and enabled here.

Actions

Here are actions you can take on the MDS Sync Tables:

Entity Catalog

In this section we will Add Entity on MDS Sync Tables.

The following are the description of the entities:

Each entity also sets default field modes.
Excluded everywhere: Costs and modification stamps.
Company-Specific in subscribers: Posting groups, tax settings, units of measure, item type, costing method, local assignments (salesperson, purchaser, location, FA location, responsible employee) and global dimensions.

Field defaults are matched by field name.

MDS Sync Fields

Open this page from MDS Sync Tables > Fields.

When you select a Field No.:

Here are the per-field exceptions for a table, in this company. A field without a line is synchronized. Listing a field as Synced is the same as not listing it.

Field Modes

Here are the Field Modes:

These are never synchronized, whatever the mode:

• Calculated Fields (FlowFields)
• BLOB/Media Fields (such as pictures)

Actions

Here are the actions you can take:

MDS Value Maps

Translates an incoming value into this company’s value. Because maps are defined in the receiving company, every company can translate the same value differently. A two-step translation (subscriber → master code → other subscriber code) is set up with a map in the master and a map in each subscriber.

MDS Number Series & MDS Number Reservations

This shows the MDS Number Reservations:

MDS Number Series (Master)

This is the MDS Number Series page, which defines the series used for master numbering.

The master locks the series while issuing a number, skips numbers that already exist as records or reservations, and records every number issued.

MDS Number Reservations

Here are the fields of the MDS Number Reservations page:

Monitoring Pages

This section will discuss Monitoring.

From the Inbox, you can select Show Payload to get more details.

Here is an example of monitoring service requests.

MDS Outbox (Sending Company)

Here is a description of the fields for the MDS Outbox page:

Actions

MDS Inbox (Receiving Company)

Here is a description of the fields for the MDS Inbox page:

Actions

MDS Sync Log

MDS Service Requests (Master Side of Real-time Calls)

Resolving a Failed Entry

To resolve a failed entry, follow these steps:

1. Open MDS Outbox (Sending Company) or MDS Inbox (Receiving Company), filter Status = Failed.

2. Read Last Error and fix the cause.

3. Select the entries → Reset to Pending → Process Now. Records are matched on their key, so reprocessing never creates duplicates.

Configuration Registry & Testing Pages

Here are the MDS Item Signatures.

MDS Item Signatures (Configuration Registry)

Open Check Master and view Result.

MDS Configuration Simulator

Actions

MDS Test Scenarios

Here are scenerios for MDS testing.

Actions

You have the options to Run Subscriber Suite and Run Master Suite.

Security & Permissions

In this section we will cover the security of the system, including permissions.

This table describes the Permission Set.

• Messages received through the API are applied by the Microsoft Entra application; messages within one environment are applied by a background task running as the user who caused them. Both identities need permission for the synchronized tables.

• Users who only create or change master data do not need MDS ALL; capture and numbering run with the app’s own permissions.

• Authentication between environments uses OAuth 2.0 client credentials. Secrets are kept in isolated storage. Every message and number reservation is logged.

Troubleshooting

In this section we will discuss how to troubleshoot known errors based on symptom or message. You can select Actions to resolve the issue from the menu bar (e.g. Process Now).

Here is a table of items for troubleshooting and the recommended fix: