Skip to content

Print Service – Setup

Step-by-step guide to setting up the merchantCENTRAL Print Service: from the license and the installation of the local print service to the connection to Business Central and your first test print.

Architecture overview

Business Central (Cloud) cannot communicate directly with local printers. MC.PrintService is a lightweight local application on the customer's premises that receives print jobs and forwards them to Windows or Zebra printers.

┌──────────────────┐   Print job       ┌──────────────────┐   PDF / ZPL    ┌──────────────┐
│ Business Central │ ────────────────► │  MC.PrintService │ ─────────────► │   Printer    │
│   (Cloud/SaaS)   │                   │  (on-premises)   │                │ Windows/Zebra│
└──────────────────┘                   └──────────────────┘                └──────────────┘

There are three transport modes for the path from BC to MC.PrintService. They are chosen per printer (field Transport Mode on the printer card) and can be mixed.

Direct Push (default) Relay (Azure Queue) Poll (Azure Queue)
How it works BC calls the service directly via its fixed public address BC puts the job into a queue in the customer's Azure The Azure Function fetches the jobs from BC; BC stays passive
Inbound port forwarding required not required not required
Fixed public IP required not required not required
HTTPS certificate self-managed not needed not needed
BC makes outbound calls yes yes (job incl. label) no (only a short wake-ping)
Customer's Azure subscription no yes (a few euros/month) yes (a few euros/month)

Which mode should I choose?

Direct Push is the default and the best choice for most customers: no additional costs, immediate status feedback, simple. It requires a fixed public IP and the ability to open a port. Relay and Poll are for customers without a fixed IP or without inbound port forwarding. The difference: with Relay, BC actively puts the job into the customer's Azure; with Poll, BC stays fully passive and the Function fetches the jobs – ideal when BC must not make outbound web service calls.

Where does the print data go?

Print data never passes through ALTENBRAND infrastructure: with Direct Push it goes straight from Business Central to MC.PrintService, with Relay and Poll it runs through the customer's own Azure subscription.

Prerequisites

  • [ ] merchantCENTRAL Hub – installed and set up
  • [ ] Print Service App – installed (AppSource or deployed by ALTENBRAND)
  • [ ] Module license – at least a demo license for PRINTSERVICE
  • [ ] Windows machine on the customer's network that runs continuously and can reach the printers: Windows 10 version 1903 or later, Windows 11, or Windows Server 2022 or later, with administrator rights for the installation. Windows Server 2016/2019: only with the ZIP package (Option B)
  • [ ] Printer – Windows printer driver (for PDF) or Zebra printer reachable via TCP/IP on the local network (for ZPL)
  • [ ] For Direct Push additionally: fixed public IP and access to the router/firewall
  • [ ] For Relay/Poll additionally: a customer Azure subscription (details in Part B)

Step 1: Activate license and module

As with the other merchantCENTRAL modules, license and switching on run through the central hub card Extension of the module.

  1. In BC, search for merchantCENTRAL Setup → Extensions section → row Print Service → action Set Up (clicking the name opens the dashboard instead). The hub card Extension opens; its License part shows the license status. The Print Service is listed there right after the installation: when merchantCENTRAL Setup opens, the Hub registers newly installed modules.
  2. Register Demo (action in the License part) unlocks a demo license; Refresh License queries the license server again. With a demo, the part also shows Demo Status (days remaining) and Demo Expiry.
  3. In the General group of the same card, switch on Enabled. The Hub then checks the license and offers the demo registration.

Nothing is printed automatically until the module is switched on

License and switching on are two separate steps. As long as the module is not switched on, the Print Service queues neither shipping labels nor reports from posting. The Dashboard names this reason in its notice banner.

Setup Wizard

The assisted setup Set up the merchantCENTRAL Print Service (under Assisted Setup, also available as the Setup Wizard action in the action menu of the Print Service Settings) guides you through the next steps: downloading the print service, creating the first printer (with a connection test for Direct Push) and switching on automatic printing.

