@crystallize/import-utilities

This repository contains a collection of types and functions that can be used to:

• Import data to a tenant
• Backup a tenant
• Transfer data from one tenant to another tenant

Examples

const myBurgerShop = {
  shapes: [
    {
      name: 'Ingredient',
      identifier: 'ingredient',
      type: 'product',
    },
  ],
  items: [
    {
      name: 'Burger Bun',
      shape: 'ingredient',
      vatType: 'No Tax',
      variants: [
        {
          name: 'Regular burger bun',
          sku: 'burger-bun-regular',
          attributes: {
            size: 'medium',
          },
          isDefault: true,
        },
      ],
    },
    {
      name: 'Burger patty',
      shape: 'ingredient',
      vatType: 'No Tax',
      variants: [
        {
          name: 'Beef burger patty',
          sku: 'burger-patty-beef',
          isDefault: true,
          price: {
            eur: 5,
          },
        },
        {
          name: 'Vegan burger patty',
          sku: 'burger-patty-vegan',
          isDefault: false,
          price: {
            eur: 6,
          },
        },
      ],
    },
    {
      name: 'Cheddar cheese',
      shape: 'ingredient',
      vatType: 'No Tax',
      variants: [
        {
          name: 'Standard cheddar cheese',
          sku: 'cheddar-cheese-standard',
          isDefault: true,
          price: {
            eur: 1,
          },
        },
        {
          name: 'Vegan cheddar cheese',
          sku: 'cheddar-cheese-vegan',
          isDefault: false,
          price: {
            eur: 1.5,
          },
        },
      ],
    },
  ],
}

Creating a tenant specification

The tenant specification describes how the tenant is configured, and can contain information on:

• Languages
• VAT types
• Price variants
• Shapes
• Topics
• Grids
• Products, Documents and Folders

It is described in a .json file, like such:

{
  "languages": [],
  "vatTypes": [],
  "priceVariants": [],
  "shapes": [],
  "topicMaps": [],
  "grids": [],
  "items": []
}

Create the specification manually

You can create the tenant specification manually, with the help of the JSONSpec type exported from the package:

import { JSONSpec } from '@crystallize/import-utilities'

const mySpec: JSONSpec = {
  languages: [{}],
}

See a simple example of this in the examples/component-numeric folder

Create the specification automatically

You can create the tenant specification automatically, with the help of the Bootstrapper class exported from the package:

import { Bootstrapper } from '@crystallize/import-utilities'

const mySpec: JSONSpec = await bootstrapper.createSpec({
  ...
});

See a simple example of this in the examples/backup-tenant folder.

See more examples in our extensive examples repository

Bootstrap a tenant

You can bootstrap a tenant using a specification with the help of the Bootstrapper class exported from the package:

import { Bootstrapper, JSONSpec } from '@crystallize/import-utilities'

bootstrapper.start()

See a simple example of this in the examples/bootstrap-tenant folder.

See more examples in our extensive examples repository

Creating single queries and mutations

For composing single queries and mutations, not using the JSON specification, there are a collection of types and functions that help with that. Here's a couple of examples.

Creating a Tenant

You can easily build the GraphQL mutation for creating a tenant.

import {
  buildCreateTenantMutation,
  TenantInput,
} from '@crystallize/import-utilities'

// Define the structure for the tenant
const input: TenantInput = {
  identifier: 'my-cooking-blog',
  name: 'My Cooking Blog',
}

// Build the mutation string
const mutation = buildCreateTenantMutation(input)

You now have a mutation string that will create a new tenant. You can then submit this query to the Core API using your preferred GraphQL client (apollo, urql, etc) to actually create your tenant within Crystallize.

Creating Shapes

If you have an existing tenant you can also just create individual shapes by generating mutations from shape definitions.

import {
  buildCreateShapeMutation,
  ShapeInput,
  shapeTypes,
  componentTypes,
} from '@crystallize/import-utilities'

// Define the structure for the shape
const input: ShapeInput = {
  identifier: 'my-shape',
  tenantId: '<your tenant id>',
  name: 'My Custom Product Shape',
  type: shapeTypes.product,
  components: [
    {
      id: 'images',
      name: 'Images',
      type: componentTypes.images,
    },
    {
      id: 'description',
      name: 'Description',
      type: componentTypes.richText,
    },
  ],
}

// Build the mutation string
const mutation = buildCreateShapeMutation(input)

You now have a mutation string that will create a new product shape with your own custom component structure. You can then submit this query to the Core API using your preferred GraphQL client (apollo, urql, etc) to create the shapes for your tenant.

Creating Items

You can easily build mutations to create items by extending the shapes to provide a schema for different items types. This is kind of a two-step process.

1. Define the structure for the shape (as per the examples above)

import {
  buildCreateShapeMutation,
  ShapeInput,
  shapeTypes,
  componentTypes,
} from '@crystallize/import-utilities'

// Define the structure for the shape
const recipeShape: ShapeInput = {
  identifier: 'recipe',
  tenantId: '<your tenant id>',
  name: 'Recipe',
  type: shapeTypes.document,
  components: [
    {
      id: 'ingredients',
      name: 'Ingredients',
      type: componentTypes.propertiesTable,
    },
    {
      id: 'instructions',
      name: 'Intructions',
      type: componentTypes.richText,
    },
  ],
}

// Build the mutation string
const createShapeMutation = buildCreateShapeMutation(recipeShape)

You can also create this shape manually via the PIM UI, if you prefer.

3. Importing a single item

import {
  buildCreateItemMutation,
  CreateItemInput,
} from '@crystallize/import-utilities'

const itemData: CreateItemInput = {
  name: 'Cookies Recipe',
  shapeIdentifier: 'recipe',
  tenantId: '<your tenant id>',
  components: {
    ingredients: {
      sections: {
        title: 'Ingredients',
        properties: [
          {
            key: 'Flour',
            value: '1 Cup',
          },
          {
            key: 'Chocolate Chips',
            value: '1 Cup',
          },
        ],
      },
    },
    instructions: {
      richText: {
        plainText: 'Start by adding the flour, brown sugar...',
      },
    },
  },
}

const createItemMutation = buildCreateItemMutation(itemData)

Tenant specification and bootstrap

The specification/bootstrap of tenant is broken down into two separate operations

1. Create a backup of a tenant, storing it as a .json specification
2. Bootstrapping a tenant, using a .json specification

Create a tenant specification

The tenant specification describes how the tenant is configured, and can contain information on:

• Languages
• VAT types
• Price variants
• Stock locations
• Shapes
• Topics
• Grids
• Products, Documents and Folders

It is described in a .json file, like such:

{
  "languages": [],
  "vatTypes": [],
  "priceVariants": [],
  "shapes": [],
  "topicMaps": [],
  "grids": [],
  "items": []
}

Long running processes

Most examples of using import-utilities library assume that you're using it as a CLI tool. In that case the execution of .kill() method is optional. However, if you want to use import-utilities in a long running process (for example in a web server) then you have to use this method like in the following example:

...
public async importProductsAsync(spec: JsonSpec): Promise<void> {
  const bootstrapper = new Bootstrapper();

  bootstrapper.setAccessToken("<access_token_id>", "<access_token_secret>");
  bootstrapper.setTenantIdentifier("<crystallize_tenant_identifier>");
  bootstrapper.setFallbackFolderId("<crystallize_fallback_folder_id>");

  bootstrapper.setSpec(spec);

  await bootstrapper.start();
  await bootstrapper.kill();
}
...