SI.WRITEBACK

Overview

The SI.WRITEBACK function sends one or more lines of values to the ERP. The function uses the fields specified in a pre-defined Object in the ERP.

Related articles

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

Syntax

=SI.WRITEBACK(
    ConnectionName,
    Object,
    Settings,
    RecordNo,
    FieldNames,
    ParentRecordReference,
    ParentRecordGroupName,
    OutputFieldNames,
    OutputRange,
    RangeOrDataItem,
    ...
)

Arguments

The SI.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 Sage Intacct object (case insensitive). Use the SI.EXPANDOBJECTRANGE function to retrieve available values.
Settings	Optional	Writeback settings - string defining the selected writeback mode. Available values: "create" "update" "create-or-update" (default) "recreate" "delete" OR A 2-column array with three rows: Mode Any of the below values "create" "update" "create-or-update" (default) "recreate" "delete" (This argument is ignored if ParentRecordReference is specified) BatchSize A number - max batch size. To avoid ERP timeouts on large writebacks and to improve responsiveness of the application, data is broken up in batches of 100 records (default). If you are processing large batches of writebacks and using screens with auto-numbered keys, you can adjust the batch size to ensure your data is not broken up in multiple records. WritebackLocation A LocationId. Set this setting to a Location Id only for entity-scoped objects (or objects' records marked as Private, in other words that are not available at the Top Level). Considering the below example, you may reference cells: $P$6:$Q$8 or use a formula instead: =HSTACK( {"Mode"; "BatchSize"; "WritebackLocation"}, VSTACK("update", 100, "") ) OR just: $P$6:$Q$7 for an object record available at the Top Level: or use this formula instead: =HSTACK( {"Mode"; "BatchSize"}, VSTACK("update", 100) ) API setting – determines the API used for writeback. See the Legacy writeback considerations section below for details. Accepted values: Standard and Legacy Default value: Standard
RecordNo	Required when the Mode argument is set to create, update, or recreate	Indicates the record number to be used for creating, updating, or recreating a record within the ERP.
FieldNames	Required	A comma-separated string OR an Excel range containing the names of the fields for writeback. To upload files as attachments, add the reserved field names ATTACHMENTFOLDER and ATTACHMENT. See the Uploading attachments section below.
ParentRecordReference	Optional	A reference to a cell containing another SI.WRITEBACK function to indicate that the current record has a child → parent relationship with the other record.
ParentRecordGroupName	Optional in most cases. Required when the parent–child pair maps to more than one XML group name (see Defaults for ParentRecordGroupName).	The name of the XML grouping element for the child entries under the parent. You can omit this argument when the parent–child pair maps to a single XML group name; Velixo applies the default automatically. Specify this argument explicitly when the parent–child pair maps to more than one possible XML group name — for example, GLACCTGRP with an ACCTRANGE or GLCOACATMEMBER child. If you omit it in those cases, Velixo creates the parent record but does not create the child, with no error returned. This argument is ignored if ParentRecordReference is not specified, or if the API setting is Legacy (in which case the XML group name is determined automatically).
OutputFieldNames	Required	An Excel cell range (or a comma-separated string) containing the field names to retrieve from the resulting object. This argument is ignored when in "delete" mode
OutputRange	Optional	The Excel range which will receive the fields of a created/updated record. This argument is ignored when in "delete" mode
RangeOrDataItem	Required	The first set of data to be sent to the ERP. The values to be written must be specified in the same order as the column/field names specified in the FieldNames argument.
...

Tips

1. As an alternative to using the Platform Services → Object screen in Sage Intacct, you may also use the SI.QUERYand/or SI.OBJECTDEFINITION functions for determining the exact column names of a given Object to use in the Writeback function.

2. The WRITEBACKCOMMIT function should be used for creating/updating/recreating parent child records (such as: Projects), so that the OutputRange value returned by the SI.WRITEBACK function can be used by subsequent SI.WRITEBACK in the same batch.

3. WRITEBACK cannot be used to update existing journal transactions within Intacct.

Defaults for the ParentRecordGroupName argument

When ParentRecordReference is set, and the parent–child pair maps to a single XML group name, you can omit ParentRecordGroupName. Velixo automatically applies the default for that pair.

For example, when the child SI.WRITEBACK formula references a parent SI.WRITEBACK formula for APBILL, ParentRecordGroupName is optional — its only valid value is APBILLITEMS, so Velixo uses it by default.

Parent–child pairs with multiple possible group names

Specify ParentRecordGroupName explicitly for these pairs.

If you omit ParentRecordGroupName for the pairs below, Velixo creates the parent record but does not create the child, and no error is returned. To avoid losing child records, always specify ParentRecordGroupName for these combinations.

Supported defaults

The table below lists the parent–child pairs for which Velixo applies a default group name when ParentRecordGroupName is omitted. The defaults apply to the standard API. With the Legacy API, the group name is always determined automatically, and any value provided is ignored.

Legacy writeback considerations

Starting with Velixo NX 2026.1, some Sage Intacct objects (for example, PODOCUMENT or OTHERRECEIPTS) can only be updated via Sage Intacct’s legacy, object‑specific functions instead of the generic Sage Intacct API. In such cases, Velixo automatically uses SI.WRITEBACK in legacy writeback mode.

As a result of this change, users whose SI.WRITEBACK formulas write back to objects PODOCUMENT, PODOCUMENTENTRY, and OTHERRECEIPTSENTRY need to update their formulas to keep writeback functional. Follow the steps outlined below to update your formulas.

1. For formulas using the PODOCUMENT object:

   1. Set the API argument to legacy.

   2. In the FieldNames argument, use VENDORID in place of CUSTVENDID.

   3. In the FieldNames argument, remove the field STATUS (it is no longer supported).

2. For formulas using the PODOCUMENTENTRY object:

   1. Set the API argument to legacy.

   2. In the FieldNames argument, use PRICE in place of UIPRICE.

   3. In the FieldNames argument, remove the field DOCPARID (DOCPARID can remain in the header).

3. For formulas using the OTHERRECEIPTSENTRY object:

   1. Set the API argument to legacy.

   2. In the FieldNames argument, use AMOUNT in place of TRX_AMOUNT.

   3. If required, add LOCATIONID to FieldNames.

4. To link child lines to headers, leverage ParentRecordReference instead of ParentRecordGroupName.

5. DOCID or RECORD_URL values may remain blank despite successful writeback. To retrieve these values, use the SI.QUERYLOOKUP function.
   For example, =SI.QUERYLOOKUP(,"PODOCUMENT",,"DOCID","RECORDNO","119") will retrieve the DOCID for the PODOCUMENT line with a RECORDNO value 119:

   

Fields available for legacy writeback objects

When creating SI.WRITEBACK formulas for legacy writeback objects, be sure to only use the field names listed below (click to expand):

Writeback scoped to document types

Some Sage Intacct objects act as containers for several document types (also refered to as transaction definitions) that share the same underlying tables. SODOCUMENT, PODOCUMENT, and INVDOCUMENT are the common examples. Each document type is a subtype of the base object, which can carry custom fields that exist only in that type – they are not present in the base object.

In SI.EXPANDOBJECTRANGE output, document types appear as the base object name followed by the document type in parentheses – for example, PODOCUMENT (Purchase Order) for the header object and PODOCUMENTENTRY (Purchase Order Detail) for the line object.

In the Sage Intacct interface, you can find the object and document type names by selecting an object in Platform Services → Object. The object name is referred to as Integration name, and the document type name is referred to as Singular name.

To write back to a document type and reach its custom fields:

1. Set the Object argument to the base object – PODOCUMENT for the header, PODOCUMENTENTRY for the lines. Do not put the parenthesized label (for example, PODOCUMENT (Purchase Order)) in the Object argument – this returns an "Invalid Character in Name" error, because the space and parentheses are not valid in an object name.

2. Add DOCPARID (the text shown in parentheses in SI.EXPANDOBJECTRANGE output) to the FieldNames argument. The header and the lines each use their own object's DOCPARID: Purchase Order for PODOCUMENT rows and Purchase Order Detail for PODOCUMENTENTRY rows. This selects the document type and makes its custom fields available for writeback.

3. Link the lines to the header by referencing the header writeback formula cell in the ParentRecordReference argument.

Refer to Example 5 for details.

Difference from querying

When you query a document type with SI.QUERY, you pass the document type directly as the object. When you write back, you keep the base object in the Object argument and identify the document type with the DOCPARID field.

Uploading attachments

You can attach files to a Sage Intacct record while you write it back (for example, a scanned vendor invoice on an AP bill). Velixo creates an attachment in Sage Intacct, adds the files to it, and links it to the record.

Requirements

Attachment upload works in Excel for Windows with Velixo Tools version 7.1.1017 or later installed. It doesn’t work in Excel for Mac or Excel for the web.

The files go into an attachment folder that must already exist in Sage Intacct, because Velixo doesn’t create folders. If the folder doesn’t exist, Sage Intacct returns the error Folder name is not valid. To list the existing folders, use the SI.EXPANDATTACHMENTFOLDERRANGE function.

You can attach files only to objects that support attachments in Sage Intacct. These objects have a SUPDOCID field; to check an object, use the SI.OBJECTDEFINITION function. The writeback mode must be create, recreate, or create-or-update.

Adding attachments to a formula

1. In the FieldNames argument, add ATTACHMENTFOLDER once, and ATTACHMENT once for each file you want to upload.

2. In the data items, provide the values in the same order as the field names. For ATTACHMENTFOLDER, enter the name of the attachment folder, for example AP Attachments. For each ATTACHMENT, enter the full path to a file, for example C:\Invoices\INV-001.pdf.

The field names aren’t case-sensitive. A file path must start with a drive letter (C:\Invoices\INV-001.pdf), a network path (\\server\share\INV-001.pdf), or a URL. Relative paths, such as Invoices\INV-001.pdf, aren’t accepted.

Velixo skips empty ATTACHMENT values, so you can keep a fixed number of attachment columns and leave some empty. If all of them are empty, the record is written back without an attachment.

Each file keeps its file name in Sage Intacct, and the files in one record must have unique names. If two files have the same name, Sage Intacct returns the error Another record with the value '' already exists. Use files that have an extension. The files for one record can total about 7 MB.

You can attach files only to a parent record. A formula that uses the ParentRecordReference argument, such as one for bill lines, can’t upload attachments. You also can’t use ATTACHMENTFOLDER and ATTACHMENT together with the SUPDOCID field.

How each mode handles attachments

When an attachment writeback fails

If a file is missing, can’t be read, or is too large, only that record fails, and the other records are still written back. If Sage Intacct rejects a record, Velixo deletes the attachment it created for that record. Sage Intacct rejects all records sent in the same request, so the other records in the batch fail too. To control how many records go into one request, use the BatchSize setting.

If any formula in the writeback fails validation, for example because ATTACHMENTFOLDER is missing, nothing is written back. Fix the error and run the writeback again.

When Sage Intacct rejects a record, the cell shows #N/A, and the full Sage Intacct error appears in the Writeback status pane. Child line formulas linked to the failed record show #VALUE!.

Sage Intacct doesn’t allow changes to a bill that is pending approval. To add attachments to such a bill, approve or recall it in Sage Intacct first.

Examples

Example 1 - Creating a new Vendor record

=SI.WRITEBACK(
    $B$4,
    $B$6,
    $D$4:$E$5,
    ,
    Table1[[#Headers],[Name]:[Status]],
    ,
    ,
    $H$4,
    $E13,
    Table1[@[Name]:[Status]]
)

Example 2 - Updating an attribute of an existing Project

=SI.WRITEBACK(
    $B$4,
    $B$6,
    $D$4:$E$5,
    [@RecordNo],
    Table2[[#Headers],[ProjectID]:[ProjectType]],
    ,
    ,
    ,
    ,
    Table2[@[ProjectID]:[ProjectType]]
)

Example 3 - Creating a record in a Private object (Cost Code Observed Percent Completed Entry scenario)

=SI.WRITEBACK(
    $K$4,
    $K$6,
    $O$4:$P$6,
    ,
    Table137[[#Headers],[TYPE]:[NOTE]],
    ,
    ,
    $P$7,
    P10,
    Table137[@[TYPE]:[NOTE]]
)

In this example, the WritebackLocation Setting is used in the 2-column Array: $O$4:$P$6, as the OBSPCTCOMPLETED object is a private object (meaning its records are "private" to a specific entity), and a specific Locationid must be referenced.

Due to a limitation within Sage Intacct, Velixo is unable to provide a specific error message to inform that the WritebackLocation argument needs to be used.

Instead, the following error message may be displayed:

Except from the message: BL01001973 Could not create obspctcompleted record

Example 4 - Update the detail data of an object without updating the header data

(using the APBILL and APBILLITEM objects)
There is a documented example of creating both header and detail information for an object. Let's look at updating only the detail portion.

Here we have both header data (from the APBILL object) and detail data (from the APBILLITEM object):

In this example, we want to change the DEPARTMENTID field at the detail-level from OPERATIONS to FINANCE.

Although we do not want to change the header data, we do need a reference to that header. So, the first thing we are going to is create a header writeback (cell I13) that does nothing except ensure that we have that reference:

All that function does is update the header with the same RECORDNO field that we already retrieved (cell A8) using the SI.QUERY function.

Now, we can create a WRITEBACK function (cell I14) that references the results of the first function (in the ParentRecordReference argument) and uses Update mode to replace the DEPARTMENTID field with the new value (cell J14) while maintaining the existing other field values (cells A14, B14, C14, D14, and F14):

After performing a Full Refresh (to clear any cached SI.QUERY data in our report), we see the updated detail data with no changes to the header:

Example 5 - creating a Purchase Order with lines

The header formula writes to PODOCUMENT, with DOCPARID set to Purchase Order as the first field. The Settings range ($D$4:$E$6) sets the mode to create, and OutputFieldNames (H4, containing DOCID) returns the created document ID to cell J10:

=SI.WRITEBACK(
    $B$4,
    $B$8,
    $D$4:$E$6,
    [@RecordNo],
    Table134565[[#Headers],[DOCPARID]:[CUSTOMFIELD]],
    ,
    ,
    H4,
    J10,
    [@DOCPARID],
    [@WHENCREATED],
    [@CUSTVENDID],
    [@WHENDUE],
    [@STATE],
    [@Status],
    [@CUSTOMFIELD]
)

Description: $B$8 contains PODOCUMENT. The FieldNames range starts with DOCPARID and continues through the header fields, including the document type-specific custom field CUSTOMFIELD. In create mode, the RecordNo cell is left empty.

The line formula writes to PODOCUMENTENTRY with DOCPARID = Purchase Order Detail on each row, and links to the header through ParentRecordReference:

=SI.WRITEBACK(
    $B$4,
    $B$13,
    $D$4:$E$6,
    [@RecordNo],
    Table1345676[[#Headers],[DOCPARID]:[TESTNBRPO]],
    Table134565[Writeback status],
    $B$14,
    ,
    ,
    [@DOCPARID],
    [@ITEMID],
    [@CONVERSIONTYPE],
    [@UIPRICE],
    [@LOCATIONID],
    [@UNIT],
    [@UIQTY],
    [@TESTNBRPO]
)

Description: $B$13 contains PODOCUMENTENTRY. ParentRecordReference points to the header writeback cell, so the lines are created under the header document. ParentRecordGroupName ($B$14) is left empty – Velixo applies the default group name for the PODOCUMENT/PODOCUMENTENTRY pair. The line fields include the document type-specific custom field TESTNBRPO.

Result:

Example 6 - Creating an AP bill with two attachments

The header formula writes to APBILL in create mode. It uploads two files to the AP Attachments folder and returns RECORDNO and SUPDOCID to K5:L5:

=SI.WRITEBACK(
    $B$1,
    "APBILL",
    "create",
    ,
    "VENDORID,WHENCREATED,WHENDUE,RECORDID,ATTACHMENTFOLDER,ATTACHMENT,ATTACHMENT",
    ,
    ,
    "RECORDNO,SUPDOCID",
    K5:L5,
    B5,
    C5,
    D5,
    E5,
    F5,
    G5,
    H5
)

Description: $B$1 contains the connection name. F5 contains AP Attachments, and G5 and H5 contain full file paths, for example C:\Invoices\INV-001.pdf and C:\Invoices\INV-001-receipt.png.

The line formula writes to APBILLITEM and links to the header through ParentRecordReference. It has no attachment fields:

=SI.WRITEBACK(
    $B$1,
    "APBILLITEM",
    "create",
    ,
    "ACCOUNTNO,TRX_AMOUNT,LOCATIONID,DEPARTMENTID",
    J5,
    ,
    ,
    ,
    B8,
    C8,
    D8,
    E8
)

Result: