Jan Blaha

Blog about software development

Implementing html email notifications

jsreport

The best practice when adding email notifications feature to your system is to separate as much as you can from email body assembling to email sending outside of the core system. The emails templates quite likely often changes and you don't want to deploy the system because of every single notification change. The best is to just separate everything into an external system and give the access to your PR or Marketing department so they change emails as the time goes without affecting the core system.

jsreport reporting server is so flexible it can even fulfill the purpose of email notifications server. It provides email template browser based designer as well as email sending capability and simple REST API.

In this tutorial I explain how use jsreport to design, store and send email notifications. I won't explain every single detail of jsreport in this article so if you never used it before, rather check its get started first.

Let's assume for this tutorial you want to send simple notification to the user when he creates an account in a core system. The notification should contain a welcome message and information about the created account. The notification sending is triggered from the core system using jsreport API and contains required input data like receiver email or user information.

Prepare sample input data

Email notification assembling and sending will be triggered using jsreport API in production deployment. However during design time it is convenient to prepare some sample inputs to mock the actual API call. This is achieved using jsreport data extension just inside jsreport studio. So let's open jsreport studio and define some required inputs we will use in the email body.

mock input data

Prepare template with email content

Now it's time to design desired body of the email notification. This is done in the jsreport studio integrated designer. To open the designer create jsreport template and then select in the left menu sample data you previously created and switch to html recipe and jsrender templating engine.

email designer

jsreport uses javascript templating engines to dynamically assemble content like html. This gives you the full power to create any output you can think of however for email notifications just simple usage should be enough.

This example's template should contain a basic welcome message and user credentials. To assemble such a html email you just need to use simple binding. For jsrender templating engine it can look as follows:

<h1>Dear {{:fullname}}</h1>
your credentials are:</br>
username: {{:username}}</br>
password: {{:password}}

Where the syntax {{:fullname}} is used to replace the value from the sample data you provided or later to replace the valua from data specified in the API call.

You can now use the jsreport studio designer to preview the email body output until you are satisfied with it.

Prepare script sending email

You should have the jsreport template with email body prepared. Now it is time to define the custom script which will actually send the email. Such a script can be created in the jsreport studio and then associated with the email template.

email designer

The following snippet shows the script implementation using SendGrid email cloud service, but note you can use your smtp as well.

Please later visit the documentation to get better understanding of the custom scripts and what you can achieve with it. For now you can just copy paste the snipped.

When the script is ready you have to associate the script with the created template. Running the template preview afterwards will always send the email and you can verify the final output.

Call jsreport API

Everything should be prepare now and you can integrate jsreport notifications into the core system. Integration is very simple and you just need to do a single API call to jsreport server to invoke email rendering. The request should look in the following way:

POST: https://jsreport-host/api/report
Headers: Content-Type: application/json
BODY:

   { 
      "template": { "shortid" : "g1PyBkARK" },
      "data" : {
          "fullname": "...",
          "username": "...",
          "password": "...",
          "email": "...."
      }
   }

Further improvements

In the more complex scenarios there will be many templates for email notifications and in this case you can use jsreport child templates to share parts of the templates between each other. To localize the emails you can look at jsreport resources extension. Or just check all of the extension right now and use whatever you like.

Summary

jsreport helps developers to achieve various goals they used to be painfully fulfilling. One of such a goal is email notification feature which can be easily separated from the core system and "outsourced" into the jsreport server. jsreport designer and permission system can be then used to modify email notifications on the fly by the responsible persons without affecting the core system.

last blog posts


09-10-2015 14:09 AWS

Such a very common thing like adding an existing external volume to Amazon elastic beanstalk is not easily supported out of the box. The official blog mentions only how to attach a snapshot or how to attach and overwrite a new volume every time the service starts. It took me a while to make the config file actually adding an existing volume without formatting it every time so I share it here with you...

read more

04-10-2015 14:09 jsreport

The best practice when adding email notifications feature to your system is to separate as much as you can from email body assembling to email sending outside of the core system. The emails templates quite likely often changes and you don't want to deploy the system because of every single notification change. The best is to just separate everything into an external system and give the access to your PR or Marketing department so they change emails as the time goes without affecting the core system.

read more

03-22-2015 14:09 .NET NHibernate

NHibernate still rocks! Even with quite a bit old code base it is still at the top of the c# frameworks we daily use. Especially the framework extensiblity is tremendous. Now I am going to show you how we use NHibernate in the multitenant fashion.

read more

Jan Blaha

About author

Hi! My name is Jan Blaha. I'm software developer and startup enthusiastic. See my current work.