Initial Configuration

After installing the BCCL extension and placing the BCCL client on your machine, you need to configure the connection between the two. This page walks you through the initial setup, from locating the web service URL to running your first command.

Prerequisite: before setting up a sync from a BC cloud tenant, obtain a BCCL Enduser license for that tenant (see "Which License Do I Need?" in License Terms). The same license immediately covers the sandbox and production environments of that tenant, so sandbox-based upgrade testing needs no extra purchase. You can complete the steps on this page in trial mode first.

Step 1: Open the BCCL Page in Business Central

Sign in to Business Central in your web browser.
Press Alt+Q to open the search bar.
Type BCCL and press Enter.

The BCCL main page opens, showing three sections:

Tasks -- quick links to download the BCCL client, open the Request Builder, manage Service Tasks, and run the SQL Bundle Builder
Connection and Commands -- a dropdown that generates ready-to-use command-line examples
Resources -- links to documentation on hougaard.com, support on github.com/hougaard, and license purchasing

This page is your starting point for BCCL configuration. The command hints are especially useful because they automatically include the correct web service URL for your environment.

Step 2: Locate the Web Service URL

BCCL communicates with Business Central through a SOAP web service. You need the URL of this web service.

Using the BCCL Page (Recommended)

The easiest way to get the URL is from the BCCL page:

On the BCCL page, set the Select Command dropdown to Remember a Basic Connection.
The command field below will display a complete BCCL command with the correct URL pre-filled.
The URL is the value after -w.

Finding the URL Manually

If you need to find the URL manually:

In Business Central, press Alt+Q and search for Web Services.
On the Web Services page, look for the entry with:
- Object Type: Codeunit
- Service Name: bccl
Copy the SOAP URL for that entry.

URL Format Examples

Cloud Business Central:

https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/WS/<company-name>/Codeunit/bccl

On-Premises Business Central:

https://<server>:<port>/<instance>/WS/<company-name>/Codeunit/bccl

Note: The URL contains the company name. If you need to work with a different company, you must change the company name in the URL. When using Service Tasks with the Windows service, you can use %1 as a placeholder for the company name, and it will be replaced with the company specified in the task.

Step 3: Choose Your Authentication Method

BCCL supports three authentication methods. Choose the one that matches your deployment:

Basic Authentication (On-Premises)

Best for on-premises environments and quick testing. You provide a username and password (or Web Service Access Key) directly on the command line.

BCCL -w "<url>" -u <username> -p <password> -t tasks

OAuth Authentication (Cloud)

Best for cloud environments with interactive user sessions. BCCL uses the device code flow -- it displays a code and URL, and you authenticate in your browser.

BCCL -w "<url>" --auth OAuth -t tasks

On first use, BCCL will display something like:

To sign in, use a web browser to open the page https://microsoft.com/devicelogin
and enter the code ABCD1234 to authenticate.

After you authenticate in the browser, BCCL proceeds with the command. The access token is cached for approximately 1 hour.

S2S Authentication (Automated/Cloud)

Best for scheduled operations and unattended automation in cloud environments. Requires an Azure AD / Entra ID app registration with a client ID and client secret.

BCCL -w "<url>" --auth S2S --tenantid <tenant-id> --clientid <client-id> --clientsecret <secret> -t tasks

S2S tokens are renewed automatically during a run (when the S2S parameters are on the command line), making this the recommended method for long-running or scheduled operations.

Step 4: Test the Connection

Run the tasks request type to verify that BCCL can connect to Business Central and the extension is responding:

Basic authentication example:

BCCL -w "https://api.businesscentral.dynamics.com/v2.0/abcd1234/Production/WS/CRONUS%20USA%2C%20Inc./Codeunit/bccl" -u admin@contoso.com -p MyPassword123 -t tasks

OAuth example:

BCCL -w "https://api.businesscentral.dynamics.com/v2.0/abcd1234/Production/WS/CRONUS%20USA%2C%20Inc./Codeunit/bccl" --auth OAuth -t tasks

If the connection is successful, BCCL returns a JSON response listing all available task types:

{
  "Tasks": [
    { "Task": "TASKS", "Description": "Get list of requests", "Parameters": [] },
    { "Task": "TABLES", "Description": "Find Tables", "Parameters": ["name"] },
    { "Task": "GETDATA", "Description": "Get Data from a table", "Parameters": ["table", "view"] },
    { "Task": "PUTDATA", "Description": "Insert Data into a table", "Parameters": ["table"] },
    ...
  ]
}

If you see this output, your connection is working correctly.

Troubleshooting Connection Failures

Symptom	Possible Cause	Solution
Timeout or no response	Wrong URL or network issue	Verify the URL and check network connectivity
HTTP 401 Unauthorized	Bad credentials	Check username/password; for on-premises, use Web Service Access Key
HTTP 403 Forbidden	User lacks permissions	Assign the BCCL permission set to the user
"Version mismatch" error	Client is older than the extension requires	Download the newest `BCCL.EXE` from `https://www.hougaard.com/on-premises/BCCL` and replace it on every machine; see Client Versions and Updates
Sign-in asks for admin approval (OAuth)	Admin consent not granted in the tenant	An administrator uses "Have an admin account? Sign in with that account" in the sign-in window; see OAuth Authentication
"The server has rejected the client credentials" (S2S)	BC-side enable-state bug on the Application Card	Disable, close, re-open, enable the Application Card; see Authentication Issues
"Cannot find the BCCL web service"	Web service not published	Check the Web Services page in BC for the "bccl" entry
SOAP fault	Extension error	Check the error message; often a permissions issue

