Building Commands
This guide walks you through every step of constructing a BCCL command using the Request Builder. By the end, you will know how to configure any task, apply filters, choose formats, define field mappings, and generate a ready-to-run command.
Step 1: Open the Request Builder
- In Business Central, press Alt+Q and search for BCCL.
- Open the BCCL page.
- Select the Request Builder action from the page toolbar.
The Request Builder opens as a two-page wizard.
Step 2: Select a Task
The Task field on Page 1 determines the operation BCCL will perform. Choose one of the following:
| Task | What It Does |
|---|---|
| GETDATA | Exports records from a BC table to a file or SQL database. |
| PUTDATA | Imports records from a file or SQL database into a BC table (insert or modify). |
| DELETEDATA | Deletes specific records identified by primary key values in an input file. |
| DELETEALL | Deletes all records in a table that match a filter. |
| MASSUPDATE | Applies the same set of field values to every record matching a filter. |
| RUNCODEUNIT | Executes a custom AL codeunit in Business Central. |
| TABLES | Searches for tables in BC by name or number. |
Select the task that matches your goal. The remaining fields on the page update to show only the options relevant to that task.
Step 3: Choose a Table
Enter the Table Number directly or use the lookup button to browse a list of available tables. The Request Builder displays the table name once you have selected a valid number.
If you are unsure of the table number, you can use the TABLES task first to search by name, or simply browse the lookup list and filter by name.
Step 4: Set a View or Filter
The View / Filter field restricts which records the operation affects. You have two ways to define a filter:
Manual Entry
Type a BC-style filter expression directly. For example:
WHERE(Status=CONST(Open),Posting Date=CONST(>01/01/2025))Using the FilterPageBuilder
Click the FilterPageBuilder action to open a visual filter editor. The FilterPageBuilder lets you:
- Select fields from the table and add them as filter conditions.
- Choose operators such as equals, greater than, less than, range, and contains.
- Use date expressions like
TODAY,WORKDATE,CM(current month), or relative expressions. - Drag and drop conditions to reorder them.
- Preview the filter string as you build it.
When you close the FilterPageBuilder, the generated filter expression is automatically placed into the View / Filter field.
The FilterPageBuilder is especially helpful for complex filters involving multiple fields or date-relative logic.
Step 5: Choose a Format
The Format field determines how data is structured for export or import. Select one of:
| Format | Best For |
|---|---|
| json | Web APIs, JavaScript applications, general-purpose interchange. |
| csv | Spreadsheets, flat-file integrations, simple tabular data. |
| xml | Enterprise integrations, legacy systems, SOAP-style workflows. |
| xlsx | Direct Excel workbook output, human-readable reports. |
| sql | Streaming data directly into a SQL Server database. |
BCCL auto-detects the format from the file extension if you do not specify it explicitly. For example, a file named customers.csv automatically uses CSV format.
Step 6: Set the Output or Input File Path
Depending on the task:
- Export tasks (GETDATA): Set the Output File path where the exported data will be written. For example:
C:\Data\customers.json. - Import tasks (PUTDATA, DELETEDATA): Set the Input File path pointing to the file containing data to import. For example:
C:\Data\new_items.csv.
If you leave the output path empty for a GETDATA task, the data is written to the console (standard output), which is useful for piping into other tools.
For remote file storage, configure the File Storage setting on Page 2 to use FTP, SFTP, or FTPS instead of local files.
Step 7: Configure Format-Specific Options
Each format has additional options you may need to set. These are found on Page 2 of the wizard.
XML Options
| Option | Description |
|---|---|
| Record Element Path | The XML element path that identifies each record node. BCCL needs this to locate individual records within the XML structure. Set with the -r parameter. |
Excel Options
| Option | Description |
|---|---|
| Sheet Name | The name of the Excel worksheet to read from or write to. |
| Data Range | The cell range containing data, using two-dot notation (for example, A1..H100). Note that BCCL uses two dots (..) rather than the Excel colon (:) to separate the range boundaries. |
SQL Options
| Option | Description |
|---|---|
| Connection String | A standard SQL Server connection string, for example: Server=myserver;Database=mydb;Trusted_Connection=True; |
| Pre-Command | An optional SQL statement to execute before the data operation begins (for example, TRUNCATE TABLE staging). |
| Zero Date | The date value to use in place of BC's empty date (0D). Defaults to 1900-01-01. |
CSV Options
| Option | Description |
|---|---|
| Delimiter | The character separating values. Defaults to comma (,). Use semicolon (;) for European locales or tab for TSV files. |
| Quote Character | The character used to wrap values containing the delimiter. Defaults to double quote ("). |
| Headers | Whether to include a header row with column names. Enabled by default. |
Step 8: Open the Mapping Builder
The Mapping Builder lets you control exactly which fields are included in the operation and how they are handled. Click the Mapping Builder action to open it.
Selecting and Deselecting Fields
The Mapping Builder shows every field in the selected table. Check or uncheck fields to include or exclude them. Only selected fields will appear in the exported data or be expected in the imported data.
Renaming Columns (MappedName)
Each field has a MappedName property. By default this matches the BC field name, but you can change it to anything. When exporting, the MappedName becomes the column header. When importing, BCCL matches incoming column headers to MappedName values.
This is useful when integrating with external systems that expect specific column names.
Setting Validation Flags
For import operations, you can enable validation on individual fields. When validation is enabled, BCCL triggers BC's field validation logic (the same logic that runs when a user enters a value on a page). This ensures business rules are enforced during import.
Configuring Format Strings
You can specify a format string for date, time, and numeric fields. This controls how values are formatted in the exported data or how they are parsed during import.
Setting Up Dimension Functions
If the table contains a Dimension Set ID field, you can use the DimensionFromSet() function to extract individual dimension values. For example, you can create a mapped column that extracts the "Department" dimension from the Dimension Set ID.
Saving the Mapping
When you close the Mapping Builder, the mapping configuration is saved. If you generate a script bundle, the mapping is included as a mapping.json file in the ZIP.
Step 9: Configure Advanced Options
Page 2 of the wizard contains advanced settings for specialized scenarios:
| Option | Description |
|---|---|
| Page Size | The number of records transferred per web service call. Smaller values reduce memory usage; larger values improve throughput. Default is 1000. |
| Binary Fields | Include BLOB fields (images, attachments) in the transfer. Disabled by default because binary fields significantly increase data volume. |
| Headers | Include column headers in CSV output. Enabled by default. |
| Delimiter | The CSV field separator character. |
| Language | A language ID that controls locale-specific formatting of dates and numbers. Use 0 for the default BC language. |
| Delayed Insert | An import pattern where BCCL assigns all mapped field values first and delays the Insert() until the record is complete (by default it inserts after assigning only the primary key, then assigns the rest). Required for tables whose OnInsert trigger needs a non-primary-key field to be filled. |
Step 10: Preview the Generated Command
At the bottom of the wizard, the Command Preview area shows the complete BCCL command line that corresponds to your current configuration. This preview updates in real time as you change any setting.
Review the preview to verify that all parameters look correct. The preview is the exact command that BCCL.EXE will execute.
Example preview:
BCCL.EXE -t getdata -s table=18 -s "view=WHERE(Country/Region Code=CONST(US))" -f csv -o "C:\Data\customers.csv" -m "C:\Data\mapping.json" -z 500Step 11: Copy or Download
You have two options for using the generated command:
Copy to Clipboard
Click Copy Command to place the full command line on your clipboard. You can paste it into a command prompt, a script file, or a task scheduler configuration.
Download Script Bundle
Click Download Script Bundle to generate and download a ZIP file containing complete scripts for Windows (batch and PowerShell) and Linux/macOS (Bash). Each script includes the BCCL command plus any necessary setup such as credential configuration.
The bundle also includes a mapping.json file if you configured a field mapping.
For more details on what the script bundle contains, see Generating Scripts.
Tips for Building Commands
- Start simple. Get a basic GETDATA working before adding filters, mappings, and advanced options.
- Use the FilterPageBuilder for anything beyond a single-field filter. It prevents syntax errors.
- Preview often. The command preview catches mistakes before you run anything.
- Generate a mapping even for exports. It gives you control over column order and naming.
- Test with a small page size (for example, 10) when developing a new command. Increase it once everything works.