How to send mail from a productive HANA XS application

By: Petra Lazarova, Dobrinka Stefanova, Boris Angelov

Disclaimer: This document relates to functionality available on the productive SAP HANA Cloud Platform landscape.

Just imagine you developed a web shop XS application on a productive HANA system, and you’d like your customers to be notified by email about changes of their sales orders.

The solution you need is sending an e-mail from the HANA XS application.

Scenario

You send a mail to your personal email account by implementing an XS Service (XSJS) via consuming HTTPS REST mail provider. (MailGun email service provider will be used for the example solution)

Prerequisites

1. Get a free MailGun account at http://www.mailgun.com/. Log in your MailGun account and copy your API key. You will need it for Basic authentication at step 5. Copy your MailGun subdomain. You will use your subdomain into your destination path prefix and as your mail domain and mail sender domain at step 1 and step 2. 
2. For more details on Sending Messages using Mailgun HTTP API, see http://documentation.mailgun.com/index.html
3. Purchase a productive HANA account obtaining host, account and schema names.
4. Set up SAP HANA Tools feature group and SAP HANA Cloud Platform Tools for Connecting to SAP HANA Systems following the offical documentation.
5. Connect to productive SAP HANA instance following the documentation.
6. Create, activate and test your simple XS application (For this example let’s assume you created a package “mypackage” and XS Application “myapplication” as a subpackage)

Procedure

Step 1: Create XS HTTP destination file “mailgun.xshttpdest” into your application root folder and add the code:

host = “api.mailgun.net”;

port = 443;

pathPrefix = “/v2/<Your MailGun subdomain>”;

useProxy = true;

proxyHost = “proxy”;

proxyPort = 8080;

authType = none;

useSSL = true;

timeout = 30000;

Note: Enter your MailGun subdomain as a part of pathPrefix and check and set the proxy for your environment at XS Destinations documentation as proxyHost.

Activate your XS HTTP destination file file.

Step 2: Create an XS Service “mailgun.xsjs” file into your application root folder, and add the following code:

var destination_package = “mypackage.myapplication”;

var destination_name = “mailgun”;

var message;

var he;

try {

  var dest = $.net.http.readDestination(destination_package, destination_name);

  var client = new $.net.http.Client();

  var req = new $.web.WebRequest($.net.http.POST, “/messages”);

  req.headers.set(‘Content-Type’, encodeURIComponent(“application/x-www-form-urlencoded”));

  req.parameters.set(“domain”,”<Your MailGun subdomain>”);

  req.parameters.set(“from”,”me@<Your MailGun subdomain>”);

  req.parameters.set(“to”,”<Your email address>”);

  req.parameters.set(“subject”,”Test subject”);

  req.parameters.set(“text”,”Test text”);

  client.request(req, dest);

  var response = client.getResponse();

  $.response.contentType = “text/html”;

  $.response.setBody(response.body.asString());

  $.response.status = $.net.http.OK;

} catch (e) {

  $.response.contentType = “text/plain”;

  $.response.setBody(e.message);

}

Note: Enter your MailGun subdomain as a “domain” and part of “from” mail address parameters and enter your mail address into “to” parameters .

Activate your XS Service file.

Step 3: Open MailGun API URL “https://api.mailgun.net:443” into your browser and export the site certificate of this site as a Base-64 encoded X.509 file local on your PC.

Note: Refer to your browser documentation on this step.

Step 4: Open “SAP HANA XS Administration” tool from “HANA XS Applications” node of SAP HANA Cloud Platform cockpit and create a trust store “MailGun” via TRUST MANAGER. Browse and import the MailGun certificate from your local PC:

Step 5: Browse the XS APPLICATIONS tree and edit your MailGun destination assigning the MailGun trust store you created, set user “api” and your account API Key from prerequisite 1 and save your destination.

Step 6: Launch your application from SAP HANA Cloud Cockpit adding “mailgun.xsjs” as a suffix:

You will see output like that:

{ “message”: “Queued. Thank you.”, “id”: “<20140115151444.9049.23372@<Your MailGun subdomain>>” }

Step 7: Open your mail box and see the mail 🙂