BCCL Documentation
Index

Service Tasks Overview

Service Tasks let you create, configure, run, and monitor BCCL data operations entirely from within the Business Central user interface. Instead of constructing command-line arguments and running BCCL.EXE manually, you define tasks inside Business Central and let a connected BCCL agent execute them on your behalf.

This page introduces the Service Tasks feature, explains the prerequisites, and walks you through the key concepts you need to understand before creating your first task.

What Are Service Tasks?

A Service Task is a record in Business Central (table 80805) that describes a BCCL operation. Each task stores everything BCCL needs to execute a request: the task type (such as GETDATA or PUTDATA), the target table, filters, output format, file paths, field mapping, and agent assignment.

When you set a task's status to Ready, the assigned BCCL service agent detects it during its next polling cycle, picks it up, executes the operation, and writes the results back to Business Central. You never need to open a terminal or construct a command line.

Service Tasks are ideal for:

  • Business Central users who need data exchange capabilities without command-line expertise
  • Organizations that want centralized, auditable control over BCCL operations
  • Scenarios where multiple agents handle different workloads across environments
  • Recurring operations that benefit from automation and scheduling

When Service Tasks are not the best fit: Service Tasks are meant for one-off operations and a limited, manually maintained set of scheduled tasks. When you need to handle a large number of tables, or replicate the same set of tables across many companies, the recommended approach is a scripted batch (.bat/.cmd) of BCCL commands scheduled with Windows Task Scheduler instead of maintaining one Service Task per table per company. The SQL Bundle Builder already generates FirstRunBCCL.cmd and RunBCCL.cmd scripts, which is exactly the recommended pattern for multi-table SQL replication. See Service Tasks vs. Scripted Runs.

When to Use Service Tasks

Service Tasks are intended primarily for ad-hoc operations run from the Business Central UI, and for operations that Business Central users need to trigger themselves.

Service Tasks are not the recommended way to run SQL synchronisation or replication. For continuous table sync, use BCCL in command-line mode with the mapping files and scripts generated by the SQL Bundle Builder (FirstRunBCCL.cmd for the initial full load, RunBCCL.cmd for the incremental sync), scheduled with Windows Task Scheduler as described in Scheduling Replication.

The reason is structural: a Service Task covers one table per task, and one agent runs one task at a time, so a multi-table sync built from Service Tasks runs sequentially and requires one task per table (and per company). The SQL Bundle Builder scripts handle many tables in one run.

Workload Recommended model
A single ad-hoc export, import, or delete Service Task
An operation a BC user must be able to trigger from the UI Service Task
A file produced by a BC report, XMLport, codeunit, or query that must land on an on-premises server DOWNLOAD Service Task (see Transferring Files to an On-Premises Server)
Many tables, many companies, or continuous SQL replication Scripts (.cmd) + Windows Task Scheduler

Prerequisites

Before you can use Service Tasks, make sure the following requirements are met:

Requirement Details
BCCL version 3.0 or later (both the BC extension and the BCCL client)
BCCL service mode BCCL must be installed and running as a Windows service
Service configuration A valid bccl_service.json file with authentication credentials
Connected agent At least one BCCL agent must be actively polling Business Central
Permissions The BC user must have the BCCL permission set assigned

If you have not yet installed BCCL as a Windows service, see Service Installation Overview for setup instructions.

Limitations

  • One agent executes one task at a time. Tasks queued for the same agent are executed sequentially. To run operations in parallel (for example several tables at the same time), install additional agents, each in its own folder with its own unique agentid in bccl_service.json and installed as a separate Windows service, and distribute tasks across them. See "Running Multiple Agents" in Service Configuration and "Multiple Agents" in Service Installation Overview.
  • Agents are visible per company. An agent registers in the Business Central company set as defaultcompany in its bccl_service.json, and tasks assigned to it must be created in that company. See Running and Monitoring Tasks.
  • One task covers one table. There is no bulk-create, duplicate-to-other-company, or spreadsheet import/export of Service Tasks. For many tables or many companies, use scripts instead.
  • Task ID length. Keep Task IDs to 20 characters or fewer (10 or fewer for Automation templates, because the clone suffix adds 10). See Creating Service Tasks.

Key Benefits

Centralized Management

All task definitions live inside Business Central. You create, configure, and monitor operations from a single place without switching between applications. Multiple users can manage tasks using familiar BC pages and controls.

No Command-Line Knowledge Required

Service Tasks abstract away the BCCL command-line interface. You fill in fields on a card page, select options from dropdowns, and use the built-in filter builder. Business Central handles the rest.

Multi-Agent Support

