Uploader with Validation

File upload input and drag-and-drop area; submits files to Avalara's File Validator Service

Demo

Fully functional aui-uploader demo

The uploader on this page shows all the states available (resting, file staging, loading, and disabled), but does not communicate with the File Validator Service. The aui-uploader page in our Pioneer app features a fully functional aui-uploader component, including file validation. The Pioneer app provides the access token required for communication with FVS. You will need to log in with Avalara Identity QA credentials.

Accessing the File Validator Service

The File Validator Service, which is a dependency for this component, is currently available for use only in selected Avalara products. If you are interested in using this service, post a message in the #file-validator-service Slack channel.

API

Tag

Name	Description
`<aui-uploader>`	Custom Element, accepts content

Methods

Name	Description
`reset()`	Call this method to reset uploader to default state

Slots

Name	Required	Description
`guidelines`		Element that contains guidelines for file upload (including maximum file size, accepted file types, maximum number of data rows, etc.)
`loading`		Element that contains HTML to be displayed while the files are being uploaded.
`disabled-content`		Element that contains HTML to be displayed when the uploader is given the `disabled` attribute.

Attributes

Name	Value	Description
`i18n`	string	A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
`configurationid`	string	You will need to register a configuration ID with the File Validator Service. Separate configuration IDs are required for prod and QA environments.
`accept`	string	Comma-separated list of accepted file types.
`multiple`	Boolean attribute	Allows users to upload multiple files.
`filelimit`	integer string	Limits the number of files that can be uploaded.
`callbackurl`	string	The callback URL, if any, to be used by the File Validator Service to report results. Apps will typically use the websocket (automatically handled by this component) for notifications, so the callback URL should not be necessary in the majority of cases.
`staginginlinecta`	Boolean attribute	Indicates that attached files should display in a staging area before the user chooses to send them to the validation service, and specifies that the "Cancel" and "Continue" buttons should be displayed in the uploader.
`stagingexternalcta`	Boolean attribute	Indicates that attached files should display in a staging area before the user chooses to send them to the validation service, and specifies that the "Cancel" and "Continue" buttons will be displayed outside the uploader. These buttons must be implemented by the app, and clicking the "Continue" button must set the `startvalidation` attribute to `true`.
`startvalidation`	Boolean attribute	Indicates that the uploader should begin the validation process. Required when `stagingexternalcta` is set to `true`.
`ctatext`	string	When used in conjunction with `staginginlinecta`, replaces the "Continue" button text with the provided string.
`disabled`	Boolean attribute	Indicates that `slot="disabled-content"` content should be displayed and drag-and-drop functionality should be disabled.
`basic`	Boolean attribute	Displays basic `aui-uploader` variant.
`retries`	Integer string	The maximum number of times the component will retry uploading a file to the File Validator Service. Defaults to 1.

Properties

Name	Value	Description
`i18n`	object	A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
`configurationId`	string	You will need to register a configuration ID with the File Validator Service. Separate configuration IDs are required for prod and QA environments.
`accept`	string	Comma-separated list of accepted file types.
`multiple`	Boolean attribute	Allows users to upload multiple files.
`fileLimit`	integer string	Limits the number of files that can be uploaded.
`callbackUrl`	string	The callback URL, if any, to be used by the File Validator Service to report results. Apps will typically use the websocket (automatically handled by this component) for notifications, so the callback URL should not be necessary in the majority of cases.
`stagingInlineCta`	Boolean attribute	Indicates that attached files should display in a staging area before the user chooses to send them to the validation service, and specifies that the "Cancel" and "Continue" buttons should be displayed in the uploader.
`stagingExternalCta`	Boolean attribute	Indicates that attached files should display in a staging area before the user chooses to send them to the validation service, and specifies that the "Cancel" and "Continue" buttons will be displayed outside the uploader. These buttons must be implemented by the app, and clicking the "Continue" button must set the `startvalidation` attribute to `true`.
`startValidation`	Boolean attribute	Indicates that the uploader should begin the validation process. Required when `stagingexternalcta` is set to `true`.
`ctaText`	string	When used in conjunction with `staginginlinecta`, replaces the "Continue" button text with the provided string.
`disabled`	Boolean attribute	Indicates that `slot="disabled-content"` content should be displayed and drag-and-drop functionality should be disabled.
`basic`	Boolean attribute	Displays basic `aui-uploader` variant.
`retries`	Integer string	The maximum number of times the component will retry uploading a file to the File Validator Service. Defaults to 1.
`requestCurrentAccessToken`	Function	Function that returns a Promise resolving to `{accessToken: "<avalara-ui-access-token>"}`.
`modifyDestinationFileKey`	Function	Function that modifies each attached file's name to create a key in the destination S3 bucket. The key will be the filename if this function is not provided.

Events

