Author: Jagmeet Kaur

You can check if you have the serialization plugin:

> dotnet sitecore plugin list

If plugin is not there, then install it by running:

> dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.Serialization

To get the information about serialization commands run:

> dotnet sitecore ser -h

You will get all the information about parameters like below:

Once setup of Sitecore CLI and Sitecore content serialization configuration is done, you are good to execute serialization of items.

First, login via interactive or non interactive flow(check link for more details):

Here, will go with non-interactive client login:

> dotnet sitecore login --authority https://<sitecore-identity-server> --cm http://<sitecore-instance> --allow-write true --client-credentials true --client-id <client-id> --client-secret <client-secret>

Login information will be saved in .sitecore/user.json.

Pull:

Serialize items from Sitecore to disk

You can figure out usage of individual commands with -h or –help command.

• Pull all items as configured in *.module.json.

> dotnet sitecore ser pull

After pulling items, you will see .yml file corresponding to each item in sitecore in disk

• Pull items from specific module only(with tags separated by comma ,For inserting tags, check – link)

> dotnet sitecore ser pull -i tags:[tagA,tagB]

• Pull items from specific module only(with Module namespace)

> dotnet sitecore ser pull -i ModuleA ModuleB

• Pull all items except certain modules with tags:

> dotnet sitecore ser pull -e tags:[tagA,tagB]

• Pull all items except some modules(with Module namespace)

> dotnet sitecore ser pull -e ModuleA ModuleB

• Pull items without integrity validation

> dotnet sitecore ser pull -s

• Check the differences/changes in disk and Sitecore without actually pulling it

> dotnet sitecore ser pull --what-if

Validate

Ensures file system integrity of serialized items in disk and their paths

It performs the following checks on serialized items:

• Invalid physical path.
• Orphaned parent ID.
• Non-included item.
• Empty folder.
• Duplicate item ID.
• Non-unique path.

• Run the validation on serialized items

> dotnet sitecore ser validate

• Fix the issues found in validation above

> dotnet sitecore ser validate --fix

If the --fix command finds duplicate content items in your file system, it keeps the last updated one and deletes the oldest one.

Package

• Create package of serialized items in disk

> dotnet sitecore ser pkg create -o FILE_PATH

Package with extension .itempackage will be created at the file path given in command.

Create package at root path location

> dotnet sitecore ser pkg create -o <Package name>

• Install the created package in Sitecore

> dotnet sitecore ser pkg install -f FILE_PATH

Push

Serialize items from disk to Sitecore

Push commands can be executed just like pull commands.

• Push all items as configured in *.module.json.

> dotnet sitecore ser push

• Push items from specific module only(with tags separated by comma , for inserting tags, check – link)

> dotnet sitecore ser push -i tags:[tagA,tagB]

• Push items from specific module only(with Module namespace)

> dotnet sitecore ser push -i ModuleA ModuleB

• Push all items except certain modules with tags:

> dotnet sitecore ser push -e tags:[tagA,tagB]

• Push all items except some modules(with Module namespace)

> dotnet sitecore ser push -e ModuleA ModuleB

• Push items without integrity validation

> dotnet sitecore ser push -s

• Check the differences/changes in disk and Sitecore without actually pushing it

> dotnet sitecore ser push --what-if

Explain

To check if specific path is present in any modules.

> dotnet sitecore ser explain --path "PATH"

It will return the module information in which mentioned “path” is present.

Watch

Pull the changed items automatically into file system.

• Activate watch

> dotnet sitecore ser watch

After this, you will get following folders and files:

.sitecore folder will have schemas and user.json file.

schemas folder contains three schemas:

• ModuleFile schema for each module configuration (<module name>.module.json)
• RootConfiguration required in setting up sitecore.json
• UserConfiguration schema used in user.json when we login into sitecore instance with interactive or non-interactive flow.

User.json saves the login information once the user logged in successfully via interactive or non-interactive flow. Do not commit this file in source control.

Configure sitecore.json

