/hmrc-email-renderer

Primary LanguageHTMLApache License 2.0Apache-2.0

hmrc-email-renderer for MMCA-3476


Build Status Download

Run the tests and sbt fmt before raising a PR

Ensure you have service-manager python environment setup:

source ../servicemanager/bin/activate

Format:

sbt fmt

Then run the tests and coverage report:

sbt clean coverage test coverageReport

If your build fails due to poor testing coverage, DO NOT lower the test coverage, instead inspect the generated report located here on your local repo: /target/scala-2.12/scoverage-report/index.html

Manages the rendering of parameterised email using templates.

Before requesting to merge your PR, please ensure that you have re-based with main

Note: Before sending a pull request with template changes, please look at our guidelines.

How to deal with pull requests for transactional email templates

DC Team Note: Before accepting a PR and merging, please ensure you read through the following acceptance criteria.
Follow these instructions: How to deal with pull requests for transactional email templates

API

Path Supported Methods Description
/templates/:templateId POST Renders the email template for the given template Id More...

POST /templates/:templateId

Renders the email template for the given template Id and returns the rendered template details.

Example request body - parameters with String type key and values.

{
  "parameters": {
    "param1" : "Parameter to be used in the email template",
    "param2" : "Parameter to be used in the email template"
  }
}

Responds with status:

  • 200 When the template is rendered successfully
{
   "plain": "Rendered template in text format",
   "html": "Rendered template in HTML format",
   "fromAddress": "From address to be used for this email when sending",
   "subject": "Email subject to use", 
   "service": "The regime (i.e. - sa/paye/etc) that this template belongs to"
}
  • 404 When the template with the provided template Id cannot be resolved.

  • 400 When an insufficient set of parameters for rendering the template is specified in the request. Only the first missing mandatory value is reported.

See the How to add a template section to see the distinction between optional and mandatory parameters.

{
   "status": "Rendering of template failed",
   "reason": "key not found: param10"
}

Preview Mode

Templates can be fiddly to get right as they can ordinarily only be viewed by actually generating an email and sending it. To work around this you can preview templates during development by running the micro-service from sbt:

# if you have already forked the repo pls run these git commands otherwise you will
# get an error related to majorVersion below
# java.lang.IllegalArgumentException: Invalid majorVersion: 2. You cannot request a major version of 2 if there are 
no tags in the repository
git remote add upstream git@github.com:hmrc/hmrc-email-renderer.git  
git fetch upstream 
cd $WORKSPACE/hmrc-email-renderer
sbt -Dhttp.port=8950 -Dapplication.router=testOnlyDoNotUseInAppConf.Routes run

You should be able to list all the templates available for preview from http://localhost:8950/hmrc-email-renderer/test-only/preview.

Note that to render logos correctly the assets frontend also needs to be started using

sm --start ASSETS_FRONTEND -f

Quick Preview

Alternatively, you can do a preview of emails by starting the service using sm to preview the source, snapshot or release versions of the micro-service.

sm --start ASSETS_FRONTEND -r
sm --start HMRC_EMAIL_RENDERER [-f|-r]

Again, list the templates can then be previewed from

http://localhost:8950/hmrc-email-renderer/test-only/preview

Handling Templates based on Language preference

If we want to make a template to work based on preference.

We have to add this to configuration in following place

https://github.com/hmrc/app-config-base/blob/master/hmrc-email-renderer.conf

key should be an english templateId and value should be a Welsh templateId

We make a call to preferences service to see whether language is set to English or Welsh, if Welsh we return welsh template otherwise english.

License

This code is open source software licensed under the Apache 2.0 License