API Reference

Table of Contents


oneschemaImporter Function (default export)

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

Sample usage:

import oneschemaImporter from "@oneschema/importer"

const importer = oneschemaImporter(clientId, iframeConfig, baseUrl)

clientId

Required
Typestring
DescriptionImporter client Id from the OneSchema dashboard

iframeConfig

Optional
Typeobject (IframeConfig)
DescriptionConfiguration object for how the iframe will be configured

baseUrl

Optional
Typestring
DescriptionIf you are a customer with EU Data Residency, set this to https://embed.eu.oneschema.co.


OneSchemaImporter Class

The OneSchemaImporter class is used to integrate OneSchema into your application. It inherits from an EventEmitter class. Events will be emitted based on what happens in OneSchema.

Sample usage:

importer.launch(config)

importer.close(open)

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

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

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

launch(config)

The launch function will show the OneSchema iframe and start an import based on the given config.

config

Required
TypeObject (OneSchemaImporterConfig)
DescriptionThe configuration for OneSchema to be used for importing data

close(clean = false)

The close function will hide the OneSchema iframe from view.

clean

Optional
Typeboolean
DescriptionIf true, it will remove and clean up all listeners and remove the iframe from DOM. By default, 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.

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.



IframeConfig

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

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.

autoClose

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


OneSchemaImporterConfig

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

webhookKey

Optional
Typestring
DescriptionThe key for the webhook that data should be sent to after import. See Importer Webhook for more information about webhooks

options

Optional
Typeobject (OneSchemaImporterConfigOptions)
DescriptionOptions for OneSchema importing


OneSchemaImporterConfigOptions

blockImportIfErrors

Optional
Typeboolean
DescriptionWhether to block imports if there are any errors in the sheet. Defaults to true

OneSchemaImporter React Component

This component is the default export from the @oneschema/react package.

Here is a sample usage:

      <OneSchemaImporter
        /* managing state from your application */
        isOpen={isOpen}
        onRequestClose={() => setIsOpen(false)}
        /* required config values */
        clientId={clientId}
        userJwt={token}
        templateKey={templateKey}
        /* optional config values */
        webhookKey={webhookKey}
        blockImportIfErrors={true}
        devMode={process.env.NODE_ENV !== "production"}
        className="oneschema-importer"
        parentId="oneschema-container"
        baseUrl="https://embed.eu.oneschema.co"
        /* handling results */
        onSuccess={handleData}
        onCancel={() => console.log("cancelled")}
        onError={(message) => console.log(message)}
      />

You will need to manage state for whether the embed should be shown through isOpen and onRequestClose

isOpen

Required
Typeboolean
DescriptionWhether the iframe for the embed should be opened

onRequestClose

Optional
TypeFunction (() => void)
DescriptionThis callback is called when the embed import is complete (regardless of success, error, or cancelled). This should set the isOpen property to false.

clientId

Required
Typestring
DescriptionImporter client Id from the OneSchema dashboard

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

webhookKey

Optional
Typestring
DescriptionThe key for the webhook that data should be sent to after import. See Importer Webhook for more information about webhooks

blockImportIfErrors

Optional
Typestring
DescriptionWhether imports should be blocked if there are any errors in the sheet. Defaults to true

devMode

Optional
Typestring
DescriptionWhether the importer should be in devMode. This will show more helpful information to developers, but should be turned off when you deploy. Defaults to process.env.NODE_ENV !== 'production'

className

Optional
Typestring
DescriptionThe CSS class of the iframe. Defaults to: oneschema-iframe

parentId

Optional
Typestring
DescriptionThe id of an HTML element the iframe should be appended to. By default appends to document.body

baseUrl

Optional
Typestring
DescriptionIf you are a customer with EU Data Residency, set this to https://embed.eu.oneschema.co.

onSuccess

Optional
TypeFunction ((data) => void)
DescriptionThis callback is called when the import is completed successfully. It will send data in the format of schema of webhook payload row data as a parameter.

onError

Optional
TypeFunction ((message) => void)
DescriptionThis callback is called when an error occurs during the import. It will send a string message as a parameter

onCancel

Optional
TypeFunction (() => void)
DescriptionThis callback is called when the user cancels the import into OneSchema.