The primary objective of the Tradecloud (TC) Business Central (BC) connector is to master the development of a bridge between TC and various ERP systems that offer an API interface. This entails understanding and crafting the necessary design, workflows, and models essential for integration. It's important to emphasize that this serves as a reference implementation, which means it has not been rigorously proven in a production environment.
The connector acts as an intermediary between TC and the ERP system. It is architecturally agnostic and can be deployed on any cloud platform that supports ASP.NET Core, making it independent of both Tradecloud and the ERP system. This design provides an overview of the connector's components and its operational flows. The flows associated with the BC side are complex due to BC's constrained API offerings.
The current features are:
- send order (updates) from BC to TC
- split order lines in BC and send them to TC
- send order response (updates) from TC to BC
- split ordes lines in TC and send them to BC
On the back log are:
- renewing the BC webhook subscription
- send BC supplier item numbers to TC
- send BC buyer and supplier contacts to TC
- send BC documents to TC
- send TC documents to BC
- adding API specs (swagger) for the end points
The connector uses the free, cross platform and open source ASP.NET Core framework and the C# programming language, further relying on:
- the MVC framework in ASP.NET Core, which provides dependency injection and controllers that can receive requests.
- the standard HTTP client, which is included in ASP.NET Core.
- the Json.NET library, which is the de facto .NET JSON library.
- Azure configuration & logging extensions.
The PoC has been deployed on Azure App Service as an example, with Github Actions facilitating its build and deployment. The technical Azure setup is detailed in Azure set up. For local execution, the PoC is designed to run seamlessly using ASP.NET Core, Visual Code, specific Visual Code extensions, and ngrok. Instructions for this setup are outlined in Local set up.
The connector uses the OAuth 2.0 client credentials flow also known as Service-to-Service Authentication to authenticate against BC.
superThis connector leverages the standard BC API v2 and OData endpoints, alongside with an optional BC API extension. There are some differences between the v2 versus OData API: The API v2 works with technical identifiers, like orderId
, while the OData API works with composed functional keys, like number
. The connector uses the BC API v2 to get the composed functional key, which is then used with the OData API. The API v2 only contains a subset of by Tradecloud required fields, and the OData API contains all fields.
There is a minimal BC extension in folder tc-bc-app
which provides a custom API to "reopen" and "release" purchase orders. It uses the AL programming language and is deployed and executed inside BC.
The connector uses JSON Web Tokens to authenticate against TC. It makes use of the One single delivery per order line as BC also has only one delivery per order line. It sends orders using the Issue an order API and receives order responses using the single delivery order event webhook endpoint.
- Install .NET SDK 8.0
- Install Visual Code
- Install Visual Code C# Dev Kit extension
- Clone the repo
git clone [email protected]:tradecloud/tradecloud-bc-connector-poc.git
- In Visual Code open the repo root folder.
- Use
Ctrl-Shift P
for the command pallete, and filter on.NET
. - Use
Ctrl-Shift B
to build. - Copy
appsettings.Development.template.json
toappsettings.Development.json
and configure. - Use
CTRL-F5
to deploy and run the app locally, the webhooks will run on localhost URL - Use
F5
to deploy and debug the app locally, please note that the app has been run locally at least once before, else you will get an error. - Use
dotnet run
from the terminal to simulate a production environment, it will detect being stopped and unsubscribe the BC webhook. - Setup ngrok to test webhooks with a local deployment.
- Run
ngrok http http://localhost:5213 --domain earwig-smart-officially.ngrok-free.app
(the ngrok domain is an example) - Configure
BaseURL
inappsettings.Development.json
with the ngrok tunnel URL, likehttps://earwig-smart-officially.ngrok-free.app
(w/o trailing slash)
- Create an App Service.
- Select Continuous Delivery en connect to your forked repo.
- Azure will create a Github Actions workflow to Build and deploy ASP.Net Core app to the Azure Web App.
- Azure will commit the Github Actions workflow yaml file in
.github/worklflows
. - Github workflow runs (replace by your forked repo).
- Github deployments (replace by your forked repo).
Set up service-to-service authentication
- Register an app
- Note the
Application (client) ID
- Note the
Directory (tenant) ID
- Select the
Authentication
sub menu on the left. - Select
Add a platform
andWeb
- Fill in
https://businesscentral.dynamics.com/OAuthLanding.htm
- Select
Configure
- Select the
Certificates & Secrets
sub menu on the left. - Select
New client secret
, copy the value - Select
API permissions
,Add a permission
,Dynamics 365 Business Central
,Application permissions
- Add
API.ReadWrite.All
,Automation.ReadWrite.All
permissions. - And similar
Delegated permissions
, addFinancials.ReadWrite.All
(This is related to theD365 FIN. & PURCH.
permission in BC, TODO: test these are really necessary) - Select
Grant admin consent
and confirm
You need to set these Name-Value pairs:
Connector__MS__ClientId
- Oauth2 service-to-service client id (Application (client) ID
)Connector__MS__ClientSecret
- Oauth2 service-to-service client secret (Client secret
)Connector__BC__TenantId
- Business Central TenantId (Directory (tenant) ID
)Connector__BC__Environment
- Buniness Central environment, for exampleTest
Connector__BC__CompanyId
- Business Central Company ID (Fetch viahttps://api.businesscentral.dynamics.com/v2.0/<TenantId>/<EnvironmentName>/ODataV4/company('<CompanyName>')
)Connector__BC__CompanyName
- Business Central Company nameConnector__BC__SharedSecret
- A random generated password string for the BC webhook hand shakeConnector__TC__BuyerId
- Tradecloud buyer IDConnector__TC__IntegrationUsername
- Tradecloud integration user emailConnector__TC__IntegrationPassword
- Tradecloud integration user passwordConnector__TC__WebhookBearerToken
- Tradecloud webhook bearer token
Set up the Microsoft Entra application in Business Central
- In Business Central, search for
Microsoft Entra Applications
, open the page, selectNew
. - Fill in the
Application (client) ID
. - Enter a
Description
which becomes the user name. - Add 3 permissions by searching on
pur
:D365 FIN. & PURCH.
,D365 PURCH DOC, EDIT
,D365 PURCH DOC, POST
. - Select Grant Consent and follow the wizard.
- in Business Central, search for
Web Service
, open the page. - search for
purchaseorder
(Object ID 50) - if its not there, add a Page object with Object Id
50
and Object NamePurchase Order
and enter Service NamepurchaseOrders
- Make sure the ODdata v4 URL is generated.
You can remotely push and deploy the Tradecloud extension in your sandbox environment:
- In Visual Code: Install AL Language extension for Microsoft Dynamics 365 Business Central.
- Open the
tc-bc-app
subfolder in Visual Code. - Set
environmentName
to your sandbox environment name likeTest
in.vscode/launch.json
. - Use
F5
to deploy the extension.
Please note that after a BC version update in a sandbox environment, you need to redeploy the extension.
You can manual upload and install the Tradecloud extension in your production environment on the "Extension Management" page.