This article is for Flatfile's Portal 3.0. If you'd like to check out the latest version of the Flatfile Data Exchange Platform, click here!
Intro
The new submission workflow in Portal V3 introduces opportunities to customize the submission and egress workflows as well as a new UI to guide users to provide more fully validated data.
Flatfile customers are now able to customize the workflow behind the new submission UI to optimize data quality and align better with their own systems -
You can configure server-side validations and push rejected records back into Flatfile for additional review along with custom, record level errors
You can define where a user is taken after a submission is completed to better integrate Flatfile within your workflow
You can customize how and when you receive data from an import, alleviating current limitations on the import experience required by system limitations (maxRecords in Portal V2)
The new submission UX also guides importers through a series of steps to ensure they are submitting a dataset validated both by Flatfile and the destination system. Importers are informed where outstanding errors exist, including those found after validation against the destination system, and guided to correct or discard as relevant. The import process is completed with a bit of celebration alongside confirmation of the submitted data.
Setting up the new submission workflow
Implementing Flatfile’s new submission workflow in your implementation of Portal V3 requires 3 steps:
Updating your SDK
The new submission workflow requires the newest version of our client side SDK. If you implemented Flatfile before September 2022 you will need to update your SDK.
Updating your SDK will require installing the new version and addressing a few changes within the configuration before moving on to customization. Instructions on how to use the new version of the SDK are here.
Note: If no onData & next (chunk processor) is passed your users will continue to see the old experience.
Providing your visual and workflow customizations
The submission loading and completion screens (below) can be visually customized in the following ways:
Your logo and display name can be used to customize the submission loading and complete pages
Guidance text on submission loading and complete pages can be customized
You can disable the confetti animation on the submission confirmation page
You can set where your users are taken after a the submission is completed
See visuals below of our submission loading screen and submission completed screen:
Visual customizations - logo, display name, guidance text and confetti 🎊
The logo you provide will currently be used in two places, both in the submission workflow. You can also provide a display name to use in place of the logo and in written references to the destination system. If nothing is provided, Flatfile will use your team name in place of both logos and on the continue button.
The image you provide for your logo will be cropped to a circle - we recommend choosing the image accordingly.
Custom text can also be provided to display under the page titles on both of the above pages. Use this space to provide context to your users on next steps after data import, expectations around data processing, or info about responding to system rejected records. We recommend limiting each set of text to 200 characters.
Your users have just completed an important task, and we’d like to celebrate! While we advocate for unexpected moments of joy, we understand that not all brand voices include confetti and you can disable the mini-party if required.
Defining the next steps for your users
Depending on your import workflow you may wish to trigger a specific next action for your users. You can customize what happens once the importer finishes their import using the onComplete callback. If no onComplete instructions are provided the iframe will close and return the users to the original screen.
Customizing your egress workflow
Adding your partial rejection callbacks
You have the option to return any records rejected by your own system and relevant errors back into Flatfile for additional correction by the importer. Making these additional corrections part of the initial import experience facilitates correction and guides users to address errors in a familiar format. When records are returned for additional validation, importers will have the option to provide corrections or dismiss records that could not be accepted as part of the previous submission.
Accessing the data
You can define the rate and volume of data transferred to accommodate any requirements from your own system.
Data provided after submission will only include records that meet all validation criteria set up in Flatfile. Users may have discarded records that did not meet these requirements as part of the submission process. You can request discarded records specifically via our GraphQL API using `fetchRowsWithSchema` with `dismissed` as filter argument.
FAQ
What happens to records discarded by the user before submission?
If a user chooses to dismiss invalid records prior to submission these records will not be included in the data sent to you via your chosen egress methods. These records will not have passed validations defined in your schema. You can request dismissed records separately as defined here.
My system can’t accept all submitted data at once. How can I manage the incoming data?
See our documentation on record chunk size to customize your egress.
If you expect data egress to be delayed, or want to provide other context on remaining steps of your process after submission, leverage the optional custom text on the submission loading screen to share details with your user at this step.
How can I customize this flow?
Currently you can customize branded elements of this process by providing your logo/preferred company name and optional guidance text as outlined here. Custom colors and fonts can also be defined for the whole import experience as outlined here.
You can disable the confetti animation run on the confirmation screen (info here)
You can define the steps following submission via onComplete (info here)
Soon you will be able to disable submission if any errors are present in the incoming data. You may wish to do this if all incoming records are required by your system.
Can my users access copies of their submitted data?
Planned expansion of this workflow will allow your users to request a copy of their dismissed records or full submitted dataset via email.