feat: advanced email template

[sbliven]

Description

Adds a more advanced email template suitable for use with email job actions.

Motivation

The existing job-template-simplified.html is too simple for real emails. This PR adds a "real" template to serve as a basis for facility-specific customization, as well as a suite of tests to check that the template is rendered properly.

Details

This adds additional handlebar helpers:

• boolean logic (or, and, not)
• concat for string concatenation
• matches to test regular expressions (eg {{#if (matches job.statusCode "^finished")}})
• default convenience helper for undefined variables
• formatUnit for unit conversions. This generalizes the v3 formatByte helper: {{formatUnit size "B" }}

These are used in job-template.html, which supports nicely-formatted emails for retrieve, archive, and public jobs.

To use, add an email action to jobConfig.yaml, eg

        - actionType: email
          ignoreErrors: true
          to: "{{job.contactEmail}}"
          subject: |-
            [SciCatLive] {{ default job.jobParams.subject "Job has been updated"}}
          bodyTemplateFile: src/common/email-templates/job-template.html

When running in production mode (nginx), the job-template.html must be mounted into the container.

Fixes

Changes:

• Additional handlebar helper functions for use in templates
• Add job-template.html

Tests included

• Included for each change/fix?
• Passing?

Documentation

• swagger documentation updated (required for API changes)
• official documentation updated

official documentation info

[minottic]

very minor comment. THanks!

[sbliven]

Generated emails can be easily viewed from the src/config/job-config/actions/emailaction/__snapshots__ directory. Here are html previews (might be blocked by some networks since it's an open proxy):

job-template-simplified_archive_jobSubmitted.snap.html
job-template_archive_finishedSuccessful_.snap.html
job-template_archive_finishedUnsuccessful_.snap.html
job-template_archive_jobSubmitted_.snap.html
job-template_public_finishedSuccessful_.snap.html
job-template_public_finishedUnsuccessful_.snap.html
job-template_public_jobSubmitted_.snap.html
job-template_retrieve_finishedSuccessful_PSI-Ra.snap.html
job-template_retrieve_finishedSuccessful_PSI.snap.html
job-template_retrieve_finishedSuccessful_URLs.snap.html
job-template_retrieve_finishedUnsuccessful_PSI-Ra.snap.html
job-template_retrieve_finishedUnsuccessful_PSI.snap.html
job-template_retrieve_finishedUnsuccessful_URLs.snap.html
job-template_retrieve_jobSubmitted_PSI-Ra.snap.html
job-template_retrieve_jobSubmitted_PSI.snap.html
job-template_retrieve_jobSubmitted_URLs.snap.html

[rkweehinzmann]

Probably I’m missing context, but when are these html snapshots used? looks OK to me - just in the various templates there're some dummy PIDs or JobIDs indicated, but I would instead find their variables like handlebars more useful, same also the updated statusCode word for finishing successfully or not.

[sbliven]

@rkweehinzmann The snapshots are part of the unit tests. Anything that breaks the templating (eg if some fields were renamed) would hopefully cause a test failure due to the template output changing. They are deliberately checked in to git.

As a side effect, the snapshots can also be useful when making your own template. In scicatlive you can modify the template and re-run (npm test emailaction -- -u). Without committing anything, check the HTML files and verify that everything looks ok before actually sending emails. I will add this as a suggestion in the documentation.

[sbliven]

I would instead find their variables like handlebars more useful, same also the updated statusCode word for finishing successfully or not.

Can you give an example of what you mean? Or even better, add a suggested change in a review?