batchInsert
Synopsis
InsertTaskResult[] batchInsert(SessionId sessionId,
InsertTask[] tasks,
BatchInsertOptions? options)
throws BasketServiceFault;
See also: SessionId
The batchInsert operation replaces multiple calls used to create a folder structure and paste OBX files with one call, significantly reducing communication latency. It also creates user article items and text items and sets properties of newly created or pasted items, avoiding separate setItemProperties calls.
tasks is a list of tasks of abstract type InsertTask. Depending on its concrete type, a task creates an item and sets its properties, or pastes one OBX file. Supported types are InsertFolderTask, InsertUserArticleTask, InsertTextItemTask and PasteTask.
Every taskId must be a valid Unicode identifier unique within this invocation. A non-empty parentTaskId must be a valid Unicode identifier identifying an InsertFolderTask earlier in tasks. A parentItemId that is present, non-empty and not the Nil UUID must identify a basket folder existing when this operation was invoked. If parentTaskId is missing or empty and parentItemId is missing, empty or the Nil UUID, the top folder is used. The parent item must be a folder; batchInsert is currently more restrictive in this respect than insertFolder, insertUserArticle and insertTextItem.
InsertFolderTask creates a Folder item using properties.name as its initial name, or an empty string if unspecified. It then applies additional properties as setItemProperties does, possibly replacing that initial name. InsertUserArticleTask and InsertTextItemTask work similarly for UserArticle and Text items. InsertUserArticleTask may also set composableGeometry as setItemProperties does.
PasteTask pastes one OBX file and optionally applies itemProperties. For each property entry, itemId must be the ID of an item in the OBX file, and there must be no more than one entry for each pasted item. An unknown itemId causes task failure after the items have been pasted and all preceding property entries have been processed. BatchInsertOptions contains the same options as PasteOptions and applies them to PasteTask in essentially the same way; original IDs are returned through InsertTaskResult.
Execution has two steps. First, all arguments, including the properties to be set, are checked. A failed check terminates the operation with BasketServiceFault. Once validation has succeeded, the operation is guaranteed not to terminate abnormally with BasketServiceFault.
Second, the insert and paste tasks are executed. A failure stops the current task, records its reason in faultMessage and does not abort the operation or affect other tasks. The exception is an InsertFolderTask that fails to create the folder, rather than merely failing to set its properties: dependent tasks referencing its taskId as parentTaskId fail too.
The operation returns one InsertTaskResult per input task. Results are currently returned in task order, but clients must match tasks and results by taskId and must not rely on the order. A present, non-empty faultMessage indicates failure and has the same format as a BasketServiceFault message.
For an insert task, insertedItemIds is empty if insertion failed and contains one ID if insertion succeeded. For PasteTask, it may contain multiple IDs or no IDs for an empty OBX file. insertedItemIds and faultMessage may both be non-empty when insertion or pasting succeeded but setting properties failed.
For PasteTask with returnOriginalItemIds=true, originalItemIds contains the original OBX IDs. It has exactly the same length as insertedItemIds; corresponding IDs are stored at the same index.