#Schedules

Your Addon can provide Schedules to be managed by MercuryCMS' Schedule System. Anything your Addon does at a regular interval needs to be added as a Schedule rather than being managed internally by your Addon.

This allows users to modify your Schedules, prevents you from having to write a complex interface within your Addon to manage Schedules, and allows MercuryCMS to hibernate when not in use but still wake up when your Addon's Schedules need to run.

#Schedule Schema

{

  // uneditable properties
  _id: '64195ce0082a4585243da56d',
  managedByAddonId: '639b8f837f5fb8a39404280a',
  createdAt: 1679460682131,
  updatedAt: 1679462215608,
  action: 'event',
  script: '',
  buildAndDeployOnSuccess: false,

  // basic properties
  name: '',
  description: '',
  isEnabled: true,
  eventName: '',
  body: null,
  timeoutSeconds: 0,
  isOverlapAllowed: false,

  // times
  times: [],

  // runs
  runs: [],

}

#Uneditable Properties

#Basic Properties

#Times

You can specify the default times for a Schedule to run which can later be changed by the user. This is an array of objects will the following properties:

Note that both startDate and startTime must be specified for an Interval time to run.

Any values not specified will be set to their default.

#Runs

While you cannot create, edit, or delete Runs, you can view them. Runs have the following properties:

#Creating Schedules

You can create Schedules using cms.createSchedule(). Note that you should first check to see if the Schedule already exists by checking your Schedules by name.

let scheduleDef = {
  name: 'Import Store Items',
  description: 'Import any Store Items created on the Store site',
  isEnabled: true,
  eventName: 'importStoreItems',
  times: [
    {minutes: 0, hours: 0}, // midnight
  ]
}

// use static-cms-addon
import cms from 'static-cms-addon'

let schedule = await cms.createSchedule(scheduleDef)
console.log(schedule._id) // "64195ce0082a4585243da56d"

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/schedule`, scheduleDef)
console.log(response.data.schedule._id) // "64195ce0082a4585243da56d"

#Listing Schedules

You can use cms.getSchedules() to get a list of the Schedules your Addon has created.

// use static-cms-addon
import cms from 'static-cms-addon'

let schedules = await cms.getSchedules()
console.log(schedules.map(schedule => schedule.name)) // ['Import Store Items', 'Import Reviews']

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/${addonId}/schedule`)
console.log(response.data.schedules.map(schedule => schedule.name)) // ['Import Store Items', 'Import Reviews']

#User Modification

While your Addon can create Schedules and set their default properties, the user can elect to modify when the Schedule runs or disable it altogether. It is also up to the user whether or not to Build and Deploy the Site when the Schedule completes successfully.

#Handling Events

Once your Addon has created its required Schedules, the Schedule System will notify your Addon when the Schedule runs at its designated time, or is manually initated by the user.

The Schedule will send your Addon an Event to its configured eventPath. You must have a configured eventPath for your Addon's Schedules to work. Once your Addon has received the Event, you can execute whatever functionality you like. Once complete, you must make a call to MercuryCMS with a status and a log. If your Addon does not make the status call before the designated Timeout, the Schedule System will record the run as a failure.

The Event the Schedule System sends will be include the Schedule's eventName and body. You can use eventName and body to pass whatever data to your Addon you want. For example, you could have two Schedules that both use an "importStoreItems" eventName, but one has a body of {category: 'hats'} and another with {category: 'shirts'}. You can then react to each of those Events appropriately in your Addon's Event Handler.

See the scheduleStarted Event for more information and examples.