Configure role serialization

Version: 10.4

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.

Warning

The Sitecore CLI allows you to serialize roles in a custom security domain. However, the custom domain will not be created automatically with the push command. To make sure the roles function correctly, manually create a security domain in your target environment.

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,