Managing approval sequences

Approval sequences are used both for Content approvals, which is part of Episerver CMS, and the Change approvals add-on.

  • Using Content approvals is a way to make sure that content is reviewed and approved before it is published. If content approvals have been defined for an item, the editor cannot publish it but has to set it as Ready for Review. For a description of content approvals from an editor's perspective, see Content approvals.
  • Change approvals lets you make sure that certain actions that affect the website structure or content are reviewed and approved before they are applied. See Change approvalsfor more information on which actions that are affected.

When an item or a change is in review, one or more appointed reviewers must approve it before the item can be published or the change is applied. The reviewers are defined by an administrator in an approval sequence.

How it works

You define an approval sequence for a specific page in the page tree or for a global or site-specific assets folder in the assets pane. You can then choose to let the item's or folder's children inherit the approval sequence, create a new approval sequence for the children or disable approval sequences for the children. For detailed information how approval sequences work on assets, see Approvals on assets.

Both individual users and user groups can be added. User groups and individual reviewers must have Read access right and at least one other access right to the content item to review and approve it. We recommend Read and Create because Create has the least capabilities since it prevents any actions on the content item itself, or Read and Change because Change alone cannot affect the visitor, unlike Delete and Publish. See Access rights and Managing users and user groups.

The approval sequence overview is opened from a page's or assets folder's context menu:

Image: Context menu, Edit approval sequence

In the approval sequence overview, you define the number of approval steps (you can have as many as you like), and also the persons responsible for review and approval in each of the steps.

Image: Approval sequence overview

Content approvals on assets

Each page in Episerver can have its own approval sequence. Assets, such as blocks and media (and also forms and catalogs if you have Episerver Forms and Episerver Commerce respectively installed), cannot have individual approval sequences. Instead, the approval sequence is set on each assets folder, and all assets in the folder have the same approval sequence set. Global and site-specific assets folders can inherit their approval sequence from a parent folder (up to the site root), or you can define a unique sequence for it (or disable it completely so that assets in the folder do not have to be approved). If there is no sequence set on a parent item, children inherit the disabled state.

Blocks and media in global (For All Sites) and site-specific (For This Site) folders inherit the approval sequence from the parent node by default. The content inherits from the site root, which is not the same for global and site-specific folders. The global assets folders inherit from Root, while site-specific assets folders inherit from the site's root, that is Start in the example image below.

Image: Assets inheritance

Local assets folders inherit their approval sequence from the page they are associated with. See Folders for a description of global, site-specific and local folders.

The Blocks and Media folders in the assets pane are actually the same folders in the software and share the same approval sequences; the Blocks and Media tabs in the assets pane are merely a way of filtering out blocks if you are in the Media tab and vice versa. This means that if Adam is set as a reviewer on block folder Bunnies, Adam is also a reviewer of media in media folder Bunnies.

As a result, if you edit a block in the Bunnies folder which links to images in the media folder Bunnies, and set the block to Ready for Review, the same content approval sequence is triggered also for the images.

Forms and catalogs have their own structures, so even if you have a Episerver Commerce catalog named Bunnies, it does not get the same content approval sequence as the Bunnies folders for blocks and media.

Assets added to an assets folder with a approval sequence set are not auto published, even if the auto publish option is set (see Auto publish media on upload).

Content approvals on multi-language sites

If you are working with a multi-language site, you can define different reviewers for the different languages in each step. Each language must have at least one reviewer, but it is recommended to have at least two reviewers per language. This is especially important if you select the Prevent users from approving their own changes check box, since an item could otherwise get stuck in the review process if the review request is started by a user who is also the only reviewer.

Items, such as images, that do not have a language set can be approved by any reviewer (even by reviewers that only have access to a specific language).

You can view how the approval sequence is defined for all languages or for each language individually by using the Display sequence for [language] drop-down list.

Image: Display sequence for language drop-down

Setting up an approval sequence

Setting up an approval sequence (single language website)

This section describes how to set up an approval sequence for one language. If your website uses multiple languages, see Setting up an approval sequence on a multiple languages website.

Image: Intro to approvals

  1. Open the approval sequence overview from an item's context menu (in the navigation pane or assets pane).
  2. In the first step, type the first letter of the reviewer's name. Select the reviewer from the list of suggestions. You can also add a user group. Groups have a special group icon in the list of suggestions and you can also see how many users are included in the user group.

    User groups and individual reviewers must have Read and at least one other access right, such as Create or Change to the item to review and approve it.

    It is recommended not to add large groups. Partly because users tend to think someone else will review if there are many responsible reviewers, and partly because many notifications will be sent out, which may annoy users. There is a setting in the web.config file which triggers a validation warning when you add a group with members exceeding this setting, and it also limits the amount of notifications sent to the users in the group. If it is set to 100, only 100 users will get email notifications even if the group contains 150 users. See Configuring the CMS user interface in the CMS Developer Guide on Episerver World.

    Image: Selecting a reviewer or user group

  3. If you added an individual reviewer, add at least one more reviewer to the step. You should have at least two reviewers in each step, in case one of the reviewers is unable to review and approve.
  4. Optional: Click Untitled Step to rename the step to something more descriptive, for example Product marketing or ISO compliance review.
  5. Optional: To add more steps to the approval sequence, click the add button: Episerver image. You can rearrange the steps by drag and drop.
  6. Optional: To require a review requester to enter a comment on the review request, select the Require comment when sending for review check box.
  7. Optional: To require a reviewer to enter a reason for approving or declining the content, select the Require comment on Approve or Require comment on Decline (or both).
  8. Optional: Select Prevent users from approving their own changes if the user who sends a review request should not be allowed to approve the changes even if the review requester is one of the appointed reviewers.
  9. Click Save.

