Generating Scripts

Once you have configured a BCCL command in the Request Builder, you can download a complete script bundle that is ready to run on any platform. This page explains what the bundle contains, how credentials are handled, and how to customize the scripts for your automation needs.

What Is a Script Bundle?

A script bundle is a ZIP file generated by the Request Builder. It packages everything you need to execute the configured BCCL command on Windows, Linux, or macOS. You download it directly from Business Central and extract it to the machine where BCCL.EXE is installed.

Contents of the ZIP Bundle

Every script bundle contains the following files:

All three script files contain the same BCCL command with identical parameters. The only differences are shell-specific syntax such as quoting rules and line continuation characters.

Anatomy of a Generated Script

Each script follows the same structure:

1. Credential Setup

The top of the script contains commands to store credentials using --remember. This runs once to save your authentication details in BCCL's isolated storage so that subsequent executions do not require credentials on the command line.

2. The BCCL Command

The main body of the script is the complete BCCL command with all parameters you configured in the Request Builder.

3. Comments

The scripts include comments explaining each section, making them easy to understand and modify.

Credential Handling in Scripts

The generated scripts include credential setup commands appropriate to the authentication method you selected. BCCL stores credentials in Windows Isolated Storage (per-user, encrypted), so they never appear in plain text after the initial setup.

Basic Authentication

For Basic authentication, the script includes a --remember command that stores the web service URL, username, and password:

REM Store credentials (run once)
BCCL.EXE --remember --wsurl "https://businesscentral.dynamics.com/..." --user "myuser" --password "mywebserviceaccesskey"

After running this once, the credentials are saved. The main BCCL command in the script does not need to include credentials.

OAuth Device Code Flow

For OAuth authentication, the script includes the --remember command with OAuth parameters. When you run the script for the first time, BCCL will display a device code and prompt you to authenticate in a browser:

REM Authenticate with OAuth (run once, interactive)
BCCL.EXE --remember --auth OAuth --clientid "your-client-id" --tenantid "your-tenant-id" --wsurl "https://businesscentral.dynamics.com/..."

After the initial authentication, the token is cached for one hour. It is not refreshed automatically, so OAuth scripts are suitable for interactive use only; use S2S for scheduled or long-running scripts.

Service-to-Service (S2S) Authentication

For S2S authentication, the script includes client credentials. This method is fully non-interactive, making it ideal for scheduled tasks and CI/CD pipelines:

REM Store S2S credentials (run once)
BCCL.EXE --remember --auth S2S --clientid "your-client-id" --clientsecret "your-client-secret" --tenantid "your-tenant-id" --wsurl "https://businesscentral.dynamics.com/..."

S2S tokens are obtained and refreshed automatically without user interaction.

Script Examples

Windows Batch Script (run.cmd)

@echo off
REM ============================================
REM BCCL Script - Generated by Request Builder
REM ============================================

REM Step 1: Store credentials (run once, then comment out)
REM BCCL.EXE --remember --wsurl "https://bc.example.com/BC/ODataV4" --user "admin" --password "webservicekey"

REM Step 2: Execute the BCCL command
BCCL.EXE -t getdata ^
  -s table=18 ^
  -s "view=WHERE(Country/Region Code=CONST(US))" ^
  -f csv ^
  -o "C:\Data\customers.csv" ^
  -m "mapping.json" ^
  -z 500

if %ERRORLEVEL% NEQ 0 (
    echo BCCL command failed with error code %ERRORLEVEL%
    exit /b %ERRORLEVEL%
)

echo Export completed successfully.

PowerShell Script (run.ps1)

# ============================================
# BCCL Script - Generated by Request Builder
# ============================================

# Step 1: Store credentials (run once, then comment out)
# & BCCL.EXE --remember --wsurl "https://bc.example.com/BC/ODataV4" --user "admin" --password "webservicekey"

# Step 2: Execute the BCCL command
& BCCL.EXE -t getdata `
  -s table=18 `
  -s "view=WHERE(Country/Region Code=CONST(US))" `
  -f csv `
  -o "C:\Data\customers.csv" `
  -m "mapping.json" `
  -z 500

if ($LASTEXITCODE -ne 0) {
    Write-Error "BCCL command failed with error code $LASTEXITCODE"
    exit $LASTEXITCODE
}

Write-Host "Export completed successfully."

Bash Script (run.sh)

#!/bin/bash
# ============================================
# BCCL Script - Generated by Request Builder
# ============================================

# Step 1: Store credentials (run once, then comment out)
# ./BCCL --remember --wsurl "https://bc.example.com/BC/ODataV4" --user "admin" --password "webservicekey"

# Step 2: Execute the BCCL command
./BCCL -t getdata \
  -s table=18 \
  -s "view=WHERE(Country/Region Code=CONST(US))" \
  -f csv \
  -o "./data/customers.csv" \
  -m "mapping.json" \
  -z 500

if [ $? -ne 0 ]; then
    echo "BCCL command failed."
    exit 1
fi

echo "Export completed successfully."

Using the Mapping File

When you configure a field mapping in the Mapping Builder, the generated bundle includes a mapping.json file. This file defines:

• Which fields to include or exclude.
• Column renaming via MappedName.
• Validation settings for import operations.
• Format strings for dates and numbers.
• Dimension extraction functions.

The scripts reference this file with the -m mapping.json parameter, assuming the mapping file is in the same directory as the script. If you move the mapping file, update the path in the script accordingly.

Customizing Generated Scripts

The generated scripts are designed to work out of the box, but you can modify them for your specific needs:

Adding Error Handling

Expand the error-checking sections to log failures, send email notifications, or trigger retry logic.

Chaining Multiple Commands

Add additional BCCL commands to the script to perform multiple operations in sequence. For example, export from one table, then export from another:

BCCL.EXE -t getdata -s table=18 -f csv -o "customers.csv"
BCCL.EXE -t getdata -s table=27 -f csv -o "items.csv"

Typical Use Case: Bulk Work Across Many Tables and Companies

Scripts are the primary tool for bulk or repetitive administrative work: the same operation repeated across many tables, and across several companies in the same tenant. Hougaard support recommends a script for this instead of creating one Service Task per table per company, because Service Tasks are maintained individually and have no bulk-create or export/import mechanism. To target another company, change the company segment of the -w web service URL on that command line, and do not use --remember when several companies are involved. See Service Tasks vs. Scripted Runs and Replicating Multiple Companies.

Keep Each Command on One Line

Batch files execute each line separately. If a long --remember or task command is wrapped over several lines (for example by an editor that soft-wraps), the fragments run as separate commands and BCCL never sees the full command. Use explicit continuation characters (^ in .cmd, </code> in PowerShell, &#`; in Bash) as the generated scripts do, or keep the command on one line. See "Batch File Rules" in Command Reference.

SET OUTPUT_DIR=C:\Data
SET PAGE_SIZE=1000
BCCL.EXE -t getdata -s table=18 -f csv -o "%OUTPUT_DIR%\customers.csv" -z %PAGE_SIZE%