Allows a Workflow Import process to be started via an API call, rather than uploading a file via the UI.

Introduced in 11.0.33.

This API is intended for internal use only at this time.

We will probably open it up for 3rd party access in the future, after we’ve finished internal evaluation.

1 Overview
2 Supported features
3 Using the API
- 3.1 HTTP Request
  - 3.1.1 Purpose of “creationPath”
- 3.2 HTTP Response
- 3.3 Error messages

Overview

The Workflow Import Queue is a Workflow-enabled bulk import tool that lets users upload CSV files through the web UI to import/update data.

This API is an alternative way of starting an import process; instead of a user uploading a CSV file through the browser, and API client sends a JSON payload to the API endpoint.

The end result is the same: in both cases, a WORKFLOW_IMPORT_QUEUE_BATCH is created with one row per imported data record and is then processed on a background queue.

Manual upload vs API call to start an import queue process

Supported features

This is an alternative way of getting data into the import queue, but once the data is in the queue it supports the full set of Workflow Import Queue functionality.

The main difference is that the UI validates the data, gives the user a summary of what operations will be performed, and waits for user confirmation before actually processing the data.

There is no “prompt for confirmation” element to this API call; the posted data is added directly to the processing queue.

Using the API

Calling this API requires an API Key with the BeginWorkflowImportProcess permission.

The key should be passed using the “apikey” authorization scheme.

Authorization: apikey xxxxxxxxxxxxxxxxx

HTTP Request

For implementation reasons, this API endpoint uses querystring parameters AND a request body.

The querystring parameters provide some control data, and the request body contains the data to be imported.

The URI provides control data:

POST /API/WorkflowImportQueue/CreateBatch
?fileName={filename}
&importProcessId={id}
&creationPath={string}
&sendSuccessEmailTo={email}
&sendFailureEmailTo={email}

fileName - displayed in the “Recent Imports” part of the UI; provide a human-readable description of this particular import, such as “ACME Process {yyyy/mm/dd}”
importProcessId - the ID of the Workflow Import Queue "file type" to use;
creationPath - a string, up to 15 characters in length, consisting only of upper case letters, numbers, and underscores. See below for explanation.
sendSuccessEmailTo - (optional) an email address to notify of a successful import process
sendFailureEmailTo - (optional) an email address to notify if any records fail to process

The request body contains the data to import, using the JSON Lines format.

{ JSON data row 1, on single line }
{ JSON data row 2, on single line }
...

Each element in that array is the equivalent to a data row in an uploaded CSV file.

Purpose of “creationPath”

The purpose of the creationPath argument is to identify which Import Queue Batches were created from which external integrations.

Callers should provide a 1-15 character string, consisting of UPPER CASE letters, numbers, and underscores only, that identifies their application.

This will be prefixed with “IMPORT_QUEUE_API:” and then stored in the IMPORT_QUEUE_BATCH.CREATION_PATH column.

HTTP Response

The HTTP response contains the WORKFLOW_IMPORT_QUEUE_BATCH_ID that can be used to locate it in the system, as well as a hyperlink to the results in the UI.

Error messages

Error	Reason / How to fix

Error	Reason / How to fix

LearningBuilder Documentation

API/Library (DRAFT)