You can run multiple BCCL service agents, each with its own identity and connection. Tasks can be assigned to specific agents based on location, network access, or workload. The Available Agents factbox shows you which agents are online and their current status.

Because one agent can execute only one task at a time, additional agents are also how you scale out: tasks queued for the same agent wait until it is Idle again, whereas tasks spread across several agents run in parallel.

Execution Logging and Monitoring

Every task execution is tracked. You can see when a task started, when it finished, and whether it succeeded or failed. The task log records detailed output from the BCCL agent, including record counts and error messages.

Reusable Task Definitions

Automation tasks serve as templates that can be run repeatedly. Each execution creates a clone with its own status and log, while the original template remains unchanged. This makes it easy to set up recurring exports, imports, or replication jobs.

Accessing Service Tasks

To open the Service Task list in Business Central:

  1. Press Alt+Q to open the search bar.
  2. Type BCCL Service Tasks.
  3. Select the BCCL Service Tasks page from the results.

The page is also available under Administration in the Business Central navigation.

The Service Task List

The Service Task List page (80804) displays all tasks with a Classification of Normal or Automation. Clone tasks are not shown here -- they are accessible from their parent automation task.

The list shows the following columns:

Column Description
Task ID The unique identifier you assigned to the task
Description A free-text description of what the task does
Request Task The BCCL operation type (GETDATA, PUTDATA, etc.)
Agent Assigned Which BCCL service agent will execute this task
Status Current task status (Draft, Ready, Working, Completed, Failed)

From the list, you can select a task and choose Start to queue it for execution. You can also open the Service Task Card for full configuration by selecting a task and pressing Enter.

Available Agents Factbox

On the right side of the Service Task List (and the Service Task Card), you will find the Available Agents factbox. This panel shows all BCCL service agents that have recently connected to your Business Central environment.

Each agent entry displays:

Field Description
Agent ID The identifier configured in the agent's bccl_service.json file
Status Current agent state: Idle (waiting for tasks), Working (executing a task), or Stale (not seen recently)
Last Seen The date and time of the agent's most recent poll

Agents that have not been seen for more than one hour are automatically removed from the list.

Task Classifications

Every Service Task has a Classification that determines how it behaves when started:

Normal

A Normal task is a one-off operation. When you start it, the task itself changes status and is executed directly. After completion, you can review the results and optionally re-run it by starting it again. Normal tasks are suitable for ad-hoc exports, imports, or data operations.

Automation

An Automation task is a reusable template. When you start an Automation task, BCCL does not execute the template directly. Instead, it creates a Clone -- a new task instance copied from the template -- and queues the clone for execution. The original Automation task remains unchanged and ready to spawn additional clones.

This design supports:

  • Repeated execution with a full history of every run
  • Incremental sync patterns that track progress across runs
  • Job Queue scheduling for fully automated, recurring operations

Clone

A Clone task is an instance created from an Automation template. You cannot manually create a Clone -- they are generated automatically when an Automation is started (either manually or via the Job Queue). Each clone has a unique Task ID in the format TaskID-000000001, TaskID-000000002, and so on, with the number incrementing for each new run.

Clones inherit all settings from their parent Automation, including table number, view filters, format, field mapping, and agent assignment. The Clone Parent field links each clone back to its source template.

You can view all clones for an Automation task by selecting See Tasks from Automation on the Service Task Card.

Task Statuses

Every task moves through a defined lifecycle:

Status Description
Draft The task is being configured. It is not visible to agents and will not be executed. New tasks start in this status.
Ready The task is queued for execution. The assigned agent will pick it up on its next polling cycle.
Working An agent has picked up the task and is currently executing it.
Completed The task finished successfully. Start and end times are recorded.
Failed The task encountered an error during execution. Check the task log for details.

The typical lifecycle is: Draft -> Ready -> Working -> Completed (or Failed).

For Normal tasks, you can re-run a completed or failed task by starting it again, which resets the status to Ready. For Automation tasks, each start creates a new Clone, so the parent never changes status.

Available Request Tasks

Service Tasks support all standard BCCL request types:

Task Description
GETDATA Export data from a Business Central table
PUTDATA Import data into a Business Central table
DELETEDATA Delete specific records by primary key
DELETEALL Delete all records matching a filter
CHANGELOG Query the Change Log Entry table for audit data
MAPPING Generate a field mapping definition
MASSUPDATE Apply the same values to multiple records
DOWNLOAD Download output from a BC report, codeunit, XMLport, or query
UPLOAD Upload binary data to a BC codeunit or XMLport
RUNCODEUNIT Execute a custom AL codeunit

What to Do Next

Now that you understand the Service Tasks concept, you are ready to create your first task. Continue with the following topics: