JavaScript

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-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',
})

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", (message) => {
  // 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 launchSession

import oneschemaImporter from "@oneschema/importer"

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

importer.launchSession()

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

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

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

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


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)
DescriptionThe parameters that can be passed to the launch function

launchSession(params?)

The launchSession 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 (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. The format of the data will be the same as the schema of webhook payload row data if webhookKey is not included.

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 message about the error.

launched Event

The launched event will fire when the iframe is ready to display. This will happen shortly after launch is called.



OneSchemaParams

OneSchemaParams also includes 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 EU Data Residency, set this to <https://embed.eu.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

autoClose

Optional
Typeboolean
DescriptionWhether the iframe should automatically hide when completion events are emitted. 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

customizationOverrides

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

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


OneSchemaLaunchSessionParams

These values can be passed into the launchSession 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