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.

...



Examples

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")