Name	Detail
`s-attach`	Emitted when files are dropped in the dropzone or selected via system dialog. An array of `files` that have been attached to the form is available in `e.detail.files`.
`s-remove`	Emitted when a file is removed from the staging area. The file that has been removed is available in `e.detail.file`.
`s-validate`	Emitted when validation results are returned for all files. See guidelines below for information about `e.detail`.
`s-error`	Emitted when an error occurs in the file upload process. The error message is available in `e.detail.error`. Note that it is not considered an error when a file fails validation. Any file that successfully undergoes the validation process -- whether it passes or fails -- will be found in the `s-validate` event payload.
`s-validationstart`	Emitted when the upload/validation process begins. The uploader `id` is available in `e.detail.id`. Once this event is fired, the uploader can be removed from the DOM and the upload and validation processes will still occur.
`s-overlimit`	Emitted when the number of files attached to the uploader exceeds the `filelimit`. The uploader `id` is available in `e.detail.id`.

Demo

Fully functional aui-uploader demo

Accessing the File Validator Service

API

Tag

Name
`<AuiUploader>`

Slots

Name	Required	Description
`guidelines`		Element that contains guidelines for file upload (including maximum file size, accepted file types, maximum number of data rows, etc.)
`loading`		Element that contains HTML to be displayed while the files are being uploaded.
`disabled-content`		Element that contains HTML to be displayed when the uploader is given the `disabled` attribute.

Props

Name	Value	Required	Description
`i18n`	object		A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
`configurationId`	string		You will need to register a configuration ID with the File Validator Service. Separate configuration IDs are required for prod and QA environments.
`requestCurrentAccessToken`	function		Function that returns a Promise resolving to `{accessToken: "<avalara-ui-access-token>"}`. The access token must have at least 5 seconds of life remaining.
`modifyDestinationFileKey`	Function		Function that modifies each attached file's name to create a key in the destination S3 bucket. The key will be the filename if this function is not provided.
`accept`	string		Comma-separated list of accepted file types.
`multiple`	Boolean		Allows users to upload multiple files.
`fileLimit`	integer		Limits the number of files that can be uploaded.
`callbackUrl`	string		The callback URL, if any, to be used by the File Validator Service to report results. Apps will typically use the websocket (automtically handled by this component) for notifications, so the callback URL should not be necessary in the majority of cases.
`stagingInlineCta`	Boolean		Indicates that attached files should display in a staging area before the user chooses to send them to the validation service, and specifies that the "Cancel" and "Continue" buttons should be displayed in the uploader.
`stagingExternalCta`	Boolean		Indicates that attached files should display in a staging area before the user chooses to send them to the validation service, and specifies that the "Cancel" and "Continue" buttons will be displayed outside the uploader. These buttons must be implemented by the app, and clicking the "Continue" button must add the `startvalidation` prop to the AuiUploader.
`startValidation`	Boolean		Indicates that the uploader should begin the validation process (use when `stagingExternalCta` is set to `true`).
`ctaText`	string		When used in conjunction with `staginginlinecta`, replaces the "Continue" button text with the provided string.
`disabled`	Boolean		Indicates that `slot="disabled-content"` content should be displayed and drag-and-drop functionality should be disabled.
`basic`	Boolean attribute		Displays basic `aui-uploader` variant.
`retries`	Integer		The maximum number of times the component will retry uploading a file to the File Validator Service. Defaults to 1.
`onS-attach`		Handles the `s-attach` event emitted when files are dropped in the dropzone or selected via system dialog. An array of `files` that have been attached to the form is available in `e.detail.files`.
`onS-remove`		Emitted when a file is removed from the staging area. The file that has been removed is available in `e.detail.file`.
`onS-validate`	Function		Handles the `s-validate` event emitted when validation results are returned for all files. See guidelines above for information about `e.detail`
`onS-error`	Function		Handles the `s-error` event emitted when an error occurs in the file upload process. The error message is available in `e.detail.error`. Note that it is not considered an error when a file fails validation. Any file that successfully undergoes the validation process -- whether it passes or fails -- will be found in the `s-validate` event payload.
`onS-validationstart`	Function		Handles the `s-validationstart` event emitted when the upload/validation process begins. The uploader `id` is available in `e.detail.id`. Once this event is fired, the uploader can be removed from the DOM and the upload and validation processes will still occur.
`onS-overlimit`	Function		Handles the `s-overlimit` event emitted when the number if files attached exceeds the `fileLimit`. The uploader `id` is available in `e.detail.id`.

React implementation notes

Using refs to call reset method

In order to call the reset() method, you must create a ref, assign it to the AuiUploader, and then use ref.current to access the method:

    
    const auiUploaderRef = React.createRef(); 
    
    function reset() {
      auiUploaderRef.current.reset();
    }
    
    return (
      <AuiUploader ref={auiUploaderRef} />
    )

Typescript

Exported types

// s-validate event's e.detail export type SValidateData = { filesPassedValidation: File[]; filesFailedValidation: File[]; }; // s-error event's e.detail export type ErrorData = { error: string; }; // s-attach event's e.detail export type SAttachFilesData = { files: File[]; }; // s-remove event's e.detail export type SRemoveData = { file: File; }; // s-validationstart event's e.detail export type SValidationStartData = { id: string; }; // s-overlimit event's e.detail export type SOverLimitData = { id: string; }; // File object used in above types export type File = { name: string; didValidate: boolean; validationId?: number; key?: string; isProcessed?: boolean; retries?: number; errorMessages: string[]; validationStatuses: object; typeIconName?: string; size: number; lastModified: Date; url: string; };

