Characteristics of the JSS code-first import process

Abstract

Important things to know about the JSS code-first/disconnected import process

The JSS import process, used for code-first development, allows you to rapidly design and define the structure of an application while disconnected from Sitecore and then publish it to Sitecore, creating appropriate Sitecore artifacts as needed, such as templates, placeholder settings, datasource items, route items, and rendering items.

If you plan on using the App Import capabilities with your JSS apps, you must keep in mind the following:

The import process is idempotent

You can run the import process multiple times on the same application to the same Sitecore instance without repercussions, with some limitations.

Any fields on an item that are not explicitly defined in the manifest are left untouched. For example, if a Sitecore developer inputs a source for an imported field, the next import does not reset the source unless the manifest also defines a value for the source.

There are also special considerations that define how import works with content items and content editors.

The import process is not a substitute for Sitecore Serialization

The import format is designed to be simple as opposed to full-featured. It is quite capable but does not represent the full fidelity of Sitecore items or handle every situation when updating items. Headless Import is not meant as a replacement for tools such as Unicorn or TDS that serialize Sitecore items.

The import process primarily allows the design of rendering apps by front-end developers who might not have an available Sitecore instance, or want to begin working on their application when Sitecore is not yet set up. Eventually, in the development process, we recommend the import process is supplemented by or replaced by purpose-built Sitecore item serialization tools to maintain the state of a JSS app, with the possible exception of rapidly developed simple campaign-style apps.

Sitecore item serialization tools can serialize items created or updated by JSS import; they are like any other Sitecore item.

The import process uses strings as IDs by default

The import process maps string names onto Sitecore items that have GUIDs. This makes the import files easier to write, but it does mean that care must be taken when moving or renaming imported items.

Note

Imported Sitecore item IDs are deterministic: importing the same app on different Sitecore instances results in the creation of items with the same IDs in Sitecore.

Renaming imported Items

Because they are matched by string name, renaming an item in your manifest (or in Sitecore) after it has already been imported results in the creation of a duplicate item if the import is re-run. There are several options to deal with this:

  • Explicitly set the manifest ID to the existing imported item ID in Sitecore, then rename it in the manifest. It is renamed on import.

  • Set the display name and leave the name alone, which visually alters the name in Sitecore.

Moving imported items

Because they are matched by name, moving an imported item causes a duplicate of it to be created on the next import.

If you must move an imported item, set an explicit ID in the manifest for the item equal to the already imported Sitecore item ID. This causes the item to be looked up by ID instead of a name, and therefore it survives the moving operation still known by the manifest.

The import process does not purge unknown items

If a template or route is removed from the manifest, it is not deleted from Sitecore on the next import.

The import process sets values only for explicitly defined manifest data

For example, if a template is imported that does not define an icon, and a Sitecore developer sets an icon on the Sitecore item, future imports do not overwrite the icon value. Explicit manifest data overwrites values set in Sitecore, however - for example, if the manifest did define an icon for a template it would overwrite any value set in Sitecore on import.

Handling of item IDs in the import process

Sitecore items have unique GUID IDs. By default, App Import uses the name defined in the manifest to derive a deterministic GUID so that the imported item always has a predictable ID. This GUID is namespaced, so that names must only be unique within a section of the app, instead of across the entire JSS app.

For example, it is legal to have both a route and a template named Home (or two routes at different levels) but it is not legal to have two templates called Home. The namespace also contains the JSS application name, so multiple JSS apps can have items with the same name.

Important

Renaming a JSS application causes all of the expected GUIDs of its items to change.

It is also possible to specify an explicit ID for all of the items in the import manifest. This takes the form of adding an id property to the manifest definition. The id can be one of two types:

  • A GUID value - this value is used literally and is the exact item ID used in Sitecore

  • A string value - this is used as the source for a deterministic GUID. Unlike name-based deterministic GUIDs, explicit string IDs are namespaced only by JSS app name. This means that they must be globally unique within a JSS app.

Note

App Import never changes an existing imported item GUID to avoid losing data. If setting an ID value on an already imported item, that new ID does not take effect in Sitecore unless you delete that item and re-run the import or you run the import in full wipe mode.

The sample applications have examples of setting explicit IDs in their content reuse Style guide examples. Note that when adding components to the manifest, there are two id properties: renderingId and templateId - this is necessary because a JSS component definition results in adding two Sitecore items.

Important

When specifying explicit IDs on route data in a multilingual import environment, ensure that the same ID value is set on all language values.