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.

Concepts

Approval definition

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.

Approval

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.

Content approvals

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.

📘

Note

The methods in this namespace should only be used for content approvals. If another approval system for content is used that also wants to identify by ContentReference, it should have its own set of extension methods in its own namespace.

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.

📘

Note

A content definition is shared for all versions/languages of a content item. Content approvals are created for a specific content version/language. That means it is possible to have multiple approvals for a content item running at the same time if they have different languages.

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.

Reviewers

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

📘

Notes

It is only the role name that is part of the definition, not the users in the role. The validation to see if a user is part of a role is made at the moment it is needed. This means that a user can be added to a role or removed from one and that will affect an already started approval.

The underlying user/role providers can have their own restrictions. For example, that the user must log in for the roles to update.

Approval flow

The normal state flow for a content version is:

• CheckedOut – The editor created a version that is being edited.
• AwaitingApproval – The editor is done and marks the version ready for approval.
• Rejected – If a reviewer does not approve the version it transitions to Rejected. After the editor has made changes, it can be set for approval again.
• CheckedIn – The version is approved and is ready for publishing.
• Published – The version is published.