How to Set Up Schedules in Displayr

Schedules allow you to schedule automatic updating of data, calculations, and republishing dashboards. You can schedule pages to recalculate automatically so that they are cached and will load instantly in view mode. Schedules can also make documents faster, see Schedule Updates and Recalculations Ahead of Time.

This article will cover how the scheduler feature works and how to create schedules for supported items. Note that associated costs are outlined in the Technical Notes below.

When and why to use schedules
Method - Creating a schedule
Method - Connect your data or outputs to a schedule
Method - How to automatically republish your dashboard using a schedule
Method - Viewing and modifying schedules
Method - Spotting and diagnosing errors
Technical Notes

Requirements

It is necessary to have Server time for private dashboards and API to use Schedules. Currently, as the feature is new, we are letting users use it in edit mode at no additional cost to experiment with the feature. We will soon turn this off and all usage triggered by schedules will count towards Server time for private dashboards and API. You can read more about this in the Technical Notes below.
An item to be scheduled. Schedules can be applied to:
- Update Data Sources (e.g., a data file from an API integration, such as Qualtrics, Forsta, or the Displayr Cloud Drive, SQL data sets, or a data file stored on a URL). A schedule will do the same thing as occurs when a user manually presses Update. This includes recalculating all outputs.
- Rerun Calculations. A schedule will do the same thing as occurs when a user clicks Calculate. Elsewhere in Displayr, a calculation only updates when the user presses Calculate or when it depends on some other data and that other data has changed. However, you can also schedule calculations to be performed at specific times. For example, if you had a calculation that downloaded the latest stock price data, you could schedule it whenever the markets close, every hour, or on another schedule.
- Pages. A schedule will do the same thing as occurs when a viewer in view mode visits the page. That is, any results will be updated, and the page itself will be added to the document's cache so that the next time a user visits the page with the same data and same selections, the results will be retrieved from the cache rather than re-calculated, which is faster for the user. Note that:
  - Each page must be selected (i.e., if you select a folder, it will not select the sub-pages). You can select multiple pages simultaneously and add them to a schedule.
  - A page's views (if they exist) can also be included in a schedule. The schedule will do the same things as occurs when a user selects a view.
- Republish an entire dashboard. A schedule will automatically republish a dashboard. See How to Automatically Republish a Dashboard.

When and why to use schedules

Schedules have three core use cases:

