BCCL Documentation
Index

Installation

BCCL installation involves two steps: installing the Business Central extension (app) into your BC environment, and placing the BCCL client executable on the machine where you will run commands. This page covers both steps, along with upgrade guidance.

Installing the Business Central Extension

The BCCL extension must be installed in every Business Central environment where you want to use BCCL. The installation method depends on your deployment type.

Cloud Business Central (SaaS)

To install the BCCL extension in a cloud Business Central environment:

  1. Sign in to Business Central as a user with administrative permissions.
  2. Open the Extension Management page. You can find it by pressing Alt+Q and searching for "Extension Management."
  3. Choose Manage > Upload Extension from the action bar.
  4. Select the BCCL .app file that you received from hougaard.com.
  5. Choose the appropriate deployment options:
    • Language -- select your preferred language.
    • Accept the extension terms -- review and accept.
  6. Choose Deploy to begin the installation.
  7. Wait for the deployment to complete. You can monitor progress on the Extension Management page. The status will change from "Installing" to a version number when the installation is finished.

Note: Deploying an extension in cloud Business Central may take several minutes. The environment remains usable during this process, but BCCL will not be available until the deployment completes.

On-Premises Business Central

For on-premises installations, you use PowerShell to publish and install the extension. Open a Business Central Administration Shell (PowerShell) on your BC server:

# Publish the app to the server
Publish-NAVApp -ServerInstance BC -Path "C:\path\to\hougaard_BCCL_3.0.0.0.app"

# Install the app in the target tenant
Install-NAVApp -ServerInstance BC -Name "BCCL" -Tenant default

Replace BC with your actual Business Central server instance name, and adjust the path to point to the .app file location.

If you are upgrading from a previous version, you may need to use Sync-NAVApp before installing:

# Sync the new version's schema
Sync-NAVApp -ServerInstance BC -Name "BCCL" -Tenant default

# Upgrade the data
Start-NAVAppDataUpgrade -ServerInstance BC -Name "BCCL" -Tenant default

Docker Business Central

For Docker-based Business Central environments using BCContainerHelper, use the Publish-BcContainerApp cmdlet:

