Overview

A collection in an Intuiface Headless CMS (H-CMS) base is a list of multiple items that share the same set of properties. Using Headless CMS's web-hosted user interface, a collection can be built manually, one item at a time. Alternatively, an import mechanism can add multiple collection items in a single step.

The import function can be used to add new items or update existing items. It cannot be used to delete existing items.

This article reviews the process for importing items into an H-CMS collection.

Import Process Summary

The import process can be broken down into four steps:

1. If it doesn't already exist, define a structure in your Headless CMS base for the collection you'd like to populate.
2. Generate a template based on that collection.
3. In the resulting CSV file, enter information about each item you wish to add or update, information mapped to the structure properties and variants you created in Step One above.
4. Import the CSV file.

Step One: Create your collection structure

Every collection in a Headless CMS base is made of 1) a structure that defines the collection's properties and variants and 2) content, which are the property values for each item in the collection. Before using the H-CMS import function, the targeted collection must first have an established structure.

You can create any structure you wish, including the use of variants. It is not important for the collection to be empty - i.e., you can use the import function to add items into a collection that already contains items or to change items already in the collection. The only prerequisite is the existence of a collection structure before importing content.

Step Two: Generate the CSV template

Overview

The H-CMS import process requires a well-formatted CSV (comma-separated values) file. In that file, the first row - the header - lists the structure properties and variants of the collection, possibly defined in Phase One above. Every other row in the file represents an item to be added or updated, with values for each property and variant.

If you have an existing data source containing the content to be imported, that resource will likely have an "Export to CSV" option. Using that option will create a CSV file from which you can extract the information needed for the H-CMS CSV import file.

NOTE:

• The CSV file you create for import cannot be larger than 16MB, and the maximum number of rows is 20k.
• Any CSV file you create using an external resource will not have the correct format required for import. The Headless CMS Import CSV file has a very specific format. The next section explains how to create a well-formatted import file.

Generate a CSV template for your collection

The easiest way to build the import CSV file is to start with a CSV template:

• Open the Content tab in your base and select the appropriate collection in the left-hand panel.
• Click the "Content Import/Export" button.
  
• Click the "Download template" button in the "Create Template" section. Check the "Include data for the first item" checkbox to include all the existing Variant values.
  
• Open the downloaded CSV file in your favorite text editor, Excel, Google Sheets, or any other software you like to use to edit CSV files. (If you open the file in anything but a text editor, make sure that when you save changes, you save it as a CSV file - i.e. with a .csv extension.)

Structure of the CSV file

The first row of the CSV file - also known as the "header" - is a comma-separated list of properties in the structure of your target collection.

• The first property is "Item ID", a value you must create for each item if one doesn't exist. The format of this Item ID is described in the next section.
• Then, all variants are listed. Variant names are preceded with the letters "v_". For example, a variant named "Meal" would be represented in the CSV file as "v_Meal".
• Finally, all other properties in the collection structure are listed.

The following image is of a sample template created for an H-CMS base collection of restaurant menu items. This collection has three variants - Meal, Dish List, Language.

Though not indicated in the template, "Meal" and "Dish List" are collection-level variants, while "Language" is a variant specific to the "Name" and "Description" properties. Note the following about this auto-generated template:

• Because we selected "Include sample data" for the template download, all 12 possible variant combinations are automatically listed below the top row.
• The Item ID remains the same when only property-level variants change - e.g. both Rows 2 and 3 have the same Item ID because only the property-level variant "Language" has changed. See the next section for a discussion about the Item ID.
• The Item ID changes when collection-level variants change - e.g. when moving from Row 3 to Row 4, the Item ID changes because there is a change in a collection-level variant "Dish List". See the next section for a discussion about the Item ID.

Step Three: Edit the CSV file

Every row in the CSV file, starting with Row 2, represents a unique item to be added or updated in your collection. For each of these item rows:

• The first value (first column "Item ID") must contain a unique identifier. This identifier can contain any combination of letters and numbers and does not need to follow any particular order or pattern or have a consistent format from one row to the next. All that is necessary is for this identifier to be unique for each item in the collection.
  • Rows that vary based only on property-level variants should have the same Item ID.
  • Rows that vary based on collection-level variants - whether or not there are also property-level variants - should have different Item IDs. 
  • The same Item ID can be used across collections to represent different items. There are no key fields in a Headless CMS base.
• Every other value, separated by commas, should map to the property fields identified in the first row. (Of course, if you use a spreadsheet program like Excel, each property would map to a unique column. No commas would appear. But remember to save it as a CSV file!)

Be sure to review the section below entitled "Note about updating existing collection items" to understand the formatting difference between new items and changes to existing items.

Variant values

The possible variant values - the variations - are predefined in the collection's structure.

Every row must have a variation value entered for each variant.

Property values unaffected by a collection-level variant only need their value assigned in the first variation row. All subsequent variation rows don't need to identify property values if those values are unchanged. For example, suppose a property value is an image that will be identical for all variations. In that case, the image must only be listed for the first variation of the item that uses it.

Property values

Properties, when defined in a collection's structure, are assigned a particular type - such as Text, Long Text, Image, Video, Date-Time, etc. Formatting rules for property values in the CSV are as follows:

• Image/Video/Document: Value is a file name that must include the file extension. Can be entered as a HTTP/HTTPS URL if the file is stored in the cloud or as just a file name if the file is on the local device.
• Long Text: Value is a file name that must include the .txt extension. Can be entered as a HTTP/HTTPS URL if the file is stored in the cloud or as just a file name if the file is on the local device. Do not include the path to the file as this will be ignored.
• Boolean: Values must be either True/False (not case sensitive), Yes/No, or 1/0.
• Color: Values must be written in hexadecimal formal (e.g. #4169E1) or using CSS3 color names (e.g. RoyalBlue)
• Date without hour: Use ISO format YYYY-MM-DD (e.g. 2022-01-25)
• Date with hour, set to the base content editor's local time: Use ISO format YYYY-MM-DDThh:mm:ss.sssZ (e.g. 2022-01-25T10:00:00.000Z)
• Date with hour, set to a Player device's local time: Use ISO format YYYY-MM-DDThh:mm:ss.sss
  (e.g. 2022-01-25T10:00:00.000)
• Date with hour, left to the base content editor's choice: Use either of the above two formats.

When to leave property values blank

For items not yet in the base:

• Only enter a property value if it differs from the last value set for an earlier variant of the same item.
• By leaving the value for a property empty, you are indicating that the value set for an earlier-defined variation should be used.
• If the first item in the CSV file represents a new item, it must have values for all properties, as there is no preceding variant.

For items already in the base:

• For the properties Image, Document, Video, Audio, 3D Model, and Long Text
  • Only enter a value if it differs from what is already in the Headless CMS base.
  • An empty field indicates the existing value in the base should be used.
• For all other properties: Text, Boolean, Color, Number, Date
  • Always enter a value, even when a value already exists in the base.
  • An empty field indicates the existing value in the base should be removed.

Sample CSV file ready for import

The following sample template is ready for import (click to zoom). Notice:

• The Item IDs obey no particular format requirements. They only need to be unique and - as noted above - repeated for items that differ only due to property-level variations and not collection-level variations.
• The empty cells in the "Image" column illustrate how properties unaffected by a property-level variant only need to have a value set for the first variation instance. The value is assumed for all other variations of the property.

NOTE: The property order and variant order in the CSV file does not have to match the order in the actual base structure. There will, however, be an import error if a property or variant is missing.

Step Four: Import the CSV file

Once the CSV file is ready, it can be imported.

• Open the Content tab in your base and select the appropriate collection in the left-hand panel.
• Click the "Content Import/Export" button.
  
• Click the "Import CSV file" button in the "Import Content" section and then browse to the CSV file you created above. Alternatively, you can drag-and-drop the CSV file onto the drop zone.
  
• Wait for the "File analysis" and "Import preparation" steps to be completed. If errors appear, correct the CSV file appropriately, then try the import again.
• If your collection contains any Image/Video/Document/Long Text properties, the "Media upload" step will appear.
  • For URL-referenced media, ensure there are only checkmarks next to the media files you wish to upload, then click the "Start upload" button.
    
  • For locally-stored media, ensure only checkmarks are next to the media files you wish to import. Then, to upload the appropriate files, use one of two methods:
    1. Click the + symbol next to a specific file name. In this case, you can upload any file of the same type, even if the file name doesn't match.
       OR
    2. Drag-and-drop multiple files from your device's file browser onto the drop-zone to the right (or click the + button on the right and select a file). In this case, the file name(s) must be identical - including the file extension - to the names in the upload list.
       
• After all appropriate file references have a checkmark and all URL-referenced and locally-stored files have been uploaded, click the "Start base update" button in the bottom-right corner of the screen.
  
• Wait for the Base Update process to complete. Once finished, click the "Close" button.
• The import process is complete. Imported items should now appear in your collection on the Content tab of the H-CMS base.

Note about updating existing collection items

As discussed above, the import process can update existing collection items, not just create new ones.

The only difference between using import to create an item vs. updating an item is how to handle unchanging property values in the import CSV file. For every updated item:

• Item ID: Must match the original Item ID assigned when the item was first created / imported.
• Image, Document, Video, Audio, 3D Model, and Long Text properties: If the media won't change, leave the field blank. This indicates to the import mechanism that the existing media file should remain as-is.
• All other properties: Include values in the CSV file even if they are not changing. An empty field indicates to the import mechanism that the existing value should be erased.