Breadcrumbs

BC.WRITEBACK

Overview

The BC.WRITEBACK function sends one or more lines of values to the ERP. The function uses the fields specified in an Object defined in the ERP.

Syntax 

=BC.WRITEBACK(
    ConnectionName,
    Object,
    Settings,
    FieldNames,
    ParentObject,
    ParentRecordId,
    OutputFieldNames,
    OutputRange,
    RangeOrDataItem,
    ...
)

Arguments

The BC.WRITEBACK function uses the following arguments:


Argument

Required/Optional

Description

ConnectionName

Required

The name of the connection as configured in the Connection Manager.

This function does not support the multiple connection functionality.

Object

Required

The name of the Business Central object (case insensitive).

Use the BC.EXPANDOBJECTRANGE function to retrieve available values.

Settings

Optional

A two-column array of setting:value pairs. The available settings are:

  1. Mode: selects the writeback mode.
    Available values:

    1. create - create new records. FieldNames must not contain key fields for the common API. For the web-service API, key fields are acceptable.

    2. update - update existing records. FieldNames must contain key fields.

    3. create-or-update (default) - if id is specified, then update the record; otherwise, create a new record. In some cases, key fields are required for the web-service API.

    4. delete - delete existing records. FieldNames must contain only key fields.

  2. Api: selects which API to use.
    Available values:

    1. common - Common API v2 (default)

    2. web-service - OData endpoints exposed per tenant

Example: {“Mode”, “delete”; “Api”, “web-service”}

Use the VX.SETTINGS function to create settings arrays ready to use with Velixo functions.

FieldNames

Required

A comma-separated string
OR
an Excel range containing the names of the fields for writeback.

ParentObject

Optional
(Required if writing back to a child object, e.g. document lines)

A parent object name (for example, salesOrders is a parent for salesOrderLines).

Use the BC.EXPANDOBJECTRANGE function to retrieve available values.

ParentRecordId

Optional

(Required if ParentObject is specified)

The ID of a parent record with which the child record will be associated.

  1. For parent objects that have a single key field, provide a string with this value (string, number, or UUID).

  2. For parent objects with multiple key fields, provide a two-column array with:

    1. key field names in the first column

    2. key field values in the second column

Use the BC.OBJECTDEFINITION function to retrieve information about key fields.

image-20260225-120621.png

OutputFieldNames

Optional

An Excel cell range (or a comma-separated string) containing the field names to retrieve from the resulting object. Returns all fields when omitted.

Use the BC.OBJECTDEFINITION function to retrieve information about available fields.

This argument is ignored when in "delete" mode

OutputRange

Optional
(required if OutputFieldNames is specified)

A reference to an Excel range where the output fields will be returned.

This argument is ignored when in "delete" mode

RangeOrDataItem

Required

An Excel range with the data items or a value to be written to the first field specified in FieldNames argument. The values must be specified in the same order as the column/field names in the FieldNames argument.

The number of RangeOrDataItem arguments must match the number of fields in FieldNames.

RangeOrDataItem2

Optional
(required if two fields are specified in FieldNames)

An Excel range with the data items or a value to be written to the second field specified in FieldNames argument.

...



How to build writeback data lines

This section explores different ways of composing data for the BC.WRITEBACK function.

We will be using an example where you write back data lines containing an order number, employee, a monetary amount, and a date.

image-20260330-124357.png


As separate lines - multiple BC.WRITEBACK functions

The first way to write back such a block of data is to specify each data line as a separate RangeOrDataItem argument:

image-20260330-124606.png

This works great when the number of lines doesn't change over time, or changes relatively infrequently.

As separate lines - single BC.WRITEBACK function

You can also use just one BC.WRITEBACK function and display the status just once on your worksheet. To specify data items as separate lines in such a case, you can use multiple RangeOrDataItem arguments representing writeback lines:

image-20260330-124726.png

The downside here, again, is when the number of items changes over time, you will need to manually modify your formula.

As a block of data - single WRITEBACK function

Alternatively, you can use an Excel range as the first RangeOrDataItem argument of the BC.WRITEBACK function:

image-20260330-125029.png

 

Hard-coded range references may be a good choice when the shape of data and the number of lines stay the same over time. If the shape of data changes, however, there is a risk of forgetting to modify the formula to include the additional data lines.


This approach works great with spill ranges:

image-20260330-130258.png

 

You can use such functions as COLLATE, HSTACK and VSTACK to compose such a dynamic block.

From separate columns of data - single WRITEBACK function

Suppose the employee's name in our example stays the same, no matter what, and the date is the same for every line.

Also, let's suppose that the number and amount are Excel spill ranges coming from two different functions or data sources.

Then, you can compose your writeback data in a more dynamic way without using HSTACK / COLLATE, and also avoid repeating JOHNDOE in each line.

image-20260330-131153.png

Note how we reference the Account / Amount using the spilling range syntax with "#", and also specify employees and orderDate as a single-cell references.

This layout is equivalent to the following rows:

JOHNDOE, 1001, 100, 01/01/2026,
JOHNDOE, 1002, 200, 01/01/2026,
JOHNDOE, 1003, 300, 01/01/2026 etc.

This saves space on the worksheet, removing unnecessary duplication, and is also completely robust when using spilling ranges of accounts/amounts resized in the future.

Example

New sales order 

=BC.WRITEBACK(
A9,
B9,
C9:D10,
E9,
F9,
G9,
H9,
I9,
J9:M9)
image-20260309-132041.png

Description:

This BC.WRITEBACK formula updates the fields orderDate, customerNumber, currencyCode, and shipToCity in the salesOrders object for the connection BC.

In the Settings argument, the API is set to common, and the Writeback mode is set to create-or-update.

The output fields are set in the OutputRange argument to be returned in the Excel range called id.

The range J9:M9 provided in the RangeorDataItem argument contains values to be written to the ERP (in the same order as in the FieldNames argument).

With references substituted by literal values, the formula translates to:

=BC.WRITEBACK(
BC,
"salesOrders",
{"api","common";"mode","create-or-update"},
"orderDate,customerNumber,currencyCode,shipToCity",
"id",
"2026-03-09,5000,GBP,London")