BCCL Documentation
Index

Request Builder Overview

The Request Builder is a graphical tool built directly into Business Central that lets you construct BCCL commands without writing a single line at the command prompt. Whether you are new to BCCL or simply prefer a visual approach, the Request Builder walks you through every option and generates a ready-to-run command for you.

Why Use the Request Builder?

Working with command-line parameters can be powerful, but it can also be error-prone. A misplaced flag or a forgotten setting can lead to frustrating debugging sessions. The Request Builder solves this by giving you:

  • A guided, two-page wizard that organizes every BCCL option into logical groups.
  • Real-time command preview so you can see the exact command line being generated as you configure each setting.
  • Downloadable script bundles containing batch, PowerShell, and Bash scripts ready for immediate use.
  • Integrated Mapping Builder for selecting, renaming, and validating fields without hand-editing JSON.
  • FilterPageBuilder for creating record filters visually instead of typing BC filter syntax.

No command-line expertise is needed. If you can fill in a form, you can build a BCCL command.

How to Access the Request Builder

  1. Open Business Central.
  2. Press Alt+Q to open the search bar (Tell Me).
  3. Type BCCL and select the BCCL page from the results.
  4. On the BCCL page, choose the Request Builder action.

The Request Builder opens as a two-page wizard inside Business Central.

The Two-Page Wizard

Page 1 -- Common Parameters

The first page contains the settings you will use in nearly every BCCL operation:

Setting Purpose
Task The operation to perform (GETDATA, PUTDATA, DELETEDATA, DELETEALL, MASSUPDATE, RUNCODEUNIT, TABLES).
Table The Business Central table to work with. You can browse a list or enter the table number directly.
View / Filter A filter expression that limits which records are affected. You can type it manually or launch the FilterPageBuilder for a visual, drag-and-drop experience.
Format The data format for the operation: JSON, CSV, XML, XLSX, or SQL.
Output / Input File The file path where data is written (export) or read from (import).
Mapping An optional mapping file that controls field selection, column renaming, and validation. You can open the integrated Mapping Builder from here.

Page 2 -- Advanced Options

The second page exposes settings that are useful in specific scenarios:

Setting Purpose
Page Size How many records to transfer per request when paging large datasets.
Binary Fields Whether to include binary (BLOB) fields such as images.
Headers Whether to include column headers in CSV output.
Delimiter The character used to separate values in CSV files.
Language A language ID that controls locale-specific formatting.
Delayed Insert An import pattern where the primary key is inserted first and then remaining fields are modified.
Excel Sheet / Range The sheet name and cell range for Excel operations.
XML Record Path The element path that identifies individual records in an XML file.
SQL Connection The connection string for direct SQL Server output.
File Storage The storage transport: local file, FTP, SFTP, or FTPS.

Real-Time Command Preview

As you change settings on either page, the Request Builder updates a live preview of the BCCL command line at the bottom of the wizard. This preview shows you exactly what will be executed, including every flag and parameter. You can copy this command directly to your clipboard for manual use.

The preview is invaluable for learning BCCL syntax. Even if you eventually move to scripting your own commands, starting with the Request Builder lets you see how each option translates to a command-line parameter.

Generating Script Bundles

Once you are satisfied with the configuration, you can download a complete script bundle as a ZIP file. The bundle contains scripts for every major platform:

  • run.cmd -- A Windows batch script.
  • run.ps1 -- A PowerShell script.
  • run.sh -- A Bash script for Linux and macOS.
  • mapping.json -- Included automatically if you configured a field mapping.

Each script contains the full BCCL command with all the parameters you selected. You can run the scripts as-is or use them as starting points for your own automation workflows.

For more details on what the bundle contains and how to customize it, see Generating Scripts.

The Integrated Mapping Builder

The Mapping Builder is accessible directly from the Request Builder. It presents all fields in the selected table and lets you:

  • Select or deselect fields to control which columns appear in the output or are expected in the input.
  • Rename columns by setting a MappedName, so external systems see friendly names instead of BC field names.
  • Set validation flags to enforce data quality rules during import.
  • Configure format strings for dates, numbers, and other formatted values.
  • Set up dimension functions such as DimensionFromSet() to extract individual dimension values from a Dimension Set ID.

The Mapping Builder writes a standard mapping.json file that BCCL consumes at runtime.

The FilterPageBuilder

Filters determine which records a BCCL operation affects. The FilterPageBuilder gives you a visual interface for creating these filters:

  • Drag and drop fields to build filter conditions.
  • Use date expressions and range operators without memorizing BC filter syntax.
  • See the resulting filter string update in real time.
  • The generated filter is automatically placed into the View/Filter field on Page 1.

This is especially helpful when you need complex multi-field filters or date-relative expressions like "this month" or "last quarter."

Typical Workflow

A typical session with the Request Builder looks like this:

  1. Open the Request Builder from the BCCL page.
  2. Select your task (for example, GETDATA to export records).
  3. Choose the table you want to work with.
  4. Optionally set a filter to limit records.
  5. Pick your output format (JSON, CSV, XML, XLSX, or SQL).
  6. Specify the output file path.
  7. Open the Mapping Builder if you need to customize field selection or renaming.
  8. Switch to Page 2 for any advanced options.
  9. Review the command preview.
  10. Copy the command or download the script bundle.

You now have everything you need to run the operation from a command prompt, a scheduled task, or an automation pipeline.

When to Use the Request Builder vs. the Command Line

Scenario Recommendation
First time setting up an export or import Use the Request Builder to explore options and generate a working command.
Building a mapping file Use the integrated Mapping Builder -- it is far easier than editing JSON by hand.
Quick one-off operation Use the Request Builder for speed and accuracy.
Automated scripts in CI/CD pipelines Start with the Request Builder, then customize the generated scripts.
Repetitive daily tasks Use the Request Builder once to generate the command, then schedule the generated script.