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 a Redirect URL (optional): https://portal.ipaas.com/customer/subscription-mgmt/subscriptions/authorization/app. This is used for returning the authentication responses (tokens) after successfully authenticating or signing out users.
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 Permissions in Microsoft Dynamics 365 Business Central
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:
app_access
AdminCenter.ReadWrite.All
API.ReadWrite.All
Automation.ReadWrite.All
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.
OAuth 2.0 Authorization Code Grant Configuration
The OAuth 2.0 authorization code grant type enables a client application to gain authorized access to protected resources, such as web APIs. This flow involves a user signing into the app to access their data.
This flow requires a user-agent (such as a web browser) that can be redirected from the authorization server back to your application.
A user must sign into your app to access their data.
This flow provides:
An access token valid for 60 minutes.
A refresh token to obtain new access tokens without requiring the user to re-authorize the application.
To configure this grant, you need the following:
Tenant ID: The directory (tenant) ID where the application is registered. Found in the Microsoft Entra Admin Center under Identity > Overview > Tenant information.
Client ID: The unique application (client) ID assigned to your app. Found in the Microsoft Entra Admin Center under Identity > Overview > Client ID information.
Response Type: Must include code for the authorization code flow.
Redirect URL: The URL of your app where authentication responses will be sent.
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.
OAuth initiated within iPaaS
Set these OAuth settings on the Edit Integration [Microsoft Dynamics 365 Business Central] screen.
Navigate to the Microsoft Dynamics 365 Business Central integration, edit the settings, locate the Authorization Type option, and select OAuth initiated within iPaaS.
Enter this URL in the OAuth URL Template text box: https://login.microsoftonline.com/{Tenant Id}/oauth2/v2.0/authorize?response_type=code&client_id={SystemTypeVersion:ClientId}&scope={SystemTypeVersion:Scopes}&redirect_uri={iPaaSRedirectUrl}&code_challenge_method=S256&code_challenge={CodeChallenge:43}&state={iPaaSState}
Scroll to the bottom of the screen and add four custom fields, using the values obtained in the Before you Begin section:
ClientID: Value obtained in the Before you Begin section.
ClientSecret: Value obtained in the Before you Begin section.
Scopes: https://api.businesscentral.dynamics.com/.default offline_access
RedirectUrl: The redirect URL provided for your iPaaS.com environment.
Initiate the OAuth Flow and Generate the Access Token
Go to the Microsoft Dynamics 365 Business Central subscription that was created earlier.
Click the Authentication icon in the top toolbar.
A new browser window opens, redirecting to a URL containing code, state, and session_state parameters. A success message displays if the code is validated. After the confirmation page is displayed, you may close the window. 3. Refresh the iPaaS.com subscription page. If successful, the Access Token and Refresh Token will now be populated. - Access Token: Typically lasts about 60 to 90 minutes. With Continuous Access Evaluation (CAE), this can be extended. - Refresh Token: Used to obtain a new access token when the current one expires. - Revocation: Tokens can be invalidated before their expiration date if a password is changed, an administrator revokes them, or the user logs out.
If an error occurs, double-check that all settings match the configuration described above.
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.
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.