Service Configuration

The BCCL service reads all of its connection and authentication settings from a single JSON file named bccl_service.json. This file must be placed in the same folder as BCCL.EXE. If the file is missing, BCCL starts in interactive command-line mode instead of service mode.

This chapter walks you through every field in the configuration file, provides complete examples for both authentication methods, and covers common configuration scenarios.

Creating the Configuration File

The BCCL installation package includes two example files:

bccl_service.example_s2s_auth -- Template for Service-to-Service authentication

(cloud deployments).

bccl_service.example_basic_auth -- Template for Basic authentication (on-premises

deployments).

To create your configuration:

Choose the example file that matches your authentication method.
Copy or rename it to bccl_service.json.
Open the file in a text editor and fill in your values.
Save the file in the same folder as BCCL.EXE.

Important: The file must be named exactly bccl_service.json. Any variation in the name (capitalization differences, extra extensions, etc.) will cause BCCL to ignore it.

Configuration Fields Reference

The following table describes every field that you can include in bccl_service.json.

Field	Description	Required
`agentid`	A unique identifier for this service agent. This is the name that appears in the Available Agents factbox in Business Central. Use a short, descriptive string such as `"MY_BCCL"` or `"WAREHOUSE_AGENT"`.	Yes
`auth`	The authentication method to use. Set to `"basic"` for Basic authentication or `"S2S"` for Service-to-Service authentication.	Yes
`url`	The Web Service URL for your Business Central instance. The exact format depends on whether you are connecting to an on-premises or cloud deployment. See the URL format section below.	Yes
`defaultcompany`	The name of the Business Central company the agent connects to and registers itself in. This must match the company name exactly as it appears in Business Central. In a tenant with multiple companies, the agent appears in the Available Agents factbox only in this company, and Service Tasks assigned to the agent must be created in this company (see "Company Scope" below).	Yes
`verbose`	Set to `"true"` to enable detailed debug logging, or `"false"` to use normal logging. Defaults to `"false"` if omitted.	No
`user`	The username for Basic authentication. Only used when `auth` is set to `"basic"`.	Basic auth only
`password`	The password or Web Access Key for Basic authentication. Only used when `auth` is set to `"basic"`.	Basic auth only
`clientid`	The Application (Client) ID from your Azure AD App Registration. Only used when `auth` is set to `"S2S"`.	S2S auth only
`clientsecret`	The Client Secret value from your Azure AD App Registration. Only used when `auth` is set to `"S2S"`.	S2S auth only
`tenantid`	Your Azure AD (Entra ID) Tenant ID. Only used when `auth` is set to `"S2S"`.	S2S auth only

S2S Authentication Configuration (Cloud)

Use Service-to-Service authentication when connecting to Business Central Online. This is the recommended approach for cloud deployments because it uses an Azure AD App Registration rather than a user account, making it more reliable for unattended operation.

Prerequisites for S2S

Before you configure S2S authentication, you need:

An Azure AD App Registration in the same tenant as your Business Central

environment.

A Client Secret generated for that App Registration.
The App Registration must be granted the appropriate API permissions for Business

Central.

The App Registration must be registered in Business Central under *Azure Active

Directory Applications** with the correct permissions assigned.

S2S Configuration Example

{
    "agentid": "MY_BCCL",
    "auth": "S2S",
    "clientid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "tenantid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "clientsecret": "your-client-secret-here",
    "url": "https://api.businesscentral.dynamics.com/v2.0/{tenantid}/{environment}/WS/{company}/Codeunit/bccl",
    "defaultcompany": "CRONUS Canada, Inc.",
    "verbose": "true"
}

S2S Field Details

agentid -- Set this to a meaningful name that identifies this particular agent.

If you run multiple agents, each must have a unique agentid.

auth -- Must be set to "S2S" (case-sensitive).
clientid -- Find this on the Overview page of your App Registration in the

Azure portal. It is labeled "Application (client) ID".

tenantid -- Also on the Overview page of your App Registration, labeled

"Directory (tenant) ID".

clientsecret -- Found under Certificates & secrets in your App Registration.

Copy the secret Value, not the Secret ID. Note that client secrets expire; set a reminder to rotate them before expiry.

url -- The Web Service endpoint for Business Central Online. Replace

{tenantid} with your actual tenant ID, {environment} with your environment name (e.g., Production or Sandbox), and {company} with the URL-encoded company name.

defaultcompany -- The company name as it appears in Business Central. This value

is used when no company is specified in a task.

verbose -- Set to "true" during initial setup to get detailed logging. Change

to "false" for production use.

Basic Authentication Configuration (On-Premises)

