Sitecore Content Serialization structural overview

Abstract

Overview of the Sitecore Content Serialization (SCS) structures.

You serialize content items in and out of a Sitecore instance using the Sitecore Content Serialization (SCS) system. This is done by configuring which content items to include and which ones to exclude, and which operations to perform on the content items.

The SCS system serializes content items into your project folder as YAML files. The default path is \serialization relative to the module file, but you can configure the relative serialization path to any path you want.

The project configuration file

The project configuration file is named sitecore.json. It has several properties including a modules property that references the relevant Sitecore Content Serialization modules.

A project configuration in its simplest form looks like this:

{
  "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",    
  "modules": [ "src/*/*.module.json" ],
  "variables": {},
    "serialization": {
      "defaultMaxRelativeItemPathLength": 120,
      "defaultModuleRelativeSerializationPath": "serialization"
   }
}

Manual and automatic serialization

You can serialize manually or automatically:

  • You use manual serialization when you want to push or pull content items to or from a Sitecore instance on demand.

  • You use automatic serialization to specify content items that you would like to have automatically serialized from a Sitecore instance to your file system when they are created or updated.

Including and excluding content items

You single out subsets of content items for serialization with includes and rules. This is useful for repeating serialization of particular parts of your content item tree.

You configure what and how content items are included and excluded from serialization in a module file such as Project.module.json. You can place and override serialization configurations in all module files.

Note

A content item is only included once across all modules.

Each include must have a name property that becomes a folder name in your file system and a path property that specifies what part of your content item tree to serialize.

For example, to serialize your entire content item tree to the serialization\content\ folder in your file system, add this to your Project.module.json file and run the sitecore ser pull command:

"items": {
  "includes": [
    {
      "name": "content",
      "path": "/sitecore/content/home"
    }
  ]
}

Important

The order of the includes is important. If your content items are dependent on a template in the same module, your template include must come first.

See the Sitecore Content Serialization configuration reference for the complete list of include and rule properties.

Note

Include properties are referred to as root properties, as in root name and root path.

Rules

Rules are used to configure the serialization of content item trees. You configure rules with a path relative to the root path, the scope of content items to influence, and any alterations to the allowed push operations.

For example, if you want to synchronize the /sitecore/content/home/products/ path and all its descendants except those in the legacy/ path, you add an include like the following:

"items": {
  "includes": [
    {
      "name": "content",
      "path": "/sitecore/content/home",
      "rules": [
        {
           "path": "/products/legacy",
           "scope": "ignored"
        },
        {
           "path": "/products",
           "scope": "ItemAndDescendants",
           "allowedPushOperations": "createUpdateAndDelete"
        },
        {
           "path": "*",
           "scope": "ignored"
        }
      ]
    }
  ]
}

The rule system works by the first-match-wins principle, meaning that when a content item matches a rule, all subsequent rules are ignored:

  • The first rule tells SCS to ignore all content items in the /sitecore/content/home/products/legacy path.

  • The second rule tells SCS to serialize all content items in the /sitecore/content/home/products path. All subcontent items are included because the scope is ItemAndDescendants.

  • The third rule prevents SCS from serializing any more /sitecore/content/home content items. The wildcard path of this rule matches all content items not matched by the previous rules, and the ignored scope prevents them from being serialized.

Keep the following things in mind when you configure rules:

  • Do not let rule paths overlap. Or, if you do, you must put the most specific rule first.

  • Rules for parent's paths override rules for children's and descendant's paths.

  • Rule scopes cannot be more inclusive than the root scope. For example, if the root scope is ItemAndChildren, the rule scope cannot be ItemAndDescendants.

  • The alias property in a rule replaces the root name property (the folder name in your file system) for this particular rule.

  • If you have configured an alias property and a scope property with an ignored value, the scope is used. Content items scoped to be ignored are not influenced by aliases.

See the Sitecore Content Serialization configuration reference for all configurable rule properties.

Exclude fields in an SCS package

Note

The excluded fields feature is available from CLI 4.0 or later.

You can specify fields to exclude from serialization. Sync operations do not take these fields into account. It is also possible for package, watch, and diff CLI commands. You can specify excluded fields in the sitecore.json config file and any *modules.json file.

Note

Sync operations always ignore excluded fields. So if you change those fields in Sitecore, the CLI does not detect any changes, and pushing data does not override them. If you have excluded fields in YAML files, they are removed only after changes in the included fields or if you manually delete that exclusion and perform a pull operation.

The excludedFields property contains an array of the excluded fields with two properties: fieldId and description.

Configure excluded fields

There are two ways to configure excluded fields: in the sitecore.json file or a *modules.json file:

Set up excluded fields in the sitecore.json file

