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.

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 recommends working with a theme developer to develop your template pages, widgets, and general site appearance.

Access the Tools

With the Mozu Import-Export Application installed and enabled, go to Main > Content > Import/Export in Kibo eCommerce Admin.

Supported File Formats

• Excel (.xlsx): All sheets appear as tabs in a single Excel file. For imports, the Excel file can have any filename, but each tab must match the sheet names below. You can remove tabs for data you do not want to import.

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. If you have questions or concerns specific to your data, please contact your integration partner or Kibo Support.

Sheets

Facets

Corresponding REST API Resource: commerce/catalog/admin/facets

Facets allow shoppers on your site to filter products within a category. For example, a shopper might want to filter results for "Shoes" by Men's > Boots > Size 10 > $50 - $100. Each element in that filter is a facet.

Categories, product attributes, and price are all valid facets. Product categories are inherently tied to facets, so if you add subcategories to a parent category, the subcategories are automatically added as facet values of the parent facet.

Catalog Content

Corresponding REST API Resource: content/documentlists/documents

The Catalog Content sheet describes the pages of your site that map to categories in your product catalog. For a category page to appear on your site, the category must exist in your site catalog and be configured to appear on your storefront (Hide category on store front set to FALSE on the category page in Admin).

Page Templates

Corresponding REST API Resource: content/documentlists/documents

The Page Templates sheet describes the templates for your theme. Templates are the default pages that define styles for live pages on your site. Any change you make to a template propagates to all pages on your site that use that template.

Pages

Corresponding REST API Resource: content/documentlists/documents

The Pages sheet describes single pages that appear on your site. Single pages are any pages that are not mapped to specific categories or products and do not provide standard functionality like log-in or checkout. Single pages only appear on your site through direct links.

Common uses for single pages include providing contact information for your store, publishing terms and conditions, and publicizing one-off promotions.

Navigation

Corresponding REST API Resource: NA

The Navigation sheet describes how single pages appear in the site tree.

Site Settings

Corresponding REST API Resource: NA

The Site Settings sheet describes theme settings that an Admin user can modify. Every theme that is available for the site appears on a new row in this sheet.

Importing site settings does not install or apply a specific theme. If you are importing site settings, be sure you have installed the appropriate theme to your tenant.

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 multiple 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 as detailed below.
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 successful 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 afterwards.

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": "Check out the latest Spring styles!"
                },
            "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.

{
        "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"
                }
    }