BCCL Documentation
Index

Managing the Service

Once you have created your bccl_service.json configuration file, you are ready to test the connection, install the Windows service, and begin running tasks. This chapter covers the full lifecycle of the BCCL service: testing, installing, configuring the service account, starting and stopping, monitoring, and upgrading.

Testing in Console Mode

Before you install BCCL as a Windows service, you should always run it interactively to verify that the configuration is correct and the connection to Business Central works.

How to Test

  1. Open a Command Prompt or PowerShell window.
  2. Navigate to the folder that contains BCCL.EXE and bccl_service.json.
  3. Run BCCL.EXE directly.

If everything is configured correctly, you will see output similar to:

BCCL vX.X.X
Application started. Press Ctrl+C to shut down.

At this point, BCCL is running in service mode but inside your console window. It is actively polling Business Central every 10 seconds for tasks assigned to its agent.

Verify the Agent in Business Central

While BCCL is running in console mode:

  1. Open Business Central and navigate to the Service Tasks page.
  2. Look at the Available Agents factbox on the right side of the page.
  3. You should see your agent listed with the agentid you configured.
  4. The LastSeen timestamp should update approximately every 10 seconds, confirming

that the agent is actively polling.

Run a Test Task

To fully validate the setup, assign a simple test task to the agent from the Service Tasks page in Business Central. Watch the console output to confirm that BCCL picks up the task, executes it, and reports the result.

Stop the Console Test

Press Ctrl+C to stop BCCL. The agent will disappear from the Available Agents factbox in Business Central after it stops polling.

Troubleshooting Console Mode

If BCCL does not start successfully, check the console output for error messages. Common issues include:

  • Authentication failure -- Verify that your credentials (username/password or client

ID/secret) are correct.

  • Connection refused -- Confirm that the URL in bccl_service.json is reachable from

this machine.

  • Invalid configuration -- Make sure the JSON file is well-formed (no trailing commas,

proper quoting) and that all required fields are present.

  • License not registered -- BCCL requires a valid license key. Register it

interactively before attempting service mode.

Only proceed to install the Windows service after you have confirmed that console mode works correctly.

Installing the Service

The BCCL installation package includes a helper script named bccl-install-service.cmd that simplifies the installation process. You can also install the service manually using sc.exe.

Using the Helper Script

  1. Locate bccl-install-service.cmd in the BCCL installation ZIP file.
  2. Open the file in a text editor.
  3. Edit the path inside the script to point to the folder where you placed BCCL.EXE.
  4. Save the file.
  5. Right-click the script and select Run as administrator.

The script uses sc.exe under the hood to create the Windows service.

Manual Installation with sc.exe

If you prefer to install the service manually, open an elevated Command Prompt (Run as administrator) and run:

sc.exe create "BCCL Service Agent" binPath= "C:\BCCL\BCCL.exe" type= share start= auto

Important: Note the spaces after binPath=, type=, and start=. These spaces are required by sc.exe syntax. Omitting them will cause the command to fail.

Adjust the path in binPath= to match the actual location of your BCCL.EXE.

What the Command Does

  • create "BCCL Service Agent" -- Creates a new Windows service with the display

name "BCCL Service Agent".

  • binPath= "C:\BCCL\BCCL.exe" -- Points to the BCCL executable.
  • type= share -- Allows the service to share a process with other services (this is

the standard type for .NET services).

  • start= auto -- Configures the service to start automatically when Windows boots.

Verify the Installation

After running the install command:

  1. Open Services (press Win+R, type services.msc, press Enter).
  2. Scroll down to find "BCCL Service Agent".
  3. Verify that the Startup Type is set to Automatic.
  4. Do not start the service yet -- first configure the service account as described

in the next section.

Configuring the Service Account

By default, a newly created Windows service runs under the Local System account. While this account has broad permissions on the local machine, it may not have the network access or specific file permissions that BCCL needs. You should configure a dedicated service account.

Changing the Log On Account

  1. Open Services (services.msc).
  2. Find "BCCL Service Agent" in the list and double-click it to open Properties.
  3. Go to the Log On tab.
  4. Select "This account" and enter the credentials of the account you want to use.
  5. Click OK.

Account Requirements

The service account must have:

  • Network access to reach Business Central. For on-premises deployments, this means

the account must be able to connect to the BC server on the Web Service port. For cloud deployments, the machine must have internet access.

  • File system permissions for any folders that BCCL tasks read from or write to. If

your tasks import CSV files from a network share or export reports to a local folder, the service account needs read/write access to those locations.

  • SQL Server access if you use BCCL's SQL replication features. The service account

(or a SQL login mapped to it) must have the appropriate database permissions.

Best Practices

  • Create a dedicated service account rather than using a personal user account. This

avoids problems when the person leaves the organization or changes their password.

  • Use a managed service account (gMSA) if your environment supports it. This

eliminates the need to manage passwords for the service account.

  • Grant least privilege -- only the permissions that BCCL actually needs.
  • If you use a domain account, ensure it has the "Log on as a service" right. Windows