Update data. For example, a schedule may be used to update data daily.
Publish documents (dashboards). For example, updated data may be released to dashboard users at 9 AM every Monday.
Make documents faster. There are two main ways to do this:
1. Split a single document into multiple documents, where schedules pass information between the documents (by exporting and importing from the Displayr Cloud Drive.
2. Use a schedule to automatically recalculate a page, and optionally, its views in a published document (dashboard). This saves the results (caches them) so that when a view goes to the published document, the already-calculated results are shown to the user, rather than having to wait for a calculation.

Method - Creating a schedule

A schedule is basically a trigger that you can set up to perform one or more actions at a set frequency. As a schedule is just a trigger, you also need to specifically add the actions desired to that schedule. Schedules will appear in the Schedules panel for items that can be scheduled. You can set up multiple schedules in a document, but items can only be assigned to a single schedule. Below is a screenshot of an empty schedule that was created but has not been used for anything yet:

empty schedule.png

Schedules are created by going to Schedules and clicking +. The configuration settings are as follows:

Start controls when the schedule will run, with options of:
- At - for running it once at a specific time.
- Every - allows specification of when it will run (e.g., 9 AM every Wednesday until the end of the year).
- On Server Start* can schedule actions relating to data sets and recalculations, and is only triggered in Edit Mode unless the including View Mode box is ticked. They are triggered by:
  - A user opening the document in Edit Mode if the document was sleeping.
  - A user opening the document in View Mode if the including View Mode box is ticked and the document was sleeping.
  - Another schedule starting the server (i.e., importing a data set or performing a calculation).
  - Other schedules set to On Publish or with Republish (runs before Page Preloads) checked.
- On Publish - causes the schedule to run once a document is published.
Republish (runs before Page Preloads) will republish the document and any embeds after the action has been taken, except if the action is caching a page or view. That is, if you are caching a page or view so that it loads more quickly in View Mode with this schedule setting, they will be cached after the document is republished to ensure caches are using the data that was included in the Republish.

* On Server Start - is triggered by loading the document on the server after it has been asleep. That is, if nobody is using the document for a period of time (usually 10 minutes), it will go to sleep and will need to be reloaded when someone wants to use it again. This reload is the trigger, and not simply closing and reopening a tab of the document in your browser. By default, this only occurs in Edit mode unless the including View Mode box is ticked. Then the document must be asleep in both Edit and View modes before the schedule will trigger.

There are additional settings for On Server Start regarding the if not run in field:

Unchecked - the schedule runs every time a project is opened after being asleep.
Checked - this ensures that the data is never older than the specified amount. Two things need to happen for the document to update:
1. You have to open the document manually (it doesn't wake up by itself) in Edit Mode or in either mode (Edit or View) if the including View Mode box is ticked.
2. The time between opening the document and the last time the schedule was run needs to be older than the period set. If the schedule has never been run, then it should update on open.

For example, you've set the schedule to be On Server Start and checked if not run in > 1 Week on January 1st. You're working in the document until January 5th, then close it until January 10th. The data will be updated as of January 10th (not January 8th, which is 1 week later) because you opened it more than 1 week after January 1st.

Method - Connect your data or outputs to a schedule

For any calculation or page to update based on a schedule, you must connect it to an existing schedule via the object inspector > General > Schedule. This includes any R calculations.

For data sets, including data sets that are added via an API integration (Qualtrics, Forsta, etc.), URL (ex., Displayr Cloud Drive), or using SQL, click Schedules to add to a schedule.

Method - How to automatically republish your dashboard using a schedule

For At, Every, and On Server Start, there's a checkbox labeled Republish (runs before Page Preloads), meaning that the document is re-published after any edit actions have been run. A common use case for this is to use a schedule to update the data, and then have the document republished with the refreshed data.

By default, when a schedule has been applied to a page, any view is also updated. Where there are lots of views, this will increase costs as it uses up computational resources. This can be turned off by clicking on the page in the schedule, unchecking Preload all views, and then manually selecting specific views.

Method - Viewing and modifying schedules

To view your document's schedules, go to the Schedules panel. The items that are using the schedule will appear when you expand each schedule.

Click on a schedule to modify it. If you want to remove a schedule, right-click the schedule and select Delete.

Method - Pausing schedules at the company level

If you are an Administrator on your Displayr account, you can pause schedules at the company level. This will affect all schedules across all documents in your Displayr company, so use this setting with caution.

To access these settings, navigate to your Account settings > Settings page and scroll to the Schedules settings area.

Tick the box next to Are schedules paused? and click Save to pause the running of all schedules in your company.

Method - Spotting and diagnosing errors

You can work out when a schedule was run by clicking on it and viewing the orange box, which will show you when it was last run (excluding pages published in view mode) and also if it was manually skipped (which is an option available to users when editing).

When an error occurs with a schedule, it is displayed with an icon on the documents page. For example, Outreach Data Mart below shows an error.

When you hover over a document with an error and press Error, you are shown a list of all the errors. They do not disappear until you click Dismiss.

Technical Notes

Document time zone

When a document is created, its time zone is set to the creating user's time zone. This time zone is then used in all the scheduler settings. You can modify the time zone by going to > Document Settings > Properties > Document time zone.

What runs when

In addition to what's discussed above, note that:

Items within a schedule run in the order shown. If you wish to force multiple calculations to run simultaneously, this can be done by having them depend on a calculation in the schedule. For example, consider the following:
- The schedule shows three calculations: A, B, and C, in that order.
- Two other calculations, E and F, are not in the schedule but depend on A.
- The calculations will be run in this order:
  - A will be first.
  - B, E, and F will all start at similar times. (There's no hard guarantee about what starts when, as many other things are going on in the background that may affect resources and thus queuing.)
  - When B has finished, C will start.
A schedule will not commence if the previous schedule has not finished. If the schedule's start time is missed, the schedule is completely skipped.
Actions in a schedule that can be run in edit mode will occur before those run in view mode (i.e., those occurring via On Publish or Republish (runs before Page Preloads).
If a viewer is editing a document and a schedule is due to start, the user editing the document will get a pop-up window with three options:
1. Skip will skip this scheduled run of the schedule. Note, if you skip an At schedule which is to run once for a specific date/time, it will never try to run again.
2. Delay (10 minutes) will delay the schedule.
3. Proceed allows the schedule to run.

Migrating to Schedules (including UpdateEvery and UpdateAt)

Many of our data importers previously had controls that indicated when the data would be updated. These controls have been removed, and if they were in use, new schedules have been created that contain whatever values were specified.

It is also possible to schedule calculations and R Data Sets using code with the UpdateEvery and UpdateAt in the flipTime package. Schedules are easier to use and have much more functionality. It is recommended that UpdateEvery and UpdateAt no longer be used.

UpdateEvery and UpdateAt need to be removed from calculations and R Data Sets before adding them to a schedule. The controls for adding to Schedules are not visible until this code is removed.

Costs

It is necessary to have purchased Server time for private dashboards and API to use Schedules. You will be notified if you are close to exceeding your available server time. Still, some users ignore notifications, so it's recommended that you verify your usage from time to time in Account Settings > Licenses > Server time for private dashboards and API.