BCCL Documentation
Index

Frequently Asked Questions

This page collects the questions that customers most often ask hougaard.com support about BCCL, together with short answers and links to the detailed articles. If your question is not answered here, check Common Issues or see Getting Support.

Licensing

We want to download Business Central cloud data into our own on-premises SQL Server database for reporting. Which license do we need?

You need one of the BCCL Enduser (Commercial) licenses. This applies whenever data is pulled from a Business Central cloud tenant into a database that you own, for example a custom on-premises SQL Server database used for reporting.

It does not matter whether the Business Central environment was recently migrated from an on-premises version (for example, a BC14 on-premises installation moved to the cloud). What matters is that the data is being read from a Business Central cloud tenant.

Licenses can be purchased at hougaard.com/product-category/bccl. See License Terms for details.

Do we need one license for the sandbox and one for production?

No. A single BCCL license covers all environments within the same tenant, including the production environment and cloud sandbox environments. You do not need to buy a second license to test BCCL downloads from a sandbox before go-live.

Can we use one license for sandbox testing first and then switch it to production at go-live?

The question is moot: the same single license already covers both the sandbox and production environments simultaneously. There is nothing to switch, move, or re-assign. You can run BCCL against a sandbox during upgrade or migration testing, against production after go-live, and continue to download from the sandbox after go-live, all under the one license.

Does it matter how many tables we sync, or whether we start with one company and add more later?

Refer to the current license tier definitions on the BCCL product page. The tier descriptions there are authoritative; this documentation does not define per-table or per-company rules.

I registered my BCCL license on the wrong tenant. Can I re-register it myself?

No. A license key is bound to the tenant ID it was registered against, and the registration must be reset by hougaard.com on the license server side. Send the following to support:

  • The license key
  • The tenant ID where the key was incorrectly registered
  • The correct tenant ID where it should be registered

Once support confirms the key has been reset, run the registration command again with the correct tenant ID:

bccl --register <license-key> --tenantid <tenant-id>

See License and Registration Issues.

We migrated our Business Central environment to another tenant. Do we need a new license?

No. The existing license is re-bound to the new tenant; you do not need to purchase another one. Note that registering the license on the new tenant does not remove the binding to the old tenant. Both registrations remain until hougaard.com support manually removes the old one, so contact support and state explicitly which tenant ID should be removed. See License and Registration Issues.

BCCL suddenly says "Trial version detected". What happened?

Either the BCCL license has expired, or the BCCL instance on this machine has not been registered. An installation that has been running for a long time can start reporting itself as a trial purely because the license reached its end date. This is not a corruption or configuration problem. Contact support@hougaard.com to have the license status checked and renewed. See License and Registration Issues.

Is "A valid license not found for ..." a BCCL error?

No. Messages of the form A valid license not found for <name>. are not produced by BCCL or any other hougaard.com app. They come from a third-party extension. Use Share Details on the error dialog and read the AL call stack to identify the app and publisher. See Identifying Which App Raised an Error.

Data and Tables

Is it possible for BCCL to get table 2000000095? Can BCCL map system or virtual tables?

No, if the Business Central platform blocks the table from being opened through a RecordRef on the Cloud target. The error you see is:

You cannot open record 2000000095 from a RecordRef data type when you are using target Cloud.

The same error can appear for other table numbers. It is raised by the Business Central platform, not by BCCL. BCCL reads and writes data dynamically through RecordRef/FieldRef, so any table the platform refuses to open that way cannot be reached by BCCL at all. There is no BCCL setting, permission, configuration, or workaround. Some tables are restricted by Microsoft. There is no way around it. When this error appears, it is not a bug in BCCL and there is nothing to fix in the mapping file.

Alternative approach: have AL code in an extension read the restricted table using a direct Record variable of that type (where the platform allows it), copy the needed rows into a normal, non-virtual table, and build the BCCL mapping against that normal table instead. Whether a direct Record variable is allowed for a given table is also decided by the platform, not by BCCL.

This was observed on app version 3.23.0.372 with Business Central 28.5, but the limitation is not specific to any BCCL version; it follows Microsoft's platform restrictions.

