Create and install a Sitecore Content Serialization package

Abstract

How to create and install a Sitecore Content Serialization (SCS) package in your continuous integration pipeline.

Sitecore Content Serialization (SCS) packages (file extension .itempackage) contain specified modules and their serialized items. You use packages as build artifacts in your continuous integration pipeline by creating them in your build pipeline and installing them in your delivery pipeline.

Create an SCS package in your build pipeline

Important

You must configure any excluded fields before package generation.

To create an SCS package in your build pipeline:

  1. Go to your project folder that contains your sitecore.json file.

  2. To create the package, run the following command:

    sitecore ser pkg create -o <name of package>

    Note

    You can use the --include and --exclude arguments to specify what modules go into your package.

    By placing your demo or test content in a separate module, you can use these arguments to exclude it from deployment to upstream environments.

  3. Ensure the package file is present among your build artifacts.

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 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.
    

Install an SCS package in your delivery pipeline

After you have created the SCS package, you can then install it as part of your continuous delivery pipeline:

To install an SCS package:

  1. Make sure that you have configured your Identity Server and Content Management roles for non-interactive client login.

  2. To install the package, run the following command:

    sitecore ser pkg install -f <name of package>.itempackage --client-id <your client id> --client-secret <your client secret> --cm <your content management host> --auth <your identity host>

    Note

    Your client secret is a password that provides administrative access to the Sitecore instance. Ensure you are properly protecting this password using proper security mechanisms in your build system.

    Use the sitecore ser pkg install --help command to see more arguments for the package install command.