Content approvals

The approval process reviews and approves content, including specific approval types. The most common case is content approvals used in the editorial UI to review and approve content items before publishing, and this is also the main reason that the approval system exists. You can create custom approval types similar to how content approvals are defined, but this is currently not supported and is not covered here.

An approval definition is a sequence of steps to be approved. Each step has one or more reviewers. In each step, one reviewer must approve the content before moving it to the next step in the definition. If the site is multi-language, you can configure the definition so that different reviewers can approve different languages in a step.

Definitions are mostly static, and they are created and changed rarely.

A definition has a Uri-based reference to an object, which, in most cases, is a content item. You can use a saved definition with a reference for that reference, and other references, such as a content item and its descendants. The resolve method, which searches for a definition, is used to check if a reference has access to a definition. In the case of content approvals, that means traversing the content tree upwards and looking for a definition.

Each time you save a definition, you create a definition version. The latest saved version is the current definition and also the version returned when asking for a definition through IApprovalDefinitionRepository. You can also get a specific version through the IApprovalDefinitionVersionRepository.

You create an approval process when something needs to be reviewed (for example, a content item before publishing) and the content is connected to a definition. You can create multiple approvals for each definition.

Running an approval is the process of stepping through the definition, where the reviewers of each step decide whether to approve or reject. All steps need to be approved for the approval to be valid. If a reviewer rejects a step, then the approval is rejected.

A Uri-based reference identifies an approval, and it must have a definition.

A started approval is locked to the definition version, which was the current version when someone started it. It does not switch to another definition version if the definition is changed, but new approvals will use the new version.

The Content approvals feature is accessed through the EPiServer.Approvals.ContentApprovals namespace, which gives access to content versions of the classes ApprovalDefinition and Approval, and also extension methods with ContentReferences in the repository interfaces. The ContentReference is converted to the Uri reference under the hood.

You can create a definition of a content item in a content tree, and the descendants of that content item can use it. Use ResolveAsync to find a definition.

You start a content approval by setting the status of a content item to AwaitingApproval. When a content approval is approved, the referenced content item transitions to status CheckedIn. If rejected, the content item transitions to status Rejected.

Before CMS UI 10.10, a reviewer in an approval definition is a user's name. In release 10.10, Optimizely introduced a role reviewer, where a reviewer can be the user name or role.

From CMS UI 11.8, you can implement the four-eyes principle. When configuring an approval sequence, you can prevent users from approving their own changes. The default value is false, allowing users to approve their changes.

When a user approves or rejects a content item, a validation determines whether the user is part of the step as a user or a role member. A call to the SecurityEntityProvider is used to validate whether a user is part of a role and call the underlying user or role provider configured for the site (for example, AspNet Identity Provider).

Approval flow

The normal state flow for a content version is: