Connecting Business Central on-premises
An administrator's guide to preparing an on-premises Business Central for the Magic CRM sync agent, and installing the agent on a Windows server.
Magic CRM syncs with Business Central through a small program, the sync agent, that you install inside your network. This guide is for Business Central on-premises: it runs on a server of yours or your partner’s, at an address such as https://bc.example.com/BC. For Business Central online, see Business Central online.
The agent signs in to Business Central as a Business Central user, with that user’s web service access key. Nothing has to be opened to the internet: the agent only makes outgoing HTTPS connections, to Business Central and to Magic CRM. Installed on the Business Central server itself, it needs no port opened at all. Business Central’s credentials stay in the agent’s configuration on your server; Magic CRM never sees them.
What the sync exchanges is described in What the Business Central sync sends.
Before you start
- Steps 1 to 3 are done by whoever administers the Business Central server, usually your partner, in the Business Central Administration Shell, as administrator.
BCbelow is the server instance’s name; yours may differ. - Steps 4 and 5 are done in the Business Central client, by a Business Central administrator.
- The rest needs an owner or admin of your Magic CRM organization, and an administrator of the Windows machine the agent will run on, usually the Business Central server itself.
You will end with four values: the API address (such as https://bc.example.com:7048/BC/api/v2.0), the company id, a user name and that user’s web service access key.
The agent supports single-tenant servers. If your Business Central’s web client only lets anyone in with ?tenant=… in its address, the server is multi-tenant and cannot be synced yet.
1. Check how the instance authenticates
Get-NAVServerConfiguration BC | Where-Object { $_.key -in 'ClientServicesCredentialType','ODataServicesEnabled','ApiServicesEnabled','ODataServicesPort','ODataServicesSSLEnabled','PublicODataBaseUrl' }
ClientServicesCredentialType decides everything:
NavUserPassword: continue.Windows: the agent cannot sign in this way. Do not change the type on the instance people use, since that changes how every user signs in. The usual answer is a second server instance on the same database, set toNavUserPasswordand used only by the API. That is your partner’s decision.- Anything else: stop and tell us what it is, at [YOUR SUPPORT CONTACT].
2. Switch the API on
Set-NAVServerConfiguration BC -KeyName ODataServicesEnabled -KeyValue true
Set-NAVServerConfiguration BC -KeyName ApiServicesEnabled -KeyValue true
Set-NAVServerConfiguration BC -KeyName ODataServicesSSLEnabled -KeyValue true # needs a certificate on the instance
Restart-NAVServerInstance BC
- The port is
7048unlessODataServicesPortsays otherwise. Allow it in Windows Firewall from the agent’s machine only. If the agent runs on the Business Central server itself, nothing needs opening. - Use TLS. Without it the access key crosses the network readable. The agent refuses plain HTTP to another machine unless told otherwise; plain HTTP to the same machine is allowed, which is one more reason to install the agent on the Business Central server.
- An API that is switched off answers
405.
3. Fill the API’s tables
In the Business Central client, search for API Setup and choose Integrate APIs. It runs once and can take several minutes. Until it has run, the API answers with empty lists.
4. Create the sync’s user
In the Business Central client, Alt+Q (or the magnifier) → Users → + New:
-
A user of its own, for example
CRMSYNC, not a person’s account. It needs a licence, like any user that signs in with a key. Use plain letters and digits in the name, without diacritics: the sign-in method cannot carry anything else. Give it a password, and set State to Enabled. -
Permission sets, in User Permission Sets on the same card, with Company left empty. Give only what the sync touches:
The sync Needs reads and writes customers, contacts reads, and creates when asked to items, sales quotes reads sales orders and their lines, item ledger entries For the first, read-only run:
D365 BASICandD365 READ. To let it write later:D365 BUS FULL ACCESSin place ofD365 READ, or narrower sets your partner knows the names of. A write then fails visibly in Magic CRM instead of changing a customer, and the reads are what need checking first. Nothing is ever deleted through the sync. -
Sign out, and sign in as that user. Open its own card under Users, and in Web Service Access choose Web Service Access Key → Key Never Expires (or a date you will remember) → OK. Copy the key now: to any other user it is shown as asterisks.
A lost password, the administrator’s included, can be reset from the Administration Shell: Get-NAVServerUser BC lists the users, and Set-NAVServerUser BC -UserName <name> -Password (Read-Host -AsSecureString) sets one.
5. Find the company id, and prove it works
From the machine the agent will run on (in Windows PowerShell, write curl.exe, not curl):
curl -u 'CRMSYNC:<access key>' 'https://bc.example.com:7048/BC/api/v2.0/companies'
The answer lists every company with its id. One agent syncs one company: take the id of the one to sync, and ask for a customer:
curl -u 'CRMSYNC:<access key>' 'https://bc.example.com:7048/BC/api/v2.0/companies(<id>)/customers?$top=1'
| Answer | Means |
|---|---|
200 and a customer |
Done: you have the four values |
401, Authentication_InvalidCredentials |
The user name or the key is wrong (most often the user name), or the instance is not on NavUserPassword |
405 |
Step 2 did not take, or the instance was not restarted |
200 with "value": [] |
Step 3 has not run, or the company has no customers |
| No answer | The port, the firewall or the certificate |
6. Get a pairing token
In Magic CRM, as an owner or admin: Admin → ERP, then Connect (once per organization), then Add an agent. Name it after where it runs, such as “the Business Central server”. Copy the pairing token: it is shown once, and works for one pairing only. If you lose it, revoke that agent and add another.
7. Install the agent on Windows
On a Windows machine inside the network that reaches Business Central, usually the Business Central server itself:
- On the same page, Admin → ERP, choose Download the agent for Windows. It is an MSI installer. Check it against the SHA-256 shown on the page, in PowerShell:
Get-FileHash .\<file>.msi -Algorithm SHA256. - Run the installer. It asks one thing, the port of its configuration page: 7050, unless another program already uses it.
- From the Start menu, open Configure Magic CRM Agent. Windows asks for an administrator’s permission, and the page opens in your browser, reachable from this machine only:
- Pairing: paste the token.
- The ERP: the API address, the company id, the user and its key.
- Check: both lines must show a tick.
- Leave The service stopped for now, until the checks below.
The agent is installed in C:\Program Files\Magic CRM Agent and runs as the Windows service Magic CRM Agent, which starts with Windows and is restarted if it stops. Its folder is closed to everyone but administrators and the service itself, and its secrets are encrypted so that a copy of its configuration file cannot be used on another machine.
Without a desktop, or on many servers, the installer runs silently: msiexec /i .\<file>.msi /qn (add UI_PORT=7051 for another port). Then, in an elevated PowerShell in the installed folder:
.\agent.exe pair <token> # joins this agent to your organization
.\agent.exe configure # asks for the address, company, user and key
.\agent.exe status # both lines must say ok
For a server on plain HTTP, the address can be given with flags; the key is still asked for, which keeps it out of the shell’s history:
.\agent.exe configure -allow-http -base-url http://<host>:7048/BC/api/v2.0 -company <id> -user CRMSYNC
8. Before the first sync
- Check the switches under Admin → ERP → Connection, which decide what the first sync may write:
- New companies become customers in the ERP should be off to begin with: your accountant first decides what a new customer gets in Business Central.
- Customers the ERP has and we do not become companies here is on by default: the first sync makes a company of every customer of yours that matches none in Magic CRM.
- Run one round by hand:
.\agent.exe oncein the installed folder, then look at Admin → ERP → Activity for the run and its tasks. With a read-only user in Business Central, any write the sync attempts fails, as it should. - Start it: Start on the configuration page, or
Start-Service MagicCRMAgent. Within a minute, Admin → ERP shows the agent as seen, and from then on it starts with the machine. - Customers whose name matches a company of yours wait under Admin → ERP → Waiting for you. Nothing happens to them until someone answers.
When you are satisfied with the reads, give the sync’s user the write permission sets in Business Central.
When something fails
What status, or Check on the configuration page, says when the Business Central line fails:
| Message | Means |
|---|---|
answered 401 to GET /customers |
The user or the key |
| No status at all | Business Central cannot be reached from this machine |
A task Business Central refused shows as Failed in Admin → ERP → Activity, with Business Central’s own message. A task that could not get through after five attempts is Parked. Retry puts either back.
Upgrading, stopping and removing
- Upgrade: run the new installer. The configuration and the port are kept, and the service is started again.
- Stop at any moment, with Stop on the configuration page or
Stop-Service MagicCRMAgent: nothing is lost and nothing is applied twice. Edits made in Magic CRM meanwhile wait, and go when the agent is back. - A new access key: enter it under The ERP on the configuration page.
- Remove: uninstall Magic CRM Agent from Settings → Apps in Windows. The configuration and logs are kept unless the uninstall is run with
PURGE=1. Then choose Revoke beside the agent in Admin → ERP, which ends its access at once.