Connect Two Systems (Integration)

In this tutorial we're going to use Merrymake to connect two 3rd-party APIs; to send ourselves an email with a random joke every day.

Prerequisites

First, open Git Bash. If you don't have Git Bash, get it from https://git-scm.com/

We also need to make sure we have NodeJS installed. We can test this by running this command in Git Bash:

npm --version

It should give something like 10.2.3 . If not get it from https://nodejs.org/ The final tool we need is the Merrymake CLI, which uses Git and NodeJS. Install the CLI with the command:

npm install --global @merrymake/cli

Start Using Merrymake

With the CLI installed, we are ready to start using Merrymake. The first command we should run on every device we want to use Merrymake on is:

mm start

The mm tool now guides us through the initial process. Select:

1. setup new key specifically for Merrymake
2. Input your email address
3. create new organization
4. Name your organization or press enter to accept the suggested name
5. Press enter to accept the suggested service group name (service-group-1)
6. Press enter to accept the suggested repository name (repo-1)
7. initialize with a basic template
8. typescript
9. deploy the service immediately
10. post an event to the rapids
11. Press enter to accept the suggested event type (hello)
12. attach plain text payload
13. Input your name
14. Input "admin key"
15. Press enter to accept the suggested duration (14 days)

We should now see Hello, XXXX!, this means our service is running in the cloud. If you don't see this please reach out on our Discord to get assistance.

Send Emails

We are ready to start sending emails. We navigate into the repository we just created with the command:

cd [organization name]/service-group-1/repo-1

We'll use mailgun as the email provider, so head over there and sign up for a free account. Remember to verify your email. Then we need to create an API key and copy it. We put this API key in a secret environment variable with the command:

mm envvar

1. Input MAILGUN
2. the value is secret
3. Insert the API key
4. accessible in both prod and init run

Trial email domain location

We also need to grab our mailgun trial email domain.

1. Navigate to Send › Sending › Overview.
2. Add your email to the "Authorized Recipients" on the right.
3. Verify your email again.
4. Copy your trial email domain (see image)
5. Put that in another secret envvar:

   mm envvar new EMAIL_DOMAIN secret
   

   Insert the trial domain xxxxxxxxxxx.mailgun.org, accessible in both prod and init run.

To work with mailgun we need to install an npm package for it:

npm install mailgun.js

Open the file index.ts and replace its content with this:

service-group-1/repo-1/index.ts

Before

After

import { merrymakeService, MIME_TYPES, replyToOrigin, } from "@merrymake/service"; async function handleHello(payloadBuffer: Buffer) { let payload = payloadBuffer.toString(); replyToOrigin(`Hello, ${payload}!`, MIME_TYPES.txt); } merrymakeService({ handleHello, });

import { merrymakeService } from "@merrymake/service"; import Mailgun from "mailgun.js"; async function handleSendEmail(payloadBuffer: Buffer) { const joke = payloadBuffer.toString(); const mailgun = new Mailgun(FormData); const mg = mailgun.client({ username: "api", key: process.env.MAILGUN!, }); mg.messages.create(process.env.EMAIL_DOMAIN!, { from: `Merrymake <merrymake@${process.env.EMAIL_DOMAIN!}>`, to: ["YOUR@EMAIL.com"], subject: "Daily Joke", text: joke, }); } merrymakeService({ handleSendEmail, });

Notice: Remember to change YOUR@EMAIL.com

Since we've changed the function name we also need to update the hooks in merrymake.json, so replace its content with this:

service-group-1/repo-1/merrymake.json

Before	After
{ "hooks": { "main/hello": "handleHello" } }	{ "hooks": { "main/send-email": "handleSendEmail" } }

We can test to verify that our code works by deploying it

mm deploy

And triggering it with

mm rapids post send-email text "This is a test" _

It should say "Queued job" and within 15 minutes an email should arrive in your inbox (or spam folder).

Get a Random Joke

To fetch a random joke we install a package for making HTTP requests:

npm install axios

We use this library to call another 3rd-party API called iCanHazDadJoke. Open the file index.ts and replace it's content with this:

service-group-1/repo-1/index.ts

Before

After

import { merrymakeService } from "@merrymake/service"; import Mailgun from "mailgun.js"; async function handleSendEmail(payloadBuffer: Buffer) { const joke = payloadBuffer.toString(); const mailgun = new Mailgun(FormData); const mg = mailgun.client({ username: "api", key: process.env.MAILGUN!, }); mg.messages.create(process.env.EMAIL_DOMAIN!, { from: `Merrymake <merrymake@${process.env.EMAIL_DOMAIN!}>`, to: ["YOUR@EMAIL.com"], subject: "Daily Joke", text: joke, }); } merrymakeService({ handleSendEmail, });

import { merrymakeService postToRapids, } from "@merrymake/service"; import Mailgun from "mailgun.js"; import axios from "axios"; async function runDaily(payloadBuffer: Buffer) { const resp = await axios.get("https://icanhazdadjoke.com/", { headers: { Accept: "text/plain" }, }); postToRapids("send-email", resp.data); } async function handleSendEmail(payloadBuffer: Buffer) { const joke = payloadBuffer.toString(); const mailgun = new Mailgun(FormData); const mg = mailgun.client({ username: "api", key: process.env.MAILGUN!, }); mg.messages.create(process.env.EMAIL_DOMAIN!, { from: `Merrymake <merrymake@${process.env.EMAIL_DOMAIN!}>`, to: ["YOUR@EMAIL.com"], subject: "Daily Joke", text: joke, }); } merrymakeService({ runDaily, handleSendEmail, });

Since we've changed the function name we also need to change the hook:

service-group-1/repo-1/merrymake.json

Before	After
{ "hooks": { "main/send-email": "handleSendEmail" } }	{ "hooks": { "main/send-email": "handleSendEmail", "main/daily": "runDaily" } }

Now to deploy the service we simply run:

mm deploy

The Merrymake platform automatically builds, packages, and deploys the service, and then hooks it up for traffic.

Run on a Schedule

The only thing left is to trigger the service automatically once every day. Merrymake supports recurring jobs out of the box. We do declare our recurring events in the event-catalogue folder

cd ../../event-catalogue

Here we can replace the content of cron.json

event-catalogue/cron.json

Before	After
{ }	{ "daily": { "expression": "0 0 0 ? * * *" } }

Save the file and deploy the event-catalogue:

mm deploy

Conclusion

Using the CLI we have:

• Registered an account and created an organization
• Deployed a backend and the event-catalogue
• Inspected and posted events to our Rapids
• Set two secret environment variable
• Created a universal API key

We have seen how to implement and deploy a serverless backend with two co-deployed services that communicate.

These are the basic steps to connect two 3rd-party systems with Merrymake.

Thank you for your time.