Microsoft Dynamics 365 F&O

The Graphite adapter for Microsoft Dynamics 365 Finance & Operations (D365 F&O) synchronizes supplier vendor-master data from graphiteConnect into your D365 environment. The integration is fully cloud-to-cloud: it runs entirely within the Graphite platform and communicates with your D365 environment through Microsoft's standard OData REST APIs. There is no software to install, host, or maintain on your side.

When suppliers create or update their information in graphiteConnect, the adapter automatically creates or updates the corresponding vendor records in D365 — including addresses, contacts, bank accounts, and document attachments — across one or more legal entities.

---

How the Adapter Works

The adapter maintains D365 vendor data the same way an integration built by your own team would: it authenticates with OAuth 2.0, reads your D365 environment to determine what already exists, and then creates or updates records through D365's standard data entities. It never accesses the D365 database directly, so all of D365's built-in validations, number sequences, and security checks apply to every change.

Architecture at a Glance

• Nothing to install: The adapter is hosted and operated by Graphite. Your only setup tasks are registering an app in Microsoft Entra ID and creating a service account in D365. See Setup.
• OAuth 2.0 (client credentials): Every sync authenticates against your Microsoft Entra ID tenant using an app registration you create and control. You can revoke access at any time by disabling the app registration or its client secret.
• Standard OData data entities: All reads and writes go through D365's published data entities (VendorsV2, VendorBankAccounts, and so on). Because changes flow through the standard entities, D365's own business logic, field validations, and configured number sequences apply to every record.
• Encrypted in transit: All communication uses HTTPS (TLS 1.2+).
• Multi-legal-entity support: A single supplier can be created and maintained across multiple legal entities (dataAreaId) in one synchronization pass, with support for sharing a single Global Address Book party across all of them.

flowchart LR
    subgraph GC["Graphite Cloud"]
        API["Graphite Public API"]
        ADP["D365 Adapter"]
        API --- ADP
    end
    subgraph MS["Microsoft Cloud"]
        ENTRA["Microsoft Entra ID"]
        D365["D365 F&O OData API"]
    end
    ADP -- "1: Acquire OAuth token" --> ENTRA
    ADP -- "2: HTTPS + Bearer token" --> D365

Data Flow

Each synchronization run processes the suppliers whose data has changed since the last sync. For each supplier, the adapter processes one ERP record per legal entity:

flowchart TD
    A["Supplier data changes in Graphite"] --> B["Adapter picks up changed supplier"]
    B --> C{"Vendor already has a<br>Vendor Account Number?"}
    C -- No --> D["Create vendor in D365,<br>capture assigned account number"]
    C -- Yes --> E["Update existing vendor"]
    D --> F["Sync addresses, contacts,<br>bank accounts, attachments"]
    E --> F
    F --> G["Acknowledge results to Graphite:<br>Vendor Account Number, Party ID,<br>address location IDs"]
    G --> H{"Errors?"}
    H -- Yes --> I["Errors recorded on the record<br>and surfaced in Graphite"]
    H -- No --> J["Supplier marked as synchronized"]

Key behaviors:

• Create vs. update: If the supplier already has a VendorAccountNumber for a legal entity, the adapter updates the existing vendor. Otherwise it creates a new vendor and captures the account number D365 assigns (internal and external number sequences are both supported).
• Existence checks before writes: Addresses, contacts, bank accounts, and attachments are looked up in D365 first, then created or updated as appropriate — the adapter does not create duplicates on re-sync.
• Acknowledgements: After each record is processed, the adapter writes the results back to the supplier's Graphite profile: the D365 vendor account number (into the ERP_Record group), D365 address location IDs, and — where configured — the vendor's Global Address Book Party ID (D365_Party_ID). See ERP Record.

---

Setup

Setting up the integration takes three steps on your side, all using standard Microsoft tooling. Once complete, you hand a small set of values to Graphite and the Graphite team configures and validates the integration with you.

Prerequisites

