V3 <-> Platform

Step up to the Platform

Legacy Documentation: This documentation is maintained for backward compatibility purposes only. For the latest features and best practices, please refer to the current documentation.

Before you begin

Signup for the new Platform

While both this and our version before it live in your current dashboard together, our new Platform has its own space. Before you can get started, you’ll need to signup for a new account here.

Environments

When talking about Environments in Portal 3.0, you had two to work with, dev and prod. While the same concept of Environments exists in Platform, you will now be able to create as many Environments as you need. By default, you will have a Development, Production, and Demo Environment configured upon signup. You can use these Environments and create more as needed. You can create additional Environments using our APIs or by using the “New Environment” button on the environment switcher in the Dashboard.

Portal vs Space

In the current Flatfile versions (V2 and V3), we refer to Portal as an iFrame that opens on a button click to allow your customers to import data. In Platform (the new version), we still call the process of embedding a Portal, but we refer to what is embedded as a Space. A Space is an open-ended component by design. You can have a Space per customer, a Space per project, or something else that fits your workflow. It is up to you. You can either work in a Space inside your Flatfile dashboard or you can embed a Space into your application that opens when your customers click on the Import button. A good way to think of a Space is as a collection of Workbooks (explained below), while a Workbook is a collection of Sheets. You can learn more about the structure and functionality of Spaces in this guide.

Familiar concepts present in the new and current versions

The new Workbook

In Platform (the new version), a Workbook is a collection of Sheets that describe the expected shape of the data you receive. You can learn more about the structure and functionality of Workbooks in this guide. To create a Workbook, you can refer to our Getting Started guide.

Same Sheet, different product

The Sheet, how it interacts with the Workbook, and what it’s for are all the same. We are calling the collections of Sheets that is the shape of your data Blueprints. You can learn about all the options of Blueprints here, but there is not a whole lot that needs to be said for you to understand it and get rolling.

Fields, data types and the new way to create them

If you’re coming from Portal 3.0 and using the PSDK, you will be familiar with something that looks like new Sheet('name', { fieldName: TextField() }). This syntax has changed to go back to an Object-based approach that looks more similar to the shape of the underlying API that powers it. Let’s go through the different field types and their new syntax, shown as part of a workbook in the Platform.

Compare fields

Portal 3.0

const MySheet = new Sheet('MySheet', {
    name: TextField({
        label: 'Name',
        description: 'A name field',
        required: true
    }),
    subscriber: BooleanField({label: "Subscribed?"}),
    status: OptionField({
        label: 'Deal Status',
        options: {
            new: { label: 'New' },
            interested: { label: 'Interested' },
            meeting: { label: 'Meeting' },
            opportunity: { label: 'Opportunity' },
            unqualified: { label: 'Not a fit' },
        },
    })
}

Things that moved

Believe it or not, the way you write DataHooks has mostly stayed the same, but where you write your DataHooks is different. The Platform has what we call Listeners. Listeners, as you might expect, wait for specific Events in the Platform to happen and then execute any of the code in the Listeners subscribed to that event. In order for your Data Hook code to run as expected, you also need to use the proper Plugin for it to work. We have created a number of open-source plugins for the Platform, with our @plugin-record-hook being one of them. Let’s take a look at an example of a simple record hook now compared to in Portal 3.0.

Portal 3.0

const MySheet = new Sheet('MySheet', {
    name: TextField({
        label: 'Name',
        description: 'A name field',
        required: true
    })
},
{
    recordCompute: (record) => {
        const { name } = record.value
        if (name === 'David') {
            record.addWarning('name', 'This is the CEO!!')
        }
        return record
    }
})

Using GraphQL?

Were you using our GraphQL API in v3? Did you love it? No???? Same here. As developers we might still love GraphQL, but offering it as the best and most polished form of our API felt wrong. For Platform, our main and best kept form of API is our REST API. You can find references to the new API in our documentation.