Guides

JavaScript

Suggest Edits

Getting Started

The OneSchema Importer package contains JavaScript utilities to help embed OneSchema into your application

Installation

You can install this package with npm:

npm i --save @oneschema/importer

or with a script tag:

<script src="https://d3ah8o189k1llu.cloudfront.net/oneschema-importer-0.5.latest.min.js"></script>

Sample usage

import oneschemaImporter from "@oneschema/importer"

const importer = oneschemaImporter({
  /* required here */
  clientId: 'YOUR_CLIENT_ID',
  /* required here or at launch */
  templateKey: 'YOUR_TEMPLATE_KEY',
  userJwt: 'YOUR_USER_JWT',
  /* optional */
  importConfig: { type: "local" },
  devMode: true,
  className: 'oneschema-importer',
  styles: {
     position: 'fixed',
     top: '0',
     left: '0',
     width: '100vw',
     height: '100vh',
     zIndex: '1000',   
  }
})

importer.launch()
// OR
// pass overrides and values not specified at creation time:
importer.launch({
  templateKey: 'YOUR_TEMPLATE_KEY',
  userJwt: 'YOUR_USER_JWT',
  importConfig: { type: "local" }
})

importer.on("success", (data) => {
  // handle success
})

importer.on("cancel", () => {
  // handle cancel
})

importer.on("error", (error) => {
  // handle error
})

Advanced usage

Using session tokens from API

You can start an embedding session via API and then use in the session token during init and using launch

import oneschemaImporter from "@oneschema/importer"

const importer = oneschemaImporter({
  clientId: clientId,
  sessionToken: token,
})

importer.launch()

importer.on("success", (data) => {
  // handle success
})

importer.on("cancel", () => {
  // handle cancel
})

importer.on("error", (error) => {
  // handle error
})

Using session tokens from SDK

The launched event will emit a session token which can be used to resume a session. By default, OneSchema will save the session token and resume in case the session was not closed through normal means (usually the browser closing or refreshing). It will not resume if the user cancels the session or if it ends. This behavior is done through the saveSession param.

If you would like to manually resume a session, you can save the session token from the launched event and then later pass it into an importer session at launch. Once a session is complete (through success, error, or cancel), it should no longer be used to init.

The following code snippet shows how you can save the session token to a variable and use later. Consider also saving to something more persistent, like browser storage.

importer.launch()

let sessionToken = null;

importer.on("launched", (data) => {
  sessionToken = data.sessionToken
})


// ... later!

importer.launch({ 
  sessionToken,
})

API Reference

Table of Contents

oneschemaImporter Function (default export)

The default export of the package is a function which will return a OneSchemaImporterClass.

Sample usage:

import oneschemaImporter from "@oneschema/importer"

const importer = oneschemaImporter(params)

params

Required
TypeObject (OneSchemaParams)
DescriptionThe parameters given at initialization

OneSchemaError

This represents an error that's happened in the importer.

message

Required
Typestring

severity

Required
Typeenum (OneSchemaErrorSeverity)

OneSchemaErrorSeverity

values

Error"error"
Fatal"fatal"

OneSchemaImporterClass

The OneSchemaImporterClass is used to integrate OneSchema into your application. It inherits from the EventEmitter class to emit events that happen in OneSchema.

Sample usage:

importer.launch(params)

importer.close(clean)

importer.on('success', (data) => {
  console.log(data)
})

importer.on('cancel', () => {
  console.log('OneSchema embed flow cancelled')
})

importer.on('error', (message) => {
  console.log(message)
})

launch(params?)

The launch function will show the OneSchema iframe and begin an importing session. Optionally, pass in params as overrides or that were not given during initialization.

Returns an OneSchemaLaunchStatus object with launch status

params

Optional
TypeObject (OneSchemaLaunchParams) or Object (OneSchemaLaunchSessionParams)
DescriptionThe parameters that can be passed to the launch function

close(clean = false)

The close function will hide the OneSchema iframe from view.

clean

Optional
Typeboolean
DescriptionIf true, will remove and clean up all listeners and remove the iframe from DOM. By default, false

setClassName(className)

className

Required
Typestring
DescriptionThe CSS class that should be set on the iframe. Replaces existing value

setStyles(styles)

styles

Required
TypeObject (CSSStyleDeclaration)
DescriptionThe CSS styles that should be set on the iframe. Replaces existing values

setParent(parent)

parent

Required
TypeHTMLElement
DescriptionThe HTML Element the iframe should be appended to. When called, the iframe will move in the DOM. This will cause the iframe's page to reload.

setIframe(iframe)

iframe

Required
TypeHTMLIFrameElement
DescriptionThe iframe the class should manage. This will set the URL and event listeners for this iframe. This should be used with the OneSchemaParam manageDom set to false.

success Event

The success event will fire when the import is complete. The parameter to the callback will include the data that has been imported for "local" imports. The format of the data is documented here.

For webhook imports, the result will be an object with eventId and responses:

The eventId field will contain a string identifier that was included in the webhook requests. You can use this to associate the user’s session with the requests sent to your webhook. (You could also use the user JWT, which is also sent with the webhook requests, to do this.)