Use Basic authentication when connecting to an on-premises Business Central instance. This method uses a username and password (or Web Access Key) and is simpler to set up than S2S, but is only available for on-premises deployments.

Prerequisites for Basic Auth

A Business Central user account with the appropriate permissions.
If your on-premises instance uses Windows authentication by default, the user must

have a Web Access Key configured, or the server must be configured to accept Basic authentication.

The Business Central Web Service endpoint must be accessible from the machine running

BCCL.

Basic Auth Configuration Example

{
    "agentid": "REMOTEBCCL1",
    "auth": "basic",
    "url": "http://bc22:7047/BC/WS/%1/Codeunit/bccl",
    "user": "admin",
    "password": "YourPasswordHere",
    "defaultcompany": "CRONUS Canada, Inc.",
    "verbose": "true"
}

Basic Auth Field Details

agentid -- A unique name for this agent, just as with S2S configuration.
auth -- Must be set to "basic" (case-sensitive).
url -- The Web Service URL for your on-premises Business Central instance. The

format follows the pattern http://{server}:{port}/{instance}/WS/%1/Codeunit/bccl. Note the %1 placeholder, which is explained below.

user -- The username for authentication. This is typically the Business Central

username, not a Windows login.

password -- The password or Web Access Key associated with the user account.
defaultcompany -- The company name as it appears in Business Central.
verbose -- Same as for S2S: "true" for debug logging, "false" for production.

Understanding the URL Placeholder

In Basic authentication configurations, you will notice that the URL contains %1 instead of a literal company name:

http://bc22:7047/BC/WS/%1/Codeunit/bccl

At runtime, BCCL replaces %1 with the value of the defaultcompany field (properly URL-encoded). This keeps the URL template clean and makes it easy to change the target company without editing the URL itself.

For S2S configurations, you typically embed the company name directly in the URL using the {company} placeholder notation, since the URL structure for Business Central Online is different.

Security Considerations

The bccl_service.json file contains sensitive credentials -- either a username and password, or a client secret. You should protect this file accordingly:

Restrict file permissions so that only the Windows service account and

administrators can read it.

Do not commit this file to version control.
Rotate credentials periodically, especially Azure AD client secrets that have

expiration dates.

Use a strong password or Web Access Key for Basic authentication.
Limit the BC user permissions to only what BCCL needs. Do not use an administrator

account if a more restricted account would suffice.

Company Scope of an Agent

The agent registers its Service Agent record in the company named in defaultcompany. In a tenant with multiple companies this has two practical consequences:

The agent is listed in the Available Agents factbox only when you are working in that

company.

Service Tasks assigned to that agent must be created in that company. Selecting the agent

from another company fails with "The field Agent Assigned in table Service Task Hgd contains a value (<AGENTID>) which cannot be found in the related table (BCCL Service Agent)". See "Errors When Assigning an Agent" in Running and Monitoring Tasks.

If you need agents in several companies, run one agent per company, each in its own folder with its own bccl_service.json, a unique agentid, and the relevant defaultcompany, as described in the next section.

Running Multiple Agents

If you need to run more than one BCCL service agent (for example, one agent per warehouse location, one agent per company, or separate agents for different Business Central environments), you can set up multiple instances. Additional agents are also how you run tasks in parallel, because one agent executes only one task at a time:

Create a separate folder for each agent (e.g., C:\BCCL\Agent1&#;,

C:\BCCL\Agent2&#;).

Copy BCCL.EXE into each folder.
Create a bccl_service.json in each folder with a unique agentid.
Install each one as a separate Windows service with a distinct service name.

Each agent operates independently, polling Business Central on its own schedule and executing only the tasks assigned to its specific agentid.

Validating Your Configuration

Before installing BCCL as a Windows service, always test the configuration by running BCCL.EXE interactively from a command prompt. If the configuration file is valid and the connection succeeds, you will see a startup message confirming the version and a notification that the application has started. If there is a problem, the error message in the console output will help you identify the issue.

Common configuration mistakes include:

Incorrect company name -- The defaultcompany value must match exactly, including

capitalization and punctuation.

Wrong company for the tasks -- The agent only appears, and can only be assigned, in

the company named in defaultcompany. Switch Business Central to that company before looking for the agent or creating tasks.

Wrong URL format -- On-premises and cloud URLs have different structures. Double-

check that you are using the correct template.

Expired client secret -- Azure AD client secrets have expiration dates. If your

agent suddenly stops connecting, check whether the secret has expired.

Firewall blocking access -- Ensure that the machine running BCCL can reach the

Business Central Web Service endpoint on the required port.

Missing BCCL extension -- The BCCL extension must be installed in Business Central

for the Web Service endpoint to exist.