Microsoft Dynamics 365 BC (Business Central) integration

This article describes the standard integration between Younium and Dynamics BC. 

Data flows at a glance

Authentication

Azure AD - OAuth 2.0 client credentials

The integration uses service-to-service authentication via an Azure AD app registration. No user login is required at runtime.

Setup steps

1. Create an App Registration in Azure AD.
2. Create a corresponding Azure AD Application in Business Central and grant it sufficient API permissions.

Full Microsoft instructions: Automation APIs using S2S Authentication

Credentials required in Younium

Required OData pages in BC

The following standard BC pages must be accessible via OData before activating the integration:

The following fields must be added to pages 43 and 44 (SalesInvoice / SalesCreditMemo):

• Sell_to_Customer_No
• Bill_to_Customer_No
• WorkDescription

The following fields must be added to pages 47 and 96 (InvoiceLine / InvoiceCreditLine):

• Document_No
• Line_No

Activation and Deactivation

Activating the integration

1. In Younium, go to Settings → Integrations → Dynamics 365 Business Central.
2. Click Get started.
3. Enter the credentials listed above.
4. Click Activate - Younium queries BC to verify the company name. On success, the integration is marked active.

During activation, Younium automatically creates the following custom fields. 
Do not rename or delete them - they are referenced by name in the integration code.

Deactivating the integration

Go to Settings → Integrations → Dynamics 365 Business Central and click Deactivate. This removes all stored credentials and unsubscribes the invoice posting event. Custom fields created during activation remain in Younium and can be reused if the integration is reactivated.

Configuration settings

All settings are available after activation under Settings → Integrations → Dynamics 365 Business Central.

Synchronization jobs

All jobs check that the integration is active before running. Jobs are configured and scheduled under Settings → General → Scheduled Jobs.

Importing accounts (BC → Younium)

Fetches all BC customers modified since the last sync date

Currency requirement. The Younium base currency must match the Local Currency (LCY) code in BC's General Ledger Setup. This is checked on every account sync run and on every invoice post - the job stops if they differ.

Behaviour rules

• Customers with Blocked = ALL or Blocked = INVOICE that do not yet exist in Younium are skipped entirely.
• Blocked customers that already exist in Younium are synced and marked inactive.
• If a customer's currency does not exist in Younium, that customer is skipped and a failure is logged. Other customers continue processing.
• Custom field mappings (if Enable Custom Mapping is on for accounts) are applied on top of the standard field mapping.

Account field mapping (BC → Younium)

Importing products (BC → Younium)

Fetches all BC items modified since the last product sync. Each item is matched to a Younium product by the Dynamics NAV Product Number custom field.

Behaviour rules

