Notifications

Notifications provide information to administration users about various events in the system. In the current version of Xperience by Kentico, notifications are system emails providing information about user management events, such as password reset or account lock notifications.

Configure domains for notifications

Service domain

A service domain is used in the URLs of various links within notification content, such as asset URLs. The service domain also sets the value of the $$ServiceDomain$$ placeholder, which can be placed into the content of the system’s default notifications.

For self-managed projects, you can configure the notification service domain using the SystemEmailOptions.ServiceDomain property and .NET configuration providers. For more information about startup options and examples, see Startup options in configuration files.

For SaaS projects, the notification service domain is fixed and in the following format:
<environment>-<project_name>.xperience-sites.com

Sending domain

For self-managed projects, you can configure a global sending domain for notifications. This domain must be used in the sender address of all notifications.

Use the SystemEmailOptions.SendingDomain property and .NET configuration providers. For more information and examples, see Global sending domain for system emails.

For SaaS projects, which use SendGrid to send emails, the sending domain is fixed and in the following format: <environment>-<project_name>.xperience-sites.com

Edit default notifications

The system contains several built-in notifications, which are necessary for the correct functioning of Xperience by Kentico, and cannot be deleted. However, you can edit the subject, content and sender address of the email.

1. Go to the Notifications application in the Xperience administration.
2. Select the notification you wish to edit.
3. On the Content tab, you can edit the subject of the email and its content. You must use the required placeholders listed below the Content field.
4. Save the edited notification.
5. On the Properties tab, you can adjust the following:
   • Notification template – allows you to adjust the notification’s overall design and layout by preparing your own notification email templates).
   • Sender email address – the “From” address that notification recipients see in their inbox. The domain part of all sender addresses must match the application’s sending domain.

To view how the generated email will appear to recipients, you can select the Preview tab.

Add URL placeholders

All of the default notifications require a URL placeholder, which is used to create a link that allows the user to perform a critical action (e.g., finish their registration, reset their password, or unlock their account). To add this placeholder into the notification Content, you can choose one of two approaches:

• Use the Insert link > Web URL option from the toolbar of the rich text editor. Add the placeholder into the URL field and enter the text you wish to display into the Text field.

  

• Switch the Content rich text editor to the Code View. This approach requires you to add an HTML tag that allows recipients to open a URL. For example, to insert a link with the multi-factor authentication reset URL and the text “Click here”, you would use the following code: <a href="{{MFAUrl}}">Click here</a>

Extend the notification editing UI

If the default Content field is not sufficient for your notification editing requirements, you can extend the UI with custom fields. Add custom fields to the Notification email module class and its corresponding UI form. Such fields allow you to manage notification content in a more structured way.

You can then insert the fields via {% field %} macros into your notification email templates.

Notification email templates

Notification email templates establish the structure, design and layout of notifications while incorporating static elements like headers or footers. A single template can be reused for multiple notifications. The content within the template is created using HTML code and styled with CSS. The templates also support the use of macro placeholders.

Create custom notification email templates

1. In the Notifications applications, go to the Email templates tab.
2. Select New template.
3. Fill in the following fields:
   • Notification email template name – the name displayed in the application.
   • (Optional) Identifiers – specify the code name if you wish to use a code name different than the pre-filled value.
   • (Optional) Description – allows you to add information and comments about the template. Only displayed to other editors in the Xperience administration.
4. Select Save.
5. On the Source code tab, write or copy the HTML and CSS code of your template.
6. Insert the {% notificationemailcontent %} macro to position the content of notification emails that use the template.
7. Save again.

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    {% notificationemailcontent %}
  </body>
</html>

Notification template macros

Notification templates must contain macro expressions, which serve as placeholders for notification email content.

The following macro types are available for notification emails:

• {% notificationemailcontent %} – represents the main content field of notification emails.
• {% field %} – represents any custom fields added to notification editing UI.

Create custom notifications

Developers can create custom notifications to inform administration users about events that are not covered by the default notifications. For example, you can send a notification to users when a specific global system event occurs.

1. Go to the Notifications application.

2. Select New notification.

3. Fill in the following properties:

   • Notification name – the name of the notification displayed in the administration.
   • (Optional) Identifiers – specify the code name if you wish to use a code name different than the pre-filled value.
     • The code name is used in code when registering placeholders and sending the notification.
   • Notification template – the notification template based on which the email body is created.
   • Sender email address – the “From” address that notification recipients see in their inbox. The domain part of all sender addresses must match the application’s sending domain.

4. Select Save.

The basic notification object is now ready. Before editors can add the notification content, you need to register placeholders and add code that sends the notification.

Register placeholders for custom notifications

Placeholders allow you to add variables into notifications. These placeholders are added into the notification’s content, and populated when the notification is actually sent. For example, a placeholder allows you to insert the name of the recipient into the notification content.

1. Create a new class in your Xperience solution.
   • See Integrate custom code for best practices about adding custom code to your project.
2. Make the class implement the INotificationEmailPlaceholdersByCodeName interface.
3. Assign the Code name of the related notification’s code name into the NotificationEmailName property.
4. List each placeholder as a property in your class. You can also adjust placeholder behavior by adding the following attributes to the properties:
   • PlaceholderDescription – text that appears next to the placeholders in the notification editing UI.
   • PlaceholderRequired – enabled validation for the notification, which fails if the placeholder is not used in the Content field.
   • PlaceholderDisableHtmlEncoding – used to render the placeholder’s value as a raw string. Otherwise the value is HTML encoded by default.
   C#

   Example of notification placeholders

   Copy

   
    // Represents the placeholders for a custom notification email.
    public class CustomNotificationPlaceholders: INotificationEmailPlaceholdersByCodeName
    {
        // Use the code name of the custom notification from the Notifications application
        public string NotificationEmailName => "CustomNotification";
   
        [PlaceholderRequired]
        [PlaceholderDescription("This is a custom placeholder.")]
        [PlaceholderDisableHtmlEncoding]
        public string CustomPlaceholder { get; set; } = "Default value";
        public string AnotherCustomPlaceholder { get; set; } = "Another default value";
    }
    

5. Add a custom module with initialization code into the project.
6. In the custom initialization code, register the placeholders to the NotificationEmailPlaceholderConfigurationStore using the store’s TryAdd method.

using CMS.Notifications;

// ...

NotificationEmailPlaceholderConfigurationStore.Instance.TryAdd(new CustomNotificationPlaceholders());

API for preparing and sending custom notifications

To send custom notifications:

1. Identify the context where you want to send the notification. For example, you can send custom notifications from global event handlers.
2. Make sure you have a placeholder class defined for the notification.
3. Create an instance of your placeholder class and populate the properties with the placeholder values for the context in which the notification is being sent.
4. Create an EmailMessage by calling the CreateEmailMessage method of the INotificationEmailMessageProvider service
5. Send the message using IEmailService.

// Services obtained via dependency injection
private readonly INotificationEmailMessageProvider notificationEmailMessageProvider;
private readonly IUserInfoProvider userInfoProvider;
private readonly IEmailService emailService;

// ...

// Gets a user with the user name "UserName" as the notification recipient
var recipientUser = userInfoProvider.Get("UserName");

// Populates values for the placeholders in the notification
var placeholders = new CustomNotificationPlaceholders
{
    CustomPlaceholder = "Value",
    AnotherCustomPlaceholder = "Another value"
};

// Creates an email message based on a notification email
var emailMessage = await notificationEmailMessageProvider.CreateEmailMessage("CustomNotification", recipientUser.UserID, placeholders);

// Sends the email asynchronously
await emailService.SendEmail(emailMessage);