Portal 2 <-> Platform Concepts

Key terms and concepts for your upgrade

Overview

This guide is designed to teach you about and use the new Platform syntax. We’ve also created a V2 Shim package to help expedite your upgrade. You can check out the quickstart guide that uses the shim to cut down your time to upgrade.

As you transition from Portal 2.0 to Platform, you’ll come across many familiar elements that resemble what you’ve known. However, there might be instances where certain components are no longer present, have been rearranged, or sport a fresh appearance. To ensure a seamless transition, this guide is designed to teach you those differences and how to convert. It will highlight both the similarities and differences between the two versions, enabling you to switch over with minimal effort. Want to see what it might look like to upgrade? Check out our upgrade repository here to compare the beginning and end of upgrading.

A comparison

Explore this illustrative diagram that lays out the distinctions between the two products. While Platform introduces a range of additional and novel concepts compared to Portal, rest assured, you’re not obligated to embrace every new element to transition your existing importer to Platform. Flexibility remains key in making the switch.

Review V2 Portal

Meet the Platform

Before you begin

Core Architecture

Meet the Environment

In Portal, setting devMode: true flagged imports as “dev” imports, but in Platform, there are true Environments.

You can have many custom Environments, but upon signup, you will have a Development, Production, and Demo Environment configured.

All of the other entities (like Spaces, Workbooks, and Sheets) will live in those Environments.

Meet the Space

A Space and its UI constitute the new data importer that has replaced Portal. The Space is what holds all the Files and Workbooks that are needed to import data. You can learn more about Spaces and all that they do in our Spaces documentation.

Meet the Workbook

For Platform, it’s a good idea to get to know the concept of a Workbook. When you’re upgrading, you can think of a Workbook as the place where your import data hangs out.

Unlike Portal, where all the editing and fixing of data happens right in the browser, Platform also has an option to perform these actions on the server side. The data gets saved in one or more Workbooks as you go along.

Inside these Workbooks, you’ll find one or more Sheets, which are similar to schemas in Portal. Other than some basic names and settings, the sheet has something called a “fields array,” which is pretty similar to what you know from Portal.

Keep in mind that if you had multiple importers to handle different data sets from different places, you will be able to consolidate them by having all your schemas now live in one Workbook.

Configuring your schema

Meet the Blueprint

Back in Portal, when you received diverse data from the same users and wished to merge it afterward, you had to establish distinct Portal configurations and display the appropriate one for each file. However, leveraging Blueprints offers a more streamlined approach. You can employ a collection of Sheets (akin to the schemas you constructed in Portal) within a Workbook. This simplifies the process of centralizing all your data structures and collating the information cohesively. The added advantage is that you’re no longer burdened with managing multiple uploads from various schemas.

Blueprint Example

{
  "sheets": [
    {
      "name": "products",
      "slug": "products",
      "readOnly": false,
      "allowAdditionalFields": false,
      "access": ["add", "edit"],
      "fields": [
        {
          "key": "code",
          "label": "Product Code",
          "type": "string"
        },
        {
          "key": "description",
          "type": "string"
        },
        {
          "key": "price",
          "type": "number"
        }
      ],
      "actions": [],
      "metadata": {}
    },
    {
      "key": "manufacturers",
      "label": "Product Manufacturers",
      "description": "A list of maunfacturers for the products",
      "fields": [
        {
          "key": "manufacturer_code",
          "label": "Manufacturer Code",
          "type": "string"
        },
        {
          "key": "manufacturer_name",
          "label": "Manufacturer Name",
          "type": "string"
        }
      ]
    }
  ]
}

Full Platform diagram

Upgrade your importer

Now we will do a side-by-side look at how we will go about upgrading your importer. This guide will show some simple snippets that will compare the different parts and how they are converted. You can follow along with the full example in our Upgrade Repo.

1. Update your Flatfile button

The skeleton of your application should remain mostly the same. You’ll see here that we can use the same updated UI element when integrating Platform.

2. Initialize Flatfile

3. Build a Workbook

This is where you will convert your Schema(s) into a Workbook. This is the point where you can combine multiple importers into one by having multiple Sheets on the Workbook. Your end users would then be able to select which data model they are uploading into during the import process.

Compare and contrast

The workbook consists of three crucial components: the name and the sheets properties.

Sheets will share many properties with those found in the Portal schema. You’ll encounter a name property (akin to the type property in a Portal schema) and fields (which closely resembles your Portal fields array).

When it comes to the fields array, you’ll find quite a few familiar elements like key, label, and description, which all transition directly from Portal.

About field types

Let’s delve deeper into the Portal and Platform type property for fields. When you don’t specify this field, both Portal and Platform will assume a default string type. In Portal, the type: "checkbox" is now "type": "boolean", and the type: "select" is now "type": "enum" in Platform.

Furthermore, keep in mind that while Portal only had three types, Platform has broadened its range to include number, date, and reference types. To get more details about these new field types, you can check out our documentation. Also, we’ve prepared a handy reference table below, outlining all the new types and how they were handled in Portal.

Portal Type	Platform Type
String	String
String	Date
String	Number
Select	Enum
Checkbox	Boolean
N/A	Reference

When providing select/enum options there is still an options array that has the same structure as it did in Portal. However, one thing to note is that this options array has been moved into a new property on the field object named config for Platform.

Set up validations

The final aspect of converting your Portal fields into Platform fields will be to handle the validators from Portal. While Portal offered many different kinds of validators, only two have been converted in the fields themselves, and those are required and unique. All other validations can still be handled, but are now handled in code instead of a setting. Check out the other validators section for examples.

The validators property will now be called constraints which is still an array of objects. The object for each validator has traded in the validate property for a type property, but the unique and required values remain the same.

4. Transform Data

Coming from Portal, you are likely familiar with the concept of Data Hooks. The same sort of functionality can be obtained in Platform, but they have moved into Listeners and use plugins like the record hook plugin. You can read more about Listeners here and more about all of our Plugins here.

Other Validators

In the set up validations section above, we talked about converting the required and unique validators, but validators like regex or required_with are now handled in code in a Listener.

Regex Validation Example:

required_with Validation Example:

5. Match your brand

Custom theming in Portal was a crucial part of making the importer like a part of your application. Platform also has custom theming that you can use to do the same. Check out our theming guide to see what all is configurable in Platform.

6. Set the destination

In Portal, you were able to specify a webhook endpoint using webhookUrl -OR- use the returned data within the Promise to do whatever needed to be done with your data. With Platform, we use the Listeners to wait for the submit action to happen and then act on it.

7. Customize

While everything above gives you all sort of great information about how your Portal implementation will convert to Platform, it’s just the beginning of all the amazing new things you can do with the Platform. Below we are going to share some links that can help make your already great workflow even better.

Make it more dynamic

Make it headless

Top Secret - Seriously, don't click this

Document things for end users