Step 2: Install MC.PrintService

The local print service is installed once on a machine in the customer's network that runs continuously and can reach the printers. With Relay and Poll, the same installation also works in agent mode (see Part B).

  1. In BC, open the Print Service Settings (action menu of the part, group Installation) or a Printer Card → action Download Print Service. The download page is pre-filtered to the versions that match your installation.
  2. Start the installation with the Windows App Installer. The Windows service merchantCENTRAL Print Service (service name MCPrintService, account LocalSystem, automatic start) is set up, started, and kept up to date automatically.
  3. On that machine, open the configuration UI http://localhost:5049/config – in a browser or in BC with the Open Local Configuration action – and put the API key on the clipboard with Copy. It is never shown. It is generated automatically on first start and is needed in BC for Direct Push.

The service creates the inbound firewall rule for the print port itself on first start.

Option B – ZIP package with Install.bat

If ALTENBRAND has provided you with a ZIP package (also for Windows Server 2016/2019, where the MSIX installation does not run):

  1. Extract the ZIP package.
  2. Double-click Install.bat → confirm the User Account Control prompt.
  3. The script (install.ps1) sets up the Windows service merchantCENTRAL Print Service (service name MC.PrintService) with automatic start and the firewall rule. It does not show the API key but puts it on the clipboard – paste it in BC (A4). Later, the configuration UI copies it again at any time with Copy.

Ports and API key

Port Purpose Reachable
5050 Print API for Business Central from the network – every call except /health requires the API key
5049 Configuration UI http://localhost:5049/config only locally on the machine itself

The configuration UI (in the merchantCENTRAL layout, in German and English) shows:

  • the service status and version,
  • whether an API key is configured – never the key itself. Copy puts it on the clipboard; Regenerate creates a new one, puts it on the clipboard as well and invalidates the old one at once – replace it in BC afterwards,
  • the agent mode for Relay/Poll with the queue the service reads,
  • the installed Windows printers and a ZPL connection test,
  • setup hints for Business Central.

No API key, no print API

Without a configured API key, the print API rejects every request except /health – from Business Central and from the machine itself alike. Regenerate creates one. Relay and Poll printers do not need the key.

Configuration file

Settings and the API key are stored in %ProgramData%\merchantCENTRAL\PrintService\appsettings.json (readable only by SYSTEM and administrators). All settings: MC.PrintService – Reference.

Part A: Set up Direct Push

With Direct Push, Business Central reaches MC.PrintService via the customer's fixed public IP. Three layers of protection secure access: API key, HTTPS, and a firewall restriction to Business Central.

A1 – Provide HTTPS

Business Central (Cloud) sends print jobs from the Azure data center and validates the server certificate. Self-signed certificates do not work. Choose one option:

Option Description Suitable for
Reverse proxy (recommended) Caddy, nginx, or IIS in front of the service, subdomain per customer (e.g. print.customer.com → fixed IP), automatic Let's Encrypt certificate most customers with their own domain
Let's Encrypt IP certificate Certificate directly on the IP address (short-lived, automatic renewal via ACME) customers without a domain
Kestrel with PFX HTTPS directly in the service: Kestrel:Endpoints:Https in appsettings.json with the certificate path simple setups with an existing certificate

Reverse proxy with Caddy

Caddy obtains and renews Let's Encrypt certificates fully automatically. A minimal Caddyfile is: print.customer.com { reverse_proxy localhost:5050 }.

Publish only the print port

Forward port 5050 only. The configuration UI (port 5049) must never be published through the proxy or the firewall.

A2 – Set up port forwarding

In the router/firewall, forward the public HTTPS port (e.g. 443) to the machine running MC.PrintService (port 5050 or the port of the reverse proxy).

A3 – Restrict the firewall to Business Central

To prevent the forwarded port from being open to the entire internet, restrict inbound access to the IP addresses of Business Central. These are grouped in the Azure service tag Dynamics365BusinessCentral (maintained automatically by Microsoft).

