Skip to main content

Setup

Integration Hub Setup​

This setup contains company wide setting that are used by the Integration Hub.

FieldPurpose
Handle Failed MessageSpecifies how to handle the original failed messages when they get retried.
Enable Workflows for IntegrationSpecifies that you want to handle integration events with workflows. The recommended approach is using Integration Handlers rather than workflows, as they perform better.
Outbound Wait (m/s)Specifies the delay added after sending each outbound message when sending delayed messages. The purpose of this setting is to avoid hitting API limits.
EDI Unit Price Tolerance (+/-)Specifies the tolerance before the difference between an EDI price and the sales price is deemed a variance. Any difference greater than or equal to this value is deemed a variance. This logic is currently only available for sales documents such as sales orders.
Sales Unit Price Field IDSpecifies an alternative field to compare the sales line's unit price to the EDI unit price.
Net Price ComputationSpecifies the Net Price Computation formula applied to sales documents' Net Unit Price field.
Allow Ext. Doc Change to EDI Sales DocumentSpecifies that you allow changes to the external document number for EDI transactions. Usually, this is not permitted, as the external document number matches the document to the external document.
Allow EDI Fields EditSpecifies that EDI system fields are editable. This is only intended for testing in a sandbox environment.
Track Sales Price ChangesSpecifies that the sales line is updated to reflect if the sales price on the line has been changed. The effect is that the sales lines will reflect if a user changes the price or discount and if there is a price/order multiple issue.
Track Price Change TypeSpecifies which method to use when tracking sales price changes.
Show Cost in Price DetailSpecifies that cost values are shown on the price overview page, accessible from sales documents to view variances.
Enable Price Variance Calculation on Credit MemoSpecifies that you want to enable the EDI price logic for credit memos. Usually, this is disabled since most organisations do not integrate inbound credit notes from customers.

API Endpoints​

Here you configure the API Endpoints that are referenced in by Outbound Integration Handlers.

FieldPurpose
General
CodeSpecifies the code.
NameSpecifies the name of the endpoint.
Endpoint TypeSpecifies the type of endpoint which influences how the outbound messages are sent. Refer to the online documentation for more information.
Endpoint URISpecifies the Endpoint URI.
Skip error on failed callSpecifies that when the HTTP request fails, no error will be raised.
Encode Message DetailsSpecifies that you want the message to be encoded as Base64 text.
Remove Special CharactersSpecifies that special characters get removed from the message during HTTP calls if you send the message as Base64 encoded. This setting will affect all messages using this endpoint. You can update the integration handler only to affect a specific message.
Authentication
Authentication TypeSpecifies the type of Authentication to use.
Basic
Access KeySpecifies the Access Key.
Access Key ValueSpecifies the Access Key Value
OAuth
OAuth 2.0 EndpointSpecifies the the OAuth 2.0 Endpoint.
Grant TypeSpecifies the Grant Type.
Client IDSpecifies the Client ID.
Client SecretSpecifies the client secret.
ScopeSpecifies the scope.
Event
Event TopicSpecifies the Event Topic for the Event Grid or the Topic for the Service Bus.
Event SubjectSpecifies the Event Subject for the Event Grid or the Subscriber for the Service Bus.

Data Exchange Definitions​

The app uses data exchange definitions to handle mapping to fields.

Data Exchange Field Mapping​

The following fields are added by the app:

FieldPurpose
CommentSpecifies a comment about this mapping. This field is for information purposes only and is not used in the data exchange process.
Mandatory ValueSpecifies whether the field must contain a non-blank value.

Upgrade instructions​

Upgrading from 21.x or lower​

You need to do a force sync when upgrading to from 21.x or lower.

Migrating from the Per-Tenant version​

We have provided a migration tool to migrate your data from the per-tenant version to the AppSource version of the app. This tool is only available to Theta consultants.

Important

The integration messages endpoint will change when you move to the AppSource version. The new endpoint will be:

  • https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{BCEnvName}}/api/theta/integrationHub/v2.0/companies({{companyId}})/integrationMessages

Compared to the old endpoint:

  • https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{BCEnvName}}/api/theta/if/v2.0/companies({{companyId}})/integrationMessages

Prerequisites​

  • Integration Hub (PTE) - version 23.0.10.0 or greater.
  • Migrate PTE Integration Hub to AppSource - version 24.0.1.0 or greater.
  • Refactor any custom extensions dependent on the Integration Hub (PTE). If you have

Process - Business Central​

caution

Please ensure you run through this process in a sandbox environment and perform the necessary testing before proceeding to do this in production.

  1. Upgrade to the latest Integration Hub (PTE) version.

  2. Install the Integration Hub from AppSource.

  3. Install the Migrate PTE Integration Hub to AppSource app. The data migration happens during the installation process and runs for all companies.

  4. Open the Data Migration Summary to perform a high-level check of the data migration. You can check this in all companies. Navigation Navigation

  5. Uninstall and unpublish the Migrate PTE Integration Hub to AppSource app.

  6. Uninstall the Integration Hub (PTE) app. Do not unpublish the app yet. This will also uninstall any custom extensions dependent on the Integration Hub (PTE)** (if applicable).

  7. Update external systems (or Microsoft API Management) to use the new endpoint.

  8. If applicable, install and custom extensions dependent on the Integration Hub.

  9. Perform smoke testing as required to ensure the integration works as expected.

Rollback​

The process described has a fail-safe, as we have not deleted the data from the PTE at this point. If you encounter any issues, you can follow these steps to revert to the PTE version:

  1. Uninstall the Integration Hub AppSource app.
  2. Reinstall the Integration Hub (PTE) app and any dependent apps.
  3. Update external systems (or Microsoft API Management) to use the old endpoint.

Final Steps​

caution

After carrying out the steps below, you cannot revert to the Per-Tenant version of the app. Only commence with these steps once you are confident that the migration has been successful and your integration is functional.

As a final step, once you have validated the outcome of the migration, you can remove all the data related to the Integration Hub (PTE) app. To do this:

  1. Reinstall the Integration Hub (PTE) app.
  2. Uninstall the Integration Hub (PTE) app and specify to Delete Extension Data.
  3. Unpublish the Integration Hub (PTE) app.
See Also