Before you Begin
Before you begin, subscribers or their MiSP will need to obtain authentication and other information from Microsoft Dynamics 365 Business Central. This includes OAuth 2.0 client credentials, the tenant ID, grant type, client ID and secret, and scope.
The integration also accesses Business Central through Business Central Web Services. As part of installation, enable the Web Services for the entities you will sync — customers, contacts, companies, items, item inventory, locations, sales orders and their lines, sales shipments, and sales invoices. Some flows require additional fields to be exposed on the Web Service response: sales order transfer to iPaaS.com (with shipment tracking) requires the Sales Shipments Web Service to expose the originating Order No., and company relationship transfer requires the Contacts Web Service to expose the related Company No. See the Known Limitations article for the full list, or contact iPaaS.com Support for assistance configuring Business Central Web Services.
An application must be created in the Microsoft Entra Admin Center. Follow these steps to create the application:
Navigate to the Microsoft Entra Admin Center.
Log in with your Microsoft administrator account.
Go to Applications > App Registrations.
Click Create New Registration.
Enter a display name for this application.
Choose the appropriate option to determine who can use this application.
Enter the Redirect URL: https://portal.ipaas.com/customer/subscription-mgmt/subscriptions/authorization/app. This redirect URL is required — it is used for returning the authentication responses (tokens) after successfully authenticating or signing out users.
Add a second Web redirect URI so you can grant consent to the application from Business Central later: https://businesscentral.dynamics.com/OAuthLanding.htm. Add this under Authentication > Platform configurations > Web alongside the redirect URL above. The portion before OAuthLanding.htm must match the address of your Business Central web client as it appears in the browser. Without this redirect URI, the Grant Consent step in Business Central fails with a redirect-URI mismatch error.
You will now receive the Client ID and Tenant ID.
To obtain client credentials
Click the Certificates & Secrets tab.
Click New Client Secret.
Add a description and set the expiration for the Client Secret.
Click Add to generate the Client Secret. Save the client secret in a secure location, as it can only be copied once and will not be displayed again.
Return to the App Registrations tab and select Overview.
Copy the Application (client) ID. This is the Client ID you will use when installing the integration.
From the App Registrations > Overview tab, find and copy the Directory (tenant) ID.
Add API Permissions in Microsoft Entra ID
These permissions are added to the application registration in the Microsoft Entra Admin Center.
Go to API permissions, then click Add a permission.
On the Request API permissions screen, select Dynamics 365 Business Central.
Select Application permissions and select or add the following permissions. API.ReadWrite.All and Automation.ReadWrite.All are required; the others broaden access for administrative scenarios:
app_access
AdminCenter.ReadWrite.All
API.ReadWrite.All
Automation.ReadWrite.All
Select Add permissions. Then select Grant admin consent for [your tenant] so the application can use the permissions without a further prompt. (If you prefer, you can instead grant consent later from Business Central using the Grant Consent step below.)
Authorize the Application in Business Central
Registering the application and adding API permissions in Microsoft Entra ID lets Microsoft issue a token for the application, but Business Central rejects the application's requests until the application is also registered and enabled inside Business Central. Complete these steps in the Business Central web client for the environment this subscription will sync.
In Business Central, use the search (Tell me what you want to do) to open the Microsoft Entra Applications page, then select New. The Microsoft Entra Application Card opens.
In the Client ID field, enter the Application (client) ID of the application you registered in Microsoft Entra ID. This must be the same Client ID you enter in the iPaaS.com subscription settings.
Enter a Description that identifies the application.
Set State to Enabled. The application cannot authenticate to Business Central until its state is Enabled — a disabled application is rejected even after consent is granted. (To change a saved application later, set State back to Disabled, make the change, then set it to Enabled again.)
Under User Permission Sets, add the permission sets the integration needs — D365 AUTOMATION and D365 BUS FULL ACCESS. Applications cannot be assigned the SUPER permission set; assign only the permission sets the integration requires.
Select Grant Consent and follow the wizard, then select Accept on the Microsoft permissions screen to consent to the application for your organization. This step requires the https://businesscentral.dynamics.com/OAuthLanding.htm redirect URI on the Microsoft Entra application (added in the Before you Begin section); without it, consent fails with a redirect-URI mismatch.
After consent completes, confirm the application's State still reads Enabled. Editing the application — including adding a redirect URI — can return it to Disabled, and a disabled application is rejected at transfer time even though the subscription saves successfully.
Enable Business Central Web Services
The integration reads and writes Business Central through Business Central Web Services, so the Web Services for the data you sync must be published in Business Central before the corresponding flows will work. Enable the Web Services for the entities you use — customers, contacts, companies, items, item inventory, locations, sales orders and their lines, sales shipments and their lines, and sales invoices and their lines.
Some flows additionally require specific fields to be exposed on the Web Service response. Publish these before using the flow:
Sales order and posted sales invoice transfer to iPaaS.com require the Sales Shipments Web Service (and Sales Shipment Lines) to expose the originating Order No. on each shipment.
Company relationship transfer requires the Contacts Web Service to expose the related Company No. field.
Contact transfer to iPaaS.com requires the Contacts Web Service to expose the contact's First Name and Last Name (or a Company Name).
Until the required Web Service is published — or a required field above is exposed — the integration cannot read or write that data and the corresponding transfer does not complete. Subscribers or their MiSP can contact iPaaS.com Support for assistance configuring or customizing Business Central Web Services.
OAuth 2.0 Client Credentials Grant Configuration
The OAuth 2.0 client credentials grant flow allows a web service (a confidential client) to use its own credentials to authenticate and access another web service. This flow is for applications that need to act on their own behalf, without a user's involvement.
Permissions are granted directly to the application by an administrator.
The application itself is authorized to perform actions, since no user is involved in the authentication.
This flow provides an access token valid for 60 minutes. To generate an access token, the following details are required in the iPaaS.com subscription settings:
Tenant ID: The directory (tenant) ID where the application is registered.
Grant Type: Must be set to client_credentials.
Client ID: The application (client) ID assigned to your app during registration.
Client Secret: The secret key generated for the application. This value must be saved in a secure location.
Scope: The specific permissions or resources the app is requesting access to. For this configuration, set this to https://api.businesscentral.dynamics.com/.default. The .default scope refers generically to a resource service (API) without specifying individual permissions.
With this information, you can install the integration.
Installation Instructions for Integration Setup
Go to Subscriptions Management > Subscriptions and click Search Certified Integration Marketplace and Subscribe.
Click the Microsoft Dynamics 365 Business Central integration title.
On the Subscription Detail page, click the Subscribe button.
Enter the name of the subscription and select a version. It can be set to any relevant and unique subscription name within the company where this subscription is created.
Format: [Product Name] - [Environment/Purpose]
Example: Microsoft Dynamics 365 Business Central - Release
Select Create Default Mappings (recommended). If you do not want to create default mappings and prefer to create all mappings from scratch yourself, uncheck this box.
Provide the API URL endpoint for your Microsoft Dynamics 365 Business Central instance.
API URL: https://api.businesscentral.dynamics.com (this is the same host for both Test/Sandbox and Production instances; the Environment value below differentiates the target instance).
Enter the Environment. For example, WEBsB2.
Enter the Company Name for the company in Business Central that this subscription will sync.
Enter the Tenant ID — the Microsoft directory where the application is registered. You can find this in the Microsoft Entra Admin Center > Identity > Overview > Tenant information. Copy the value and paste it in. For example, 08d1a030-9b1a-491d-a1fe-8fd964a372fa.
Set the Grant Type to client_credentials.
Enter the Client ID — the unique identifier for your application registered in Microsoft Entra ID. You can find this at Microsoft Entra Admin Center > Identity > Overview > Client ID information.
Enter the Client Secret and the Scope (https://api.businesscentral.dynamics.com/.default) captured in the Before you Begin section.
Optional settings
The following settings are optional and are not required to install a Microsoft Dynamics 365 Business Central subscription.
Transfer Customer Price Groups: A flag that determines whether to transfer Customer Pricing Group (CPG) information. Enter True to transfer the data or False to not.
Initial Setup: False (disable until Customer Pricing Groups and sales codes are properly mapped in iPaaS.com).
Ongoing Operations: True (enable once mappings are confirmed).
Sales Codes For Customer Price Groups: A comma-separated list of sales codes that identifies the customer groups for which custom pricing information should be transferred. For example, if set to Y1004N, W1035N, the system fetches and transfers sales prices for both the Y1004N and W1035N codes.
Placeholder value — replace during implementation: The codes shown are examples. Enter the sales codes relevant to your own Business Central company, or leave empty to transfer none.
Initial Setup: Leave empty, or provide only one or two test codes for validation.
High Volume: Limit to only the most critical sales codes to reduce lookup and API overhead.
Sales Price Field Separator: A string character (for example //, |, or ~) used to separate fields inside a single sales price record when building the formatted string. For example, with a separator of //, a single sales price record would look like: 25.99//Customer//CUST001//1000//Wireless Mouse//PCS//5//2024-01-01//2024-12-31.
Initial Setup: Empty value.
Ongoing Operations: | or ~ (to avoid conflicts if descriptions contain commas).
High Volume: // (preferred for clean downstream parsing and large data volumes).
Sales Price Record Delimiter: A single character (for example |, ;, or ~) that separates multiple sales price records in a formatted output string. It distinguishes between different price records when more than one exists for the same sales code. For example, with | as the delimiter, two separate price records appear as: record_1|record_2.
Initial Setup: Empty value.
Ongoing Operations: | or ~.
High Volume: //.
Exclude Expired Rules: Set to True or False. This flag controls whether sales price records that have passed their ending date are included in the output. It prevents outdated or expired pricing rules from being transferred to iPaaS.com, ensuring only valid and active pricing rules are included in downstream processes.
Initial Setup: False or empty (include all records initially for testing and validation).
Ongoing Operations: True (exclude expired rules to keep pricing data clean and current).
High Volume: True (recommended to reduce unnecessary data transfer).
Process Company Relationship: Set to True or False. This setting enables or disables the logic for retrieving, transforming, and adding company relationship data to the final output. It is also used in the polling process to fetch relationships. If True, the system retrieves relationship data for each entity, enriches it, and adds the results to the output. If False, no relationship data is processed or added.
Initial Setup: False (or empty) to disable it until the relationship structure is confirmed.
Ongoing Operations: True to regularly process and transfer relationship data.
High Volume: Use True only if this data is critical for downstream processes; otherwise False can improve performance and reduce payload size.
Contacts Endpoint: A string value that defines the API path used for retrieving company contact information. If not specified, it defaults to contacts. This offers flexibility to use different API paths for retrieving contact data when the underlying system uses different endpoints, such as contacts versus customers.
Initial Setup and Ongoing Operations: contacts is the standard default and works with most Business Central instances. Use a different value only if your system requires it.
High Volume: Use the endpoint optimized for contact retrieval in your specific environment.
Enable Company Hierarchy: Set to True or False to determine whether parent-child company relationships are processed and transferred to iPaaS.com. If True, the system retrieves the parent company data and creates a relationship with a relationship type of Parent Company, which is then attached to the child company's output. If False, parent-child relationships are ignored and only direct entity information is transferred.
Initial Setup: False (or empty) until you confirm the hierarchical data is correct in the source system.
Ongoing Operations: True to ensure the company hierarchy is consistently maintained in downstream integrations.
High Volume: Use True only if the hierarchy data is essential. Keeping it False can significantly reduce API calls and improve performance.
Excluded Lineitem SKUs from Preprocessing: A comma-separated list of SKUs (for example SKU123, SKU456) to be excluded during the preprocessing of sales order lines. It prevents specific products from being validated or mapped, which is useful for skipping items that should not be transferred, such as test SKUs, service items, or internal placeholders.
Placeholder value — replace during implementation: The SKUs shown are examples. Enter the SKUs you want to exclude in your own environment, or leave empty.
Initial Setup: Leave empty unless you already know of specific test or sandbox SKUs to exclude.
Ongoing Operations: Add SKUs for non-transferable items, such as freight charges or internal service codes.
High Volume: Keep this list up to date to improve performance and prevent errors from system-only products.
Transaction Poll Search Days: Defines the number of past days the system looks back when polling for new or modified transactions (sales orders, invoices, shipments). It ensures the polling process captures all recently created or updated transactions within a specific time window. The default is 5 days if no value is provided. This value is overridden if a persistent timestamp from a previous successful poll exists; the system then resumes from that last saved date, regardless of the Transaction Poll Search Days value.
Initial Setup: Use a larger value (for example 10 to 30 days) to ensure all historical transactions are captured during the initial migration.
Ongoing Operations: Set a lower value, such as 3 to 7 days, to balance performance with data completeness.
High Volume: A very low value (1 to 2 days) is recommended to avoid large data pulls and minimize system load.
Processing Company Creation In Prerequisite: Set to True or False to control whether parent-child company relationships are processed and included when transferring company data into iPaaS.com. When True and a company has a parent organization defined, the parent-child relationship is created and maintained in iPaaS.com (a relationship type of Parent Company is assigned and the parent company is associated with the child), allowing companies to sync not just individually but as part of their corporate structure.
Initial Setup: True (ensures hierarchies are created when first migrating companies into iPaaS.com).
Ongoing Operations: True (maintains the parent-child structure in normal synchronization).
High Volume: False (to reduce processing overhead when only individual company records are required).
Update Non-Existing Invoice Lines: Set to True or False. This flag controls whether invoice line items that are present on the iPaaS.com transaction but not in the Business Central invoice payload are updated during a transfer. When False (the default), such lines are not updated.
Initial Setup: False (or empty) until invoice line handling has been validated.
Ongoing Operations: Set to True only if your process requires updating lines that are absent from the Business Central payload.
Post-Installation Verification
After completing the installation, perform these tests to verify the installation:
Data Sync Test
Initiate a sample data pull (to iPaaS.com).
Initiate a sample data push (from iPaaS.com).
Functionality Test
Run an end-to-end business process.
Validate key features such as field mappings, workflow triggers, and logging.
Review integration logs in iPaaS.com under Dashboard > Integration Monitoring > Error Logs.
Common Issues and Solutions
Insufficient Permissions
Issue: The user lacks required roles.
Solution: Assign the System Administrator or Dynamics 365 Administrator role before installation.
Unsupported Environment
Issue: The app is not compatible with the target environment.
Solution: Verify the environment meets the app requirements.
Missing License
Issue: Users do not have the right license.
Solution: Assign or purchase the correct Dynamics 365 license via the Microsoft 365 Admin Center.
Customization Conflicts
Issue: Existing solutions cause dependency issues.
Solution: Install in a sandbox or test environment first and resolve conflicts.
Storage Limits
Issue: The environment has reached database or file storage limits.
Solution: Free up space or buy additional storage capacity.
Slow or Stuck Installation
Issue: The install takes too long or does not finish.
Solution: Wait up to 1 hour (normal). If it takes longer than 2 hours, cancel and retry.
Regional Restrictions
Issue: The app is not available in the selected geography.
Solution: Confirm availability for your region or use an alternate region.
Integration Failures
Issue: API access is blocked.
Solution: Enable the required Microsoft Entra permissions, re-check the configuration, or re-authenticate.
Business Central Rejects the Credentials
Issue: Transfers fail with an error similar to "The server has rejected the client credentials" (
Authentication_InvalidCredentials), even though saving the subscription succeeds and shows a token.Solution: Saving the subscription only confirms that Microsoft Entra ID issued a token; it does not confirm that Business Central accepts it. In Business Central, open Microsoft Entra Applications and confirm that the application is listed with State = Enabled, that the D365 AUTOMATION and D365 BUS FULL ACCESS permission sets are assigned, and that consent has been granted. Confirm the application's Client ID matches the Client ID in the iPaaS.com subscription settings, and that the Microsoft Entra application has the https://businesscentral.dynamics.com/OAuthLanding.htm redirect URI. Adding a redirect URI or making other edits can leave the application Disabled — re-check that the State is Enabled after any change.
Cannot Grant Consent (Redirect URI Mismatch)
Issue: Selecting Grant Consent fails with a redirect-URI mismatch (
AADSTS50011).Solution: Add https://businesscentral.dynamics.com/OAuthLanding.htm as a Web redirect URI on the Microsoft Entra application (under Authentication > Platform configurations > Web), then retry Grant Consent. The portion before OAuthLanding.htm must match the address of your Business Central web client as it appears in the browser.
Missing Dependencies
Issue: Required solutions or updates are not installed.
Solution: Install all prerequisites before retrying app installation.
Support and Troubleshooting
Click the Help button on any iPaaS.com page to contact Support or to search our documentation.
Documentation: Search our documentation at the top of this article.
Support Portal: Click the Help and Support button at the lower-right of this window.
Contact Information: Contact iPaaS.com.