Service Installation Overview

BCCL operates in two distinct modes: as a standalone command-line tool that you run interactively, and as a Windows service that runs unattended in the background. This chapter covers everything you need to know about deploying BCCL as a Windows service so that Business Central can dispatch tasks to it automatically.

Why Run BCCL as a Service?

When you run BCCL from the command line, you execute commands one at a time, and the tool exits when the command completes. That works well for ad-hoc tasks and development, but many real-world scenarios call for unattended, continuous operation:

Scheduled data imports that run overnight without anyone logged in.
On-demand tasks triggered by Business Central users through the Service Tasks page.
Automated file processing pipelines that react to new work as it arrives.

In service mode, BCCL registers itself as a Service Agent inside Business Central. It then polls Business Central every 10 seconds, asking: "Do you have any tasks for me?" When a task is waiting, BCCL picks it up, executes it, and reports the result back to Business Central. This cycle repeats indefinitely until you stop the service.

How Service Mode Works

The mechanism that switches BCCL from interactive mode to service mode is simple:

If a file named bccl_service.json exists in the same folder as BCCL.EXE, BCCL starts in service mode.

There is no command-line flag or registry setting to toggle. You control the behavior entirely by the presence or absence of that configuration file.

When BCCL starts in service mode, it performs the following sequence:

Reads bccl_service.json to obtain connection details and authentication credentials.
Connects to Business Central using the configured authentication method.
Registers itself as an available agent, using the agentid value from the

configuration file.

Enters a polling loop, checking for assigned tasks every 10 seconds.
When a task is found, executes the requested BCCL command.
Reports the result (success or failure) back to Business Central.
Returns to polling.

Business Central users see the agent appear in the Available Agents factbox on the Service Tasks page. They can then assign tasks to that specific agent and monitor execution status directly from the Business Central interface.

How BCCL Decides Between Service Mode and Command-Line Mode

BCCL has two run modes:

Mode	How it starts	Behaviour
Service mode	`bccl_service.json` exists in the BCCL folder	Hosted, long-running. Registers as an agent, polls Business Central, stopped with Ctrl+C (console) or by stopping the Windows service.
Command-line task mode	No `bccl_service.json` in the BCCL folder	Executes the task given with `-t <task>` and its `-s`, `-o`, `-f`, `-m` parameters once, then exits.

The presence of the file bccl_service.json in the BCCL folder (the folder reported as Content root path at start-up) is the only thing that puts BCCL into service mode. When the file exists, the command-line parameters are not run, even if you pass a full -t getdata ... command; BCCL starts the service host instead and waits to be shut down.

Consequence: to execute an ad-hoc command-line task on a machine that is also set up as a BCCL service host, bccl_service.json must not be present in the folder you run the command from. Either move or rename the file out of the folder for the duration of the command (and put it back afterwards to run as a service again), or, better, keep two copies of BCCL.EXE in two separate folders: one folder with bccl_service.json for the service agent, and one folder without it for scheduled scripts and ad-hoc commands. The two copies do not interfere with each other.

Checklist item: before running an ad-hoc task, verify that no bccl_service.json exists in the BCCL folder.

How to Tell Which Mode BCCL Started In

If the console output includes the Microsoft.Hosting.Lifetime lines, BCCL is running in service mode and is not executing the command-line task:

BCCL <version>
info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0] Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0] Content root path: <BCCL install folder>

The Content root path line tells you which folder BCCL is using, that is, where to look for the bccl_service.json file that triggered service mode. A command-line task, by contrast, prints its result (or an error) and returns to the prompt. See also "A Command-Line Task Starts but Never Finishes" in Common Issues.

Do You Need Service Mode at All?

Service mode is only required if you want Business Central users to dispatch Service Tasks to an agent. If all your replication and data movement runs from scheduled scripts (.cmd/.bat files with BCCL command lines, scheduled with Windows Task Scheduler), BCCL can run purely in command-line mode and no bccl_service.json is needed. Scripts are the recommended approach for many tables, many companies, and continuous SQL synchronisation; see Service Tasks vs. Scripted Runs.

Prerequisites

Before you install BCCL as a service, make sure you have the following in place.

Windows Server

You need a Windows machine that remains running. In most environments this is a Windows Server instance, but any Windows edition that supports Windows Services will work. The machine must have network access to your Business Central instance (either on-premises or cloud).

