Embedding the Uploader in your Web App

Overview

This page outlines the implementation process for installing an Osmos Uploader button from the Osmos platform onto your webpage.

Prerequisites

  1. 1.
    Destination Connector
  2. 2.
    Uploader HTML Snippet (Provided in Uploader Setup)
  3. 3.
    Access to your webpage HTML

Implementing an Uploader on your Webpage

Step 1: Navigate to your web hosting provider's page configuration menu
Step 2: Copy the HTML Snippet from the Osmos Application
Uploader snippet
Step 3: Paste the snippet into your web page at the point where you'd like it to display on the page. Include both script tags and the button element together.
Step 4: Edit the snippet to set custom displayName and description values for schema. These will be shown to the user in place of the actual name. Note that you should not change the ordering of the fields from the order it appears in the snippet example.
Step 5: Edit the snippet to set a custom uploadDescription which will also be shown to users when they click the button.

Optional: Custom Styling

Optionally set custom styling on the button element. This can be done either by setting a style property on the element itself or via css with the .ftl-button class.

Optional: Additional Configuration

There are a number of additional options that can be modified in the initial osmos.configure function call to customize the uploader further. Below is a configured sample Uploader with a single field:
osmos.configure({
schema: {
fields: [
{
name: "Sample Field",
displayName: "Sample Field",
description: "<a sample of a field>"
}
]
},
token: '123abc',
uploadDescription: "<Sample Uploader 1>"
maxRecords: 100_000,
hideUploadSchema: true,
hideUploadDescription: true,
completionHandler: async () => {},
});
uploadDescription: A standard output of the HTML snippet which must be configured. This function shows a description of the Uploader to a user.
maxRecords: Not a standard output of the HTML snippet. This function defines the maximum amount of records or rows to display and validate. This defaults to 100_000. This also limits the amount of records that will be sent to validation webhooks. Setting a lower limit can be useful if your users are encountering performance issues when uploading large files or if your validation webhooks fail with large payloads.
hideUploadSchema: A standard output of the HTML snippet which defaults to true. This function will be called when the user closes the Uploader. It will be called with the following arguments:
  • originalFileUrl - string | undefined, the url the submitted file was uploaded to or undefined if they closed the uploader before submitting
  • reachedTransformStep - boolean, whether the user reached the transform step
  • successfullySubmittedData - boolean, whether the user's data was successfully submitted or not
  • numRecordsSubmitted - number, the number of records submitted
  • skippedRowNumbers - number[], the indices of rows from the original file that were manually skipped by the user
hideUploadDescription: A standard output of the HTML snippet which defaults to true. This function determines whether to show the destination description when the user is uploading their file.
completionHandler: Not a standard output of the HTML snippet. This function determines whether to show an "upload complete" callback when the user upload has been completed.

Testing the Uploader

To view the uploaded data, navigate to Uploaders in the Osmos Application and select the Uploader you created
Click View to verify proper collection of records
Copy link
On this page
Overview
Prerequisites
Implementing an Uploader on your Webpage
Optional: Custom Styling
Optional: Additional Configuration
Testing the Uploader