A4 – Create the printer in Business Central

  1. In BC, search for Printers (Print Service) → New.
  2. Leave Transport Mode at Direct Push.
  3. Fill in the fields:
Field Value
Code Unique identifier, e.g. PDF-OFFICE or ZPL-WH1
Description Descriptive name
Service URL Public HTTPS URL of the service, e.g. https://print.customer.com (for local tests http://localhost:5050)
API Key Click the field → paste the API key copied in step 2 (Ctrl+V). It is stored encrypted; the field only shows Configured or Not configured
Printer Name For PDF: exact Windows printer name. For ZPL: IP address of the Zebra printer
Print Method PDF (Windows printer) or ZPL (Zebra thermal printer)
ZPL Port ZPL only: TCP port (default 9100)

HTTPS required for remote addresses

The Service URL must use https://. http:// is only allowed for localhost/127.0.0.1 (local tests) and is rejected for remote addresses.

A5 – Test the connection

On the Printer Card, run the Test Connection action. If successful, the Status changes to Online. Then trigger a test print (see Print Queue).

Error Cause Solution
Status Offline Service not reachable Check port forwarding, reverse proxy, service status
Status Error, HTTP 401 API key missing or wrong Get it with Copy in the configuration UI and paste it again in the API Key field on the printer card
Certificate error Invalid or self-signed certificate Use a valid certificate (Let's Encrypt)

Part B: Relay and Poll (Azure)

With Relay and Poll, the customer runs the intermediary components in their own Azure: an Azure Function on the Flex Consumption plan, a Service Bus with the queue print-jobs (with several printing computers, additionally one queue print-jobs-<agent> per computer, see Several computers), and a storage account for the labels. MC.PrintService runs in agent mode and holds only an outbound connection (AMQP over WebSockets, port 443) – no port forwarding, no fixed IP, no certificate of your own.

  • Relay: BC puts the job into the queue via the Function.
  • Poll: The Function fetches the jobs from BC – at once after a short wake-ping from BC, otherwise on its timer (every 5 minutes by default). A Poll deployment serves exactly one company.

In both modes, the Function reports the print result back to BC; the job changes from Sending to Printed or Failed.

Procedure in brief

  1. Provision the Azure resources: In the Print Service Settings (action menu of the part, group Installation), run the Set up Relay/Poll in Azure action. It shows the values for bcCompanyId and bcEnvironmentUrl already filled in and opens the Azure portal with the template ("Deploy to Azure"). The Function code comes with the template. For Poll, set the parameter enablePoll = true; with several printing computers, also agentNames (see Several computers).
  2. Grant access to Business Central: The script grant-bc-access.ps1 (e.g. in Azure Cloud Shell) assigns the app role API.ReadWrite.All of "Dynamics 365 Business Central" to the Function's managed identity and outputs its client ID. Enter it in BC under Microsoft Entra Applications (state Enabled) and assign the permission set ALN MCPS Relay API (Relay only) or ALN MCPS Poll API (Poll, also covers Relay) – in every company with Relay or Poll printers. Further permission sets such as D365 AUTOMATION are not needed: both sets include D365 Basic - Read.
  3. Retrieve the keys: Function key (Function App → App keys → default) and the listen connection string of the queue (print-jobs → Shared access policies → AgentListen). With several computers, each computer needs the listen connection string of its own queue print-jobs-<agent>.
  4. Configure the BC side:
    • Relay: On the printer card, Transport Mode = Relay (Azure Queue), Relay Function URL = base URL of the Function App, click Relay Function Key and enter the Function key.
    • Poll: On the printer card, only Transport Mode = Poll (Azure Queue), printer name and print method. The Azure connection is stored once centrally in the Print Service Settings in the Poll Connection (Azure) group (Poll Function URL, Poll Function Key). This wake-ping is required in production: without it, BC stays fully passive and Poll only prints every 5 minutes, on the Function's timer. The Test Poll Connection action checks URL and key and shows the Function's answer.
    • Several computers: also set the Agent field on the printer card (see Several computers).
  5. Switch on agent mode: In the appsettings.json of MC.PrintService, fill in the Relay section (Enabled, listen connection string, status URL and Function key; with several computers also QueueName) and restart the service. See MC.PrintService – Reference.
  6. Test: Print a label on the Relay or Poll printer. Flow: Sending → the agent prints → Printed. With Poll and no wake-ping, it can take until the next timer run.

Do not grant consent

Do not run the Grant Consent action on the Microsoft Entra Applications page: a managed identity has no app registration, and Entra answers with AADSTS1003031. grant-bc-access.ps1 has granted the consent already – the script points this out itself at the end.

Detailed instructions

All template parameters and outputs, costs, updates and troubleshooting for Relay and Poll are described in the Print Service Installation and User Manual (chapters 7 and 8).

Customer firewall

The agent only needs outbound port 443 to *.servicebus.windows.net. No inbound port forwarding is needed.

Several computers

One computer in agent mode is often enough, as long as it reaches every printer: the service addresses ZPL printers by their IP address on the network, only PDF printers have to be installed on the computer as Windows printers. When several computers print on different printers – say one in the warehouse for the labels and one in the office for the delivery notes – each computer gets a queue of its own:

  1. Deployment: Enter the names of the computers in the parameter agentNames, e.g. ["LAGER","BUERO"], and deploy the template (again) into the same resource group. For every name, the queue print-jobs-<name> is created in lower case with its own listen rule AgentListen. Letters, digits and - _ . are allowed, at most 20 characters.
  2. Each computer: In appsettings.json, Relay:QueueName = print-jobs-lager and as Relay:ServiceBusConnectionString the listen connection string of this queue. Status URL and Function key are the same for all computers. The configuration UI shows the queue under Relay / Poll.
  3. Printer card: Field Agent = LAGER on every printer this computer prints for (group Relay (Azure Queue) or Poll (Azure Queue)). Printers without an agent keep using the default queue print-jobs.

Why not all computers on one queue?

Several agents on the same queue share the jobs: each job goes to the agent that picks it up first. If the printer is missing there, the job fails ("Printer … is not installed on the print service machine "). Nothing is ever printed twice, but a seemingly random part is not printed at all. Identically set up computers – all of them have all printers – may share one queue.

Agent without a queue

If a printer names an agent for which the deployment has no queue, the job fails at once: "No queue for print agent …". Once the agent is added to agentNames and the template is deployed again, Retry prints it.

Check the print queue

The Print Service prints new print jobs immediately: every new job – from a posting, a shipping label, printing by hand or a retry – starts a background task that renders and sends it seconds after the commit, never inside the posting itself. In addition, the app creates a job queue entry that runs the print queue every 5 minutes. It is the safety net: it sends retries once their delay has passed and takes the jobs a task did not reach.

Whether it is scheduled is shown in the Print Service Settings in the Print Queue field of the Maintenance group (Scheduled or Not scheduled - no retries). If it is not scheduled, run the Restart Print Queue action.

Troubleshooting

A detailed overview can be found in MC.PrintService – Reference.

Quick check on the machine running the print service:

  1. Service running? → services.msc → "merchantCENTRAL Print Service" must show Running. The service name (e.g. for Get-Service) is MCPrintService (MSIX) or MC.PrintService (ZIP).
  2. Reachable? → http://localhost:5050/health in the browser (or the Check Local Print Service action in BC) → shows the status page "The print service is running".
  3. Printers visible? → http://localhost:5049/config lists the installed Windows printers.
  4. API key configured? → The configuration UI shows at the top whether a key is configured (never the key itself).

The Open Local Configuration and Check Local Print Service actions (Print Service Settings and printer card, group Installation) only work on the computer where the service is installed.

Next Steps