Skip to main content

Module: command_scheduler

Overview​

Module

This module allows executing commands on a schedule.

Its typical use case is executing broadcast commands on a schedule.

However, it can also be used to execute any specified commands.

Color Boxes​

Note

◉ How it works?

  1. Define a job to execute commands on a schedule.

1.a. The schedule is expressed using the cron expression language.

1.b. You can specify multiple cron expressions for a job.

1.c. A job is triggered if any of its cron expressions match.

  1. A job is automatically triggered according to its cron expressions.

  2. When a job is triggered, it will do:

3.a. If the enable property is false, then do nothing.

3.b. If the remaining runs property is <= 0, then do nothing.

3.c. Otherwise, it decreases the remaining runs property by 1, and pick a random command group to execute.

  1. You can trigger a job using /command-scheduler trigger <job> manually.
Tip

◉ You can use cron expression generator, to specify when a job should be triggered.

See

  1. https://www.freeformatter.com/cron-expression-generator-quartz.html

  2. https://crontab.cronhub.io/

  3. https://odown.com/free-tools/cron-expression-generator/

◉ List the next fire dates for each defined job.

Issue /fuji inspect jobs to see the fire dates of defined jobs.

Configurations​

The following JSON content is provided for reference only. It must NOT be copied directly into the configuration directory, as it does not represent valid JSON syntax.

Config
  • File Name: scheduler.json
  • File Content:
Click to see the default content...
config/fuji/modules/command_scheduler/scheduler.json
{
  "jobs": [
    {
      "enable": true
      /* The `unique` name of this `job`. */,
      "name": "example_job"
      /* Allowed left times to run. */,
      "remaining_runs": 1024
      /* Defined `cron` expression list.
      
      Any met `cron` expression can `trigger` this `job`. */,
      "schedules": [
        "0 */3 * ? * *",
        "0 */5 * ? * *"
      ]
      /* The commands to execute when the `job` is `triggered`. */,
      "command_groups": [
        [
          "send-broadcast Group 1 Command 1 -> This is the first group of commands.",
          "send-broadcast Group 1 Command 2 -> When job is fired, a random command group will be picked.",
          "send-broadcast Group 1 Command 3 -> Commands in a group run in order from top to bottom.",
          "send-broadcast Group 1 Command 4 -> You can execute `/command-schedule trigger` to `run` a `job` directly."
        ],
        [
          "send-broadcast Group 2 Command 1 -> This is the second group of commands",
          "send-broadcast Group 2 Command 2 -> You can use `/fuji` command to inspect the `next fire dates` of each job.",
          "send-broadcast Group 2 Command 3 -> The schedule for this job is described using 2 cron expression: one says `every 3 minutes`, another says `every 5 minutes`"
        ]
      ]
    }
  ]
}

Jobs​

Job

  • Job Name: CommandScheduleJob

  • Document: This job is defined by command_schedule module.

    And used to execute specified commands.

Job

  • Job Name: CommandScheduleJob

  • Document: This job is defined by command_schedule module.

    And used to execute specified commands.

Commands​

Command

  • Command Syntax: /command-scheduler list

  • Document: List all defined jobs.

  • Can be executed by console: false

  • Required Level Permission: 4

Command

  • Command Syntax: /command-scheduler trigger <JobName jobName>

  • Document: Trigger a job manually.

  • Can be executed by console: true

  • Required Level Permission: 4

Argument Types​

Argument Type
  • Argument Type Name: [schedule-job-name, job-name]
  • Argument Type Class: [JobName]