BCCL.EXE in a Dedicated Folder

Copy BCCL.EXE to a permanent location on the server. A common convention is something like C:\BCCL&#; or C:\Program Files\BCCL&#;. Avoid placing it in a user's Downloads or Desktop folder, since those locations may be subject to cleanup policies or permission restrictions.

bccl_service.json Configuration File

This JSON file tells BCCL how to connect to Business Central and which identity to use. You create it by renaming one of the included example files and filling in your values. The file must reside in the same folder as BCCL.EXE.

Azure AD App Registration (Cloud Only)

If you are connecting to Business Central Online (SaaS), you need an Azure AD (Entra ID) App Registration configured for Service-to-Service (S2S) authentication. This provides a Client ID, Client Secret, and Tenant ID that you enter in the configuration file. On-premises deployments can use Basic authentication instead.

BCCL License Key

BCCL must be registered with a valid license key. You can register it interactively before installing the service, or include the license information in your deployment process. The service will not start successfully without a valid license.

Authentication Options

BCCL service mode supports two authentication methods:

Basic Authentication (On-Premises)

Use this when connecting to an on-premises Business Central instance. You provide a username and password (or Web Access Key) in the configuration file. This is the simpler option but is only available for on-premises deployments.

Service-to-Service Authentication (Cloud)

Use this when connecting to Business Central Online. S2S authentication uses an Azure AD App Registration with a Client ID, Client Secret, and Tenant ID. This is the recommended approach for cloud deployments because it does not depend on a user account and does not expire in the same way that user passwords do.

Service Identity in Windows

The Windows service registers under the name "BCCL Service Agent" in the Windows Services console. By default, it runs under the Local System account, but you should change this to a dedicated service account that has:

Network access to reach Business Central (or internet access for cloud instances).
File system permissions for any folders where BCCL reads input files or writes output.
SQL Server access if your tasks involve SQL replication features.

Logging

BCCL writes log entries to the Windows Event Viewer under the Application log with source name "BCCL". You can filter the Application log by this source to see only BCCL-related entries. Log entries include:

Service startup and shutdown events.
Connection status to Business Central.
Task execution results (success or failure).
Error details when something goes wrong.

If you enable the verbose option in bccl_service.json, BCCL writes additional debug-level information to the event log. This is useful during initial setup but generates a high volume of log entries, so you should disable it once everything is working.

Recommended Approach: Test Before You Install

Before registering BCCL as a Windows service, you should test it in console mode first. When you run BCCL.EXE from a command prompt with bccl_service.json present in the same directory, BCCL starts in service mode but runs interactively in the console window. You see all output directly in the terminal, which makes it much easier to diagnose connection problems, authentication errors, or configuration mistakes.

Once you have confirmed that BCCL connects to Business Central, registers as an agent, and successfully picks up and executes a test task, you can proceed to install it as a proper Windows service.

What Happens in Business Central

When a BCCL service agent connects, Business Central tracks it on the Service Tasks page:

Available Agents factbox -- Shows each connected agent by its agentid, along with

a LastSeen timestamp that updates every time the agent polls.

Agent status -- Displays either Idle (waiting for work) or Working

(currently executing a task).

Task assignment -- You assign tasks to a specific agent from the Service Tasks

page. The agent picks up the task on its next polling cycle.

Execution history -- Business Central logs the results of each task execution,

including any output or error messages returned by BCCL.

This tight integration means that Business Central users can trigger and monitor BCCL operations without ever leaving the Business Central interface.

Multiple Agents

You can run multiple BCCL service agents, each on a different machine or even on the same machine in different folders. Each agent must have a unique agentid in its bccl_service.json file. All agents appear independently in the Available Agents factbox, and you can assign different tasks to different agents based on their location, installed software, or network access.

Two facts make additional agents necessary in practice:

One agent executes only one task at a time. Tasks queued for the same agent run

sequentially. To run several operations in parallel (for example several tables at the same time), install additional agents and distribute the tasks across them.

An agent is visible in one company. The agent registers in the company set as

defaultcompany in its bccl_service.json, and tasks for it must be created in that company. To serve several companies, run one agent per company.

Next Steps

With the prerequisites in place and a clear understanding of how service mode works, you are ready to configure your bccl_service.json file and set up the connection to Business Central.