Request update notification

Description

Send a mail to a defined user on every request update or create. Show the changes that are made.

Approach

Prepare a package for request.update and request.create trigger. Prepare a HTML Template for the mail that can work with audit data. Merge the audit data before using the template. Send the mail.

Prerequisites

A HTML template in the needed language in the Templates tab, and the mail recipient must be set in the Environment variables tab.

• $DEMO_RECIPIENT - a default value containing the mail address
• request-watch-all-notes - the name of the template

Default values are used so solve the following problems:

• Different environments: E.g. template id's are different in sandbox and production. Testing is done in sandbox - after completion the package code can be transferred to production without a change, only the default values must be changed in production.
• Different packages: The same value should be used in different packages - a default value is identical in every package of an environment.

Templates are used so solve the following problems:

• Special text for mail or notes maintained outside the package code
• Identify the template by simple template names to use exactly the one that is needed
• Different language versions and fallback language versions of the same template are supported

In addition the webhook must be set with following parameters:

• Account: datacenter
• Event: request.update, request.create

Information about Audit data

With the mergeAudit(request) function call the request variable is enhanced by audit information. For each field there are new identifiers with a special prefix:

• request.audit_unchanged_subject - if the subject is not changed this variable is filled. if changed it is empty
• request.audit_changed_subject - if the subject is changed this variable is filled. if not changed it is empty.

This two enhancements are exclusive - only one of them is filled depending if the base value is changed or not in the last update. This makes it easy to write special code that shows the value in a different manner if it is updated.

There are other prefixes that are enhanced by the mergeAudit function:

• request.audit_is_changed_subject - indicates if the value is changed
• request.audit_old_subject - the old value before the update. If not changed it is identical to the new value.
• request.audit_new_subject - the new value after the update. If not changed it is identical to the old value.

In addition there are some variables that give information about the latest update

• request.audit_id - the id of the audit
• request.audit_user - the user responsible for the audit
• request.audit_action - the action that leads to the audit
• request.audit_created_at - the date and time the audit is created - this is the date and time of the update

Commented code

//
// send an email on every update
//

// write a log before the execution of the log
log('******* Send Request Notification Begin ********');

// enhance the data in the request variable with audit data
mergeAudit(request); // inject request with latest audit information

// use a template to create a mail
// request-watch-all-notes is defined in 'Templates', uses request
let mailData = createTemplateHTMLMail('request-watch-all-notes');

// set the email address of the mail
mailData.to = $DEMO_RECIPIENT; // defined in 'Defaults'

// set the mail out profile. since this is the default profile this code only shows how it works - it is not needed.
mailData.profile = 'built-in'; // defined in 'Email Out' (optional)

// send the mail with the text and data above
sendMail(mailData);

// write a log after the execution of the code
log('******* Send Request Notification End ********');    

A template similar to the one that is used here is discussed on the Templates page.

What it does: Write a mail with request update infos to a special recipient.

Condensed code

The comments and log entries are helpful, but make the code above quite long. Leaving them out, the code can be condensed to:

mergeAudit(request);
let mailData = createTemplateHTMLMail('request-watch-all-notes');
mailData.to = $DEMO_RECIPIENT;
sendMail(mailData);