Content Template

The Content template for the import/export tools describes data for your Kibo eCommerce sites. This template is provided for the purposes of migrating site content between Kibo eCommerce environments. For example, you can use this functionality to export site data from a sandbox environment and then to import the data to your production tenant.

Caution: Successfully importing site content requires a solid understanding of various types of Kibo eCommerce data. Do not attempt to build out a new, full site using this template. Use this template only to migrate an existing site. For the smoothest possible migration, change as little data as possible within the template. Remember, if Publishing is set to Live, your import will immediately overwrite your live site.

Sites are comprised of a combination of document data for the page content, category information from your product catalog, and Hypr templating information for the page appearance, and widget code from your theme. Kibo eCommerce recommends working with a theme developer to develop your template pages, widgets, and general site appearance.

Access the Tools

With the Kibo eCommerce Import/Export Tool (1.0) installed, go to System > Customization > Applications. Click Mozu Import/Export (version 1.0.0), and click the Configuration link.

Supported File Formats

Note: Microsoft Excel limits both total file size and cell size. A single worksheet can contain a maximum of 1,048,576 rows and 16,384 columns. A single cell can contain up to 32,767 characters.

Template Key

For each sheet, we define each column and describe valid values for the column. Some values are not required for an import, but are required Kibo eCommerce data. For example, you do not have to specify a customer's FirstName every time you modify the customer account, but all customer accounts require a FirstName when they are created. For additional context about the process of building out Kibo eCommerce data, refer to the topics in Guides. If you have questions or concerns specific to your data, please contact your integration partner or Kibo eCommerce Support.

Information Provided for Each Sheet of the Template
Corresponding REST API Resource Every column in a sheet corresponds to a property in the Kibo eCommerce REST API. For each sheet, we provide a link to any API resources that contain properties in the sheet.
Column Name The name of the column in the sheet.
Description A description of the data a column contains.
Valid Values Lists valid values for the column.

Sheets

Tip: Each of the following sheets can be imported independently of any other sheet. If you are iterating on migration content, you can remove any sheets you do not need to re-import to save time.

Migrate Content

Migrating content to a new site or environment, such as from a live site in production to a new sandbox for testing, requires a few more set-up steps than a typical import operation:

  1. In the environment that contains the original site, launch the Mozu Import/Export Tool (v. 1.0.0).
  2. Export Content.
  3. Switch to the environment where you are creating the new site. Ensure that all catalog data exists and that the catalog structure, categories, products, and facets all mirror the environment you exported from.
  4. Go to System > Structure > Sites and create the new site. Note the Site Name, and make sure you associate the new site with the correct Catalog.
  5. In Dev Center, confirm that you have installed the theme the new site will use, and note the Legacy Application ID and Release Package ID. You will need these values for Site Settings.
  6. Modify the sheets of the Content template you exported in step 2, paying attention to the following:
    • All instances of Site Name and Catalog Name are correct for the new site.
    • On sheets that reference the same content multiple times, global fields match exactly on all rows that reference the same content. For example, if one of your Page Templates has mutliple dropzones, only the Dropzone and Config fields should have different values in different rows.
    • Any category codes, both in the sheets and in widget configuration content, are correct for the new site.
    • The Pages, Page Templates, and Navigation sheets are consistent.
    • All URLs are correct.
    • The Site Settings sheet references the correct theme.
    • You have followed any relevant best practices.
  7. Launch the Mozu Import/Export Tool (v. 1.0.0) and import the updated template.

Best Practices

Set Publishing to Staged Before Importing

If you encounter problems with your site import, you can delete your imported changes if Publishing is set to Staged. If Publishing is set to Live, your import will immediately overwrite your live site. In Admin, go System > Settings > Publishing to change your publish settings.

Mirror Your Catalog Structure Exactly

Site content is complex and maps to various types of catalog, product, and category data. The best scenario for a succesful import operation is to mirror your entire catalog structure on the new tenant so that you do not have to make extensive changes to the template.

Only Make Necessary Edits in the Template

Because of the complexity and quantity of site data, making extensive edits in the template can get confusing. It is generally safer to import a site that is in a good state and then make any desired tweaks through Site Builder.

Use Category Codes Instead of Category IDs

When adding configuration code that relies on a category – such as referencing a facet or a category page in a widget or URL - use Category Codes instead of Category IDs whenever possible. Category IDs are specific to a tenant and environment, but Category Codes do not change when you migrate content. Using Category Codes will help avoid unexpected breaks in your links.

Use the make_url Hypr Tag to Construct Image Links

Often, widget configuration code references image files that you have uploaded to the Kibo eCommerce CMS. When specifying the URL for an image, avoid using a full URL that is specific to a tenant. Use the make_url Hypr tag to generate consistent URLs that you can use across sites.

Reuse Document IDs (GUIDs) Across Sites

When referencing content, such as a page or an image file, in the Kibo eCommerce CMS, try to maintain the same document ID (GUID) across all sites. Even if you migrate the file itself from one tenant to another, you can still specify any GUID. To be valid, a document ID simply must be a 32-character alphanumeric string.

Do Not Hardcode Dynamic Content

Some configuration code includes dynamic content that references a particular value, such as a site or tenant ID. This content is indicated by curly braces: {tenant}

The Import/Export Tool will handle mappings of this content for you. Do not hardcode these values.

Sample Code

Sample Code: Dropzone and Widget

The following sample code describes a dropzone that contains an HTML widget and would be valid JSON for the Config fields in the Catalog Content, Page Templates, and Pages sheets. In the following code, the dropzone spans 12 columns on the page and contains raw HTML. The id value is the GUID for a document in the Kibo eCommerce CMS. GUIDs are fully customizable, and Kibo eCommerce recommends using the same GUIDs across sites for simplicity.


	[
	  {
	  "columns": [
		{
		"span": 12,
		"widgets": [
			{
			"definitionId": "html",
			"isRichText": false,
			"config": {
				"body": "<i><center>Check out the latest Spring styles!</center></i>"
				},
			"id": "1e5675a8-e8a6-25e4-b414-e16f2a9b200a"
			}
		    ]
		 }
	   	]
	   }
	]
				

Sample Code: Site Setting Properties

The following code sample sets theme setting values for a theme with a Legacy Application ID of 1111 and a Release Package ID of 2222, and would be valid JSON for the Properties field on the Site Settings sheet. This code defines settings for pageSizeOptions, defaultPageSize, primaryColor, primaryButtonColor, and primaryFont.

Note: The actual settings available for any given theme are defined in the theme's theme.json and theme-ui.json files. Importing site settings simply sets values for existing settings, it does not create new settings in a theme.


	{
		"theme": "~1111~2222",
		"tags": [
			"something"
				],
		"data": {
		"pageSizeOptions": [
						16,
						32,
						48,
						64
					],
		"defaultPageSize": 16,
		"primaryColor": "rgba(66, 18, 50, 1)",
		"primaryButtonColor": "rgba(66, 18, 50, 1)",
		"primaryFont": "Lato, sans-serif"
				}
	}