Can I truncate or shorten a value in the mapping file, for example Left(Description,30)?

No. A mapping entry is a field-to-column assignment consisting of FieldNo, FieldName, MappedName, Validate, and optionally CreateRelatedStub, plus the documented Format and Function properties. It contains no expression or length property.

If a value is longer than the target SQL column (error "String or binary data would be truncated"), widen the target column or ensure the source data fits. See SQL Output Issues, and see the --sqlprecommand parameter in Command Reference for setting SQL session options on the connection.

Are certain tables, such as the Shopify tables, not accessible via BCCL?

No category of Business Central tables is blocked from BCCL (apart from the platform-restricted tables described above). Shopify connector tables and other standard-app tables are readable like any other table. An error on such a table indicates a data-type or client-version problem, not an access restriction. The most common case is the Int32 overflow on BigInteger fields with older clients; see SQL Output Issues.

Microsoft changed standard Option fields into Enum, for example the Document Type field on Sales Header, which is now the Enum Sales Document Type but still uses field ID 1. Is that a breaking change, and why can Microsoft do it?

It is not a data-level change. Option and Enum are stored identically in the database, so re-declaring an existing field from Option to Enum keeps the same field ID and the same stored values. Enum exists so that AL code can share one value set across multiple fields and objects instead of defining the option string separately for every field.

You may notice that Page Inspection (Ctrl+Alt+F1) still displays such a field as Option. This is consistent with Option and Enum being the same underneath and is not an error.

Further reading: video explanation of options and enums.

Should I convert my own custom Option fields to Enum?

Behind the scenes, in the SQL database, Option and Enum are stored identically. Enums exist mainly as an AL coding convenience: they let the same option set be defined once and reused in several places. Because the stored data is the same, switching a field's declaration between Option and Enum is not a change to how the value is stored. BCCL exports both types the same way (as the numeric option value in SQL output). See the previous question for further reading.

Why does a getdata run fail with "Field ... is obsoleted"?

The mapping file refers to a field that Microsoft has marked obsolete in the Business Central base application. Fields can be removed, renamed, or moved into a separate app. A real-world example:

An error has occurred: Field IRS 1099 Amount (10021) of table Purchase Header (38) is obsoleted, reason: Moved to IRS Forms App.

Remove the obsoleted field from the mapping file and re-run the task. There is no setting or option that lets a Get Data task skip obsoleted fields; editing the mapping is the only option. Each error reports one field at a time, so you may need to repeat until the task completes. This behaviour is not version-specific. See Common Issues and Mapping Files.

SQL Replication and Change Log

Do I have to enable the Change Log on the tables I replicate to capture inserts and updates?

No. The GetData task handles inserts and updates without the Change Log. Change Log configuration is therefore not required on ledger tables, sales order tables, or master data tables (customers, vendors, and so on) for insert/update replication. If you want to keep Change Log volume low, you do not need to enable Change Log entries for inserts and updates on replicated tables.

The Change Log is used by BCCL for deletion tracking: the CHANGELOG task reads deletion entries and removes the corresponding rows in SQL Server. See SQL Replication Overview and Change Log Configuration.

Why does every run report "0 inserted, N updated"?

GETDATA performs a full transfer of every record matching the view filter on every run and upserts them into the SQL table. A second run of the same command therefore updates every row again. To transfer only recently changed records, add a view filter on the SystemModifiedAt system field (field number 2000000003), with a window that matches your run frequency:

view=WHERE(Field2000000003=1({today(-1D)}..))

See Filtering Data.

Service Tasks

Can I export my Service Tasks to Excel or another file, edit the company name, and import them into other companies?

No. There is no supported export/import of Service Tasks for that purpose, and no bulk-create or duplicate-to-other-company mechanism. When the same operation must be repeated across many tables or many companies, use a script of BCCL command lines instead of Service Tasks. See Service Tasks vs. Scripted Runs.

Why did the field mapping on my Service Task disappear?