This file will be common to the project. We can configure following information in sitecore.json.

• RootConfigurationFile.schema.json schema is added at the top
• Modules: Add path of module or you can add a wildcard as given above to include all modules by itself based on architecture of project.
• Plugins: plugins installed in this for serialization, index, publish, resource packaging and database are added here.
• Serialization: It contains information about allowed max relative path length, module relative serialization path(where item ymls will be created), should it continue if serialization fails at some item, what fields need be excluded, etc.

There are several fields on items which do not contain important information and not required to be serialized. So you can add an array of the excluded fields with two properties: fieldId and description to Exclude property.

For Example:

"excludedFields": [
      {
        "fieldId": "badd9cf9-53e0-4d0c-bcc0-2d784c282f6a",
        "description": "__Updated by"
      }
]

NOTE:

-Excluding Revision fields from serialization can result in issues when publishing with the serialization command.
-You can also mention excluded fields in specific *module.json files to exclude from particular module items only.

Settings: It contains boolean entries to enable/disable telemetry and to enable the feature to check the Sitecore management services version compatibility.

Configure <module name>.module.json

• Create module file with <module name>.module.json.
• Add the Module schema at the top.

Update the path as per location of file.

• After schema, add following:

{
  "namespace": "",
  "references": [""],
  "items": ""
}

• In items property, mention sitecore item’s include paths to sync items, descendants, children, etc. as given below:

items:"
"includes": [
        {
          "name": "<name>",
          "path": "<sitecore item path>",
          "scope": "<scope>",
          "allowedPushOperations": "<allowedPushOperations>"
          "rules": [
                    {
                        "path": "<sitecore item path>",
                        "scope": "<scope>"
                    }
        }
]"

Details about include properties:

• Order of the include paths is important. For example: templates, layouts, renderings, should be added first in include path list to avoid conflicts while syncing content items due to dependency on templates, layouts, etc.

• You can also create a separate Base.module.json file for base items like templates, branches etc. and the add it as references(refer below code snippet) in rest of files. So in this way, we can order include paths inside the *.module.json and also set the hierarchy in which all module files need to be serialized.

• You can set the relative path at the module level(refer below code snippet) inside items. This will override the defaultModuleRelativeSerializationPath given in sitecore.json.

• You can also set the different exclude fields in different modules rather than setting same exclude fields for all modules.

...
items": {
        "includes": [
            {
                "name": "Apikey",
                "path": "/sitecore/system/Settings/Services/API Keys"
            },
            {
                "name": "Media",
                "path": "/sitecore/media library/my-first-jss-app"
            }
        ],
        "excludedFields":[
            {
	          "fieldID": "{EB504D1B-B612-4FFF-B239CA3BD7273D1B}",
		  "description": "FieldsForExclude1"
	    },
            {
		  "fieldID": "{3C2C061E-F61F-4DF6-89EA-0B7A56348737}",
		  "description": "FieldsForExclude2"
	     }
        ]
    }

• Like the include paths of content items, you can exclude certain set of items with rules along with each include path. For example:

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

Details about rule properties:

NOTE:

- Scope: Ignored, is only valid in configuring rules
- Sitecore CLI does not support duplicate item names and will break push/pull operations

• In the initial serialization, you will require to sync everything. However, in proceeding serialization, you may require to serialize a module or couple of modules. You can mention tags in the individual module files and then use those tags with push and pull commands to sync more targeted changes rather than to sync all

Pull command with tags:

dotnet sitecore ser pull --include tags:[global-208]

• You can also serialize role by adding roles property in module.json. The roles property is an array that consists of role predicate items with two properties: domain (Sitecore role domain) and pattern (a regex pattern to determine specific roles to include under the domain). For example:

{
    ...
    "items": {
        ...
    },
    "roles": [
      {
        "domain": "sitecore",
        "pattern": "Developer"
      },
      {
        "domain": "custom",
        "pattern": "Role*"
      },
      {
        "domain": "extranet",
        "pattern": "^MySite.*$"
      }
    ]
}