Configuring workflow email notifications

Development model: MVC Portal Engine
✖
Copy to clipboard

When a page reaches a workflow step, the system can send out notification email messages to those involved in the workflow process. This topic describes how to enable email notifications:

The topic applies to both basic and advanced workflow.

The emails are based on global email templates. Kentico comes with several default templates, which you can use without any additional configuration. If you want to create your own email templates for workflow notifications, follow the instructions in the Writing workflow email templates section.

The system sends notification emails according to the following rules:

  • When a page reaches a step (except Edit, Published and Archived), the Waiting for approval email is sent to users allowed to approve or reject the current (new) step.
  • When someone approves a page, i.e., moves it from an approval step to the next step, the Approved email is sent to the user who submitted the page for approval.
  • When someone rejects a page, i.e, moves it to the previous step, the Rejected email is sent to the user who submitted the page for approval.
  • Emails are never sent to users who performed the action that invoked the sending.

The system sends all workflow emails to users who have the Manage workflow permission, regardless of the settings on the Security tab of a custom workflow step.

Enabling workflow email notifications globally

  1. Open the Settings application.
  2. Navigate to Content -> Content management.
  3. Turn the Send workflow emails setting on.
  4. Type an address into the Send workflow emails from setting. This address will appear to recipients as the sender of the e‑mails.
  5. Click Save.

Configuring email notifications for a workflow

  1. Edit () the workflow and switch to the Emails tab.
  2. Set the Send notification emails setting to Yes. Alternatively, you can Use site settings.
  3. Check the box next to events that you want users to be notified about:
    • Send waiting for approval - sends an email when a page reaches an approval step (i.e. all steps except Edit, Published and Archived).
    • Send approved - sends an email when a page leaves an approval step in the direction towards the end of the workflow process.
    • Send rejected - sends an email when a page leaves a step in the direction towards the beginning of the workflow process.
    • Send published - sends an email when a page reaches a Published step.
    • Send archived - sends an email when a page reaches an Archived step.
  4. (Optional) Select an email template for events for which you don’t want to use the default template.
    • To bring up the list of available templates, click Select.
    • To edit the currently selected template, click Edit.
    • To create a new template, click New.
    • To clear your template selection and revert back to the default template, click Clear.
  5. (Optional) Specify whether you want to notify users who are not involved in the process. This notification will be sent every time a page reaches a step that needs to be manually approved.
    1. Select users using the Add users button.
    2. (Optional) Select an email template. Otherwise, the default template will be used.
  6. Click Save.

Configuring email notifications for a particular custom workflow step

You can configure email notifications for particular custom workflow steps.

  1. Edit the step and switch to the Emails tab.
  2. Set the Send notification emails setting to Yes. Alternatively, you can Use workflow settings. See Configuring email notifications for a workflow.
  3. Choose events you want users to be notified about.
    • Send waiting for approval - sends an email when a page reaches the step.
    • Send approved - sends an email when a page leaves the step in the direction towards the end of the workflow process.
    • Send rejected - sends an email when a page leaves the step in the direction towards the beginning of the workflow process.
  4. (Optional) Select an email template for events for which you don’t want to use the default template.
    • To bring up the list of available templates, click Select.
    • To edit the currently selected template, click Edit.
    • To create a new template, click New.
    • To clear your template selection and revert back to the default template, click Clear.
  5. Click Save.

Writing workflow email templates

  1. Open the Email templates application.

  2. In the Site drop-down list, select global.

  3. Click New template.

  4. Enter a name for the new template into the Display name field.

  5. Choose Workflow from the Email type drop-down list. This ensures that you will have relevant macros available to insert into the template’s text.

  6. (Optional) Specify a sender, a recipient, copy and blind copy recipients and a subject (From, Cc, Bcc and Subject fields).

  7. Write the text of the template.

    • An email template can have two formats - HTML and plain text. You should write the template text at least in the format that you use on you websites. By default, the system sends HTML emails. You can find out what your settings are in Settings -> System -> Emails -> Email format. You can insert context-specific information into the template’s text, such as the current step name or the link to edit the page, using macros. See the following section for a list of available macros.

  8. Click Save.

Macros in workflow email templates

In email templates of the Workflow type, you can use macros that hold information about the workflow and about the page that invoked sending the email. The following list presents workflow-related macros that you can use:

  • ActionDefinition - object that holds the parameters of the current step, if the current step is an action step.
  • ApplicationURL - URL address of the application.
  • Comment - comment that users can add when approving or rejecting pages.
  • CurrentStep - object that holds data of the step the page is currently in.
  • CurrentUser - object that holds data of the currently logged in user.
  • Document - object that holds data of the page.
  • DocumentPreviewUrl - address where anyone can view the latest version of the page as it would appear on the live site.
  • DocumentEditUrl - address pointing to the page in the Pages application where editors can modify the page.
  • DocumentActionName - name of the action that was performed with the page. The macro has four possible values.
    • Approve
    • Archive
    • Publish
    • Reject
  • OriginalStep - object that holds data of the step the page was in before it was moved to the current step.
  • Workflow - object that holds data of the workflow process.

Besides the listed macros, you can also use any other macro expression, as described in the Macro expressions chapter.