XML notification templates

Notification template example:

<?xml version="1.0" encoding="utf-8"?>
<Notifications description="Object notifications" version="3.7.3.13420">
   
  <Default>
    <Filter>
      <Event>IEntityActionHandler.ActionExecuted</Event>
      <Object>ObjectIconModule.Models.MyObject</Object>
    </Filter>
    <RecipientSet>
      <User>{$WatchList}</User>
    </RecipientSet>
    <URL>
      /ObjectIconModule/Home/ViewItem/{$New.Id}
    </URL>
    <ObjectId>{$New.Id}</ObjectId>
  </Default>
   
  <Notification description="Object renamed">
    <Filter>
      <Action>Rename</Action>
    </Filter>
    <Subject>
      ({SR(’Object renamed’)}) {$New.Name}
    </Subject>
    <ShortMessage>
      {SR(’{$New.ChangeAuthor} renamed the object from "{$Old.Name}" to "{$New.Name}"’)}
    </ShortMessage>
    <FullMessage>
      {TableStart()}
      {PropertyRowWithChanges({$Old.Name};{$New.Name})}
      {PropertyRow({$New.Name})}
      {PropertyRow({$New.ChangeAuthor})}
      {TableEnd()}
    </FullMessage>
  </Notification>
 
</Notifications>

To add your template to the system notification templates folder ({Configuration folder}\Notifications\) and make it work, do the following:

1. Implement an empty class, inherited from NotificationTemplateEmbeddedDataSource. Place this class in the same folder, where you XML notification template is;
2. Change the properties of the notification template file.

Example of implementation of an empty class, inherited from NotificationTemplateEmbeddedDataSource:

class MyObjectNotificationsDataSource : NotificationTemplateEmbeddedDataSource
{
}

Also, change the properties of your notification template file. Set Build Action to Embedded Resource:

Fig. 1. Changing the properties of the notification template file

To make the template display "old" values in notifications (e.g. {$Old.Name}), implement the following class:

[Component]
internal class MyObjectRenameActionsEventAggregator : BaseEntityUpdateEventAggregator
{
    protected override IEnumerable<Guid> ProcessedActions
    {
        get { yield return MyObjectActions.RenameGuid; }
    }
}

Consider an XML notification template from the article with the object subscription. There are two required tags in a notification template: Notifications and Notification.

<Notifications description="Object notifications" version="3.7.0.41532"></Notifications> - the main notification tags, that must contain all the other necessary tags.

<Notification Name="AddComment"></Notification> - tag with the notification. The same tags, as in the <Default> tag can be inside.

Example:

<Notification description="Object renamed">
  <Filter>
    <Action>Rename</Action> <!-- Action name -->
    <Object>ObjectIconModule.Models.MyObject</Object> <!-- Object to apply the action to -->
  </Filter>
  <Subject>
    ({SR(’Object renamed’)}) {$New.Name} <!-- Message subject -->
  </Subject>
  <ShortMessage>
    {SR(’{$New.ChangeAuthor} renamed the object from "{$Old.Name}" to "{$New.Name}"’)} <!-- Short message that contains the object author, old name and new name -->
  </ShortMessage>
  <FullMessage>
    {TableStart()}<!-- Table start -->
    {PropertyRow({$New.Name})} <!-- New object name -->
    {PropertyRow({$New.ChangeAuthor})} <!-- Changed by -->
    {TableEnd()}<!-- Table end -->
  </FullMessage>
</Notification>

There can be any number of <Notification> tags. Names may match, as well as <Action> actions and objects. It enables, for example, using the same action name in different objects or different actions in one object. Therefore you should pay attention when creating a notification. Names in Notification are also used in child notification templates to add to the parent notification.

If you plan to use your notification template as a parent one, you should assign Names in the Notification tag. Then in child templates, in the Notifications tag use the Default tag, in which specify the parent template, e.g. <Notifications Default="Projects.ProjectTaskBase/">; it means that the default template will be selected from the file Projects.ProjectTaskBase.xml. To use existing Notification, in your child template create a Notification with the Parent parameter, in which specify the parent Notification, e.g. <Notification Name="CreateMilestone" Parent="Projects.ProjectTaskBase/Create"> - in this case, the notification with the name Create from the template Projects.ProjectTaskBase.xml will be used.

Inside the Notifications tag you can use the optional tag <Partial Name="DefaultFullMessage"> </Partial>, which is a partial representation of the text, which later can be inserted to the required places, e.g. to <ShortMessage>/<FullMessage>. The Name parameter should be used in the method {Partial(’Partial name’)}. You can see an example of using the Partial method below in the <ShortMessage>/<FullMessage> tags. <Partial> tag example in CRM.ContractorLegal.xml:

<Partial Name="DefaultContractorFullMessage">
{PropertyRow({$New.CreationAuthor})} <!-- Author -->
{PropertyRow({$New.Name})} <!-- Contractor name -->
{PropertyRow({$New.Phone})} <!-- Phone -->
{PropertyRow({$New.Email})} <!-- Email -->
{PropertyRow({$New.Site})} <!-- Website -->
{PropertyFullRow({$Comment.Text};SR(’Comment’))} <!--Comment text-->
{PropertyFullRow({$Attachments})} <!-- Attachments -->
{ExtensionZone(’EleWise.ELMA.CRM.Models.ContractorLegal-DefaultFullMessage-AfterAttachments’)}
</Partial>
<Partial Name="DefaultContractorShortMessage">
{PropertyFullRow({$Comment.Text};’’)} <!-- Comment text -->
</Partial>

 <Default></Default> - Default values are inside this tag.

 1. Message sending channels:

<Channels>EMail</Channels>

If you add this tag and specify a message channel in it, then the notification will be sent only via the specified channel. If you do not specify this tag, then by default the notification will be sent via all the existing message channels, such as Email or via the channel you created. To learn more about creating a new message channel, read this article.

2. Object URL:

<URL>/ObjectIconModule/Home/ViewItem/{$New.Id}</URL>

3. Message subject:

<Subject>({SR(’Object renamed’)}) {$New.Name}</Subject>

4. Filter:

<Filter>
  <Event>IEntityActionHandler.ActionExecuted</Event>
  <Object>EleWise.ELMA.Projects.Models.ProjectTask</Object>
  <Condition>
    (IsProjectTemplate({$New}) = false) and ({$New.Project.Status} = ’Active’)
  </Condition>
</Filter>

5. List of users who will receive the notification <RecipientSet><User> {$WatchList} </User></RecipientSet> (In this case, only the users subscribed ({$WatchList}) to the object will receive the notification, but you can pass other users as well, such as responsible users, executors, etc.). The user list has several additional parameters:

• Clear, responsible for clearing the list of notification recipients. Using this parameter may be necessary if your notification template is a child template, therefore to prevent adding the users from the parent template you can use this parameter.
• SendToAuthorOnly, responsible for sending a notification only to the author.
  Example:

<RecipientSet Clear="true">
  <User>{$New.Executor}</User> <!-- Executor -->
  <User>{$New.InformTo}</User> <!-- Informed -->
  <User>{$New.CreationAuthor}</User> <!-- Author -->
  <User>{$WatchList}</User> <!-- Subscribed users -->
</RecipientSet>

To learn about creating a custom data type in the list of notification recipients, read this article.

6. Object ID. Required for the messages section, where a notification is generated depending on the object type and a notification is shown by the specified ID, as well as for keeping history on the object with the specified ID (reassignments, rescheduling…):

<ObjectId>{$New.Id}</ObjectId>

7. Full message:

<FullMessage>
  {TableStart()}{Partial(’DefaultFullMessage’)}{TableEnd()}
</FullMessage>

8. Short message:

<ShortMessage>
  {TableStart()}{Partial(’DefaultShortMessage’)}{TableEnd()}
</ShortMessage>

9. Clearing the list of notification recipients. The difference from <RecipientSet Clear=true> is that Clear clears a specific set of notification recipients, while <RecipientSetClear> clears all the notification recipients:

<RecipientSetClear>true</RecipientSetClear>

10. Sending a message to the author. The author is a system user who performed an action, which led to sending a notification (e.g. created a task). By default, the system filters notifications and does not send notifications about actions, a user performed him/herself:

<SendToAuthor>true</SendToAuthor>

Object dictionaries

In notification templates you can use object dictionaries - Dictionary<string, object>, its key is a name, used in a notification template, and its object may be any system object. Using object dictionaries may be useful to write objects more conveniently in case of a complex logic, e.g. separate the users who had already received a notification about the object from those, who had not received notifications. Example:

<RecipientSet>
  <User>{$Group}</User>
</RecipientSet>

In this example, Group is the dictionary key and the list of notification recipients is the object. You must implement an object dictionary in the same place, where the EntityActionEventArgs is initialized. Let's refer to the example from the article, in which subscription to notifications about changes in an object is implemented. The Rename method is defined in the object manager. Inside this method, EntityActionEventArgs is initialized. A simple use case of an object dictionary:

public IEntityActionHandler EntityActionHandler { get; set; }
 
[Transaction]
[ActionMethod(MyObjectActions.Rename)]
public virtual void Rename(IMyObject model, string newName)
{
    model.Name = newName;
    model.Save();
    var users = model.UserGroup.Users;
    var args = new EntityActionEventArgs(null, model, MyObjectActions.Rename);
    if (users.Count > 0)
    {
        args.ExtendedProperties.Add("Group", users);
    }
    EntityActionHandler.ActionExecuted(args);
}

As you can see, users from the UserGroup object group were added to the dictionary. Alternatively, the following structure can be used:

<RecipientSet>
  <User>{$New.UserGroup.Users}</User>
</RecipientSet>

However, {$Group} is shorter and can be used only inside a certain event, therefore you can implement a complex logic of compiling object dictionaries, for example, exclude certain users from the list of notified users.

Functions in notification templates

You can use functions in notifications. The function name must be specified in braces, and then pass parameters in parenthesis. Parameters are separated with semicolumns. Two notification formats are generated: text and HTML; the sending channel decides which format to use. These functions are useful because they generate different markup for different formats.

Functions in notifications: 

Using document template generation language in notification templates

You can use both conditions and cycles in notification templates. The syntax is the same as the one used in reports and document templates. To learn more, read Help or this article.