• Items without a description in BC are skipped and logged as errors.
• If no matching product exists in Younium, a new product is created with a default charge plan and a single charge using the Quantity charge model.
• If a matching product exists, the product name, charge plan name, and charge name are updated.
• Products previously synced from BC that are no longer present in the BC item list are marked end-of-sale in Younium (set to today's date).
• Dynamics NAV Product Number is set on both the Product and the Charge.

Product field mapping (BC → Younium)

Importing payment terms (BC → Younium)

Fetches all BC payment terms. Only day-based terms with no discount are supported.

Skipped terms are logged. A term is skipped if:

• It has a Discount_Date_Calculation value (discount terms are not supported).
• Its Due_Date_Calculation does not contain D (only day-based terms are supported).
• Its Due_Date_Calculation contains more than one letter (e.g. compound formats are not supported - only formats like 30D are accepted).

Existing payment terms are updated if the description or number of days has changed.

Payment term field mapping (BC → Younium)

Importing chart of accounts (BC → Younium)

Fetches all accounts from BC's ChartOfAccount endpoint. Only accounts with Account_Type = POSTING are imported. Account names are updated if changed in BC.

Financial account field mapping (BC → Younium)

Importing currencies (BC → Younium)

Fetches all currencies from BC. New currencies not already present in Younium are created. Existing currencies are not updated - Code is the match key (case-insensitive).

Currency field mapping (BC → Younium)

Importing exchange rates (BC → Younium)

Fetches all exchange rates from BC's CurrencyExchangeRate endpoint. The rate is calculated as Relational_Exch_Rate_Amount / Exchange_Rate_Amount. Currencies not yet present in Younium are skipped.

Exchange rate field mapping (BC → Younium)

Importing dimensions (BC → Younium)

Fetches all values for a configured dimension code from BC. Values are stored as items in a custom field list on invoice lines.

Requirements - both must be configured before the job runs:

• Dimension Code - the BC dimension to import (e.g. DEPARTMENT).
• Invoice Line Dimension Custom Field - the Younium invoice line custom field that will hold the dimension value. It must be a List type and reference a valid custom field list.

Behaviour: New dimension values are added to the list. Existing values are updated if the name has changed.

Invoice posting (Younium → BC)

When an invoice is posted in Younium, the InvoicePosted event fires and the integration automatically creates a Sales Invoice or Sales Credit Memo in BC.

Credit memos. Any invoice with a negative total amount (TotalAmount.Amount < 0) is posted as a SalesCreditMemo. Prices on lines are negated - BC expects positive amounts on credit memo lines.

Prerequisites

All of the following must be in place before an invoice can post successfully:

• Younium base currency matches BC LCY code (checked on every post).
• The account has Dynamics NAV Customer Number populated.
• Every invoice line has Dynamics NAV Product Number populated on its charge.
• The account's payment term exists in BC.
• EAN number does not exceed 13 characters (if the EAN setting is enabled).

Behaviour rules

• Credit memos: any invoice with a negative total amount is posted as a SalesCreditMemo. Prices on lines are negated - BC expects positive amounts on credit memo lines.
• Lines are sent in order of ProductLineNumber ascending, then ChargeNumber ascending - matching the order they appear in the Younium order.
• Each line is patched immediately after creation to force Line_Discount_Percent = 0
• If a Younium line price is 0, Unit_Price is also explicitly patched to 0 after line creation
• For non - One-Off lines with a service period, a comment line is added in BC with the service period dates (YYYY-MM-DD to YYYY-MM-DD).
• Line notes are split on line breaks and chunked to 100 characters each, with each chunk posted as a separate comment line.
• Multi-order invoices (when Allow Multiple Orders is enabled): lines are grouped by account. A comment line with the account name is inserted before each group; an empty comment line follows as a separator.
• On success, the BC document number is written back to the Dynamics NAV Invoice Number custom field on the Younium invoice and to ExternalERPId.

Invoice header field mapping (Younium → BC)

Invoice line field mapping (Younium → BC)

Write-back (BC → Younium)

Deferral codes

Invoice lines in Younium can be mapped to BC deferral templates. The Dynamics NAV Deferral Code custom field is available on charges, order product charges, and invoice lines.

When an invoice line has a service period and this field is populated, the integration:

1. Looks up the matching deferral list item by value.
2. Formats the list item's key using the rounded period length (e.g. the key R{0:D2} becomes R06 for a 6-month period).
3. Posts Deferral_Code and the service period start date to the BC line.

A BC customisation is required to use deferral codes. Contact your Younium implementation team before enabling this feature. The service period start date field name in BC is configurable via the DeferralServicePeriodStartDateCustomMapping setting. The default is EDX_Returns_Deferral_Start_Date.

Troubleshooting

Cannot connect to BC

• Verify the Base URL format exactly: https://api.businesscentral.dynamics.com/v2.0/{TenantId}/{EnvironmentName}/ODataV4/
• Confirm the BC Company name matches exactly what is configured in BC (the connection test is case-sensitive).
• Confirm the Azure AD app has the required BC API permissions.
• Check the integration log for the token fetch error message.
• Check network connectivity and firewall settings - the Younium service must be able to reach the BC OData endpoint. 
• If using SSL bypass validation, confirm this is only enabled for development or sandbox environments.

Invoice posting fails

• LCY mismatch - check BC General Ledger Setup and the Younium base currency under Settings → Legal Entity. They must match exactly.
• Missing customer number - populate Dynamics NAV Customer Number on the account.
• Missing product number - populate Dynamics NAV Product Number on every charge linked to the invoice.
• Payment term not found - sync payment terms first, or add the term manually in BC.
• EAN number too long - EAN values must be 13 characters or fewer.
• Line discount cleared - this is expected behaviour. The integration always patches Line_Discount_Percent = 0.
• Zero-price line shows item list price - if the item list price appeared briefly before the patch ran, this is expected. The integration patches Unit_Price = 0 immediately after creation.

Synchronization failures

• Currency missing - sync currencies before syncing accounts or products. A customer's currency must exist in Younium before that customer can be imported.
• Payment terms skipped - check the integration log for "has discount" or "support only days" messages. BC terms with discounts or formats other than {n}D are not supported and will always be skipped.
• Dimension sync fails - confirm that both Dimension Code and Invoice Line Dimension Custom Field are set in the integration settings.
• Individual record failures do not stop the full sync run. Check the log for created / updated / failed counts.

Best practices

• Synchronize master data in this order before enabling invoice posting: currencies → payment terms → chart of accounts → customer accounts. Currency must exist in Younium before an account using that currency can be imported.
• Test invoice posting in a sandbox or non-production BC environment before enabling in production.
• Review synchronization logs regularly to catch and resolve issues early.
• Maintain consistent customer and product numbers between Younium and BC. The integration matches on these identifiers - discrepancies will cause duplicate records or failed postings.
• If using EAN numbers, verify values are 13 characters or fewer before enabling the setting.
• Keep custom field mappings up to date when BC fields or Younium field configurations change.