Imports

Imports are ImportFile records created from an ImportFileTemplate. Operations follow the standard route pattern:

• /api/importfile/{operation} runs synchronously on the web server.
• /api/importfile/queue/{operation} queues the operation for an app server. Use it for imports, watches, and batches of any size.

Classes and interfaces

Type	Purpose
ImportFileTemplate	Engine, mappings, statements, validators, queue, and thresholds for a kind of import.
ImportFile	One run. PreTransformID is the source document; SuccessCount, ErrorCount, Warnings, ImportStart, ImportComplete track it.
IImportEngine	Plugin that previews, validates, and imports. Engines are registered by name in ImportEngine.config.
ImportFileMap	Column mapping: ImportFileMap (source), Destination, Translation, IsText, Required, DataType, ImportFileMapType.
ImportFileQueue	One queued ClassName/Operation with ParameterXml, plus QueuedDate, SuccessDate, FailureDate, ExecuteCount.
ImportOperationsAllowed	Flags: None = 0, Insert = 1, Update = 2, Both = 3, Invoke = 4, All = 7.

Import a file or payload

Post the file as the request body and name the template:

POST /api/importfile/importbyobject?Template=New Claims
{raw file bytes}

QBO saves the body as the source document, runs schema validation if the template enables it, then either imports immediately or, when the template is Async, queues the import. If the template’s AppliesTo matches a record the import inserted or updated, the import file is bound to that record. Errors are returned unless you pass Validate=false.

To re-run an existing import file:

GET /api/importfile/queue/import?ID=1234

Import reads the source through the engine, then checks FailureThreshold and SuccessThreshold before calling EndImport, which starts the template’s workflow (if any) and sets the status to Complete (or OnCompleteStatus).

Preview, validate, and results

GET /api/importfile/preview?ID=1234
GET /api/importfile/validate?ID=1234
GET /api/importfile/results?ID=1234

validate runs the template’s ValidateStatement and queues Import on success. results runs the template’s ResultMethod.

Watch storage for files

GET /api/importfile/queue/watch?Template=New Claims&FileObject=ClientSftp&Path=/inbound/&Pattern=*.csv&MoveTo=AmazonS3&Async=true

Parameter	Default	Notes
FileObject	required	Named storage location to list.
Path / Pattern / Depth	/, *, 0	Folder, file mask, and recursion depth.
Template or TemplateID		Import template applied to each file.
TransferTo / MoveTo		Copy (or copy and delete) each file to another storage location.
ToPath		Destination path for transfer or move.
Async / Queue	false	Queue each Import rather than running it inline.
Statement		Statement to run against the new documents (ID is the list of document IDs).
Attachment_{Field}		Values set on each created document.

For each file, QBO creates the import file first, then a document pointing at the file (recording its source path and file name), then transfers or moves it, then imports.

Detect a template

GET /api/importfiletemplate/detecttemplate?AttachmentID=5678

Returns every template whose engine reports that the document matches its schema.

Queue an operation per row

batch runs a query and queues a method signature for each row, tracked as ImportFileQueue items under a new import file:

GET /api/importfile/batch?ClassName=Contact&Operation=Search&State=CA&Signature=Decision%2FSave%3FTemplate%3DWelcome%26Object%3DContact%26ObjectID%3D%7BContactID%7D

The decoded Signature is Decision/Save?Template=Welcome&Object=Contact&ObjectID={ContactID}; {ContactID} is substituted from each row. BatchQueue sets the queue; a Queue column on a row overrides it. The source operation must return a data set, data reader, or XML.

To process a file instead, upload it as a document and call one of the batch shortcuts. Each uses the BatchReader engine:

GET /api/importfile/scorecalculatebatch?Attachment=Applications.xlsx&AttachmentID=5678&ImportFileTemplate=Application Score
GET /api/importfile/attachmentgeneratebatch?Attachment=Letters.xlsx&AttachmentID=5679&ImportFileTemplate=Welcome Letter
GET /api/importfile/messagesendbatch?Attachment=Notices.csv&AttachmentID=5680&ImportFileTemplate=Status Notice

Row columns

When BatchReader queues a row, columns map as follows:

Column	Maps to
ClassName	ImportFileQueue.ClassName (default: template AppliesTo)
Operation	ImportFileQueue.Operation (default: Save)
ImportFileQueue	Row label (default: Unknown)
ParameterString	Extra parameters for the row
_{Field}	ImportFileQueue.{Field} (for example _Status)
anything else	ParameterXml, passed to the operation as parameters

The template’s ParameterString is merged into every row, with {Column} substitution. Add LogCategory, SuccessLogCategory, or FailureLogCategory to it to log row outcomes.

Retry row items that haven’t succeeded (rows with a SuccessDate are skipped):

GET /api/importfilequeue/requeue?ID=9001,9002&Queue=Imports

Bulk engine options

Set these in the template’s ParameterString for BulkReader and BulkMerge:

Option	Default	Effect
TableName	import.[ImportFile_{ID}]	Staging table; {TableName} uses the source table or file name.
TargetTableName		Exposed to the import statement.
Connection	qbo.Default	Connection string name to bulk-copy into.
Truncate	false	Empty the staging table first.
EnsureTable	true	Create the staging table if missing.
AllowAlterColumn	false	Alter staging columns to fit the data.
IdentityColumn		Add an identity column.
BulkCopyTimeout	30	Seconds.
UseTransaction / ThrowOnError	false / false	Transaction and error behavior for the copy.
UseSafe	true	Strip spaces and special characters from column names.

Parameters

The parameters shown are the commonly used ones. Check the operation’s method signature in source (paths listed under the page title) before relying on less common options.