Tutorial

How do I process jobs?

To understand how to use rethinkdb-job-queue we need to go through a real example. In this document we will see how to send emails using the Nodemailer SMTP client.

The example we are going through will be very similar to the one on the README document with a little more detail.

This example is broken down into the following parts.

• Installation
• Create send-mail.js File
• Create index.js File
• Test Sending Emails
• Full Code
• Summary

Installation

Install RethinkDB

The rethinkdb-job-queue requires an installation of RethinkDB. Please follow the installation procedure for your operating system to get RethinkDB up and running.

Install Node.js / NPM

Once you have RethinkDB installed you will need an installation of Node.js. Follow the installation procedure for Node.

Now that you have Node.js installed you will also have the "Node Package Manager" or NPM package installed. NPM is bundled with the Node.js installation package. Using the npm command line tool you can continue the installation.

Install rethinkdb-job-queue

If you are adding rethinkdb-job-queue to an existing project then change directory to that projects root directory. If you are starting from scratch you may want to initialize a project using npm init. Either way get into the directory you would like to install rethinkdb-job-queue.

Finally we install rethinkdb-job-queue by typing the following into the command line.

npm install rethinkdb-job-queue --save

Install Nodemailer

Seeing as this example is using the Nodemailer package you will also need to install Nodemailer as follows:

npm install nodemailer --save

At this point we have all the programs and packages installed that we need to start coding.

Create send-mail.js File

To make this a complete tutorial we need to make our code modular. In this section we are going to make a node module that returns a function we can use to email a new user to confirm their email address.

To start with, create a new file in your project directory called 'send-mail.js'.

Require Modules

At the top of the send-mail.js file add the following code.

const Queue = require('rethinkdb-job-queue')
const nodemailer = require('nodemailer')

These two statements give us access to rethinkdb-job-queue and nodemailer modules.

Configure Nodemailer

Now under the require statements add the following to configure Nodemailer.

const transporter = nodemailer.createTransport({
  service: 'Mailgun',
  auth: {
    user: 'postmaster@your-account-domain-here.com',
    pass: 'your-api-key-here'
  }
}, {
  // Default message fields
  from: '"Application" <support@application.com>'
})

// setup e-mail data with unicode symbols
const mailOptions = {
  subject: 'Email Address Confirmation',
  text: `
  Thankyou for registering for this great Application.
  Please click the link below to confirm your email address.

  url`
}

There are two configurations above. The first creates the Nodemailer transport object with service, authentication, and default fields setup. The second is creating an object holding the Nodemailer options for sending email.

Important: You will need to register with mailgun or some other SMTP service provider. Replace the service and Auth Nodemailer options above with your own account details.

Create the Queue

Next we are going to use the rethinkdb-job-queue to create the Queue object and queue.

const cOptions = {
  db: 'JobQueue', // The name of the database in RethinkDB
}
const qOptions = {
  name: 'RegistrationEmail' // The name of the table in the database
}

const emailQueue = new Queue(cOptions, qOptions)

The above statements do a lot as listed below.

• Connect to a RethinkDB instance operating on the localhost at port 28015.
• Create a database in RethinkDB called JobQueue if it doesn't exist.
• Create a table in the database called RegistrationEmail if it doesn't exist.

Provide Job Handler

To send emails we need to provide a job handler function to the Queue object.

emailQueue.process((job, next) => {
  console.log('Job processing started')
  mailOptions.to = job.to
  mailOptions.text = mailOptions.text.replace('url', job.url)
  return transporter.sendMail(mailOptions).then((info) => {
    console.dir(info)
    return next(null, info)
  }).catch((err) => {
    console.error(err)
    return next(err)
  })
})

The process method call above provides the job handler with two parameters being the job and the next function. You can see we are using the job.to property for the recipients and the job.url for the confirmation address.

In this example we are using a simple text.replace to replace the template mailOptions.text url value with the provided URL from the job.

Lastly we are calling the transporter.sendMail method to send the email. If it succeeds we call next(null, info) and the job is completed. If it fails we call next(err) to retry the job at a later time.

Export the Function

With all the setup complete, we need to expose the function we can call to send emails by adding jobs to the queue. Place the following code at the bottom of the send-mail.js file.

module.exports = function sendMail (recipient, confirmUrl) {
  const job = emailQueue.createJob()
  job.to = recipient
  job.url = confirmUrl

  emailQueue.addJob(job).then((savedJobs) => {
    console.log('Job Added: ' + savedJobs[0].id)
  }).catch(err => console.error(err))
}

As you can see, the function takes two parameters being the recipient and the confirmUrl. We create a new job calling emailQueue.createJob() and populate it with the job.to = recipient and the job.url = confirmUrl. Finally we add the job to the queue calling emailQueue.addJob(job).

Create index.js File

Now it is time to test out our send-email.js module. To do this create a file called indes.js and place the following at the top of the file.

const sendMail = require('./send-mail')
sendMail('your@email.address', 'http://confirm.net')

That's all we need in the index.js file to test our new module.

Test Sending Emails

Now the fun part. Lets test sending emails by calling the index.js file with Node.js.

> node index.js

If everything is setup correctly we should see something like the following in the console.

Job Added: 638855b9-0d40-4558-ae07-c431f0b5f9a0
Job processing started
{ accepted: [ 'your@email.address' ],
  rejected: [],
  response: '250 Great success',
  envelope:
   { from: 'support@application.com',
     to: [ 'your@email.address' ] },
  messageId: '75ea8cfa-f6a8-395f-c12b-f4dc3cb4f70f@application.com' }

Full Code

Below is a copy of the send-email.js file and the index.js file for reference.

send-email.js

const Queue = require('rethinkdb-job-queue')
const nodemailer = require('nodemailer')

const transporter = nodemailer.createTransport({
  service: 'Mailgun',
  auth: {
    user: 'postmaster@your-account-domain-here.com',
    pass: 'your-api-key-here'
  }
}, {
  // Default message fields
  from: '"Application" <support@application.com>'
})

// setup e-mail data with unicode symbols
const mailOptions = {
  subject: 'Email Address Confirmation',
  text: `
  Thankyou for registering for this great Application.
  Please click the link below to confirm your email address.

  url`
}

const options = {
  db: 'JobQueue', // The name of the database in RethinkDB
  name: 'RegistrationEmail' // The name of the table in the database
}

const emailQueue = new Queue(options)

emailQueue.process((job, next) => {
  console.log('Job processing started')
  mailOptions.to = job.to
  mailOptions.text = mailOptions.text.replace('url', job.url)
  return transporter.sendMail(mailOptions).then((info) => {
    console.dir(info)
    return next(null, info)
  }).catch((err) => {
    console.error(err)
    return next(err)
  })
})

module.exports = function sendMail (recipient, confirmUrl) {
  const job = emailQueue.createJob()
  job.to = recipient
  job.url = confirmUrl

  emailQueue.addJob(job).then((savedJobs) => {
    console.log('Job Added: ' + savedJobs[0].id)
  }).catch(err => console.error(err))
}

index.js

const sendMail = require('./send-mail')
sendMail('your@email.address', 'http://confirm.net')

Summary

That's it. We have created a module file that will send emails using Nodemailer and the Job Queue.

There are a few things missing from this tutorial. For example the recipient email address is hard coded in the index.js file. You need to get these from your application users. You will also need to generate the confirmation urls.

This is a very simple tutorial to get you started. It is not a best practice or recommendation in any way. You will need to come up with your own modules and functions for your application.