Basic Builds :: Custom Scheduled Email Rotation on RStudio Connect

7 min readFeb 21, 2019

TLDR; Create custom variants of a single R Markdown document, schedule each to execute at different times, and send emails to pre-defined recipients.

Basic Builds is a series of articles providing code templates for data products published to RStudio Connect.

Link to full code template

Goal: Use parameterized R Markdown published on RStudio Connect to schedule and send reminder emails to a rotating recipient list.

Theoretical use case: Each week my engineering group assigns one person to be the “on call” point person for responding to any and all requests from the business overlords.The schedule rotates as follows: Cole on week 1, Kris on week 2, Kelly on week 3, and Sean on week 4. We would like to set up an email reminder system to let each engineer know when it’s their week to be on call, just in case they may have forgotten. It would also be nice if that email reminded the engineer to set up a check-in meeting with the next person in the rotation.

Resources:

User Guide — Parameterized R Markdown
R Markdown Lessons: Using Parameters
Blastula Package Documentation
Email Customization in R Markdown with RStudio Connect

Note: RStudio Connect needs to be configured to enable email. Contact your administrator or see the admin guide for information on how to set up email features

Create a Parameterized R Markdown Report in the RStudio IDE

R Markdown documents can include a metadata section of parameters whose values can be set when you render the report and injected into the document code. This will allow me to write a single “template” report, that can be rendered to appear customized for each of the engineers.

Start a new Rmd document in the RStudio IDE — I called my new document rotation-emailer.Rmd
To set up parameters, define them in the YAML header statement under params:

---
title: "Variants with Different Schedules"
output: html_document
params:
  engineer:
    label: "On-call Engineer:"
    value: Kelly
    input: select
    choices: [Cole, Kris, Kelly, Sean]
---

In this case I’ve defined an input: select type parameter called “engineer”. The input choices are set to be the names of the four engineers in the on-call group. I also picked the default value to be “Kelly”.

The parameter value can be injected into the R Markdown document to appear inline like this:

Engineer On Call: `r params$engineer`

Next I’ll create an R code chunk to calculate which engineer is next in the rotation based on the value of params$engineer:

library(tibble)
library(dplyr)# Create a rotation
rotation <- tribble(
  ~oncall, ~ondeck,
  "Cole", "Kris",
  "Kris", "Kelly",
  "Kelly", "Sean",
  "Sean", "Cole"
)# Use the 'engineer' parameter to look up the on-deck engineer
thisweek <- rotation %>%
  filter(oncall == params$engineer)
nextup <- thisweek$ondeck

Using the tribble() function, I’ve produced a two-column tibble called rotation. I can then filter rotation to get the correct row, and query the single-row tibble result for the value of its ondeck engineer:

Engineer On Deck: `r thisweek$ondeck`

Craft an email message with the blastula package

Now that all the pieces of information I need are in place, all that’s left is to craft the contents of the email. I’m going to use the blastula package.

blastula : Easily send great-looking HTML email messages from R

Note: The blastula package requires the availability of openssl. Visit the GitHub Readme file for more information on installation requirements.

If using blastula isn’t an option for you, don’t worry — there are other methods of creating custom emails that you can read about here.

When working with custom emails and R Markdown with the end-goal of publishing to RStudio Connect, there are a couple of important metadata items that need to be set. These values can be set in the YAML header, or in the body of the R Markdown document using the rmarkdown::output_metadata$set() function. In the example below, I’ve set output_metadata for the email body html and email images.

library(blastula)# Link to published banner created in Google Drive
img_link <- "https://docs.google.com/drawings/d/e/2PACX-1vTA_XbfXQ2Ms90lqrrHVYf7ugeS42Gd1JpTc5VFodiy6t0RqOXUzvySdlx3zSwD5ZmGDIXsMetA-DM6/pub?w=480&h=124"message <- compose_email(
    body = "
  Hi {params$engineer},This is an automated notice reminding you that you'll be on-call this week!
  
  ![Cute Reminder Image]({img_link})Remember to schedule a meeting with {thisweek$ondeck} \\
  on Friday to transition any carry-over tasks for next week.
  
  <br />
  Cheers, <br /> 
  Solutions Engineering Reminder-Bot"
)# Set the R Markdown Output Metadata for email body and images
rmarkdown::output_metadata$set(rsc_email_body_html = message$html_str)
rmarkdown::output_metadata$set(rsc_email_images = message$images)

I’m using the blastula compose_email() function to create the body of the email. Notice that the email should change based on the parameter for engineer selected when the report is rendered.

You can preview emails inside the RStudio IDE viewer with preview_email(message):

Publish to RStudio Connect

When you’re happy with the document and the email message, use push-button publishing to deploy the R Markdown content to your RStudio Connect Server.

Note: If this is your first time publishing to RStudio Connect, read about how to link your Connect account to the RStudio IDE here.

When publishing to Connect, make sure to select the “Publish document with source code” option, as this is a requirement for executing the report on a schedule.

Upon a successful deployment, you should be able to see the default report displayed in the RStudio Connect content dashboard.

The content view for publishers opens to show the Settings panel and Access tab. The default access setting for newly published content is viewership limited to only ‘You’.

Update the viewership setting so that you’ll be able to save shared variants and send emails to other individuals. There are a number of options for accomplishing this. Since each of the engineers in my group are named users on this Connect server, I could have listed them all as allowed viewers. But I don’t mind if other users in my organization can see this document, so I’ve taken the easier route of simply setting viewership to ‘All users — login required’.

Since this is a parameterized R Markdown report, you’ll also see the Input Sidebar (highlighted in the red box above).

Open the Input Sidebar to access the report parameters:

Here you can interact with the parameter selector to change the On-call Engineer and re-run the report.

Note: This example shows how to set up a parameterized R Markdown document with a single (1) input parameter. Adding more than one input parameter is easy to do — see examples here.

Save Shared Variants

Generate and save a variant of the report for each member of the team. Use the Input Sidebar to create these variants:

Choose + New
Select “Cole”
Run Report
Save > “Cole-OnCall” > Select Access: “Everyone with access to this document”

Repeat these steps for each input parameter — Remember to select +New each time!

After you’re finished, you should be able to toggle between each report listed in the “Shared” variant selector as shown here:

Scheduling and Email

Now that I have a saved variant for each engineer, the next step is to open each variant and use the Settings panel > Schedule tab to set up scheduling and email delivery.

My strategy for rotating the emails will be to schedule each report to execute once every four weeks, but to increment the start date — for example: