Skip to content

Custom emails with blastula on RStudio Connect

Earlier this month, RStudio released blastula 0.3.1, which significantly improved the workflow for adding custom emails to reports hosted on RStudio Connect.

The new recommended way to email content from RStudio Connect is by building an email document as a separate R Markdown file using blastula's R Markdown output format: blastula::blastula_email. Read more here: RStudio Blog

This post is a quick demo of what to expect from the new blastula custom email experience on RStudio Connect. You can follow along by downloading the latest version of blastula and using the example files provided:

blastula::prepare_rsc_example_files()

Prepare

Before you're able to follow along with this post, follow the steps below to set up your environment. - Create a new RStudio Project in the RStudio IDE - Run blastula::prepare_rsc_example_files() which creates a connect_examples folder in your working directory, which will include the following

  • austin_home_sales.csv
  • connect-example-email.Rmd
  • connect-example-main.Rmd
  • connect-example-text-only.Rmd (example of the previous custom email workflow - still functional)

Crafting the main R Markdown document/report#

Open connect-example-main.Rmd - this is the main R Markdown report. The two other Rmd files are emails you could choose to include with the main report.

There are two components to the Main Report that you should be aware of:

  1. All the code chunks have been labeled (named). Labeling your code chunks makes it possible to reuse them in the email document.

  2. Excerpt on chunk labels from the R Markdown Book: There is an optional chunk option that does not take any value, which is the chunk label. It should be the first option in the chunk header. If the label of a chunk is missing, a default one of the form unnamed-chunk-i will be generated, where i is incremental. I strongly recommend that you only use alphanumeric characters (a-z, A-Z and 0–9) and dashes (-) in labels.

  3. The blastula configuration code chunk (very bottom of the document) uses three functions to create emails for RStudio Connect:

  4. render_connect_email is passed an input parameter to specify which R Markdown document will be used to build the email body. It also automatically adds a footer to the email with useful links back to the content on RStudio Connect.

  5. attach_connect_email ensures RStudio Connect sends the custom email, and also makes it easy to customize the subject line, include additional email attachments, and optionally attach the report output.
  6. suppress_scheduled_email() allows you to skip sending the email. This pattern is very powerful. For example, reports can be run once a day, but only distributed if certain conditions are met.

Crafting the email document#

Open connect-example-email.Rmd - here the email body is constructed using standard R Markdown. The body of the email will respect R Markdown output, including markdown syntax and code chunk outputs.

Work done (code) in the Main document (connect-example-main.Rmd) does not need to be replicated in the email document. Code chunks that are defined and labeled in the Main Document can be reused/included in the email by adding an empty R Markdown code chunk with a matching name:

Comparative anatomies of the main document and the email document.

Previewing and publishing reports with custom emails#

Knit the Main document to see previews of both the report and the custom email:

Left: Main document preview, Right: Email document preview

Publish the Main document to RStudio Connect where it can be scheduled for regular execution and distribution. Publish the document with source code, and make sure the email document and csv attachments are included as supporting files:

Example publishing steps from the RStudio IDE to RStudio Connect.

Note: Trying git-backed deployment? I recommend explicitly specifying the primary document and application files list when generating the manifest:

rsconnect::writeManifest(appPrimaryDoc = 'connect-example-main.Rmd', appFiles = c('connect-example-email.Rmd', 'austin_home_sales.csv', 'dallas_home_sales.csv'))

Test: Once the document is published, send a test email to yourself using the RStudio Connect email trigger.

Manually trigger a test email from the RStudio Connect toolbar.

If everything looks good in the test email, use the publisher tools to adjust the Access and Schedule settings for your report:

Example schedule: Run this report on the first Monday of every month.

This report is scheduled to run on the first Monday of every month. After the report runs, the resulting email document will be delivered to the content owner (me) and two of my colleagues, as specified in the additional recipients list.

Finished#

Now that the report has been scheduled, you're all set. The workflow on RStudio Connect itself is unchanged. You can update the Access and Schedule settings at any time. Pushing changes to the report or email documents is as simple as doing a redeployment of the content bundle. If the report ever breaks, the content owner/publisher will receive an email alert about that error.

Copyright © RStudio, PBC. All Rights Reserved.