Schedules allow you to schedule the updating of data and calculations automatically. This article describes:

• When and why to use schedules
• What can be scheduled
• Creating, adding to, and reordering schedules
• Options
• Viewing schedules
• Document time zone
• What runs when
• Migrating to Schedules (including UpdateEvery and Update At)
• Costs
• Spotting and diagnosing errors

When and why to use schedules

Schedules have three core use cases:

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

What can be scheduled

Schedules can be applied to:

• Data Sources (e.g., SQL data sets, Excel Tables, a data file stored on a URL). A schedule will do the same thing as occurs when a user manually presses Update. 
• 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. 

Creating, adding to, and reordering schedules

Schedules are created by selecting a data set, calculation, or one or more pages and pressing General > Schedule > + in the object inspector. Where a schedule has already been created, the object can be added from the Schedule combo box.

Options

Start controls when the schedule will run, with options of:

• At for running it once at a specific time.
• Every, which allows specification of when it will run (e.g., 9 AM every Wednesday until the end of the year).
• On Server Start, the schedule runs whenever a project is opened in edit or view mode.
  • There's a checkbox called if not run in that permits additional control (e.g., having the schedule start when the server starts, provided the schedule has not been run in the past week). This ensures that the data is never older than the specified amount.
  • On Server Start schedules relating to data sets and calculations are triggered by either:
    • A user going into the document in edit mode.
    • Another schedule starting the server (i.e., importing a data set or performing a calculation).
  • On Server Start relating to pages and views are triggered by either:
    • A user going to the document (if the document was sleeping)
    • Other schedules set to On Publish or with Republish (runs before Page Reploads) checked
• On Publish, which causes the schedule to run once a document is published.

For At, Every, and On Server Start, there's a checkbox called Republish (runs before Page Preloads), meaning that the document is re-published after any edit model 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 and unchecking Preload all views and then manually selecting specific views.

Viewing schedules

To view schedules,  clock on the hamburger and click Schedules, which will display the Schedules Panel. Click on the schedules to modify them. Use drag and drop to reorder.

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 clicking the hamburger and choosing Document Settings > Properties > Document time zone.

What runs when

In addition to what's discussed in the previous section, note that:

1. Items within a scheduled 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.
2. 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.
3. 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).
4. If a viewer is editing a document and a schedule is due to start, the user editing the document will get a popup window with three options:
   1. Skip which will skip the schedule.
   2. Delay (10 minutes) which will delay the schedule.
   3. Proceed which allows the schedule to run.

Migrating to Schedules (including UpdateEvery and Update At)

Many of our data importers used to have 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 are possible. 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. Currently, as the feature is new, we are letting users use it in edit mode for no additional costs to experiment with the feature. We will soon turn this off all usage triggered by schedules will count towards Server time for private dashboards and API.

You will be notified if you are likely to exceed your server time. Still, some users ignore notifications, so it's recommended that you manually verify your usage from time to time in Account settings > Licenses > Server time for private dashboards and API.

 

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.