Schedule-based Hook

The following is an overview of how a schedule-based hook is defined in a server hook configuration file.

{
  "kiicloud://scheduler": {
    "<job_name>": {
      "cron": "<cron_expression>",
      "endpoint": "<endpoint_name>",
      "parameters": {
        "arg1": "xxxx"
      },
      "what": "EXECUTE_SERVER_CODE"
    }
    /* Other hooks */
  }
  /* Other paths with hooks */
}

Server code (the target function name specified with the endpoint) will be executed at the time designated by the cron_expression. You can also assign a job_name on each schedule definition so as to make it easy to later check if the defined hook is properly executed. You can optionally define parameters you want to pass to the endpoint in the parameters property.

You can set multiple schedules under "kiicloud://scheduler". When setting multiple schedules, make sure to use different job_name so as to distinguish them (Kii Cloud will not give you an error if the name is duplicating). If you set the same schedule with multiple names, the specified endpoint will be executed for the number of the times it was set.

The following illustrates how to define the time with the cron expression.

Note that time should be specified in UTC.

You can also use the following special characters.

  • Asterisk (*) means that the cron expression matches with any field values.
  • Hyphen (-) indicates ranges.
  • Slash (/) means the incrementation. For example, "0/10" in the first field (min) means "every 10 minutes".
  • Comma (,) means a list of values. For example, "MON,WED,FRI" in the fifth field (day of the week) means "Monday, Wednesday, and Friday".

Here are some examples:

#run hourly
0 * * * *

#run at one minute past midnight (00:01) on every day:
1 0 * * *

#run at 05:00 on weekdays (Monday to Friday)
0 5 * * MON-FRI

#run every two hours, at midnight, 2 am, 4 am, 6 am, 8 am, and so on:
0 0/2 * * *

#run every 5 minutes starting at 2 pm and ending at 2:55 pm, every day:
0/5 14 * * *

#run at 11:00 and 16:00 on weekends (Sunday and Saturday)
00 11,16 * * SUN,SAT

Be aware of the following limitations:

  • You cannot use "*" with "/" at the same time.

    • OK: 0/5 14 * * *
    • NOT OK: */5 14 * * *

  • You can use just one range (e.g. 4-7), one incrementation (e.g. 2/5) or one list (e.g. 0,5,10,15) in single cron expression item (minute, hour,...). You cannot mix them in the same item.

    • OK: 0,5,10 21-23 * * MON-FRI
    • NOT OK: 5-8/2 * * * *

  • You cannot set a day-of-week and a day-of-month at the same time.

    • NOT OK: 0 0 1 1 SUN

Here are sample server hooks.

{
  "DailyMessage_5am": {
    "cron": "0 5 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "5am"
    },
    "what": "EXECUTE_SERVER_CODE"
  },
  "DailyMessage_10pm": {
    "cron": "0 22 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "10pm"
    },
    "what": "EXECUTE_SERVER_CODE"
  }
}

In this example, the endpoint sendDailyMessage will be executed on 5:00 am and 10:00 pm every day (in UTC). For each execution, the different parameters are passed to the server code (See Logging an Execution Caused by a Schedule-based Hook for sample server code that works well with these hooks).