Transferring Files to an On-Premises Server

A common requirement is to get a file out of Business Central Online and onto an internal, on-premises server: an XML file for a shipping system, a print or prepress file, a report as PDF, or a data extract for a local application. This page explains what BCCL can do out of the box, what requires AL development, and how to set it up.

The Scenario

Business Central Online runs in Microsoft's cloud and has no direct access to your internal file shares. Standard Business Central can hand files to a user's browser or to SharePoint, but not to a folder on a server behind your firewall. BCCL bridges that gap: a BCCL agent running on your on-premises server connects outbound to Business Central Online, picks up tasks, and writes the resulting files to the local file system.

Nothing needs to be opened inbound in your firewall. The agent initiates all communication.

Architecture

[Business Central Online]                      [On-premises server]
        |                                              |
        |  Service Task created in BC                  |  BCCL.EXE running as a
        |  (status Ready, assigned to agent)           |  Windows service (agent)
        |                                              |
        |  <---- agent polls every 10 seconds -------- |
        |  ----- task + output payload --------------> |
        |                                              |  writes file to local disk,
        |                                              |  network share, or FTP/SFTP/FTPS

The building blocks are:

Component	Role
BCCL agent	`BCCL.EXE` installed on the on-premises server and running as a Windows service with a `bccl_service.json` configuration.
S2S authentication	The agent authenticates to Business Central Online with a Microsoft Entra app registration (client ID, client secret, tenant ID). No user needs to be signed in.
Service Task	Created in Business Central. Describes what to run and where the agent should save the output.
Output location	A path on the agent's machine (local folder or UNC share) or an FTP/SFTP/FTPS destination configured on the task.

File paths on a Service Task are always relative to the agent's machine, never to the Business Central server or to the browser session of the user who created the task. C:\Export\shipping.xml on a task means that folder on the server where the agent runs.

For the service setup itself, see Service Installation Overview and Service Configuration.

What Works Out of the Box

Two Service Task types deliver files to the on-premises server without any development.

DOWNLOAD: Run an Object and Save Its Output

A DOWNLOAD Service Task runs a Business Central Report, Codeunit, XMLport, or Query and saves the output to the Output filename configured on the task. This is the right choice when the file is produced by a Business Central object:

A report rendered as PDF, Word, Excel, or HTML.
An XMLport that writes an XML or text file (for example, a shipping or EDI file).
A query exported as CSV or XML.
A codeunit that builds a file.

The relevant fields on the Service Task Card are:

Field	Description
Object Type	Report, Codeunit, XMLport, or Query
Object ID	The ID of the object to run
Object Output Type	PDF, CSV, XML, HTML, Excel, or Word. Reports cannot be exported as CSV; Queries support only CSV or XML.
Output filename	The full path on the agent's machine where the file is saved

When you start a DOWNLOAD task, Business Central runs the object and stores the result in the task's binary payload. The agent downloads the payload on its next poll and writes it to the configured file. For reports, a request page appears when you start the task so you can set report parameters.

See the "Download Object Output" section in Creating Service Tasks for the complete field reference.

GETDATA: Export Table Data to a File

A GETDATA Service Task exports records from a Business Central table directly to a file on the agent's machine in json, xml, csv, or xlsx format, optionally filtered with a Table View and shaped with field mapping. Use this when the "file" you need is simply table data in a given format, for example an XML file of today's shipments taken from a shipment header table.

Important Limitation: Moving Existing Files Requires AL Development

Moving an existing file that already lives inside Business Central down to the on-premises server is not a built-in, configuration-only feature. This includes:

A file that Business Central currently uploads to SharePoint.
A file stored in a BLOB field.
A document attachment on a record.

To transfer such a file, custom AL code is required. The AL code must create a Service Task that carries the file (that is, populate the task's binary payload with the file content) and set the task to Ready, so that the agent can pick it up and write it to disk. This is a development task for an AL developer familiar with your extension, not a setting you can turn on.

Do not plan on any other mechanism. If your requirement is "Business Central produces a file and I want it on an internal server", the two supported paths are:

Produce the file from a Report, Codeunit, XMLport, or Query and deliver it with a DOWNLOAD task (no development needed).
Have a developer write AL that creates the Service Task with the file content as its payload.

Step-by-Step: Delivering an XMLport Output to a Local Folder

This example assumes a BCCL agent is already installed as a Windows service on the on-premises server, authenticated with S2S, and visible in the Available Agents factbox.

In Business Central, press Alt+Q, search for BCCL Service Tasks, and choose New.
Set Task ID to a short, unique code such as SHIP-XML (keep it within 20 characters).
Set Description to Shipping file to on-premises server.
Set Classification to Normal for a one-off run, or Automation if it will recur.
Set Request Task to DOWNLOAD.
Under Download Object Output, set Object Type to XMLport, Object ID to the ID of your XMLport, and Object Output Type to XML.
Set File Storage to Local files.
Set Output filename to the destination on the agent's machine, for example C:\Integration\Shipping\shipping.xml or &#\;fileserver\integration\shipping.xml. The service account of the BCCL Windows service must have write permission to that location.
Under Task Scheduling, set Agent Assigned to the agent running on the on-premises server. Create the task in the company configured as defaultcompany in that agent's bccl_service.json, otherwise the agent is not selectable.
Start the task. The agent picks it up within its next polling cycle and writes the file.
Check the task Status and, if needed, View Remote Output for the agent's log.

To deliver to an FTP, SFTP, or FTPS server instead of a local folder, set File Storage accordingly and fill in the FTP connection fields; the agent then uploads the output from its machine to the remote server.

Making the Transfer Recurring

If the file must be transferred on a schedule (for example, a shipping file every 15 minutes), turn the task into an Automation and schedule it with the Business Central Job Queue:

Set the task's Classification to Automation.
Create a Job Queue Entry with Object Type to Run = Codeunit and Object ID to Run = 80807 (BCCL Run From Job Queue).
Set the recurrence you need and set the Job Queue Entry to Ready.

Each run creates a Clone of the Automation, which the agent executes. See Automations and Scheduling for details, and keep the Task ID short enough for the 10-character clone suffix.

Tips and Best Practices

Test the path first: run a simple GETDATA task that writes a small JSON file to the target folder to confirm the agent's service account has write access.
Use a UNC path if the file must land on a different internal server than the one running the agent, and grant the service account access to the share.
Keep the agent's bccl_service.json protected; it contains the S2S client secret.
If several departments need files from different companies, remember that an agent registers in one company (defaultcompany). Run one agent per company if needed.
One agent runs one task at a time; if many file transfers must run concurrently, install additional agents.