Setting up Notification and Email

Modified on Sun, 10 Dec, 2023 at 1:40 AM

Configuration of the notification and email templates are by default set in appsettings.json. They can be adjusted as HTML text with the exact number of placeholders each, depending on their format in the below description.

If present, it enables in app notifications (and emails) for the following actions:

change of an item that user is subscribed to
user is assigned to an item
user is set as owner of an item

The entire configuration can be missing or commented out if notifications are not required.

Parent section is NotificationConfiguration and it contains:

LogEntryTemplate - HTML text template with placeholders for one log entry; this is used in both app notifications and email notifications for element change
MessageTemplates - section for app notification templates
EmailTemplates - section for email notification templates
EmailSettings - section for email settings such email server, sender address, username, password, etc.

Each of the MessageTemplates and EmailTemplates sections contains 3 templates corresponting to the previously enumerated actions:

ElementChangeTemplate
AssignedToElementTemplate
OwnerChangedToElementTemplate

Example of full notification configuration in JSON format:

"NotificationConfiguration": {
	"LogEntryTemplate": "<li><b>{0}</b><ul><li>Old Value: {1}</li><li>New Value: {2}</li></ul></li>",
	"MessageTemplates": {
		"ElementChangeTemplate": {
			"TitleTemplate": "Project {0} {1} updated",
			"ContentTemplate": "<p>This object in Hopp which you are following has been updated at <b>{4}</b> by <b>{5}</b>:</p><p>Project <b>{0} {1}</b></p><p>with these changes:</p><ul>{2}</ul><p>You added this comment when you subscribed to the object:</p><p><b>{{0}}</b></p><p>Please follow this link if you wish to review the changes:</p><p><a href=\"{3}\">{1}</a></p>"
		},
		"AssignedToElementTemplate": {
			"TitleTemplate": "Project {0} {1} was assigned to {2}",
			"ContentTemplate": "<p>This object in Hopp was assigned to <b>{2}</b> by <b>{3}</b>:</p><p>Project <b>{0} {1}</b></p><p>Please follow this link if you wish to review the changes:</p><p><a href=\"{4}\">{1}</a></p>"
		},
		"OwnerChangedToElementTemplate": {
			"TitleTemplate": "Project {0} {1} changed owner to {2}",
			"ContentTemplate": "<p>This object in Hopp changed owner to <b>{2}</b> by <b>{3}</b>:</p><p>Project <b>{0} {1}</b></p><p>Please follow this link if you wish to review the changes:</p><p><a href=\"{4}\">{1}</a></p>"
		}
	},
	"EmailTemplates": {
		"ElementChangeTemplate": {
			"EmailSubject": "Project {0} {1} updated in Hopp",
			"EmailBody": "<div style=\"font-family: sans-serif\"><p>{0},</p><br><p>This object in Hopp which you are following has been updated by <b>{6}</b>:</p><p>Project <b>{1} {2}</b></p><p>with these changes:</p><ul>{3}</ul><p>You added this comment when you subscribed to the object:</p><p><b>{4}</b></p><p>Please follow this link if you wish to review the changes:</p><p><a href=\"{5}\">{2}</a></p><br><p>Regards</p><p>Hopp</p></div>"
		},
		"AssignedToElementTemplate": {
			"EmailSubject": "Project {0} {1} was assigned to {2}",
			"EmailBody": "<div style=\"font-family: sans-serif\"><p>{2},</p><br><p>This object in Hopp was assigned to <b>{2}</b> by <b>{3}</b>:</p><p>Project <b>{0} {1}</b></p><p>Please follow this link if you wish to review the changes:</p><p><a href=\"{4}\">{1}</a></p><br><p>Regards</p><p>hopp</p></div>"
		},
		"OwnerChangedToElementTemplate": {
			"EmailSubject": "Project {0} {1} changed owner to {2}",
			"EmailBody": "<div style=\"font-family: sans-serif\"><p>{2},</p><br><p>This object in Hopp changed owner to <b>{2}</b> by <b>{3}</b>:</p><p>Project <b>{0} {1}</b></p><p>Please follow this link if you wish to review the changes:</p><p><a href=\"{4}\">{1}</a></p><br><p>Regards</p><p>hopp</p></div>"
		}
	}

	// In order to receive the notifications via email you'll have to uncomment 'EmailSettings' section and provide values for a valid SMTP provider
	//"EmailSettings": {
	//	"Username": "(not set)",
	//	"Password": "(not set)",
	//	"From": "(not set)",
	//	"DisplayName": "(not set)",
	//	"SmtpServer": "smtp.office365.com",
	//	"Port": 587,
	//	// This numeric value will be converted to enum which possible values are: { 0:None, 1:Auto, 2:SslOnConnect, 3:StartTls, 4:StartTlsWhenAvailable }	
	//	"SecureSocketOptions": 3
	//}
}

Templates are HTML representation with a specific set of placeholders marked as {number}

LogEntryTemplate - Single log entry of a change used for ElementChange actions that is used in both in app notification and in email notification. It has 3 placeholders that corresponds to the following:
- {0} - changed field
- {1} - previous value
- {2} - current value

MessageTemplates
- ElementChangeTemplate
  - TitleTemplate - 2 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
  - ContentTemplate - 6 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
    3. {2} - change log (multiple lines, each using LogEntryTemplate)
    4. {3} - item link
    5. {4} - time of change
    6. {5} - changed by user
- AssignedToElementTemplate / OwnerChangedToElementTemplate (same section structure for both, but separate templates)
  - TitleTemplate - 3 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
    3. {2} - target user (assignee or owner)
  - ContentTemplate - 5 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
    3. {2} - target user (assignee or owner)
    4. {3} - changed by user
    5. {4} - item link

EmailTemplates
- ElementChangeTemplate
  1. TitleTemplate - 2 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
  2. ContentTemplate - 7 placeholders:
    1. {0} - subscribed user
    2. {1} - project name
    3. {2} - item identifier and title
    4. {3} - change log (multiple lines, each using LogEntryTemplate)
    5. {4} - item subscription comment
    6. {5} - item link
    7. {6} - changed by user
- AssignedToElementTemplate / OwnerChangedToElementTemplate
  (same section structure for both, but separate templates)
  - TitleTemplate - 3 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
    3. {2} - target user (assignee or owner)
  - ContentTemplate - 5 placeholders:
    1. {0} - project name
    2. {1} - item identifier and title
    3. {2} - target user (assignee or owner)
    4. {3} - changed by user
    5. {4} - item link

In order to setup the infrastructure for sending emails, the application will need to be configured with details of an SMTP server which can be used to deliver the email in the EmailSettings section of NotificationConfiguration.

The parameters for this are:

"SmtpServer": "(the name of SMTP provider, for instance smtp.gmail.com or smtp.office365.com)"
"Port": "(the port of SMTP provider, for instance 587)"
"SecureSocketOptions": "(way of specifying the SSL and/or TLS encryption that should be used, with numeric values from 0 to 4, corresponsing for instance with values 0:None, 1:Auto, 2:SslOnConnect, 3:StartTls, 4:StartTlsWhenAvailable )"
"Username": "(name used to authenticate to the smtp server, for instance username)"
"Password": "(password used to authenticate to the smtp server, for instance password)"
"From": the from field for the email, suggest a generic Hopp user be set up for this
"DisplayName": "an alias for the from field for the email, suggest a generic Hopp user be set up for this"

If the "EmailSettings" section is missing from appsettings file the emails won't be sent and the application won't crash. If one of the above parameters are missing or incorrect, the application will crash. More details can be found in Readme.md file that is included in the source code.