Acumatica Writer

Write Acumatica database template XML files

The Acumatica Writer plugin enables writing transformation results to Acumatica XML import files. It generates the proprietary XML format used by Acumatica ERP for table data import.

URI Format

The Acumatica Writer recognizes the following URI formats:

• acumatica.xml://<filepath> - Write to an Acumatica XML file

Configuration File

The Acumatica Writer requires a configuration file that defines the table schema and sorting options. The configuration file path is specified in the config attribute of the <Target> element.

Configuration File Format

<config>
    <table name="TableName" status="optional_status">
        <col name="ColumnName1" type="DataType1" default="DefaultValue1" />
        <col name="ColumnName2" type="DataType2" nullable="true" />
        <col name="ColumnName3" type="DataType3" />
        <!-- ... more column definitions ... -->
    </table>
    <sort>
        <field>SortField1</field>
        <field>SortField2</field>
        <!-- ... more sort fields ... -->
    </sort>
</config>

Configuration Elements

Table Element

• name: Table name (supports parameter substitution with %parameter%)
• status: Optional status attribute for the table

Column Elements

• name: Column name (must match a field in your transformation)
• type: Data type (e.g., Int, Char(32), NVarChar(MAX), DateTime, Bit)
• nullable: Set to "true" if the column can be null (optional)
• default: Default value name (optional)
• raw-default: Raw default value (optional)
• identity: Identity specification (optional)

Sort Element

Defines the order in which records are written to the output file. Records are sorted by the specified fields in order.

Generated XML Format

The Acumatica Writer generates XML in this format:

<?xml version="1.0" encoding="utf-8"?>
<data>
    <table name="TableName">
        <col name="Column1" type="Type1" />
        <col name="Column2" type="Type2" nullable="true" />
        <!-- ... column definitions from config ... -->
    </table>
    <rows>
        <row Column1="value1" Column2="value2" />
        <row Column1="value3" Column2="value4">
            <column name="LargeField"><![CDATA[Large content...]]></column>
        </row>
        <!-- ... more rows ... -->
    </rows>
</data>

Field Value Handling

Attribute vs. CDATA

• Short values (≤1000 characters): Written as XML attributes
• Long values (>1000 characters): Written in nested <column> elements with CDATA sections
• Exception: Fields named "Data" are always written as attributes, even if long
• Exception: Values containing ]]> are always written as attributes to avoid CDATA conflicts

Nullable Fields

Fields marked as nullable="true" in the configuration:

• Empty values: Omitted from the output (no attribute written)
• Non-empty values: Written normally

Special Fields

Three fields have special handling and are always omitted when empty:

• CompanyID
• CompanyMask
• tstamp

Tab Character Encoding

All tab characters (\t) in field values are automatically encoded as 	 (except in CDATA sections), as required by Acumatica.

Line Ending Handling

The Acumatica Writer always uses Windows-style line endings (CR+LF / \r\n), regardless of the operating system, ensuring compatibility with Acumatica ERP.

Sorting

Records are sorted in memory before being written to the output file. The sort order is determined by the <sort> section in the configuration file:

• Records are compared field by field in the order specified
• If a sort field is not found in the field list, it is ignored
• If no sort fields are configured, records are written in the order they were received

Example Configuration

Transformation Config

<Transformation>
    <Source config="delim=';'">file://some-file.csv</Source>
    <Target config="acumatica_config.xml">acumatica.xml://output.xml"</Target>
    <Fields>
        <Field name="Id">$Id</Field>
        <Field name="NeutralValue">$Value</Field>
        <Field name="IsNotLocalized">$NotLocalized</Field>
        <Field name="IsSite">$Site</Field>
        <Field name="CreatedDateTime">$Created</Field>
    </Fields>
</Transformation>

Entity Configuration File: acumatica_config.xml

<config>
    <table name="LocalizationValue">
        <col name="CompanyID" type="Int" default="Zero" />
        <col name="Id" type="Char(32)" />
        <col name="NeutralValue" type="NVarChar(MAX)" />
        <col name="IsNotLocalized" type="Bit" />
        <col name="IsSite" type="Bit" raw-default="1" />
        <col name="TranslationCount" type="Int" />
        <col name="CreatedDateTime" type="DateTime" />
        <col name="tstamp" type="Timestamp" />
    </table>
    <sort>
        <field>Id</field>
    </sort>
</config>

Example Output: output.xml

<?xml version="1.0" encoding="utf-8"?>
<data>
	<table name="LocalizationValue">
		<col name="CompanyID" type="Int" default="Zero" />
		<col name="Id" type="Char(32)" />
		<col name="NeutralValue" type="NVarChar(MAX)" />
		<col name="IsNotLocalized" type="Bit" />
		<col name="IsSite" type="Bit" raw-default="1" />
		<col name="TranslationCount" type="Int" />
		<col name="CreatedDateTime" type="DateTime" />
		<col name="tstamp" type="Timestamp" />
	</table>
	<rows>
		<row Id="0001E8CACD459989BA90C5BB548CC2CB" NeutralValue="Packaging Type -&gt; Auto and Manual" IsNotLocalized="0" IsSite="1" CreatedDateTime="2019-04-02 11:21:17.997" />
		<row Id="000289BE413833AFDB0215223ACFC75C" IsNotLocalized="0" IsSite="1" CreatedDateTime="2024-10-11 08:27:27.847">
			<column name="NeutralValue"><![CDATA[A Boolean value that indicates whether users can archive the cost roll results without updating the pending costs.]]></column>
		</row>
	</rows>
</data>

Note:

• Empty fields (CompanyID, TranslationCount, tstamp) are omitted
• Short values are written as attributes
• Long values (>1000 chars) are written in CDATA sections
• Records are sorted by Id field
• XML entities are encoded (> becomes >)
• Tab indentation is used (one tab per level)

Post-Processing

After writing the XML, the writer performs post-processing:

1. Tabs in content (not indentation) are encoded as 	
2. CDATA sections are preserved without tab encoding
3. The temporary file is replaced with the final output file

Limitations

• All records are kept in memory until FinishWrite() is called
• Large datasets may cause memory issues
• All values are written as strings; no type conversion is performed
• Arrays or complex nested structures are not supported
• Field names must match those defined in the configuration file
• The configuration file must be valid XML matching the AcumaticaEntityConfig schema

See Also

• Acumatica Reader