Introduction

Version 2 imports are the new expanded format for importing content into Carbon Editor. They have been designed for flexibility and control of your imported content. Version 2 imports have a more complex structure than version 1 imports as they give more control over the import to the user and the creator of the zip, the best example of this is the ordering of imported pages, where version 1 imports import all pages in the order they appear in the zip (file system order) version 2 imports require you to explicitly list which pages are to be imported and what order they should appear in.

New Features

In addition to providing additional control over the import process version 2 imports contain a number of new features which cannot be supported with version one imports.

Import Validation

Version 2 imports support validation of the import zip and its contents in the context of the current space, including checking the existing space for conflicting themes, and system types for the features mentioned below. This gives the user the ability to selectively import themes and system types. 

Document and Page Metadata

Documents and Pages can now contain metadata through the Metadata feature of Carbon Editor. Version 2 imports support setting the metadata for a document or page.

Theme Imports

Themes can now be imported alongside the documents which use them, and have all page styles automatically associated with the newly imported content. This makes it easier to import a document and have it styled and ready for publishing without further work.

System Type Imports (Field Types, Page Section Types, Page Templates)

Where as version 1 imports are capable of automatically creating field and page section types which are missing from the current space and required to import content, version 2 imports give you increased control over this process. In addition to creating new field types, page section types and page templates, version 2 imports support importing all default content and html markup associated with these types to ensure that a smooth editing experience once the content is imported.

Import Structure

Compared to version 1 imports the structure of a version 2 import is slightly more complex. Note the XML export from Carbon Editor will produce version 2 imports so can be used to easily generate an example from your own content.

Basic Structure

The basic structure of a version 2 import depends on which features you are using, some of these directories may not be required for you.

document.json
pages/
	my-page-slug/
		page.json
		page.xml
	my-second-page
		page.json
		page.xml
		assets/
			my-field-image.png
themes/
	theme-1/
		theme.json
		page_styles/
			page_style_id/		
				style.css
				assets/
					font.otf
system/
	field-types/
		pages/
			my-field-type/
				page.xml
	page-section-types/
		pages/
			my-page-section-type/
				page.xml
	page-templates/
		pages/
			my-page-template/
				page.xml

Document.json

Document.json is the driving file for the import, it contains a description of the entire import and which content should be imported as well as any metadata for the document. The following are conditions for the document.json file followed by an example.

• document.json must be all lowercase, and present at the root of the import zip
• document.json must contain a key __VERSION__ with a value of 2 (This is used to indicate that this is a version 2 import)
• document.json must contain the following keys even if they are empty:
  • metadata: The metadata for this document, empty value is {}
  • metadata_strategy: The strategy by which metadata is combined with existing metadata for the document. Options are: "merge" and "replace"
  • pages: The list of page slugs to import, these should match the directory names inside the pages folder, pages are imported in the order they appear in this array. empty value is []
  • system: The collection of system types to import. Empty value is {}
  • themes: The list of themes to import. Empty value is []

Pages

Pages are contained in a folder called pages. Each page should be contained within a folder named with the slug of the page, matching the slug in the pages list from document.json. Each page should contain at least 2 files, page.json and page.xml. Page.xml should contain the page content as described in XML Format while page.json contains the metadata and metadata_strategy keys from document.json but are used for describing the metadata for this particular page.

Themes

Themes can contain any theme you want to import alongside your document. Themes can be omitted from imports if you do not need to import a theme. theme.json contains the definition for this theme including the page styles which should be imported and all html markup for field types and page section types. An example of theme.json is below. Note that the directory for each page style should use the page style UUID as the directory name.

{
    "export_type": "html",
    "name": "Pathologist Profiles",
    "page_layouts": [],
    "page_styles": [
        {
            "is_default": true,
            "js_files": [],
            "name": "Default Style",
            "override_default": false,
            "pages": [],
            "slug": "default-style",
            "uuid": "e7a09126-36d0-45b0-adf1-846fe2d6c917"
        }
    ],
    "slug": "pathologist-profiles",
    "system_types": {
        "field_types": [
            {
                "content_type": "text",
                "markup": "<h2>{{content}}</h2>",
                "name": "Heading",
                "slug": "heading"
            }
        ],
        "page_section_types": [
            {
                "name": "Embedded Section",
                "slug": "embedded-section"
            }
        ]
    },
    "uuid": "c4c681da-f5bb-4255-a76c-eb7384f0aff0"
}

System Types

It is not recommended for you to manually construct system types imports. These are internal to Carbon editor and while they are available they are primarily used by exporting from an existing space in Carbon editor. If you feel you have a use case for manually constructing system types please contact us.

Importing with the API

Importing a version 2 import is almost exactly the same as a version 1 import with one small difference, after the import begins but before pages are imported the status of the import will change to "Waiting for user". During this time you need to review and respond to any validation messages before the import will continue. Below is a step by step guide for handling this state.

1. Retrieve the validation messages from the api response by getting the "validation" key from the import_data.
2. Construct an object of responses for each message,
   1. For each validation message the key should be the UUID of the validation message
   2. The value should be one of:
      1. dont-import //Does not import this theme/system-type 
      2. replace //Replaces the existing theme/system-type with the one from the import
      3. create-new //Creates a new theme/system-type based on the import and uses it for all content in the import in the place of the existing one.
3. Retrieve the respond url by accessing the "respond" key in your api response.
4. POST the object you constructed in step 2 to this url. The object should be sent with a name of "responses" and JSON encoded.
5. Retrieve the "continue_import" key from the api response.
6. POST to continue_import with no data to resume the import with your validation responses.
7. Complete the import as usual.