Running and Monitoring Tasks

Once you have created a Service Task and have at least one BCCL agent connected, you can run tasks directly from within Business Central and monitor their execution in real time.

Running a Task

Step-by-Step

Open the Service Task Card for the task you want to run
Verify all settings are correct (table, format, mapping, file paths, agent)
Ensure an agent is assigned in the Assigned To Agent Id field
Change the Status field from Draft to Ready
The assigned BCCL agent picks up the task on its next poll cycle (within 10 seconds)
The status automatically changes to Working while the task executes
Upon completion, the status changes to Completed or Failed

Quick Run from Service Task List

Open the Service Task List page
Select the task you want to run
Change the status to Ready
Press F5 to refresh and see the updated status

Prerequisites for Running

Before running a task, ensure:

At least one BCCL agent is running and connected
The agent appears in the Available Agents factbox
The agent's Last Seen timestamp is recent (within the last minute)
All required task settings are configured (table, format, paths)
File paths are accessible from the agent's machine (not your BC browser)

Understanding Task Statuses

Status	Description	Next Steps
Draft	Task is being configured	Complete setup, then change to Ready
Ready	Queued for the next agent poll	Wait for agent pickup (up to 10 seconds)
Working	Currently executing on the assigned agent	Wait for completion, refresh to check
Completed	Successfully finished	Review results and logs
Failed	An error occurred during execution	Check logs for error details

Status Flow

Draft → Ready → Working → Completed
                       → Failed

You can set a task back to Ready to run it again (for Normal classification tasks).

Monitoring Execution

Service Task List

The Service Task List page provides an overview of all tasks:

Task ID: Unique identifier
Task: Request type (GETDATA, PUTDATA, etc.)
Status: Current execution status
Classification: Normal, Automation, or Clone
Assigned To Agent Id: Which agent is running this task
Start Time / End Time: Execution timestamps

Press F5 to refresh the list and see updated statuses.

Available Agents Factbox

The Available Agents factbox on the Service Task pages shows:

Field	Description
Agent ID	Unique identifier for the agent
Status	Idle (waiting) or Working (executing a task)
Last Seen	Timestamp of the agent's last check-in

If an agent's Last Seen timestamp is more than a few minutes old, the agent may have stopped or lost connectivity.

Viewing Task Logs

To view execution details for a task:

Open the Service Task Card
Use the View Remote Output action
The Service Task Log shows:

Field	Description
Start Time	When the task began executing
End Time	When the task finished
Status	Completed or Failed
Log	Detailed execution output from the agent

The log contains the same information that would appear on the console when running BCCL from the command line, including:

Records processed (inserted, modified, deleted)
Skipped operations
Error messages and stack traces (if failed)
Paging information for large datasets

Troubleshooting Failed Tasks

When a task fails, follow these steps:

Errors When Assigning an Agent

Symptom: Setting the Agent Assigned field on a new Service Task produces a Business Central error, even though the agent was picked from the dropdown:

The field Agent Assigned in table Service Task Hgd contains a value (<AGENTID>) which cannot be found in the related table (BCCL Service Agent).

In a Danish client the same error reads: "Feltet Agent tildelt i tabellen Service Task Hgd indeholder en værdi (<AGENTID>), som ikke blev fundet i den relaterede tabel (BCCL serviceagent)."

First question: does the environment have more than one company? The BCCL agent connects to, and registers itself in, the company configured in the defaultcompany field of its bccl_service.json. The Service Agent record therefore exists in that company only, so the Service Task must be created and run in the same company the agent is connected to.

Remedy:

Check which company is set in defaultcompany in the agent's bccl_service.json.
Switch Business Central to that company.
Verify that the agent appears in the Available Agents factbox in that company with a recent Last Seen timestamp.
Create the task there.

The setup itself is supported and intended: the BCCL agent may run as a Windows service on an on-premises server while the Service Tasks are created in Business Central Online, using S2S authentication. If you need agents in several companies, run one agent per company; see "Running Multiple Agents" in Service Configuration.

Field Mapping Is Missing on a Service Task

Field mapping on a Service Task is stored as separate field-mapping records linked to the Service Task record. There are exactly two operations in BCCL that delete field-mapping records:

Deleting a Service Task. Its field-mapping records are deleted with it.
Entering or typing a table number on a Service Task. The existing field mapping for that task is removed and a new default mapping is created in its place. This also happens when the same table number is re-typed, because the trigger fires on entry of the value.

These two operations are the only code paths in BCCL that delete field-mapping records, so any other loss of mapping is not caused by them. After a reset by table-number entry, only the newly created default mapping exists; customised mapping must be re-entered manually.

Diagnostic checklist when mapping appears to be missing:

Was the Service Task deleted and re-created? Deleting a task deletes its mapping records.
Was the table number on the task entered or changed? That resets the mapping to a new default mapping.
Field-mapping records belong to the individual Service Task record. A Service Task that looks identical in another company is a separate record with its own mapping records; mapping lost on one does not affect the other.
If neither (1) nor (2) applies, report the case to support with: the ID of the Service Task(s) concerned, which mapping lines are missing, approximately when it was noticed, the environment type (production or sandbox) and company, and whether the BCCL app version or Business Central version was changed around the same time.
Recovery: re-enter the missing field-mapping lines manually on the affected Service Task.

1. Check the Task Log

Open the Service Task Card and view the log. Common error patterns:

Error	Possible Cause
"Table not found"	Incorrect table number in task settings
"Permission denied"	Agent's BC user lacks BCCL permission set
"File not found"	Input file path not accessible from agent's machine
"SQL connection failed"	SQL Server connection string incorrect or server unreachable
"Authentication failed"	Expired credentials in bccl_service.json

2. Verify Agent Connectivity

Check the Available Agents factbox for the agent's Last Seen time
If the agent is not visible, check that the BCCL service is running
Review Windows Event Viewer on the agent's machine for service errors

3. Check File Paths

Remember that file paths in Service Tasks are relative to the agent's machine, not the BC server or your browser session:

Local files: the path must exist on the machine where BCCL.EXE runs
FTP/SFTP: the credentials and server must be reachable from the agent
SQL Server: the connection must work from the agent's network

4. Enable Verbose Logging

Set "verbose": "true" in the agent's bccl_service.json file for more detailed logging:

{
    "agentid": "MY_BCCL",
    "verbose": "true",
    ...
}

Restart the service after changing the configuration.

5. Test the Operation via CLI

If a Service Task fails, try running the equivalent operation from the command line on the agent's machine. This often provides more detailed error information:

BCCL -t getdata -s table=18 -f csv -o C:\data\customers.csv -v

Re-Running Tasks

Normal Tasks

You can re-run a Normal classification task by changing its status back to Ready. The task executes again with the same settings.

Automation Tasks

Automation tasks create a new Clone each time they run. See Automations and Scheduling for details.

Multiple Agents

An agent processes a single task at a time. If several tasks are Ready for the same agent, they wait in the queue until the agent is Idle again. Scaling out means more agents, not more tasks per agent.

If you have multiple BCCL agents running:

Each task is assigned to a specific agent via the Assigned To Agent Id field
Only the assigned agent picks up the task
You can distribute workload across agents by assigning different tasks to different agents, which is the only way to run tasks in parallel
Each agent has its own bccl_service.json with a unique agentid
Each agent is visible, and its tasks must be created, in the company set as defaultcompany in its bccl_service.json

Tips and Best Practices

Always test new tasks with small datasets before processing large volumes
Use descriptive Task IDs for easy identification in the list
Check agent connectivity before running critical tasks
Enable verbose logging when troubleshooting, but disable it for routine operations to reduce log volume
Schedule regular checks of the Service Task List for failed tasks
Use the Available Agents factbox to confirm agents are online before running tasks