Configure role serialization

Current version: 10.2

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

Note

This feature is available from CLI 4.0 or later and is currently unavailable for creating *.dat files. From version 4.1, the Sitecore CLI supports the inclusion of serialized roles in an item package.

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:

    RequestResponse
    {
        ...
        "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:

    RequestResponse
    ModuleWithRole
      Subtrees:
        ...
      Roles: 1

To check the full details of the role data:

  • Run the serialization info -t command. Output:

    RequestResponse
    Maximum subtree-relative item path allowed: 120
    
    ModuleWithRole
        File: C:\Projects\Example\serialization\src/ModuleWithRole/ModuleWithRole.module.json
        Subtrees:
            ...
        Roles:
            domain :extranet
            pattern:^MySite.*$

Do you have some feedback for us?

If you have suggestions for improving this article,