11.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 integral 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 setting the external folder with templates, you can use the property '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 done at the start of the application only if there isn't any other system template.

In the notification template agenda, it is possible to restore/redeploy/refresh templates that are in the resources. For templates that can not be found there, it isn't possible to 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 it isn't allowed to change any 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.