Overview

A collection in an Intuiface Headless CMS (H-CMS) base is a list of multiple items that share the same set of properties. A collection can be created manually, one item at a time. Alternatively, multiple collection items can be created in a single step through the use of an import mechanism. This approach is usually taken when the items to be added are already cataloged in an external resource, such as a CMS, CRM, DAM, PIM, or Excel spreadsheet.

This article reviews the import process for creating and updating items in an H-CMS collection.

Import Process Summary

The import process can be broken down into three phases:

1. If it doesn't already exist, define a structure in your Headless CMS base for the collection you'd like to populate.
2. Build a CSV file that contains information about each item you wish to import, information mapped to the structure properties and variants you created in Phase One above.
3. Import the CSV file.

Phase One: Create your collection structure

Every collection in a Headless CMS base is made up of a structure, which defines the collection's variants, properties, and property types, and content, which are the property values for each item in the collection. Before you can use the H-CMS import function to add content to a collection, that collection must first have an established structure.

You can create any structure you wish, including the use of variants. It is also 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. All that matters is the existence of a collection structure before importing content.

Phase Two: Create the CSV file

The H-CMS import process requires a well-formatted CSV file - aka a comma-separated values file. In that file, the first row - the header - is a list of the structure variants and properties you defined in Phase One above. Every other row in the file represents an item to be imported, with values for each variant and property.

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 you'll need for the H-CMS import file.

NOTE: 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 CSV template" button in the "Create CSV Template" section. Be sure to check the "Include sample data" checkbox.
  
• 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.)

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 the collection you're targeting.

• The first property is the "ID", a value you will have to create for each item if one doesn't already exist. The format of this 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.

Do not change the order of these properties in the header. The order produced by the template export must be respected.

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. The Meal and Dish List variants are at the collection level; the Language variant is only applied to the Name and Description properties.

Note the following about this auto-generated template:

• All 12 possible variant combinations are automatically listed below the top row.
• In this case, as there were no existing collection items in the H-CMS base, no values appear for any properties in the list.
• The ID remains the same when only property-level variants change - e.g. both Rows 2 and 3 have the same ID because only the property-level variant "Language" has changed. See the next section for a discussion about the ID.
• The ID changes when collection-level variants change - e.g. when moving from Row 3 to Row 4, the ID changes because there is a change in a collection-level variant "Dish List". See the next section for a discussion about the ID.

Preparing the CSV file for import

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

• The first value (first column "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 ID.
  • Rows that vary based on collection-level variants - whether or not there are also property-level variants - should have different IDs. 
  • The same ID can be used across collections to represent different items.
• Every other value, separated by commas, should map to the property fields identified in the first row. (Of course, if you're using a spreadsheet program like Excel, each property would map to a unique column. No commas would appear. But don't forget to save as a CSV file!)

Variant Values

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

Property values unaffected by a collection-level variant only need to have their value assigned in the first variation row. All subsequent variation rows only need to identify property values that change for each variation.

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.

Sample template ready for import

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

• The IDs obey no particular format requirements. They just need to be unique and - as noted above - repeated for items that differ only due to property-level variants and not collection-level variants.
• 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.

Phase Three: 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 complete. If errors appear, correct the CSV file appropriately then try the import again.
• If your collection contains any Image/Video/Document/Long Text properties, then you are presented in the Media upload step with the following screen.
  • For URL-referenced media, make sure there are only checkmarks next to the media files you wish to upload then click the "Start upload" button
    
  • For locally-stored media, make sure there are only checkmarks 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 after 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.

Updating existing collection items

The import process can be used to update existing collection items, not just to create new items.

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

• ID: Must match the original ID assigned when the item was first created / imported.
• Image/Video/Document/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 unchanged.
• 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.