BCCL

Business Central Command Line

Change Log Tasks

The Change Log replication feature in BCCL allows you to synchronize data between Business Central and SQL Server using the Business Central Change Log as the source of truth.

This feature enables incremental replication, applying only the inserts, updates, and deletes captured in the Change Log to your target system.

Prerequisites

Before using Change Log replication, ensure that:

  • BCCL 3.0 or later is installed.

  • Change Log is enabled in Business Central for the tables you want to replicate.

  • A mapping file (JSON format) exists to define field mappings between Business Central and the destination system.

  • Destination connection (e.g., SQL, FTP) is configured in BCCL.

Mapping Files

A mapping file is a JSON document that defines how fields in Business Central correspond to fields in the destination system.

Example (customer.json):

 
{
    "Customer": [
    {
        "FieldNo": 1,
        "FieldName": "No.",
        "MappedName": "No",
        "Validate": true
    },
    {
        "FieldNo": 2,
        "FieldName": "Name",
        "MappedName": "Name",
        "Validate": true
    },
    {
        "FieldNo": 3,
        "FieldName": "Search Name",
        "MappedName": "Search_Name",
        "Validate": true
    }
        .... many more fields
    ],
    "ValidateOnInsert": true,
    "ValidateOnModify": true,
    "ValidateOnDelete": true
}

Mapping files can be:

  • Created manually.

  • Generated using available tools in BCCL.

Command Line Usage

The Change Log replication can be triggered directly from the command line.

Syntax

 
bccl -t changelog -s table=<tableId> -m <mappingFile> -o <destinationTable>

Parameters

  • -s table=<tableId>
    The Business Central table ID to replicate (e.g., 18 for Customer).

  • -m <mappingFile>
    Path to the JSON mapping file.

  • -o <destinationTable>
    Destination table name in the SQL database.

Example

 
bccl -t changelog -s table=18 -m customer.json -o Customer

This command replicates Customer table (ID 18) changes from Business Central into the Customer table in SQL Server.

Service Mode and Tasks

When running in service mode, BCCL exposes Change Log replication as service tasks.

  • Tasks can be created and managed through the Service Tasks menu.

  • Each task defines source table, mapping file, destination, and assigned agent (server).

  • Logs and execution history are stored for monitoring.

Example task:

  • Name: Customer Change Log

  • Source: Table 18 (Customer)

  • Mapping: customer.json

  • Destination: SQL → Customer table

Automations and Scheduling

Change Log replication tasks can be defined as automations for repeat execution.

  • Automations store all task settings for reuse.

  • Option to filter Change Log entries to only those since last run.

  • Can be scheduled via the Business Central Job Queue.

Example: Scheduling Every Minute

  1. Create an automation for Customer table replication.

  2. Enable “filter entries since last run.”

  3. Schedule it to run every minute.

This ensures near real-time synchronization between Business Central and the destination.

Supported Destinations

Change Log replication only supports SQL as a destination.

Logs and Monitoring

Each replication run produces a log entry containing:

  • Number of inserted, updated, and deleted records applied.

  • Number of skipped operations (e.g., attempting to delete a non-existent record).

  • Execution time and status.

Logs can be accessed:

  • From the command line output.

  • In Service Tasks or Automation history when running in service mode.

Best Practices

  • Use “filter since last run” to avoid reprocessing the entire Change Log on each run.

  • Schedule replication tasks according to your business needs (e.g., every minute, hourly, daily).

  • Periodically archive or clear the Change Log in Business Central to avoid uncontrolled growth.

  • Validate mapping files carefully to ensure field compatibility.