Skylab React links

General information about using our React package

i18n Strings

ID	Description	Default value
`"auiUploader.processingTextMultiple"`	The default text displayed while files are being uploaded (when uploader has the `multiple` attribute).	Processing the files...
`"auiUploader.processingTextSingle"`	The default text displayed while a file is being uploaded.	Processing the file...
`"auiUploader.uploaderLabel"`	The file uploader input's label.	File uploader
`"auiUploader.confirmLeavePage"`	The text that may appear (depending on the browser) to warn users when they try to navigate away from the page with files staged.	Import still processing. Leaving the page will cancel your import. Are you sure you want to leave?
`"auiUploader.chooseFileSingle"`	The CTA button text in the uploader's resting state.	Choose a file
`"auiUploader.chooseFilesMultiple"`	The CTA button text in the uploader's resting state (when uploader has the `multiple` attribute).	Choose files
`"auiUploader.cancelButton"`	The cancel button text in the uploader's staging state.	Cancel
`"auiUploader.continueButton"`	Default text fo rthe CTA button in the uploader's staging state.	Continue
`"auiUploader.ariaLabel.remove"`	The `aria-label` of each staged file's "remove" button.	Remove file
`"auiUploader.dragDropFileSingle"`	Header in the uploader's guidelines.	Drag and drop a file here
`"auiUploader.dragDropFilesMultiple"`	Header in the uploader's guidelines (with `multiple` attribute).	Drag and drop files here
`"auiUploader.dropFileSingle"`	Dragover state text.	Drop the file here
`"auiUploader.dropFilesMultiple"`	Dragover state text (with `multiple` attribute).	Drop the files here
`"auiUploader.chooseFileToUploadSingle"`	Label for non-DnD-enabled uploader.	Choose file to upload
`"auiUploader.chooseFilesToUploadMultiple"`	Label for non-DnD-enabled uploader (with `multiple` attribute).	Choose files to upload

Guidelines

Providing the access token

Your app must set (via the requestCurrentAccessToken property) a function that returns a Promise resolving to {accessToken: "<avalara-ui-access-token>"}. The access token must have at least 5 seconds of life remaining.

Avalara Identity access tokens are short-lived by default, so it is essential that the requestCurrentAccessToken function either fetch an access token fresh from the server or have knowledge of a particular access token's expiration so it does not deliver a stale access token.

A sample implementation is shown in the Pioneer Demo app

File validation

This component opens a websocket when it is created. When files are attached, it sends files to the File Validator Service and then dispatches a custom event (s-validate) when all validation results have been received via the websocket. Once the s-validate event has been dispatched, the websocket is closed and the component can be removed from the DOM if desired. If the websocket fails to open, the uploader will instead poll the File Validator Service until it receives all validation results, and then the s-validate event will be fired.

See the FVS wiki page for more information about the API.

The s-validate object

The s-validate event contains the following object on e.detail:

    
      {
        filesPassedValidation: [
          {name: "file name (string)", key: "S3 Bucket Key (string)", validationId: "validationId-from-FVS"}
        ],
        filesFailedValidation: [
          {name: "file name (string)", type: "failure type (string)", message: "error message (string)", validationId: "validationId-from-FVS"}
        ]
      }

Failure types

Possible failure type and message strings in the s-validate object:

`type`	`message`
`maxsize`	The file is too large. Check the file size requirements.
`accept`	The file format isn’t supported. Check the file format requirements.
`filename`	The file name exceeds the 681 character limit. Shorten the file name.
`virus`	There could be an issue with this file. Scan the file using your security or virus protection software to make sure the file is safe.
`notvalidated`	The file couldn’t be validated. Please try uploading the file again.

CORS errors

Some users have reported seeing a CORS error returned when attempting to initialize the component or validate a file. If you receive such an error, please validate that your access token maps to the correct env attribute and that it is not stale per the access token guidelines.

For prod and sbx, File Validation Service accepts both production and sandbox AI tokens. For lower environments, the following types of tokens are accepted:

awsfqa reference tokens
awsfqa JWTs
Okta QA JWTs
Okta CI JWTs

If errors persist, post on the #file-validator-service Slack channel

Environment

In order to use lower environment URLs for external links (e.g. header links, aui-uploader API calls, etc.), you may optionally set the environment as an attribute on the script tag where you load the aui.min.js script as seen below. We typically recommend using qa for lower environments.

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com

Demo

Processing the files...

Uploading is unavailable

Fully functional aui-uploader demo

Accessing the File Validator Service

API

Tag

Methods

Slots

Attributes

Properties

Events

Demo

Fully functional aui-uploader demo

Accessing the File Validator Service

API

Tag

Slots

Props

React implementation notes

Using refs to call reset method

Typescript

Exported types

Skylab React links

i18n Strings

Guidelines

Providing the access token

File validation

The s-validate object

Failure types

CORS errors

Environment

Design