• Admin access to your organization's Microsoft Entra ID (Azure) tenant, to create an app registration.
• Admin access to your D365 F&O environment, to create a service account user and register the app.
• Your D365 environment URL (for example https://yourcompany.operations.dynamics.com).
• If your organization restricts API access by source IP, plan to allowlist Graphite's egress IP addresses (available from your Graphite integration contact).

Step 1 — Register an application in Microsoft Entra ID

1. In the Azure portal, go to Microsoft Entra ID → App registrations → New registration.
2. Give the app a recognizable name (for example Graphite Connect Integration). No redirect URI is needed.
3. After the registration is created, note the Application (client) ID and Directory (tenant) ID from the app's overview page.
4. Go to Certificates & secrets → New client secret. Create a secret, choose an expiration per your security policy, and copy the secret value immediately (it is only shown once).

Note: Track the client secret's expiration date. When the secret expires, the integration stops authenticating until a new secret is created and shared with Graphite.

Step 2 — Create a service account user in D365

The integration runs under a dedicated service account user in D365, so every change it makes is attributable and scoped to permissions you control.

1. In D365, go to System administration → Users → Users and create a new user (for example svc-graphite).
2. Assign a security role that permits vendor master maintenance. The role must allow creating and updating vendors, vendor addresses, contact information, vendor bank accounts, and vendor document attachments. Depending on your configuration, it may also need to create bank groups, tax exempt numbers, and address master data (states, cities, postal codes). We recommend starting from your standard vendor-maintenance role and tightening to least privilege after validation in a test environment.

Step 3 — Register the app in D365 and bind it to the service account

1. In D365, go to System administration → Setup → Microsoft Entra ID applications (called Azure Active Directory applications on older versions).
2. Create a new entry: set Client Id to the Application (client) ID from Step 1, give it a name, and set User ID to the service account user from Step 2.

This tells D365 that API calls authenticated with your app registration should execute as the service account user, with that user's permissions.

Step 4 — Provide the configuration values to Graphite

Send the following values to your Graphite integration contact through a secure channel:

The Graphite team then configures the integration — including the field mapping between your Graphite profile and D365 — and validates it with you, typically first against a D365 sandbox environment.

---

Data Scope

The adapter maintains D365 vendor master data. Within the vendor master it can synchronize:

• General vendor data — names, vendor group, currency, payment terms, and other VendorsV2 fields per your mapping
• Postal addresses — including creation of supporting address master data (states, cities, postal codes) when a supplier address references values that do not yet exist in your environment
• Contact information — email addresses and phone numbers, both on the vendor and as Global Address Book contacts
• Bank accounts — including automatic creation of bank groups and attachment of supplier-provided bank documentation
• Document attachments — files from the supplier's Graphite profile (for example W-9s or certificates) attached to the vendor record
• Tax exempt numbers — registered in D365 before being referenced on the vendor
• Multiple legal entities — each supplier can be extended to any number of legal entities, controlled per supplier in Graphite

Exactly which fields are synchronized is controlled by a per-customer mapping configured with the Graphite team. See Transformations.

---

D365 API Reference

All calls target standard OData data entities on your environment (https://<environment>/data/...). Reads and writes use the cross-company query option so a single connection can serve all legal entities.

---

Bank Account Handling

Bank data is the most sensitive part of vendor master synchronization, and the adapter has dedicated behaviors for it:

• Primary bank selection. The adapter sets the vendor's default bank account (BankAccountId on the vendor) to the supplier's primary account. By default this is the first account in the mapped payload; the integration can instead honor the account explicitly designated as primary on the supplier's Graphite profile, so the supplier's selection drives the D365 default.
• Duplicate prevention. Before creating a bank account, the adapter looks for an existing record by its bank account ID, with a fallback lookup by key fields (account number, IBAN, SWIFT/BIC, routing number).
• Legacy bank retirement. If a matching bank account exists in D365 under a different bank account ID (for example, one created manually before the integration), the adapter can retire the legacy record by setting its ExpirationDate and create the Graphite-managed account in its place. Bank account IDs are record keys in D365 and cannot be renamed, so this preserves history while making the Graphite-managed record authoritative.
• Removed-bank expiry. When a supplier deletes a bank account in Graphite or stops sharing it, the adapter can automatically expire the corresponding D365 record by setting its ExpirationDate — the record and its history remain in D365, but the account is no longer usable for payments. If a previously expired account is shared again, the expiration is cleared and the account is reactivated. If the expired account was the vendor's selected default, the run reports an error prompting a new primary selection.
• Safety first. Removed-bank reconciliation only runs after every account in the current payload has synchronized successfully, so a transient failure can never cause a valid account to be expired.

Note: Bank retirement behaviors are optional and enabled per customer with the Graphite team.

---

Error Handling

• Automatic retries: Transient failures (network interruptions, timing issues while D365 propagates newly created master data) are retried automatically with backoff.
• Per-record errors: Errors are captured per supplier record with the D365 response message, so one supplier's failure never blocks the rest of the run.
• Visibility: All sync results and errors are visible in graphiteConnect's Interfaces Administration tool, and failed records are retried on subsequent runs after the underlying issue is resolved.

---

Common Technical Questions

Do we need to install or host anything?
No. The adapter runs entirely in the Graphite cloud. Your setup consists of the Entra ID app registration and the D365 service account described in Setup.

Do we need to open firewall ports or set up a VPN?
No, provided your D365 environment's standard OData endpoint is reachable over HTTPS. The adapter authenticates with Microsoft Entra ID and calls the same public API surface Microsoft provides for all D365 integrations. If your security policy restricts API access by source IP, Graphite's requests originate from a fixed set of egress IP addresses that you can allowlist — ask your Graphite integration contact for the current list.

Does the adapter write directly to D365 tables?
No. All writes go through D365's standard OData data entities, so D365's business logic, validations, and configured number sequences apply to every change.

Can it bypass D365 security?
No. Every call executes as the service account user you create, limited to the security roles you assign. You can revoke access at any time by disabling the app registration, expiring the client secret, or disabling the service account.

Does it support internally assigned vendor number sequences?
Yes. For internally assigned number sequences, the adapter captures the vendor account number D365 generates and writes it back to the supplier's Graphite profile. Externally assigned numbers from Graphite are also supported.

How are multiple legal entities handled?
Each supplier can be extended to any number of legal entities. The vendor's Global Address Book Party ID can be captured on first creation and reused when extending to additional legal entities, so all of a supplier's vendor records share one party.

How fresh is the data?
The adapter processes supplier changes shortly after they are approved in Graphite, on a polling cycle configured per customer.

What happens when a supplier updates previously synced data?
The adapter looks up the existing D365 records and updates them in place — re-syncing a supplier does not create duplicate vendors, addresses, contacts, or bank accounts.

---

Related Documentation

• Public API Integrations — Standard ERP integration workflow
• Authentication — Authenticating with the Graphite Public API
• Transformations — The mapping engine used to configure the D365 field mapping
• ERP Record — Field definitions for the ERP_Record group used in acknowledgements