To set up excluded fields in the sitecore.json file:

  • Modify the serialization section of the sitecore.json file, for example:

    ...
      "serialization": {
        "defaultMaxRelativeItemPathLength": 120,
        "defaultModuleRelativeSerializationPath": "serialization",
        "excludedFields": [
          {
            "fieldId": "8cdc337e-a112-42fb-bbb4-4143751e123f",
            "description": "__Revision"
          },
          {
            "fieldId": "badd9cf9-53e0-4d0c-bcc0-2d784c282f6a",
            "description": "__Updated by"
          },
          {
            "fieldId": "d9cf14b1-fa16-4ba6-9288-e8a174d4d522",
            "description": "__Updated"
          },
          {
            "fieldId": "5dd74568-4d4b-44c1-b513-0af5f4cda34f",
            "description": "__Created by"
          },
          {
            "fieldId": "25bed78c-4957-4165-998a-ca1b52f67497",
            "description": "__Created"
          },
          {
            "fieldId": "{52807595-0F8F-4B20-8D2A-CB71D28C6103}",
            "description": "__Owner"
          },
          {
            "fieldId": "{001DD393-96C5-490B-924A-B0F25CD9EFD8}",
            "description": "__Lock"
          }
        ]
      }

    Note

    Specify base fields, for example, fields from the standard template that you do not want to sync. They are taken into account during serialization independently of particular module configurations.

Set up excluded fields in the modules.json file

To set up excluded fields in the *modules.json file:

  • Modify the items section of the *module.json file, for example:

    ...
    items": {
            "includes": [
                {
                    "name": "Apikey",
                    "path": "/sitecore/system/Settings/Services/API Keys"
                },
                {
                    "name": "Media",
                    "path": "/sitecore/media library/my-first-jss-app"
                },
                {
                    "name": "Templates",
                    "path": "/sitecore/Templates/Project/my-first-jss-app"
                },
                {
                    "name": "Content",
                    "path": "/sitecore/content/my-first-jss-app"
                },
                {
                    "name": "Layout",
                    "path": "/sitecore/Layout/Layouts/Project/my-first-jss-app"
                },
                {
                    "name": "Renderings",
                    "path": "/sitecore/Layout/Renderings/Project/my-first-jss-app"
                },
                {
                    "name": "Placeholders",
                    "path": "/sitecore/Layout/Placeholder Settings/Project/my-first-jss-app"
                }
            ],
            "excludedFields":[
                {
    				"fieldID": "{EB504D1B-B612-4FFF-B239-CA3BD7273D1B}",
    				"description": "FieldsForExclude1"
    			},
    			{
    				"fieldID": "{3C2C061E-F61F-4DF6-89EA-0B7A56348737}",
    				"description": "FieldsForExclude2"
    			},
    
    			{
    				"fieldID": "{4F7446A4-79C8-4853-A357-723665FE68DA}",
    				"description": "ExcludeUnversionFIeld"
    			}
            ]
        }

    Note

    Specify only fields from this particular module config file.

Check excluded fields

To check the summary of configured excluded fields:

  • Run the serialization info command. Output:

    Project
      Subtrees:
        Apikey: /sitecore/system/Settings/Services/API Keys
        Media: /sitecore/media library/my-first-jss-app
        Templates: /sitecore/Templates/Project/my-first-jss-app
        Content: /sitecore/content/my-first-jss-app
        Layout: /sitecore/Layout/Layouts/Project/my-first-jss-app
        Renderings: /sitecore/Layout/Renderings/Project/my-first-jss-app
        Placeholders: /sitecore/Layout/Placeholder Settings/Project/my-first-jss-app
          FieldsFilter Excludes: 3
    
    Excluded Fields From Default Serialization Config:
          FieldsFilter Excludes: 7

To check the full details of the configured excluded fields:

  • Run the serialization info -t command. Output:

    Maximum subtree-relative item path allowed: 120
    
    Project
      File: C:\Repos\Sitecore.DevEx\samples\Prototype\items/Project.module.json
      Subtrees:
    ...
          Excluded Fields:
            Field Id :{EB504D1B-B612-4FFF-B239-CA3BD7273D1B}: Description :FieldsForExclude1.
            Field Id :{3C2C061E-F61F-4DF6-89EA-0B7A56348737}: Description :FieldsForExclude2.
            Field Id :{4F7446A4-79C8-4853-A357-723665FE68DA}: Description :ExcludeUnversionFIeld.
    
    Excluded Fields From Default Serialization Config:
          Excluded Fields:
            Field Id :8cdc337e-a112-42fb-bbb4-4143751e123f: Description :__Revision.
            Field Id :badd9cf9-53e0-4d0c-bcc0-2d784c282f6a: Description :__Updated by.
            Field Id :d9cf14b1-fa16-4ba6-9288-e8a174d4d522: Description :__Updated.
            Field Id :5dd74568-4d4b-44c1-b513-0af5f4cda34f: Description :__Created by.
            Field Id :25bed78c-4957-4165-998a-ca1b52f67497: Description :__Created.
            Field Id :{52807595-0F8F-4B20-8D2A-CB71D28C6103}: Description :__Owner.
            Field Id :{001DD393-96C5-490B-924A-B0F25CD9EFD8}: Description :__Lock.