===== Notification templates =====
{{tag> notification template configuration}}

[[http://velocity.apache.org/|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 [[http://velocity.apache.org/engine/devel/user-guide.html|documentation]].

==== Deploy of templates from resource ====

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''.

<note tip>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/`. </note>

<code properties>
# 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
</code>

=== XML template structure ===

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

<code xml>
<?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>
</code>

Schema for XML file can be found in XSD file: [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/resources/eu/bcvsolutions/idm/templates/IdmNotificationTemplate.xsd|IdmNotificationTemplate.xsd]]

XML file is loaded from resource by method [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/java/eu/bcvsolutions/idm/core/notification/service/impl/DefaultIdmNotificationTemplateService.java#L203-L251|initSystemTemplates]]. This method use JAXB and type class specially annotated for xml [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/java/eu/bcvsolutions/idm/core/model/jaxb/IdmNotificationTemplateType.java|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 [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/java/eu/bcvsolutions/idm/core/model/jaxb/IdmNotificationTemplateType.java|IdmNotificationTemplateType]].

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

==== Redeploy and backup ====

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.

==== System templates ====

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 ====

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 [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-api/src/main/java/eu/bcvsolutions/idm/core/security/api/domain/GuardedString.java|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 [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/java/eu/bcvsolutions/idm/core/notification/entity/IdmMessage.java|IdmMessage]].