Exactly two operations in BCCL delete the field mapping records of a Service Task:

  1. Deleting the Service Task deletes its field mapping records with it.
  2. Entering or typing a table number on the Service Task removes the existing mapping and creates a new default mapping in its place. This happens even if you re-type the same table number.

After a reset, only the default mapping exists; customised lines must be re-entered manually. See Running and Monitoring Tasks.

Can one agent run several tasks at once?

No. One BCCL agent executes one task at a time. Tasks queued for the same agent run sequentially. To run operations in parallel, install additional agents, each in its own folder with its own bccl_service.json and a unique agentid. See Service Tasks Overview.

Can I get a file that Business Central Online produces down onto an internal on-premises server?

Yes, with a BCCL agent running on the on-premises server. A DOWNLOAD Service Task runs a Report, Codeunit, XMLport, or Query and saves the output to a file on the agent's machine, and a GETDATA task can export table data directly to a file there. Moving an existing file that is stored in Business Central (an attachment, a BLOB, a file BC uploads to SharePoint) is not a configuration-only feature and requires AL development. See Transferring Files to an On-Premises Server.

Running Against Multiple Companies

Can I run BCCL for several companies at the same time? Will --remember overwrite my data or connection?

Running per-company extractions is supported, but do not use --remember for this. Remembered settings are stored in the prompt session, and simultaneous sessions conflict with each other, so the wrong company or connection may be used. Instead, run one self-contained BCCL command per company with all parameters specified on that command line, including authentication, a company-specific -w web service URL (the URL contains the company name), and a company-specific -o output table. See Replicating Multiple Companies.

Authentication

BCCL sign-in fails or asks for approval. What permission am I missing?

None in particular. The BCCL application has not been granted admin consent in your Microsoft Entra ID tenant. An administrator must consent once, either by clicking "Have an admin account? Sign in with that account" in the sign-in window that BCCL opens and signing in with an administrator account, or from the Azure Portal under Enterprise Applications. No individual permission needs to be hand-picked or requested from your MSP. See OAuth Authentication.

I can't find BCCL in the list of Enterprise Applications in the Azure Portal. Do we need to create the app?

No. The BCCL application is not listed under Enterprise Applications until consent has been granted, so an empty search result is expected. Do not create or register an app manually. Have an administrator use the "Have an admin account? Sign in with that account" link in the BCCL sign-in window; this creates the enterprise application entry as part of granting consent.

The server has rejected the client credentials, but the same values work in Postman?

This is a long-standing bug in Business Central itself, not in BCCL. The registered application looks enabled and correct, yet the server rejects the credentials, and a successful token request from Postman does not rule it out. The fix is to cycle the Enabled state of the application's card in Business Central: disable it, close the card completely, re-open it, and enable it again. The same Client ID, Tenant ID, and Secret Value are reused afterwards. The full steps, including a version you can forward to the Business Central owner, are in Authentication Issues and Service-to-Service Authentication.

Business Central Data Model

Which Business Central table tells me which invoice a customer payment is applied to?

There is no field or table in Business Central that directly links a payment to a record in the Sales Invoice table. The application information does not point at the Sales Invoice table at all.

The application information lives on Customer Ledger Entries, in the "Closed by ..." fields and the "Applies-to ..." fields. To determine what is applied to what, these fields must be read and interpreted together; the answer cannot be taken from a single field. This is complicated by design in standard Business Central: any custom report, query, or integration that needs a "payment to invoice" relationship must implement that logic itself. BCCL does not maintain its own payment-to-invoice mapping table; this is standard Business Central behaviour.

Where to look:

  • Open the Customer Ledger Entries page for the customer in question.
  • Inspect the "Closed by ..." and "Applies-to ..." fields on the entries. Not all of these fields are shown by default; add them through page personalisation.
  • The link found this way is ledger entry to ledger entry. To reach the posted sales invoice, go from the invoice's customer ledger entry to the posted document via the document number, since no direct table relation to the Sales Invoice table exists.

Common misunderstanding: readers often assume a single table stores "payment X is applied to invoice Y". That assumption is wrong; use the closed-by / applies-to fields on Customer Ledger Entry as described above.