The responses field returns the bodies of the responses sent by your webhook endpoint. It is entirely fine to return nothing at all — you can return whatever data you’d like here. It will be array of objects with a body field containing the response, and a sequenceNumber field that indicates which request returned that response. Once this data is sent to your app you can use it however you want to guide the rest of the user’s import process.

cancel Event

The cancel event will fire when the import is cancelled.

error Event

The error event will fire when an error occurs during the import. The parameter to the callback will be a OneSchemaError.

launched Event

The launched event will fire when the iframe is ready to display. This will happen shortly after launch is called. The event data will include a field named sessionToken which can be used to resume a session manually.

OneSchemaParams

OneSchemaParams also includes one of OneSchemaLaunchParams or OneSchemaLaunchSessionParams so that you can include any of the launch params.

clientId

Required
Typestring
DescriptionImporter client Id from the OneSchema dashboard

baseUrl

Optional
Typestring
DescriptionIf you are a customer with multi-region hosting, set this to <https://embed.[region].oneschema.co>.

className

Optional
Typestring
DescriptionCSS class which will be set on the iframe. Defaults to: oneschema-iframe

parentId

Optional
Typestring
DescriptionHTML Id tag for an element the iframe should be appended to. By default, appends to document.body

styles

Optional
TypeObject (CSSStyleDeclaration)
DescriptionCSS styles which will be set on the iframe.

devMode

Optional
Typeboolean
DescriptionWhether OneSchema should be in developer mode. Defaults to reading process.env.NODE_ENV and will be false if NODE_ENV is production, otherwise true.

languageCode

Optional
Typestring
DescriptionOptional language code (like 'en' or 'zh') to force importer language. By default, will use user's set language. Requires enterprise licensing

Supported languages documented here

autoClose

Optional
Typeboolean
DescriptionWhether the iframe should automatically hide when completion events are emitted. Defaults to true.

saveSession

Optional
Typeboolean
DescriptionWhether the SDK should save session information to browser storage so that an import can be resumed (if someone closes the browser and returns). The session is saved based on the JWT and template key. This will not save the session if it is 'cancelled'.
Defaults to true.

manageDOM

Optional
Typeboolean
DescriptionWhether the class should create and append an iframe to the DOM. If false, you will need to make an iframe and pass the reference to the class via setIframe so that it can be used. Defaults to true.

OneSchemaLaunchParams

These values can be passed into the launch function or with the OneSchemaParams at initialization

userJwt

Required
Typestring
DescriptionThe JWT to be used for authentication. See generating a secure JSON Web token for a user for more information about setting up a JWT

templateKey

Required
Typestring
DescriptionThe key for the template that should be used in the import. See Creating and Editing Templates for more information about templates

customizationKey

Optional
Typestring
DescriptionKey for the customization that has been created in the dashboard to be used with this importer. See Multiple Customizations for more information

customizationOverrides

Optional
TypeOneSchemaCustomization (See Customizations)
DescriptionValues that will override the saved customization from your dashboard

templateOverrides

Optional
TypeOneSchemaTemplateOverrides (See Templates)
DescriptionValues that will override the saved template and template columns to be used with this importer.

importConfig

Optional
TypeObject (ImportConfig)
DescriptionConfiguration for how data will be imported out of OneSchema when the import is complete. If not specified, will be a full LocalImportConfig

eventWebhookKeys

Optional
Typestring[]
DescriptionAn array of strings for event webhooks to be triggered during the import. For more information, see Using Event Webhooks.

OneSchemaLaunchSessionParams

These values can be passed into the launch function or with the OneSchemaParams at initialization

sessionToken

Required
Typestring
DescriptionUnique string key which identifies the configuration that the OneSchema importer should initialize as. To be used when initializing the importer via external API.

config

Optional
TypeObject (OneSchemaConfig)
DescriptionConfig for OneSchema importing behavior

OneSchemaLaunchStatus

success

Required
Typeboolean
DescriptionWhether the launch was successful or not

error

Optional
Typeenum (OneSchemaLaunchError)
DescriptionIf success is false, will be included with enum value of error

OneSchemaLaunchError

values

MissingTemplatetemplateKey was not passed in at init or launch
MissingJwtuserJwt was not passed in at init or launch
MissingSessionTokensessionToken was not passed in at init or launch

ImportConfig

Configuration for how data will be imported out of OneSchema when the import is complete.

An import config is one of the following types:

LocalImportConfig

type

Required
Type"local"

metadataOnly

Optional
Typeboolean
DescriptionWhether the import should only include metadata. This can then be used inconjuction with the API to get data. If false, all row data will be included in the import

WebhookImportConfig

type

Required
Type"webhook"

key

Required
Typestring
DescriptionThe webhook key which has been setup inside OneSchema the data should be sent to when the import is complete

FileUploadImportConfig

type

Required
Type"file-upload"

url

Required
Typestring
DescriptionThe signed url that the file should be sent to

format

Optional
Typestring ("csv" | "json")
DescriptionThe type of file that should be sent. Defaults to "csv"

headers

Optional
TypeObject { [key: string] : string }
DescriptionRequest headers that should be sent on the PUT request. Header names should not contain underscores and should be all lowercase. Header values must be strings.

Updated 5 months ago