Step 5: Remember Your Settings

Typing the full URL, username, and password on every command is tedious and error-prone. Use the --remember flag to save your connection settings:

For Basic auth:

BCCL -w "<url>" -u <username> -p <password> --remember

For OAuth:

BCCL -w "<url>" --auth OAuth --remember

For S2S:

BCCL -w "<url>" --auth S2S --tenantid <tenant-id> --clientid <client-id> --clientsecret <secret> --remember

BCCL responds with:

Remembering parameters:
{
  "BC_URL": "https://...",
  "BC_USER": "admin@contoso.com",
  "BC_PASSWORD": "***************",
  ...
}

After remembering, subsequent commands only need the task-specific parameters:

BCCL -t tasks
BCCL -t getdata -s table=18 -f json -o customers.json

The remembered settings are stored in isolated storage at BCCL/BCCL.Settings.json. To clear them:

BCCL --forget

Two rules for --remember: put all parameters to remember on one single command line (settings from separate --remember commands do not accumulate), and do not use it for parallel or multi-company runs, where every command should carry its own parameters. See "Rules for --remember" in Command Reference.

Step 6: Use the Command Hints

The BCCL page in Business Central provides ready-made command examples through the Select Command dropdown. These hints use your actual web service URL and username, so you can copy them directly:

Hint	Description	Generated Command
Register BCCL	Registration command template	`BCCL --register <your key> --tenantid <your tenant id>`
Remember a Basic Connection	Saves Basic auth credentials	`BCCL -w "<your-url>" -u <your-user> -p password --remember`
Remember a OAuth Connection	Saves OAuth settings	`BCCL -w "<your-url>" --auth OAuth --remember`
Remember a S2S Connection	Saves S2S credentials	`BCCL -w "<your-url>" --auth S2S --tenantid <tenantid> --clientid <clientid> --clientsecret <secret> --remember`
Your first command	Test connection with tasks	`BCCL -w "<your-url>" -u <your-user> -p <password> -t tasks`
Export data from BC	GETDATA template	`BCCL -t getdata -s Table=<TableNo> -f <format> -o <OutputFile>`
Import data into BC	PUTDATA template	`BCCL -t putdata -s Table=<TableNo> -f <format> -m <MappingFile> -i <ImportFile>`

Select a command from the dropdown, then copy the text from the command field and paste it into your command prompt or terminal. Replace the placeholder values (shown in angle brackets) with your actual values.

Step 7: Run Your First Data Command

With your connection remembered, try exporting some data:

Export Customers to JSON

BCCL -t getdata -s table=18 -f json -o customers.json

This exports all records from the Customer table (table 18) to a JSON file named customers.json.

Export Items to CSV

BCCL -t getdata -s table=27 -f csv -o items.csv

Export with a Filter

BCCL -t getdata -s table=18 "view=WHERE(Country/Region Code=FILTER(US))" -f json -o us_customers.json

View Available Tables

If you are not sure of the table number, search for it:

BCCL -t tables -s name=customer

This returns a list of tables whose names contain "customer".

Using the Request Builder

For a graphical alternative to manual command-line construction:

In Business Central, open the BCCL page.
Click Request Builder in the Tasks section.
Select the Task (GETDATA, PUTDATA, etc.).
Enter the Table No. (use the lookup to search).
Optionally set a Table View (filter).
Set the Output filename or Input filename as appropriate.
Choose the File Format.
Optionally configure a Mapping file using the Mapping Builder.
The Current Command Line field at the bottom updates in real time with the complete command.
Copy the command and paste it into your terminal.

You can also click Download Current BCCL Script to download a ZIP file containing:

run.cmd -- Windows batch file
run.ps1 -- PowerShell script
run.sh -- Linux/macOS shell script
The mapping file (if configured)

Summary of Connection Parameters

Here is a quick reference of the most common parameters for initial configuration:

Parameter	Short	Purpose
`--wsurl`	`-w`	Business Central web service URL
`--user`	`-u`	Username for Basic authentication
`--password`	`-p`	Password or Web Service Access Key
`--auth`		Authentication method: Basic, OAuth, or S2S
`--tenantid`		Azure AD tenant ID (for S2S and cross-tenant OAuth)
`--clientid`		Azure AD app client ID (for S2S)
`--clientsecret`		Azure AD app client secret (for S2S)
`--task`	`-t`	The operation to perform
`--remember`		Save all current settings for future use
`--forget`		Clear all saved settings and tokens
`--verbose`	`-v`	Show detailed debug output

Next Steps

With your connection configured and tested, you are ready to use BCCL for real data operations. Explore these topics next:

Learn about exporting data with GETDATA
Learn about importing data with PUTDATA
Set up field mapping for controlling which fields are transferred
Configure SQL Server replication for reporting and analytics
Set up Service Tasks for automated, scheduled operations