Importing Data into Crystallize

There are many ways to import data into Crystallize, catering to different scenarios:

• Initial (or recurring) import from an external source that may include:
  • Performing batch editing operations, e.g. adding a whole spreadsheet’s worth of products to your tenant at once.
  • Integrating seamlessly between Crystallize and third-party applications that support file formats like XLS, JSON, CSV, XML, HTML, or Markdown.
  • Manual import/export.

• Automated import/export for backup, CI/CD, or local development that may include:
  • Duplicating tenants for backup purposes.
  • Creating staging/development environments.

If you’re performing your initial import of data, your first step should always be to build a strong content model. This is to instruct Crystallize how your data will be structured. We offer a content modeling kit along with helpful advice within our Best Practices section. Once you’ve properly established your structure–components, relations, shapes, items, and catalogue–you’re ready to import data.

• You’ll need access tokens for the Crystallize tenant(s) you work with.
• You must be the owner or a Tenant Admin of the tenant(s) you work with. You can read more about authorization in Crystallize and managing user roles and permissions by following the links.
• All operations performed will count against your tenant’s API call usage metric. (You can read more about monitoring tenant usage in the User Guide.)
• Webhooks and fulfilment pipelines are not included in the import-export process and need to be transferred via the PIM API. They are not part of the different SDKs and transfer methods described here.

The Crystallize command line interface (CLI) is an open-source application. (You can contribute to the CLI here.) Within the CLI, you can run the following command to create a “spec” file containing the target tenant’s data:

npx @crystallize/cli-next@latest dump ~/my-projects/mydumpfolder tenantIdentifier

The CLI has many options that you can see by using the `--help` flag. For instance, you may want to add `--exclude-orders=false` and `--exclude-customers=false` to include Orders and Customers in the spec file. (This is disabled by default.)

Once you have your spec file, you can import it into a target tenant with the following command:

npx @crystallize/cli-next@latest import ~/my-projects/mydumpfolder/spec.json tenantIdentifier

Please note that if you use the CLI, there’s currently no option to exclude anything to be imported. If there’s anything you don’t want to import, you have two options:

• Remove it from the spec file (after the dump command and before the import).
• Use the import-utilities tools instead, which are described below.

This method does everything server-side. Currently, it’s available for Crystal plan customers only, but will eventually be open to all activated accounts. (If you have any questions about your Crystallize plan, you can contact our sales team.)

In the PIM API, use the following mutation to trigger the cloning of a tenant:

mutation {
  tenant {
    createCopyTask(
      desiredIdentifier:"newidentifierformyclone"
      desiredName:"newnameformyclone"
      exclude: assets
      overwrite: true|false
      tenantId: "0987654123123"
    ) {
       id
      }
   }
}

With this command, you can copy an existing tenant and either create a new tenant with the data, or overwrite an existing tenant that you own by specifying overwrite: true. This method of copying a tenant is the fastest, and it will aggregate usage on the source tenant.

The Crystallize import-utilities are a set of tools that enable powerful import and export operations between Crystallize tenants, data specification, and conversion between a solid range of file formats. As free open-source code, you can use import-utilities in conjunction with the Crystallize APIs you already have and adjust it to support your own unique applications.

Whether you need to perform data dumps, automate backups, or pull data from Crystallize to convert and use somewhere else, you have the flexibility to do pretty much anything. See for yourself the many examples already coded for you at our example repository.

You can also check out our import-utilities livestream for more information:

You could manually import data using the product.create, product.update, and all the other mutations available within the PIM API. This is not recommended for most use cases, as you will miss optimization, throttling, and many things you get out of the box by using import-utilities.

The Crystallize App supports Apps, which are custom external applications that you can link to via a URL. Anyone may create and add Apps to their tenant. Crystallize offers a number of open-source Apps as well. One of these is the Crystallize Import App, a user interface to import/export data by doing a field mapping.