BC.WRITEBACKBUDGET

Overview

The BC.WRITEBACKBUDGET function enables you to write lines to a specified GL budget in Business Central.

Writing back to General Ledger budgets is not available to users with the MS Dynamics 365 Team Members license.

Getting started with Writeback - A general article on setting up and using writeback functions.

Syntax

=BC.WRITEBACKBUDGET(
  ConnectionName, 
  Budget, 
  BudgetDescription, 
  BudgetDimensions,
  BudgetUpdateMode,
  Account, 
  Amount, 
  Date, 
  Description, 
  Dimensions, 
  EntryNumber,
  EntryNumberOutput
)

Arguments

Header data

Argument	Required/Optional	Description
`ConnectionName`	Required	The name of the connection, as specified in the Connection Manager. This function does not support the multiple connection functionality.
`Budget`	Required	The name of the GL budget targeted for Writeback. If a budget with the provided name is not present in Business Central, a new budget by that name will be created.
`BudgetDescription`	Optional	A textual description of the budget.
`BudgetDimensions`	Optional	Comma-separated array of budget dimensions. This parameter affects only newly created budgets. If skipped, the new budget is created without budget dimensions. Global dimensions are not affected by this parameter.
`BudgetUpdateMode`	Optional	One of four available values: `by-entry-number`, which requires specifying the internal ID for update in the `EntryNumber` line argument. If the ID is not specified, a new budget entry is created. `recreate` – erases all entries in the budget, then creates new entries. Be careful with using WRITEBACKCOMMIT. `by-natural-key` – (default value) "smart" mode where you can specify a set of columns (such as the date, account, dimension values) by which Velixo will decide whether to update an existing budget entry or to create a new one: If one entry matching the key is found, update it. If multiple entries matching the same key are found, update one of them with the new value and set the others to zero. If no entry is found, create a new one with the specified value. A manually provided set of key values, for example, `dimensions, description`. The available values are: `account`, `date`, `dimensions` (or `dimension`), `description`. The values `account` and `date` are added automatically if not provided.

Line data

This function is spill-aware. When you provide an array for line data arguments, the function outputs a spill range with one status cell per line. The spill direction follows the shape of the input: column arrays produce a column spill, row arrays produce a row spill, and a matrix produces a 2D spill. All array arguments must be consistent in size and orientation; mismatched arrays return a #VALUE! error.
The formula recalculates automatically when source data changes.

Argument	Required/Optional	Description
`Account`	Required	Account code for which the budget entry is created.
`Amount`	Required	Budget entry amount.
`Date`	Required	Budget entry date.
`Description`	Optional	A description of the budget entry.
`Dimensions`	Optional	A two-column Excel range, where the first column contains the name of a predefined dimension (e.g. department, customer, project etc.), and the second column contains the value for that dimension. When writing to an existing budget, make sure the dimensions you specify in this argument are part of the budget's configured dimensions. See the Using Dimensions article for more details.
`EntryNumber`	Optional	Budget entry number.
`EntryNumberOutput`	Optional	Reference to a cell where the GL budget entry numbers will be returned.

BudgetDimensions vs. Dimensions arguments

BC.WRITEBACKBUDGET uses two separate arguments for dimension-related information:

BudgetDimensions (4th argument) sets up a new budget's dimension structure. This is the equivalent of adding dimensions to a budget on the G/L Budgets page in Business Central. It tells BC which non-Global dimensions the budget should track. If omitted, the new budget tracks only the Global Dimensions.
The argument applies only when creating a new budget (ignored for existing budgets).
Do not include Global Dimensions in BudgetDimensions, as they are included for each budget by default. Specifying one returns an error.
Dimensions (10th argument) assigns dimension values to each budget entry. This argument provides the actual values for each entry. Specify dimension/value pairs for all dimensions, including those listed in BudgetDimensions.
This argument uses the standard two-column format (dimension code + value code) and allows one value per dimension.

When writing to an existing budget, make sure the dimensions you specify in the line-level Dimensions argument are part of the budget's configured dimensions.

For example, you need a new budget that tracks AREA (a non-Global dimension) in addition to the Global Dimensions DEPARTMENT and SALESPERSON.

First, provide "AREA" in the BudgetDimensions argument to assign the dimension to the budget.

Then provide values for all three dimensions in the Dimensions argument:

=VX.SETTINGS(
  "AREA", "40",
  "DEPARTMENT", "SALES",
  "SALESPERSON", "MH"
)

BudgetDimensions defines what the budget can track. Dimensions defines what each entry contains.

Dynamic awareness and spill ranges

BC.WRITEBACKBUDGET is a dynamic-aware function — its dimension arguments accept dynamic arrays and spill ranges.

This makes it possible to define a set of dimension-value pairs (for example, using HSTACK or VSTACK) and pass that range as the Dimensions argument. The function's output will spill according to the orientation and size of the input data.

A single dimension array applies to all records in the writeback, regardless of how many data rows are being written.

If the spill ranges used in different arguments are of different lengths, an error will occur.

Example

Writeback to particular dimensions

Assume the following dimension range A3:B4:

You can reference this range in your BC.WRITEBACKBUDGET formula:

=BC.WRITEBACKBUDGET(
  "BC",
  "BUDGET2025",
  "Annual Budget 2025",
  ,
  ,
  "61100",
  5000,
  "2025-01-01",
  "Q1 office budget",
  E3:F4
)

This formula writes a budget entry of 5000 to account 61100 for 1 January 2025, and assigns the dimension value codes DEPARTMENT – ADM and PROJECT – PROJ-01 in line data.