typically grants this automatically when you configure it through the Services console, but some Group Policy settings may override this.

Starting and Stopping the Service

You can start and stop the BCCL service using any of the standard Windows methods.

Using the Services Console

  1. Open Services (services.msc).
  2. Find "BCCL Service Agent".
  3. Use the Start, Stop, Pause, or Restart buttons in the toolbar, or

right-click the service for the same options.

Using the Command Line

Open an elevated Command Prompt and use sc.exe:

sc start "BCCL Service Agent"
sc stop "BCCL Service Agent"

Using PowerShell

Open an elevated PowerShell prompt:

Start-Service -Name "BCCL Service Agent"
Stop-Service -Name "BCCL Service Agent"
Restart-Service -Name "BCCL Service Agent"

Automatic Startup

Because the service is installed with start= auto, it will start automatically whenever Windows boots. If the server is restarted due to Windows Updates or a power event, the BCCL service comes back online without manual intervention.

If you need to temporarily prevent the service from starting (for example, during maintenance), you can set the startup type to Manual or Disabled in the service properties, and change it back to Automatic when you are ready.

Monitoring the Service

Windows Event Viewer

BCCL writes log entries to the Windows Event Viewer. To view them:

  1. Open Event Viewer (press Win+R, type eventvwr.msc, press Enter).
  2. Navigate to Windows Logs > Application.
  3. Click Filter Current Log in the right pane.
  4. In the Event sources dropdown, select or type "BCCL".
  5. Click OK to apply the filter.

You will see log entries for:

  • Service startup and shutdown.
  • Successful connections to Business Central.
  • Task pickup and execution results.
  • Errors and warnings.

If you enabled "verbose": "true" in bccl_service.json, you will see additional debug-level entries that show each polling cycle and detailed execution steps. This is useful for troubleshooting but produces a large volume of log data, so disable it once the service is running reliably.

Business Central Monitoring

From within Business Central, you have several monitoring options:

  • Available Agents factbox -- Shows all connected agents with their agentid and a

LastSeen timestamp. If the timestamp stops updating, the agent has lost its connection or has been stopped.

  • Agent status -- Each agent shows a status of Idle (waiting for tasks) or

Working (currently executing a task). If an agent stays in the Working state for an unusually long time, the task may have encountered a problem.

  • Service Task logs -- The Service Tasks page in Business Central keeps a history of

executed tasks, including the result, any output messages, and timestamps. Use this to verify that tasks completed successfully and to investigate failures.

Health Checks

For a quick health check of your BCCL service:

  1. Confirm the service is running in services.msc.
  2. Check the Available Agents factbox in Business Central for a recent LastSeen timestamp.
  3. Review the Event Viewer for any recent errors.

Uninstalling the Service

If you need to remove the BCCL service from a machine:

  1. Stop the service first using any of the methods described above.
  2. Open an elevated Command Prompt and run:
sc.exe delete "BCCL Service Agent"

This removes the service registration from Windows. It does not delete BCCL.EXE or bccl_service.json from disk. You can remove those files manually if they are no longer needed.

Upgrading BCCL

When a new version of BCCL is released, upgrading the service is straightforward:

  1. Stop the service using the Services console, sc stop, or Stop-Service.
  2. Replace BCCL.EXE in the installation folder with the new version. You do not

need to touch bccl_service.json -- the configuration format is backward-compatible.

  1. Start the service again.

That is the complete upgrade process. No configuration changes are needed, and the agent will reconnect to Business Central with its existing agentid and settings.

Upgrade Tips

  • Check the release notes for any breaking changes before upgrading. While configuration

changes are rare, it is good practice to review what has changed.

  • If you run multiple agents, you can upgrade them one at a time to maintain availability.
  • After upgrading, check the Event Viewer and the Available Agents factbox to confirm that

the new version started successfully.

Troubleshooting Common Issues

Service Fails to Start

  • Check the Event Viewer for error details.
  • Verify that bccl_service.json is in the same folder as BCCL.EXE.
  • Confirm the service account has the necessary permissions.
  • Try running BCCL.EXE interactively in console mode to see detailed error output.

Agent Does Not Appear in Business Central

  • Verify the service is running.
  • Check that the URL and authentication credentials in bccl_service.json are correct.
  • Ensure the BCCL extension is installed in Business Central.
  • Look in the Event Viewer for connection errors.

Tasks Are Not Being Picked Up

  • Confirm the agent status shows as Idle in the Available Agents factbox.
  • Verify the task is assigned to the correct agentid.
  • Check that the LastSeen timestamp is updating (agent is actively polling).
  • Review the Event Viewer for any errors during task pickup.

Service Stops Unexpectedly

  • Check the Event Viewer for unhandled exceptions or crash reports.
  • Verify that the service account password has not expired.
  • Confirm that the Azure AD client secret has not expired (for S2S authentication).
  • Check that the Business Central instance is online and accessible.