Configure role serialization

Abstract

How to serialize roles in your project.

It is possible to serialize roles so that sync operations include the specified roles. The serialization lets developers and DevOps engineers manage roles in their solution by synchronizing roles with other developers on the same project and lets them promote changes to source-controlled roles across Sitecore environments.

Note

This feature is available from CLI 4.0 or later and currently unavailable for creating *.itempackage and *.dat files.

Configure roles in *module.json files

You can define which roles to include in the serialization process. You can specify roles in any *module.json configuration file. The roles property is an array that consists of role predicate items with two properties:

domain (Sitecore role domain)
pattern (a regex pattern to determine specific roles to include under the domain)

Important

You must make sure your local environment is up-to-date before making changes. Defining a pattern such as ^.*$ and performing a push command before a pull command (so that serialized roles are not present on your computer) deletes all roles staged for removal from the Sitecore instance.

To set up roles in a *module.json configuration file:

Inside the root section, specify the pattern and domain role properties. For example:

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

Important

Nonserialized orphaned roles that match the configuration predicate are automatically deleted from Sitecore.

Check role serialization

To check the summary of the role data:

Run the serialization info command. Output:

ModuleWithRole
  Subtrees:
    ...
  Roles: 1

To check the full details of the role data:

Run the serialization info -t command. Output:

Maximum subtree-relative item path allowed: 120

ModuleWithRole
    File: C:\Projects\Example\serialization\src/ModuleWithRole/ModuleWithRole.module.json
    Subtrees:
        ...
    Roles:
        domain :extranet
        pattern:^MySite.*$