Setting up an approval sequence for children items

When you have defined an approval sequence for an item, you can define if its children have to be approved or not.

  1. Open the approval sequence overview from a child item's context menu.
  2. Depending on how you want to set up the item's approval sequence, select one of the three radio buttons:
    • Enabled. This setting lets you edit and define the approval sequence any way you what. The approval sequence is not connected to the parent item's approval sequence. Set up the sequence in the same manner as described in the section above.
    • Inherited. This setting locks the approval sequence for the current item and it gets whatever settings its parent has. If the parent item's approval sequence is changed, so is the approval sequence for the current item.
    • Disabled. This setting disables the approval sequence for the item and it does not have to be approved.
  3. Inherited is set by default, so if you do not define an approval sequence for an item's children, they automatically get the same approval sequence as the parent. If inheritance is set on children and the approval sequence is disabled on the parent item, the children inherits the disabled state. Local assets folders inherits the approval sequence set on the associated page or block.

Setting up an approval sequence on a multiple languages website

The language setting only applies to Content approvals. Change approvals does not take this setting into consideration; all appointed reviewers can approve changes in all languages.

  1. Open the approval sequence overview from an item's context menu.
  2. In the first step, type the first letter of the reviewer's name. Select the reviewer from the list of suggestions. You can also add a user group. Groups have a special group icon in the list of suggestions and you can also see how many users are included in the user group.
  3. Click the Episerver image icon and select the languages the reviewer or group of reviewers can approve in the Select Language drop-down list. A reviewer or group of reviewers can approve content in one, several, or all languages.

    Image: Selecting a language

    There is a difference between selecting Any language and selecting all languages one by one. If you select Any language, the reviewer can approve an item in any language it exists in, which also includes any new languages you may add in the future. If you select all available languages one by one, these are the only languages the reviewer can approve content in. If you add a new language in the future, the reviewer does not have the rights to approve in that language.

  4. If you added an individual reviewer, add at least one more reviewer to the step. You should have at least two reviewers per language in each step, in case one of the reviewers is unable (or not allowed as the review requester) to review and approve.
  5. Optional: Click Untitled Step to rename the step to something more descriptive, for example Product marketing or ISO compliance review.
  6. Optional: To add more steps to the approval sequence, click the add button: Episerver image. You can rearrange the steps by drag and drop.
  7. Optional: To require a review requester to enter a comment on the review request, select the Require comment when sending for review check box.
  8. Optional: To require a reviewer to enter a reason for approving or declining the content, select the Require comment on Approve or Require comment on Decline (or both).
  9. Optional: Select Prevent users from approving their own changes if the user who sends a review request should not be allowed to approve the changes even if the review requester is one of the appointed reviewers.
  10. Click Save.

Editing an approval sequence

Open the approval sequence from the content item's context menu and make sure that the Enabled radio button is selected. Edit and save the approval sequence as described in Setting up an approval sequence. You can rearrange the approval steps by drag and drop. Hover over a group name to see the users included in the group.

Image: Group added to approval sequence

If the selected content item has children that are set as Inherited, they will inherit all changes.

Approving and canceling approval sequences

As an administrator, you have the right to approve the entire approval sequence in one go, and to cancel a review request. You do that from the Options button. When you are approving an entire approval sequence, you are required to motivate why you are skipping the approval sequence and approving all steps. As administrator, you can always approve the entire approval sequence even if you sent the review request yourself and Prevent users from approving their own changes has been selected.

Image: Approve entire sequence menu option

Deleting an approval sequence

You cannot delete an approval sequence but you can disable it. Open the approval sequence from the item's context menu and select Disabled. The item can now be published immediately and does not have to be approved. If the selected content item has children that are set as Inherited, these children do not have to be approved.

Commenting on content approvals

As an administrator, you decide whether review requesters have to add a comment on the review request, and if reviewers have to add a reason when they approve or decline content or not. An exception to this is when you approve an entire sequence, in which case you are always required to add a comment. For more information on commenting, see the Collaboration between editors.

The comments will be visible in the notification list in the user interface and in email notifications. Comments are also displayed in the project overview, if the content item in review is associated with a project.

All comments are stored in the database as part of the change log and can be used later on for auditing purposes without using projects.

Four-eyes principle

Certain businesses have the requirement that at least two persons must approve content or changes to a website before the content is published or changes applied. To achieve this, you need to set up an approval sequence with at least two steps, and at least two reviewers in each step.

To avoid that one of the reviewers in a step happens to be the user who starts the review, and thereby can evade the four-eyes principle by approving their own changes, you also need to select Prevent users from approving their own changes in the approval sequence.

Image: Four-eyes approval

Using notifications

Appointed reviewers can get notifications in the user interface (the bell icon Image: Notification icon in user interface shows the number of new notifications ) and by email. These notifications let the reviewers know that they have a review request waiting. The editor who started the review request is also notified when the reviewers approve or decline the request.

User interface notifications

For the notifications in the user interface to be instantly displayed, your web server needs to have WebSocket support enabled. See WebSocket support on Episerver World. If WebSocket support is not enabled, editors need to refresh the user interface to see the notifications.

Email notifications

For the email notifications to work, you need to configure your SMTP server with a from address. See Configuring your email server on Episerver World.

A scheduled job, Notification Dispatcher, determines how often email notifications are sent out to users. The job gathers all notifications into one summary email which contains the user's all content approval notifications generated since the last email. The scheduled job is set to run every 30 minutes by default. See Scheduled jobs for more information on how to configure this scheduled job.

If you want emails to be sent out immediately, this can be configured by a developer through code, see Configuring email notifications for content approvals in the Episerver CMS Developer Guide on Episerver World.