Creating Service Tasks
This page walks you through creating and configuring a Service Task in Business Central. You will learn how to fill in each section of the Service Task Card, set up field mapping, and prepare a task for execution.
Opening the Service Task Card
To create a new Service Task:
- Press Alt+Q and search for BCCL Service Tasks.
- On the Service Task List page, select New from the action bar.
- The Service Task Card opens with a blank record ready for configuration.
The Service Task Card is organized into several groups: Task, Download/Upload Object Output, Local File (or SQL Connection or FTP Connection depending on file storage), Task Scheduling, Field Mapping, and Defaults.
Basic Settings
The top section of the card defines what the task does and how it is classified.
| Field | Type | Description |
|---|---|---|
| Task ID | Code, max. 20 characters in practice | A unique identifier for this task. Choose a short, descriptive name such as EXP-CUST or SYNC-ITEMS. Although the underlying field is Code[50], the Service Task Card truncates values longer than 30 characters, and the Service Task Log stores Task IDs in a 20-character field, so Task IDs longer than 20 characters fail when the task writes its log. Automation templates must leave room for the 10-character clone suffix (-000000001), which limits template IDs to 10 characters. See "Naming Service Tasks" below. |
| Description | Text[300] | A free-text description of what this task does. This appears in the task list and clone list for easy identification. |
| Classification | Option | Normal for one-off tasks, Automation for repeatable templates. You cannot manually select Clone -- clones are created automatically. |
| Request Task | Code[30] | The BCCL operation to perform. Select from the available request types: GETDATA, PUTDATA, DELETEDATA, DELETEALL, CHANGELOG, MAPPING, MASSUPDATE, DOWNLOAD, UPLOAD, or RUNCODEUNIT. |
| Format | Option | The data format: json, xml, csv, xlsx, or sql. This determines how data is serialized for export or how input files are parsed for import. When you select sql, the file storage automatically switches to Local files and SQL-specific fields appear. When you select xlsx, the task type is set to PUTDATA. |
| Table No. | Integer | The target Business Central table number. This field is editable for GETDATA, PUTDATA, DELETEDATA, CHANGELOG, and MAPPING tasks. When you set or change this value, the field mapping subform is automatically populated with all non-obsolete fields from the selected table. Caution: entering a table number discards the existing field mapping (see the warning below). |
| Table View | Text[2048] | A WHERE filter expression using Business Central filter syntax. Editable for GETDATA tasks. You can type the filter string directly or use the AssistEdit button to open the Filter Page Builder, which provides a visual interface for constructing filters. |
| File Storage | Option | How files are accessed: Local files (the agent's local file system), FTP, SFTP, or FTPS. This determines which file path and connection fields are visible on the card. |
Warning: entering a table number resets the field mapping. Typing or changing the Table No. on an existing Service Task deletes the current field mapping for that task and generates a fresh default mapping (all non-obsolete fields, selected, with default mapped names). This happens even when you re-type the same table number, because the trigger fires on entry of the value. The previous mapping cannot be recovered from the UI afterwards and must be re-created line by line. Before entering or changing the table number on a task with a customised mapping, record the mapping (screenshot, notes, or an export of the mapping lines). Deleting a Service Task also deletes its mapping records. These are the only two operations in BCCL that delete field-mapping records; see "Field Mapping Is Missing on a Service Task" in Running and Monitoring Tasks.
Naming Service Tasks
The short practical Task ID limit of 20 characters has consequences:
- Task IDs must be unique, so a per-company plus per-table naming scheme (for example
<CompanyPrefix>-<TableName>) quickly runs out of characters. Use short company abbreviations rather than full company names. - If the task will be used as an Automation template, the clone suffix (
-000000001) consumes 10 additional characters, so the usable template ID length is the limit minus 10, that is 10 characters. - Task lists sort alphabetically, so a consistent prefix groups related tasks together.
- If your naming scheme does not fit inside the Task ID limit because you have many tables or companies, that is a signal to use the scripted Task Scheduler approach instead. See Service Tasks vs. Scripted Runs.
Choosing a Request Task
The Request Task field determines which BCCL operation the agent performs. Here is a quick reference for choosing the right one:
| If you want to... | Use this task |
|---|---|
| Export data from BC to a file or SQL Server | GETDATA |
| Import data from a file or SQL into BC | PUTDATA |
| Delete specific records using a key file | DELETEDATA |
| Delete all records matching a filter | DELETEALL |
| Export change log entries for auditing | CHANGELOG |
| Generate a field mapping definition | MAPPING |
| Update multiple records with the same values | MASSUPDATE |
| Download report/query/XMLport output | DOWNLOAD |
| Upload a file to a codeunit or XMLport | UPLOAD |
| Execute a custom codeunit | RUNCODEUNIT |
Local File Settings
When File Storage is set to Local files and Format is not sql, the Local File group appears with these fields:
| Field | Description |
|---|---|
| Input filename | The full file path on the agent's machine for import operations (PUTDATA, DELETEDATA). Example: C:\Data\customers.json |
| Output filename | The full file path on the agent's machine for export operations (GETDATA, CHANGELOG, MAPPING, DOWNLOAD). Example: C:\Export\items.csv |
| Excel Sheet Name | The name of the worksheet within an Excel file. Only enabled when Format is xlsx. |
| Excel Sheet Range | The cell range containing data, such as A2..F700. Only enabled when Format is xlsx. Uses the double-dot notation (..) rather than a colon. |
| XML/JSON Path | The path to the repeating element in XML input files, with levels separated by /. Example: /Customers/Customer. Only enabled when Format is xml. |
All file paths are relative to the BCCL agent's machine, not to the Business Central server. Make sure the agent's service account has read/write access to the specified locations.
SQL Connection Settings
When File Storage is Local files and Format is sql, the SQL Connection group appears instead of the Local File group:
| Field | Description |
|---|---|
| SQL Connection String | A full ADO.NET connection string to your SQL Server. Example: Server=myserver;Database=BCData;Trusted_Connection=True; |
| SQL Select statement | For PUTDATA: a SQL SELECT statement that provides the source data. |
| SQL Table | For GETDATA or CHANGELOG: the target SQL table name where exported data is written. |
| SQL PreCommand | An optional SQL statement to execute before the main operation. Commonly used to truncate a table before a full reload: TRUNCATE TABLE [dbo].[Customer]. Available for GETDATA and CHANGELOG tasks. |
| SQL Zero Date | The date value to use for blank dates (0D in Business Central). Defaults to 1900-01-01. SQL Server does not accept blank dates, so this substitution prevents insertion errors. |
FTP Connection Settings
When File Storage is set to FTP, SFTP, or FTPS, the FTP Connection group appears:
| Field | Description |
|---|---|
| FTP Input File | The remote file path for import operations (PUTDATA, DELETEDATA, UPLOAD). Include the full path on the FTP server. |
| FTP Output File | The remote file path for export operations (GETDATA, MAPPING, DOWNLOAD). |
| FTP Server | The hostname of the FTP server, such as ftp.example.com. |
| FTP Username | The username for FTP authentication. |
| FTP Password | The password for FTP authentication. This field is masked in the UI. |
| FTP Certificate | The full path to a certificate file on the agent's machine. Used for SFTP key-based authentication or FTPS certificate validation. |
| FTP Rename Postfix | After a successful download from FTP, the remote file is renamed by appending this value. Useful for marking files as processed. Example: .done |
Download Object Output
When the Request Task is DOWNLOAD, an additional group appears for configuring which Business Central object to run and how to format its output:
| Field | Description |
|---|---|
| Object Type | The type of BC object to execute: Report, Codeunit, XMLport, or Query. |
| Object ID | The ID of the specific object to run. The lookup is filtered to the selected object type. |
| Object Output Type | The format for the object's output: PDF, CSV, XML, HTML, Excel, or Word. Note that Reports cannot be exported as CSV, and Queries only support CSV or XML. |
When you start a DOWNLOAD task, Business Central runs the specified object and stores its output in a binary payload field. The agent then downloads this payload and saves it to the configured output file.
For Reports, a request page dialog appears when you start the task, allowing you to configure report parameters before execution.
DOWNLOAD tasks are the supported way to get a file produced by Business Central Online (for example an XML file for a shipping system or a print file) onto an on-premises server where the agent runs. Note that moving an existing file stored in Business Central (an attachment or a file BC uploads to SharePoint) requires custom AL code that creates a Service Task carrying the file. See Transferring Files to an On-Premises Server.
Upload Object Input
When the Request Task is UPLOAD, a similar group appears:
| Field | Description |
|---|---|
| Object Type | The type of BC object to receive the upload: Report, Codeunit, or XMLport. Query is not available for uploads. |
| Object ID | The ID of the specific object to run. |
The agent reads the input file and sends its contents to Business Central, where the specified object processes it.
Task Scheduling
The Task Scheduling group controls agent assignment and shows execution status:
| Field | Description |
|---|---|
| Agent Assigned | Select the BCCL service agent that should execute this task. The dropdown shows agents from the Service Agent table. Check the Available Agents factbox on the right to see which agents are currently online. |
| Status | The current task status (read-only). Automatically updated as the task moves through its lifecycle. |
| Started at | The date and time the agent began executing the task (read-only). |
| Ended at | The date and time the agent finished executing the task (read-only). |
Agents are visible per company. An agent registers in the Business Central company set as
defaultcompanyin itsbccl_service.json. Tasks must be created in that same company for the agent to be selectable and valid. If you pick an agent from the dropdown and then get the error "The field Agent Assigned in table Service Task Hgd contains a value (<AGENTID>) which cannot be found in the related table (BCCL Service Agent)", you are most likely in a different company than the one the agent is connected to. See "Errors When Assigning an Agent" in Running and Monitoring Tasks.
You must assign an agent before you can start a task. If you attempt to start a task without an assigned agent, you will see the error: "Please assign the Task to a BCCL Agent before trying to start it."
Field Mapping
The Field Mapping subform appears at the bottom of the Service Task Card for GETDATA, PUTDATA, and DELETEDATA tasks. It is automatically populated when you set the Table No. field.
Each row in the mapping represents one field from the target table:
| Column | Description |
|---|---|
| Selected | Whether this field is included in the operation. Toggle on or off to control which fields are exported or imported. Use the Toggle Selected action to flip the selection for multiple fields at once. |
| No. | The field number in the Business Central table (read-only). |
| Field Name | The name of the field as defined in the table (read-only). |
| Type | The data type of the field (read-only). |
| Mapped Name | The name to use in the output format or input file. Defaults to the field name with invalid XML characters replaced by underscores and dots removed. You can change this to match your target schema. For SQL format, this becomes the column name. |
| Function | Apply a special function to this field: (blank) for normal processing, dimensionfromset to expand dimension set IDs into individual dimension values, or custom for custom processing via AL events. |
| Create Related Stub | When enabled, BCCL automatically creates a stub record in the related table if the referenced record does not exist. Useful when importing data that references master records not yet in the system. |
| Format String | A .NET format string for controlling date, time, or decimal output in CSV files. Click the AssistEdit button for a link to the Microsoft documentation on format strings. |
BLOB, Media, and MediaSet fields are only included in the mapping if the Include Binary Files option is enabled in the Defaults section.
Defaults Section
The Defaults group contains additional settings that fine-tune the task's behavior:
| Field | Description |
|---|---|
| Filter to only entries since last run | When enabled on an Automation task (CHANGELOG or GETDATA only), each clone automatically adjusts its view filter to only include records changed since the previous run. This enables incremental sync patterns. |
| Include Binary Files | Include BLOB, Media, and MediaSet fields in exports and imports. Binary data is transferred as Base64-encoded content. |
| Use CSV headers | Include a header row in CSV output. Enabled by default. Only editable when Format is csv. |
| Delimiter for CSV files | The character used to separate fields in CSV files. Defaults to ,. Only editable when Format is csv. |
| Quote Char for CSV files | The character used to quote field values in CSV files. Defaults to ". Only enabled when Format is csv. |
| Use DelayedInsert Pattern | When enabled, BCCL fills in all field values on a new record before calling Insert(). This avoids validation triggers firing on partially filled records. Enabled by default. Only applies to PUTDATA tasks. |
| Verbose Output logging | Enable detailed logging from the BCCL agent for this task. Useful for troubleshooting but produces larger log entries. |
Step-by-Step Example: Creating a Customer Export Task
Here is a complete example of creating a task that exports all domestic customers to a CSV file:
- Open the Service Task List and select New.
- Set Task ID to
EXPORT-DOMESTIC-CUST. - Set Description to
Export domestic customers to CSV. - Set Classification to Normal.
- Set Request Task to GETDATA.
- Set Format to csv.
- Set Table No. to 18 (Customer table). The field mapping populates automatically.
- In the Table View field, click the AssistEdit button. In the Filter Page Builder, set the Country/Region Code filter to your domestic code and confirm.
- Set File Storage to Local files.
- Set Output filename to
C:\Export\domestic-customers.csv. - In the Field Mapping subform, deselect any fields you do not need in the export. Optionally rename mapped names to match your target system.
- Under Task Scheduling, set Agent Assigned to your active BCCL agent.
- Under Defaults, verify that Use CSV headers is enabled and the Delimiter is set to your preferred separator.
Your task is now configured and ready to run. See Running and Monitoring Tasks for the next steps.
Tips for Task Configuration
- Use short, descriptive Task IDs (20 characters or fewer) that convey the purpose at a glance. Task IDs appear in logs, clone lists, and Job Queue entries.
- When building view filters, use the AssistEdit button on the Table View field. The visual Filter Page Builder is less error-prone than typing filter syntax manually.
- For SQL format tasks, test your SQL connection string independently before configuring the task. Connection failures produce generic errors that can be hard to diagnose.
- If you plan to convert a Normal task to an Automation later, keep the Task ID to 10 characters so that the clone suffix (
-000000001, 10 characters) still fits within the 20-character limit. - When configuring field mapping for SQL targets, make sure the Mapped Name matches your SQL column names exactly.
- Set the Table No. once, before customising the mapping. Re-entering it discards your customised mapping.
Limitations and Alternatives
Service Tasks are created and maintained individually. There is no bulk-create, duplicate-to-other-company, or spreadsheet import/export mechanism for them, so you cannot export your tasks to Excel, change the company name, and import them into other companies. If the same task must exist for many tables, or must be repeated for each company in the environment, write a script of BCCL command lines instead of creating individual Service Tasks. See Service Tasks vs. Scripted Runs and Replicating Multiple Companies.