# Publish and install in one step
Publish-BcContainerApp -containerName bcserver `
    -appFile "C:\path\to\hougaard_BCCL_3.0.0.0.app" `
    -install `
    -sync

Replace bcserver with the name of your Docker container.

If you are using the newer BcContainerHelper module (BcContainerHelper v6+), the syntax is the same. The -install parameter causes the app to be installed immediately after publishing, and -sync synchronizes the database schema.

For development containers where you want to skip verification:

Publish-BcContainerApp -containerName bcserver `
    -appFile "C:\path\to\hougaard_BCCL_3.0.0.0.app" `
    -install `
    -sync `
    -skipVerification

Note: Only use -skipVerification in development and testing environments. Production environments should always verify app signatures.

Verifying the Extension Installation

After installing the extension, verify that it is working:

  1. Open Business Central in your web browser.
  2. Press Alt+Q to open the search bar.
  3. Type BCCL and press Enter.
  4. The BCCL main page should open, displaying:
    • Tasks section with links to Download the BCCL Client, Request Builder, Service Tasks, and SQL Sync Bundle Builder
    • Connection and Commands section with a command hint selector
    • Resources section with links to documentation, support, and licensing

If the BCCL page appears, the extension is installed correctly.

If you see an error or the page is not found, check the Extension Management page to confirm the BCCL extension shows a version number (not "Installing" or an error status).

Installing the BCCL Client

The BCCL client requires no formal installation. It is a single self-contained executable.

Steps

  1. Obtain the client -- download the BCCL client for your platform from the link on the BCCL page in Business Central, or from hougaard.com/on-premises/BCCL. This page is the authoritative source for the newest client; beta builds are published under hougaard.com/on-premises/BCCL/beta. Because BCCL is distributed as a downloaded file that you unpack locally, it does not update itself: an installed copy stays at whatever version was downloaded.
  2. Choose a location -- copy the executable to a directory on the machine where you will run BCCL commands. Common choices:
    • C:\BCCL&#; on Windows
    • /opt/bccl/ on Linux
    • /usr/local/bin/ on macOS
  3. Verify the executable -- open a command prompt or terminal and run:
   BCCL --help

You should see the BCCL help text showing the available parameters and their descriptions.

Platform-Specific Notes

Windows:

  • The file is named BCCL.exe
  • You can add the directory to your system PATH environment variable so you can run BCCL from any location
  • No special permissions are required to run the client

macOS:

  • The file is named BCCL (no extension)
  • You may need to mark it as executable: chmod +x BCCL
  • On first run, macOS may block the executable because it is not from a verified developer. Go to System Preferences > Security & Privacy and allow it to run, or use: xattr -d com.apple.quarantine BCCL

Linux:

  • The file is named BCCL (no extension)
  • Mark it as executable: chmod +x BCCL
  • No additional libraries or dependencies are needed

File Size

The BCCL client is approximately 80 MB. This is because it is a self-contained .NET application that bundles the entire runtime and all libraries. The benefit is zero external dependencies -- you do not need to install .NET or any other framework.

Upgrading from BCCL 2.x to 3.0

If you are currently using BCCL version 2.x and want to upgrade to 3.0, follow this sequence to avoid compatibility issues:

Understanding Version Compatibility

  • The BCCL 3.0 App (Business Central extension) requires the BCCL 3.0 client. It will not work with the 2.x client.
  • The BCCL 3.0 Client is backward compatible with the BCCL 2.0 app. It can communicate with both 2.x and 3.0 extensions.

Because of this asymmetry, the safest upgrade path is:

  1. Upgrade the client first. Replace your BCCL 2.x executable with the BCCL 3.0 executable on all machines that run BCCL commands. Since the 3.0 client works with the 2.0 app, your existing operations will continue to function.
  2. Verify the client works. Run a simple test command (like -t tasks) to confirm the 3.0 client communicates successfully with your existing 2.x extension.
  3. Upgrade the BC extension. Install the BCCL 3.0 app in your Business Central environment, replacing the 2.x version. Follow the installation steps above for your deployment type.
  4. Verify the extension works. Run the same test command again to confirm everything works with both components at version 3.0.

What Changes in 3.0

The 3.0 extension enforces a minimum client build number. If you try to use an old client with the 3.0 extension, you will receive a "Version mismatch" error that tells you the expected minimum build number. This is a safety check to prevent protocol incompatibilities.

Keeping Client and Extension in Sync

BCCL consists of two components that must be version-matched: the Business Central extension installed in the BC environment, and the BCCL.EXE client installed locally or on-premises. Whenever the BC extension is updated (for example through a new app version from AppSource or an extension upgrade), re-download the newest BCCL.EXE from https://www.hougaard.com/on-premises/BCCL and update it as well.

If the two are out of sync, operations such as GETDATA fail with:

An error has occurred: Version mismatch (222 vs. 281), please update your BCCL client to match the version of the BCCL Business Central Extension installed.

The fix is always to update BCCL.EXE to the newest version on every machine, server, and scheduled job that runs the client. The two numbers in the message are internal protocol versions, not the extension's version string, so do not try to match them against the app version. The client may be newer than the extension (a newer client against an older app is supported); it may not be older than the extension requires. See Client Versions and Updates.

Deploying BCCL to an Additional Server

Use this checklist when you already have a working BCCL setup on one server and are deploying a second one (for example test to production) against the same BC tenant:

  1. Copy the BCCL executable, your batch file(s), and the mapping&#*;.mapping.json files to the new server.
  2. Verify the new server can reach check.hougaardlicense.com: run ping check.hougaardlicense.com and open the host in a browser on the server itself. A successful ping alone is not proof; if the browser cannot open the site, the block is at the HTTP/HTTPS or proxy level and must be lifted by your network administrators.
  3. Run BCCL --register <registration-key> --tenantid <tenant-id> on the new server. Put this line first in the batch file so registration is verified on every run. The registration key is issued per customer; obtain it from the license owner.
  4. Verify that the BCCL --remember ... command in the batch file is on a single, unbroken line, and update the --sqlconnect value to point at the new target SQL server, database, and credentials. Remembered parameters are stored locally, so the new server needs its own --remember run.
  5. Run the batch file and confirm that the Trial version detected, data transfers are limited to 100 records upload and 50000 bytes download. message no longer appears before running production data loads.

The Business Central tenant, environment, web service URL, and the S2S client ID and secret do not need to change when only the local target server changes. Only the local registration and the SQL connection string are machine-specific.

If the new server is also to run as a service agent, note that the agent registers in the company set as defaultcompany in bccl_service.json; see Service Configuration.

Uninstalling BCCL

Uninstalling the Extension

Cloud Business Central:

  1. Go to Extension Management.
  2. Find the BCCL extension.
  3. Choose Uninstall.

On-Premises:

Uninstall-NAVApp -ServerInstance BC -Name "BCCL" -Tenant default
Unpublish-NAVApp -ServerInstance BC -Name "BCCL"

Docker:

UnInstall-BcContainerApp -containerName bcserver -appName "BCCL"
UnPublish-BcContainerApp -containerName bcserver -appName "BCCL"

Uninstalling the Client

Simply delete the BCCL executable file. To remove stored settings and credentials, run BCCL --forget before deleting the file. Remembered settings are stored in .NET isolated storage under the user's profile in a directory named BCCL/.

Troubleshooting Installation Issues

Extension fails to deploy in cloud BC

  • Confirm you have administrative permissions in Business Central.
  • Check that the .app file is the correct version for your Business Central version.
  • Review the Extension Management page for error messages.

PowerShell commands fail for on-premises

  • Ensure you are running the Business Central Administration Shell, not a regular PowerShell window.
  • Verify the server instance name is correct.
  • Check that the .app file path is accessible from the server.

Client shows "Version mismatch" error

  • The installed client is older than the BCCL extension requires. Download the newest client from https://www.hougaard.com/on-premises/BCCL and replace BCCL.EXE on every machine that runs it. See "Keeping Client and Extension in Sync" above.

Command output shows BCCL.BigStringBuilder instead of data

  • You are running an older copy of the client. Re-download from the download page, replace the executable, and re-run the same command. See Client Versions and Updates.

Client cannot connect to Business Central

  • Verify network connectivity: can you reach the Business Central URL from the machine running BCCL?
  • Check that SOAP web services are enabled in your Business Central configuration.
  • Verify the web service URL is correct (see Initial Configuration).