This article is for Flatfile's Portal 2.0, Portal 3.0, and Workspaces. If you'd like to check out the latest version of the Flatfile Data Exchange Platform, click here!

Background

Data Templates are the backbone of all Flatfile imports. You can create a Data Template or sheet by using the Flatfile Platform SDK. We recommend this for generating templates, especially if you need to generate templates in bulk. Alternatively, you can use the Flatfile GraphQL API to create Data Templates.

Create an API Access Key

See: How can I create API Keys?

Exchange the API Access Key for an Auth Token

API Access Keys are long lived and do not expire unless manually deactivated in the dashboard. Therefore, it is good form to exchange them for short lived Auth Tokens which have a configurable expiration time. You can learn how to exchange an API Access Key ID and API Access Key Secret for an Auth Token using our REST API here: https://api.us.flatfile.io/rest/docs/#/auth/AuthController_exchangeAccessKeyForAccessToken

Use the resulting Auth token as a HTTP header when sending the GraphQL mutation request:

Authorization: Bearer <auth token>

Mutation GraphQL

You will need a GraphQL client to issue GraphQL requests. GraphQL clients are available for many programming languages. You can find an appropriate client library here: https://graphql.org/code/

Note: a "Data Template" is referred to as "Schema" in the GraphQL API

mutation(
  $name: String!
  $teamId: ID!
  $schema: JsonSchemaDto!
) {
  createSchema(
    teamId: $teamId
    jsonSchema: $schema
    name: $name
  ) {
    name
    id
  }
}

Example Mutation Variables

Note: replace the teamId with your Flatfile Team ID (available in the URL when viewing the dashboard, i.e. if your URL shows https://app.flatfile.io/a/5251 then your team ID is 5251)

{
  "name": "Products",
  "teamId": "5251",
  "schema": {
    "schema": {
      "properties": {
        "sku": {
          "label": "SKU",
          "type": "string"
        },
        "productName": {
          "label": "Product Name",
          "type": "string"
        },
        "Size": {
          "label": "Size",
          "type": "string",
          "enum": [
            "XS",
            "S",
            "M",
            "L",
            "XL",
            "2XL",
            "3XL",
            "4XL"
          ],
          "enumLabel": [
            "XS",
            "S",
            "M",
            "L",
            "XL",
            "2XL",
            "3XL",
            "4XL"
          ]
        },
        "color": {
          "label": "Color",
          "type": "string"
        },
        "available_after": {
          "label": "Available After",
          "type": "string"
        },
        "available_before": {
          "label": "Available Before",
          "type": "string"
        },
        "featured": {
          "label": "Featured",
          "type": "boolean"
        },
        "image": {
          "label": "Image",
          "type": "string"
        },
        "currency": {
          "label": "Currency",
          "type": "string"
        },
        "price": {
          "label": "Price",
          "type": "number",
          "minimum": 0
        },
        "Cost": {
          "type": "number",
          "label": "Cost",
          "minimum": 0
        }
      },
      "type": "object",
      "required": [
        "sku"
      ],
      "unique": [
        "sku"
      ],
      "primary": "sku"
    }
  }
}

Find your environment variable

When creating data templates using GraphQL, if no environment variable is specified the template will be created in your production environment by default. Some trial accounts may be locked into a development mode by default, so in order to see your templates in the dashboard and be able to access them easily, it's best to know and include your environment variable with each template and upload.

You can find your environment ID by calling getEnvironmentBySlug - your slug being the string after /env/ in your FlatFile app URL - either 'test' or 'prod'.

Test your Mutation using the GraphQL Playground

The GraphQL Playground is a good place to test your GraphQL queries and mutations before adding them into your codebase.

Log in to the Flatfile API at https://api.us.flatfile.io/ using an existing Flatfile account email address and password
If your login attempt was successful, copy the authorization headers from the "JSON for GraphQL" section
Open the Flatfile GraphQL Playground at https://api.us.flatfile.io/graphql and paste the JSON headers copied in the previous step into the "HTTP HEADERS" tab at the bottom left of the screen
Enter your mutation and variables and press the "Play" button in the middle. The result will appear on the right side of the screen. Note the "id" of the newly-created Template
Open the Flatfile dashboard at https://app.flatfile.io/ and navigate to Configuration > Templates. You will see the new Data Template in the list. Click to open the template and review.

Please note that when updating templates, a new template with a new templateID will always be created. Any direct references to the templateID in your code will need to be updated when you make changes to your current template. Changes to data hooks will also trigger this change.