Before you Begin
Before you begin, you will need to obtain authentication and other information from Microsoft Dynamics 365. This include OAuth 2.0 client credentials, the tenant ID, grant type, client ID and secret, and scope.
An application must be created in the Microsoft Entra Admin Center. Follow these steps to create the application:
Navigate to Microsoft Entra Admin Center.
Log in with your Microsoft Admin Account.
Go to Applications > App Registrations.
Click on 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(for the returning 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 installing the integration.
From the App registrations > Overview tab, find and copy Directory (tenant) ID.
Add Permissions in Microsoft Dynamics 365Business Central
Go to the 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 statically 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 our configuration, this must be statically set to
https://api.businesscentral.dynamics.com/.default. The .default scope is used to refer 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 (like 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 get new access tokens without requiring the user to re-authorize the application. This allows for seamless subsequent requests.
To configure this grant, you need the following:
Tenant ID: The directory (tenant) ID where the application is registered.
Location: Found in the Microsoft Entra admin center under Identity > Overview > Tenant information.
Client ID: The unique application (client) ID assigned to your app.
Location: Found in the Microsoft Entra admin center under Identity > Overview > Client ID information.
Response Type: Must include code for the authorization code flow. It can also include an id_token or token.
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 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 – Release
Select Create Default Mappings (recommended).
If you don’t want to create default mappings and want to create all mappings from scratch by yourself then uncheck this box.
Provide the API URL endpoint for you Microsoft Dynamics 365 instance.
Environment URLs:
Test/Sandbox:
https://api.businesscentral.dynamics.comProduction:
https://api.businesscentral.dynamics.com
Enter the Environment.For example, WEBsB2.
Enter the Tenant ID. For example, 08d1a030-9b1a-491d-a1fe-8fd964a372fa
Enter the Company Name.
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.
Set 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.
The following settings are optional and are not required to install a Microsoft Dynamics 365 subscription.
Enter the Transfer Customer Price Groups. This is a flag that determines whether to transfer Customer Pricing Group (CPG) information. Enter True to transfer the data or False to not.
Recommended Values:
Initial Setup: False (disable until Customer Pricing Groups and sales codes are properly mapped in iPaaS).
Ongoing Operations: True (enable once mappings are confirmed).
Enter Sales Codes for Customer Price. This field uses a comma-separated list of sales codes to identify the customer groups for which custom pricing information should be transferred. The codes you enter here tell the system which specific customer categories to use when fetching and transferring sales prices. For example, if set to "Y1004N, W1035N", the system will fetch and transfer sales prices for both Y1004N and W1035N codes.
Recommended Values:
Initial Setup:"" (leave empty, or provide only 1–2 test codes for validation).
Ongoing Operations:"Y1004N, W1035N" (use the standard set of sales codes relevant to your business).
High Volume: Limit to only the most critical sales codes (e.g., " Y1004N, W1035N") to reduce lookup/API overhead.
Enter the Sales Price Field Separator, a string character (//, |, ~) used to separate fields inside a single sales price record when building the formatted string.
Example: If Sales_Price_Field_Separator = "//", a single sales price record would look like:
25.99//Customer//CUST001//1000//Wireless Mouse//PCS//5//2024-01-01//2024-12-31
Recommended Values:
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).
Enter the Sales Price Record Delimiter, a single character (e.g., |, ;, ~) that separates multiple sales price records in a formatted output string. It's essential for distinguishing between different price records when more than one exists for the same sales code. It ensures that each sales price record is clearly separated from the next, preventing data from being mixed together. For example, if you use | as the delimiter, two separate price records would appear as: record_1|record_2.
Recommended Values:
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).
Set Exclude Expired Rules to True or False. This flag controls whether sales price records that have passed their EndingDate should be included in the output, preventing outdated/expired pricing rules from being transferred to iPaaS, and ensuring that only valid and active pricing rules are included in downstream processes.
Recommended Values:
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 and improve performance).
Set Process Company Relationship Flag to True or False. This setting enables or disables the logic for retrieving, transforming, and adding company relationship data to the final output. It's also used in the polling process to fetch relationships. If True, the system calls CompanyRelationship.Get() for each entity, enriches the data (e.g., setting RelationshipType = "Person"), and adds the results to the output. If False, no relationship data is processed or added to the output.
Recommended Values:
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 Trueonly if this data is critical for downstream processes; otherwise, false can improve performance and reduce payload size.
Enter the Contacts Endpoint, a string value that defines the API endpoint used for retrieving company contact information. If not specified, it defaults to contacts. It offers the flexibility to use different API paths for retrieving contact data. This is useful when the underlying system has different endpoints, such as contacts versus customers. For example, If the endpoint is contacts, the call will be /api/v2.0/companies({companyId})/contacts... If the endpoint is customers, the call will be /api/v2.0/companies({companyId})/customers...
Recommended Values:
Initial Setup & Ongoing Operations: contacts is the standard default and works with most Business Central APIs. Use a different value only if your system requires it.
High Volume: Use the endpoint that is optimized for contact retrieval in your specific environment.
Set Enable Company Hierarchy to True or False, to determine whether parent-child company relationships are processed and transferred to iPaaS. The correct setting is crucial for maintaining organizational structures in downstream systems.
If True, the system calls GetCompanyHierarchy() to retrieve the parent company data and creates a new relationship with RelationshipType = "Parent Company". This relationship is then attached to the child company's output.If False, Parent-child relationships are ignored, and only direct entity information is transferred.
Recommended Values:
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.
Enter Excluded Lineitem SKUs from Preprocessing, a string that specifies a comma-separated list of SKUs (e.g., "SKU123,SKU456") to be excluded during the preprocessing of sales order lines. It prevents specific products from being validated or mapped. This is useful for skipping items that should not be transferred to other systems, such as test SKUs, service items, or internal placeholders
Recommended Values:
Initial Setup: Leave it empty unless you already know of specific test or sandbox SKUs to exclude.
Ongoing Operations: Add SKUs for non-transferable items, like freight charges or internal service codes, to streamline processing.
High Volume: Keeping this list up-to-date is crucial for improving performance and preventing errors from system-only products.
Enter Transaction Poll Search Days, which defines the number of past days the system will look back when polling for new or modified transactions (sales orders, invoices, shipments). It ensures that 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 will then resume from that last saved date, regardless of the Transaction Poll Search Days value.Recommended Values:
Initial Setup: Use a larger value (e.g., 10–30 days) to ensure all historical transactions are captured during the initial migration.
Ongoing Operations: Set it to a lower value, like 3–7 days, to balance performance with data completeness.
High Volume: A very low value (1–2 days) is recommended to avoid large data pulls and minimize system load.
Set Processing Company Creation In Prerequisite to True or False, whether parent-child company relationships should be processed and included when transferring company data into iPaaS. It ensures that if a company has a parent organization defined (via ParentCustomerNo), that relationship is maintained in iPaaS, allowing companies to sync not just individually but as part of their corporate structure.
How it works:
If the setting is set to TRUE and a company has a ParentCustomerNo (indicating a parent company), then a CompanyRelationship list is created if one doesn't already exist. The system calls GetCompanyHierarchy to find the parent company record.
If the parent record is found, the following details are assigned to the relationship:RelationshipType is set to "Parent Company."
ParentCustomerNo_Hierarchy is assigned the parent company's ID.
The Id for the relationship is updated to combine both the parent and child IDs (e.g., parentId|childId).
This newly created parent relationship is then added to the company's Relationships list.
Recommended Values:
Initial Setup:True (Ensures hierarchies are created when first migrating companies into iPaaS.)
Ongoing Operations:True (Maintains parent–child structure in normal synchronization.)
High Volume:False (To reduce processing overhead when only individual company records are required.)
OAuth initiated within iPaaS
Set these OAuth settings on the Edit Integration [Microsoft Dynamics 365] screen. Integration Settings for Use with Integrator
Navigate to Microsoft Dynamics 365 Integration, edit the settings, and 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. You will add four Custom Fields: with values obtained in the Before Your 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_accessRedirectUrl:
https://stagingportal.ipaas.com/customer/subscription-mgmt/subscriptions/authorization/app
Initiate the OAuth Flow and Generate the Access Token
Initiate OAuth Flow and Generate Access Token
Go to the Microsoft Dynamics 365 Subscription that was created earlier.
Click the Authentication icon in the top toolbar.
A new browser window will open, 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.Refresh the iPaaS.com subscription page .If successful, the Access Token and Refresh Token will now be populated
Access Token: Typically lasts for 60-90 minutes (average 75 minutes). With Continuous Access Evaluation (CAE), this can be extended up to 28 hours.
Refresh Token: Valid for 90 days (24 hours for Single-Page Applications). It is used to get a new access token when the current one expires.
Dynamics 365: Access tokens usually expire in about one hour, so using the refresh token is necessary.
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 like field mappings, workflow triggers, and logging.
Review integration logs in iPaaS.
Common Issues and Solutions
Insufficient Permissions
Issue: User lacks required roles.
Solution: Assign System Administrator or Dynamics 365 Administrator role before installation.
Unsupported Environment
Issue: App not compatible with target environment.
Solution: Verify environment has Dataverse and meets app requirements.
Missing License
Issue: Users don’t have the right license.
Solution: Assign or purchase the correct Dynamics 365 license via Microsoft 365 Admin Center.
AppSource Errors
Issue: Install fails through AppSource.
Solution: Retry via Power Platform Admin Center or switch browser.
Customization Conflicts
Issue: Existing solutions cause dependency issues.
Solution: Install in a sandbox/test environment first and resolve conflicts.
Storage Limits
Issue: Environment has reached database/file storage limits.
Solution: Free up space or buy additional storage capacity.
Slow/Stuck Installation
Issue: Install takes too long or doesn’t finish.
Solution: Wait up to 1 hour (normal). If >2 hours, cancel and retry.
Regional Restrictions
Issue: App not available in selected geography.
Solution: Confirm availability in AppSource for your region or use an alternate region.
Integration Failures
Issue: Connectors or API access blocked.
Solution: Enable Azure AD permissions, re-check connectors, or re-authenticate integrations.
Missing Dependencies
Issue: Required solutions/updates 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