UPCOMING WEBINAR: Faster (and better) survey analysis Displayr now has a built-in scheduling tool to remove the need to write custom R code to schedule updates. In most cases, you no longer need to use the process below. See How to Set Up Schedules in Displayr. Please note that the steps below may be discontinued in the future and fully replaced by the Schedule functionality.
If the Schedule functionality doesn't currently meet your specific needs, you can follow the steps listed below for how to make R-based calculations, variables, and data sets refresh automatically after a specified time period by including a line of code with a message or a function call. To prevent overload the Displayr server ignores any update frequency less than 600 seconds. Do keep in mind that if an input (dependency) of an R-based item is updated, the R-based item will trigger a recalculation automatically. This article covers:
- Method - Updating with flipTime functions
- Method - Updating with message()
- Method - Adding an end date for updating
- Important Functionality
Requirements
- Depending on the inputs, some steps may require a Displayr license.
- An R-based item in your Displayr document.
- Purchased Server time for private dashboards and API hours (view hours/viewers).
As a reminder, the schedule functionality has replaced the process below. Only use the steps below if the schedule functionality does not meet your specific requirements. If you're unsure, contact Support, and we will help you get set up.
Method - Updating with flipTime functions
The preferred method to achieve updating uses the R package flipTime. Do keep in mind that using this feature does count towards your Server time for private dashboards and API hours (view hours) allotment, see Tracking API Hours. There are 3 options you can specify within the update functions, where options =
-
"only when open"- causes R-based item to automatically recalculate at the scheduled time interval if the document is currently open by a user -
"wakeup"- causes the document to be opened by the software and the item recalculation to occur -
"snapshot"- causes the document to be opened and the dashboard to be re-published after the recalculations have updated.
UpdateEvery()
The function UpdateEvery allows you to specify a number of "minutes", "hours", "weeks", or "months" as follows:
#load the R package of functions
library(flipTime)
#make item automatically recalculate every 5 days and snapshot republishes the dashboard
UpdateEvery(5, "days", options = "snapshot")
UpdateAt
The function UpdateAt is more flexible and allows specification of an initial update date, time and timezone, then a recurring update frequency thereafter. For example:
#load the R package of functions
library(flipTime)
#update automatically every 3 days after May 15, 2017 at 6pm New York time
UpdateAt("05-15-2017 18:00:00", us.format = TRUE, time.zone = "America/New_York", units = "days", frequency = 3, options = "wakeup")
See here for a list of time zones.
Method - Updating with message()
The older way of updating involves using the R function message(). Do keep in mind that using this feature does count towards your Server time for private dashboards and API hours (view hours) allotment, see Tracking API Hours. However, it is preferable to use the flipTime package above as it is more robust. An example using message() is the following:
#recalculate every hour while the document is open
message("R output expires in 3600.0 seconds")
The decimal point and the word "seconds" may both be omitted. Note that the above code will only affect a refresh while the document is open. If you are using Displayr and would like the system to re-open the document in the background in order to re-run the calculation, just include the suffix "with wakeup", e.g.:
#recalculate every hour, open the document on the back-end if not already open
message("R output expires in 3600.0 seconds with wakeup")
When using the "with wakeup" form, note that the calculation may actually be re-run up to several minutes after the requested time, depending on the size and complexity of the document, server load, and other factors.
It is not possible to perform long-running calculations (over 230 seconds) when using the "with wakeup". Documents must remain open to run such calculations.
fter a "with wakeup"-style refresh, you can optionally cause a snapshot to be taken of the document by adding "and snapshot" to the message. The effect will be that any viewers of the document will see the changes reflected, e.g.
#recalculate every hour, open the document on the back-end if not already open
message("R output expires in 3600.0 seconds with wakeup and snapshot")
Method - Add an end date for updating
There isn't a parameter in the functions above to set an end date for the scheduled updating. However, you can create an if-else construct inside your code to effectively do this. The concept is to get the current time, and if it is after a cut-off date/time, return a final message instead of running the updating function. In the example below, the updating R code was run at 11:39 Central time. The output will update every 10 minutes, and the final update will be the 11:49 am update (i.e. the cut-off time is set to 11:48 Central 16:48 UTC):
#get the current time
thetime=Sys.time()
#set the cutoff time to be right before the last update you want to happen
#date and time are in UTC
cutoff=as.POSIXct("2024-04-15 16:48")
#if the current time is after the cutoff, then simply return a string to stop updating
if(thetime > cutoff){
"stop updating"
} else {
#else, if it is before the cutoff rerun the updating function to schedule the next update
flipTime::UpdateEvery(10, "minutes",options="wakeup")
}
You can check General > Output > Show raw R output to see the time the output was run to kick off the updating:
Once the last update happens, instead of an expiration note, you'll see the text "stop updating" and future automatic updating will stop - notice that the update last happened at 11:50 (11:49 was the scheduled "wakeup" to reload the document to the server) and it has been more than 10 minutes since without another update.
Important Functionality
Dependencies
Automatically updating an R-based item will cause all upstream dependencies that have expired to update with one small caveat.
If a Calculation with an automatic update from above depends on an R Data Set (either directly or via intermediate calculations) then you will need to use the same automatic update code without wakeup in the R Data Set code as well. This ensures that the previous data will have expired and so be refreshed for every update of the object. Note that when updating data sets, serious and unrecoverable errors may occur if there are changes in the structure of the data file (e.g., new variables, changes of variable type).
Any downstream dependencies from the R item that was automatically updated will be marked as "out of date" and will recalculate upon opening or refreshing a view mode document as a result of the "with wakeup" message.
Precedence
If a single piece of R code attempts to set up more than one schedule, e.g. via multiple calls to either message or UpdateEvery, the schedule with the least number of seconds is preferred. That is the earliest wins. If multiple schedules are returned with the same number of seconds, but differing with respect to "with wakeup" or "and snapshot", only one schedule will be affected, which will be selected arbitrarily.
If multiple "with wakeup" schedules are put in place, e.g. by re-running the R code via the Calculate button before a previously scheduled automatic update has taken place, the schedule with the least number of seconds is preferred. Any other schedules for the same object are deleted prior to the update taking place. If there is a tie between schedules with the same number of seconds, a schedule with "and snapshot" is preferred.
Error Feedback
When an R-based object is updated in the background there is no immediate feedback if something goes wrong (e.g. if an error occurs in your R code). Displayr addresses this situation in multiple ways:
- If an error occurs during scheduled updating
"with wakeup"the update will be automatically re-tried one hour later. The retry process continues until the update succeeds, the object is removed from the document or the document is deleted. - Company administrators can view a status page that lists any failing "with wakeup" updates. A link to the status page can be accessed from your document via the Profile icon > Account settings > General > Miscellaneous > Scheduled R update status.
- Displayr provides an integration with the Slack messaging system whereby Displayr will perform a daily check of the company's documents. If at the time of the check, there are any R objects awaiting retry due to an error during scheduled R updating
"with wakeup", Displayr will send a Slack message. The message summarizes the number of errors that are outstanding and provides a link to the status page, see How to Set Up a Slack Alert of Updating Errors From Your Displayr Account.
Additional Notes
- Importantly, any Calculations must be run at least once before automatic updating will be triggered. If you have uploaded an archived project you should go through and click Calculate for those Calculations which are set to update automatically.
- Note that if an object is referred to by an HTML embedding, then the update of the embedding may be delayed due to caching by the content delivery network.
Next
How to Set Up Schedules in Displayr
How to Automatically Update Dashboards in Displayr
How to Automatically Republish a Dashboard
How to Create Dashboards with Real-Time Updating
How to Set Up a Slack Alert of Updating Errors From Your Displayr Account