Imports

An import template captures everything about a kind of import, so the people running it only need the file.

Create a template from a sample

Drag a sample file onto the import templates search results. QBO creates a template, stores the file as its sample import, and creates a mapping for each column it finds. From the template’s summary page you can Copy the template, Import Sample File to test it, or Delete Schema and File Mapping to start the mappings over.

QBO can also detect the template for an unknown file: it asks each template’s engine whether the file matches that template’s layout, and returns the templates that do.

Template settings

Setting	Property	Purpose
Engine	ImportEngine	How the data is read and loaded. See Import engines.
Applies to	AppliesTo	The kind of record rows create by default (for example Contact).
Parameters	ParameterString	Engine options and default values for every row, in query-string form. Supports {Column} substitution.
Import statement	ImportStatement	A statement or method signature run against the data (for example, to merge a staging table).
Preview / Validate statement	PreviewStatement, ValidateStatement	Show the data before importing, and check it first.
Results method	ResultMethod	A method signature that lists what the import touched, shown on the import file.
Async / Queue	Async, Queue	Run the import on an app server, and on which queue.
Subscriber URN	SubscriberURN	A pattern such as acme.example-Order-{OrderNumber} that matches rows to records QBO already has.
Operations allowed	ImportOperationsAllowed	Whether rows may Insert, Update, or Invoke methods (or a combination).
Thresholds	FailureThreshold, SuccessThreshold	Mark the import Error if errors reach the failure threshold, or successes fall short of the success threshold.
Workflow	DecisionTemplateID, DecisionTemplateMatrixID	Start a workflow on the import file when it completes, optionally chosen by a rules matrix.
Translation matrix	TranslationMatrixID	Add or change values on each row using a rules matrix.

Import engines

Engine	Best for	How it works
BatchReader	Most row-by-row imports	Reads Excel, delimited, or query results and queues one operation per row (default: save a record of the Applies to type). Each row is tracked and can be retried.
BulkReader	Large files (100,000+ rows)	Bulk-copies the data into a staging table, then runs the import statement. Fast, but bypasses per-record API behavior such as method listeners.
BulkMerge	Large files that create several record types	BulkReader plus mappings that generate SQL MERGE statements, inserting or updating each record type in order.
JsonXsltEngine	JSON payloads	Converts JSON to XML, optionally reshapes it with the template’s XSLT, then imports the XML.
ExcelXsltEngine / TextXsltEngine	Spreadsheets or text that need reshaping	Converts the file to XML and applies the template’s XSLT before importing.
XmlEngine	XML already in QBO’s import format	Imports each item node as a record, with its child nodes as fields.
ParameterEngine	Data posted as parameters	Turns the parameters into XML, transforms it, and imports it.
TaskEngine	Task lists	Creates a task template (with a question per column) if needed, then a task per row.
GeoCodeBulkEngine	Address lists	Bulk-loads addresses and geocodes them, then runs the import statement.
SqlBulkADONetEngine	Another database	Runs a stored procedure over a named connection and bulk-copies the results into staging.
SQL	Database-side processing	Runs the import statement against the uploaded file.

Older engines (ExcelEngine, ExcelBatchEngine, ExcelBulkEngine, BatchEngine, TextBatchEngine, TextBulkEngine, SqlBulkEngine, ImportFileQueueEngine) remain for existing templates. Use BatchReader or BulkReader for new ones.

Mappings

Each mapping pairs a source column with a destination and can:

• Rename a column (Zip to PostalCode), including with wildcards (* keeps every column).
• Translate a value with an expression that references other columns.
• Add static data (mark it Text; the translation is the value).
• Require a column, so rows without it are rejected.
• Apply only on Insert or only on Update (bulk merge).

For BulkMerge, group mappings by prefix (Client., Order.), give each group a SubscriberID translation such as acme.example-Client-{Client Code}, and list the merges in the import statement in order:

{Merge.Module.Organization.Client}
{Merge.Module.Process.Order}

When several rows map to the same record, the last row wins.

Delimited and fixed-width files

Attach a schema.ini file to the template to describe columns, delimiters, or fixed widths. Add SkipIf{Column}=value lines to skip header and trailer records.

Validation and preview

• Schema validation checks the raw file before anything is imported. Failures set the import file to Validation Error.
• The validate statement checks the loaded data; failure sets Validation Failed and stops the import.
• The preview statement lets you inspect data before committing it.

Watch a folder

Schedule a watch (as a recurring job or a workflow step) to monitor a storage location such as an sFTP site, Amazon S3 bucket, or network share:

Parameter	Purpose
Template	Import template for each file found.
FileObject, Path, Pattern	Where to look and what to pick up (for example /inbound/ and *.csv).
TransferTo / MoveTo	Copy the file into QBO storage; Move also deletes the original.
Async, Queue	Queue each import instead of running it during the watch.

Each file becomes a document and an import file, then imports.

Run an operation per row

Batch runs a query and queues a method for every row it returns, tracked as an import file with one row item per result. For example: search for contacts in a state, then start a workflow on each. Built-in shortcuts upload a file and, for each row, generate a document, send a message, or calculate a score (see Scoring).

Row items read their columns as parameters. Reserved columns ClassName and Operation choose the method; prefix a column with _ to set the row item itself (for example _Status).