8.1:documentation:notifications:dev:notification_template

Apache velocity was used as a templating system. This system enables an easy replacement of parameters in the text, supports various macros and more. See more in the user documentation.

A classpath for templates that are an intergral part of the system was created. The classpath (subfolders included) is searched for templates in the XML format. The complete classpath is: /templates . This setting is controlled by an attribute in application.properties.

For set external folder with templates, you can use property with name 'idm.sec.core.notification.template.folder' and value classpath*:/eu/bcvsolutions/idm/templates/, file:/home/some_user/templates/.
# more locations can be given e.g. classpath*:/eu/bcvsolutions/idm/template/,classpath*:/external/templates/
# the latest location has the highest priority (last wins). Resources are prioritized - put resource, which has to override some core resource to last location
# Locations can be configured https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#resources
idm.sec.core.notification.template.folder=classpath*:/templates/
idm.sec.core.notification.template.fileSuffix=**/**.xml # template suffix

XML template structure

A template saved in resources as an XML file has the following structure:

<?xml version = "1.0" encoding = "UTF-8" standalone = "yes"?>
<!-- 
Description of the template and its parameters
 -->
 
<template>
	<name>Template name</name>
	//code//Unique template code///code//
	<subject>Notification subject</subject>
	<bodyHtml>Notification body, html can be used (if using html, don't forget the CDATA! block)</bodyHtml>
	<bodyText>Notification body without html.</bodyText>
	<parameter>Notification parameters, separated by a comma</parameter>
	<systemTemplate>Indication whether it is a system template, see system templates for more</systemTemplate>
	<moduleId>Module identifier for which the template is created, informative indication on the FE</moduleId>
</template>

Schema for XML file can be found in XSD file: IdmNotificationTemplate.xsd

XML file is loaded from resource by method initSystemTemplates. This method use JAXB and type class specially annotated for xml IdmNotificationTemplateType

All template elements are required. It is desirable to place only one template within one file, i.e. one root element template. This behavior is checked by IdmNotificationTemplateType.

Loading of templates is currently se at the start of the application only if there isn't any other system template.

From notification template agenda is possible to restore/redeploy/refresh templates that are in the resources. For templates that there can not be found, isnt possible apply restore/reload/refresh process.

It is possible to backup all templates without any difference of origin.

For backup and redeploy, you must have the configured property:

 idm.sec.core.backups.default.folder.path=

If configuration property is set and the folder does not exist, the folder will be created.

If we set the template indication as system (either in the form from FE or in XML), this template will not be allowed to change these attributes from FE forms: system template indication, parameters and code. System templates are closely tied with BE, currently isn't allowed to change some of their attributes.

Template parameters are fill-in as a Map where the key is the parameter name and the value is an object. The object can be virtually anything. Our object GuardedString is controlled via parameter showGuardedString.

At the moment, message parameter aren't persisted anywhere. The 'parameters' box on FE has only an informational purpose. Real parameters are added to the message when creating object IdmMessage.

Edation of templates (html, text, subject) we can now performed using component RichTextArea, this component contains simple WYSIWYG editor.

This WYSIWYG editor allows simplified filling template parameters with putting character $. After put this character into editor, we offered a current list of parameters:

On parameters we can use any available style from WYSIWYG editoru and their combinations.

Styl MUST be applied on all parameter including character $. Style cann't be applied for example only half of parameter. See examples

Good applied style to parameter:

Bad applied style to parameter: