Creating custom functions for notification templates

The article describes how to create custom functions for notifications. The function performs markup generation and specifies the start and end dates. Find further information about system functions that can be used for notification templates in this article. 

Example of data display

Fig. 1. The value of the Period function in the notification when creating a task 

Example of the expansion point class  

FormatedValue - it's a formatted value of the function.

FunctionEvaluationContext - the parameters for calculating the function. The number of parameters can be unlimited. The function parameters are separated by a semicolon, for example, {Period ({$ New.StartDate}; {$ New.EndDate}; SR ( 'Period'))}, where {$ New.StartDate}, {$ New. EndDate} and SR ( 'Period') are the parameters. In order to get the value of a parameter, you must refer to its position number. Referring to the above example, the parameter {$ New.StartDate} has a sequence number equal to 0, {$ New.EndDate} is the number 1 and so on. To be able to write the value, you must cast it to the correct format, using the function context.GenerationContext.FormatProvider.FormatValue (context.Parameters [Parameter_Position_Number]). It's necessary to cast values to the right format due to the fact that the value of the variable may include extra characters. For example, in case of passing the end date of a user task without time (dd.mm.yyyy).  If the value is not cast to the correct format, the notification will contain the start date dd.mm. yyyy 23:59:50, and if you cast the value, the date will be written in the correct format.

The function name will be similar to the name of the custom class method that implements the function to notification template. In this example, the functions for the notification is as follows: {Period ({$ New.StartDate}; {$ New.EndDate}; SR ( 'Period'))}; the third parameter is optional, as the field name ("End Date") will be generated by default.

[Component]
public class MyNotificationFunction: INotificationFunctions
{
    /// <Summary>
    /// Generates a string consisting of a property name and values ​​of the two dates.
    /// Option 1 - Value 1 (start date).
    /// Parameter 2 - Value 2 (end date).
    /// Parameter 3 - Title (optional), the default generated name "End Date".
    /// </ Summary>
    public static FormatedValue Period (FunctionEvaluationContext context)
    {
        string captionFinish = SR.T ( "End Date");

        if (context.Parameters.Count <2) return new FormatedValue (string.Empty);

        // The value of the first parameter (Start Date)
        var startDateValue = context.Parameters [0];
        // Formatted string value Start Date
        var startDateFormatedValue = context.GenerationContext.FormatProvider.FormatValue (startDateValue);

        // The value of the second parameter (End Date)
        var endDateValue = context.Parameters [1];
        // Formatted string value End Date
        var endDateFormatedValue = context.GenerationContext.FormatProvider.FormatValue (endDateValue);

        // Form values of notification 
        var formattedValue = SR.T ( "{0} to {1}", startDateFormatedValue, endDateFormatedValue);

        if (context.Parameters.Count == 3)
        {
            // Form a field name
            var caption = context.Parameters [2];
            var captionFormatedValue = context.GenerationContext.FormatProvider.FormatValue (caption);
            captionFinish = captionFormatedValue;
        }

        // Generate markup
        return new FormatedValue (string.Format ( "{0} {1}", captionFinish, formattedValue));
    }
}

Creating custom function of the notification templates generator 

The implementation of the ITemplateGeneratorFunctionsContainer is similar to the implementation of INotificationFunctions. In this example, the PriorityHight function is implemented, which returns true, if the task has a High priority. Note that INotificationFunctions is used to display markup, whereas ITemplateGeneratorFunctionsContainer is used in filter conditions.

Example:

<Filter>
  <Condition>
	(PriorityHight({$New}) = true)
  </Condition>
</Filter>

Example of the extension point class 

[Component]
public class TemplateGenerator : ITemplateGeneratorFunctionsContainer
{
    public static FormatedValue PriorityHight(FunctionEvaluationContext context)
    {
        var result = false;
        if (context != null && context.Parameters != null && context.Parameters.Count > 0)
        {
            var ctxParam = context.Parameters[0];
            if (ctxParam != null && ctxParam.Value is ITaskBase)
            {
                var task = (ITaskBase)ctxParam.Value;

                if (task.Priority == TaskPriority.High)
                    result = true;
            }
        }

        return new FormatedValue(result);
    }
}

This function can be added to an existing template of the notification Tasks.Task.xml in <Notification Name = "Create">. This template already contains a condition to send a notification to recipients, but if you add and (PriorityHight ({$ New}) = true) - notifications will be sent when a task with a high priority is created.

Links to API elements

INotificationFunctions
ITemplateGeneratorFunctionsContainer

Links to Knowledge Base

XML Message Templates