The smos-scheduler tool can be used to schedule recurring projects. It is configured declaratively using a configuration file.

A scheduled project is configured to be activated on a given schedule. An activation consists of filling in a template project (with extension .smos.template) and putting the result at a given destination as a .smos file.

Configuration

Example configuration:

scheduler:
  schedule:
    - description: "Rent"
      template: templates/rent.smos.template
      destination: projects/rent-[ %m | 1 ].smos
      schedule: "0 12 16 * *" # Cron schedule: "At 12:00 on the 16th day of the month"
    - decscription: "Haircut
      template: templates/haircut.smos.template
      destination: projects/haircut.smos
      schedule: 1 month # One month after the provious haircut project has been completed.

See below for the reference documentation about configuration.

Example template at templates/rent.smos.template:

- entry:
    header: Rent
    properties:
      goal: Pay rent on time
  forest:
  - header: Pay rent
    state: READY
    timestamps:
      SCHEDULED: "[ %F | 25 ]"

See the template format reference documentation for instructions on how to write a template.

Usage

Run smos-scheduler check to make sure everything is ready for the template to be scheduled correctly.

Run smos-scheduler next to see when your items will next be activated.

Then run smos-scheduler schedule periodically. Once per hour or once per day should be enough but make sure to automate it.

Types of recurrence

Recurrence falls into two categories: rent recurrence and haircut recurrence. The difference between the two lies in when the next instance should be scheduled if one overruns. In the case of rent recurrence, for example on the first day of every month, the next instance should be scheduled on the same day irrespective of whether rent was late last month. In the case of haircut recurrence, the situation is different. When your most recent haircut was late, the next one should not be any sooner after that.

Examples of rent recurrence:

• Paying rent
• Sending invoices
• Paying taxes

Examples of haircut recurrence:

• Getting a haircut
• Watering plants
• Getting a massage
• Seeing a dentist
• Cleaning your home

The smos-scheduler tool supports both of these types of recurrence. Rent recurrence is configured using a cron schedule, and haircut recurrence is configured using an amount of time.

Usage: smos-scheduler COMMAND [--config-file FILE_PATH] 
                      [--workflow-dir DIRECTORY_PATH] 
                      [--archive-dir DIRECTORY_PATH] 
                      [--projects-dir DIRECTORY_PATH] 
                      [--archived-projects-dir DIRECTORY_PATHPATH]

  
  Smos Scheduler Tool version: 0.8.0
  
  Current Smos data format version: 2.0.0

Available options:
  -h,--help                Show this help text
  --config-file FILE_PATH  The config file to use
  --workflow-dir DIRECTORY_PATH
                           The workflow directory to use
  --archive-dir DIRECTORY_PATH
                           The archive directory to use
  --projects-dir DIRECTORY_PATH
                           The projects directory to use
  --archived-projects-dir DIRECTORY_PATHPATH
                           The archived projects directory to use

Available commands:
  check                    Check that all schedules are sensible
  next                     List the next times that scheduled will be activated
  sample                   Produce a sample scheduled project being filled in
  schedule                 Run the schedules

Available environment variables:

  SMOS_ARCHIVED_PROJECTS_DIR
                         Archived projects directory
  SMOS_ARCHIVE_DIR
                         Archive directory
  SMOS_CONFIG_FILE
                         Workflow directory
  SMOS_PROJECTS_DIR
                         Projects directory
  SMOS_WORKFLOW_DIR
                         Workflow directory

# Configuration
workflow-dir: # optional
  # The workflow directory
  # or null
  <string>
archive-dir: # optional
  # The archive directory
  # or null
  <string>
projects-dir: # optional
  # The projects directory
  # or null
  <string>
archived-projects-dir: # optional
  # The archived projects directory
  # or null
  <string>
colour: # optional
  # Colour configuration
  # or null
  # ColourConfiguration
  background: # optional
    # The table background colours
    # any of
    [ null
    , null
    , # A single background colour
      def: Colour
      # any of
      [ <string>
      , # Set this to a number between 0 and 255 that represents the colour that you want from the 8-bit colour schema.
        # See this overview on wikipedia for more information:
        # https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
        <number> # between 0 and 255
      , # Colour24Bit
        red: # required
          # The red component, [0..255]
          <number> # between 0 and 255
        green: # required
          # The green component, [0..255]
          <number> # between 0 and 255
        blue: # required
          # The blue component, [0..255]
          <number> # between 0 and 255
      ]
    , # Bicolour
      even: # optional
        # background for even-numbered table-rows (0-indexed)
        # or null
        ref: Colour
      odd: # optional
        # background for odd-numbered table-rows
        # or null
        ref: Colour
    ]
scheduler: # optional
  # The scheduler configuration
  # or null
  # SchedulerConfiguration
  schedule: # optional
    # The scheduler schedule
    # or null
    - # ScheduleItem
      description: # optional
        # A description of this item
        # or null
        <string>
      template: # required
        # The file to copy from (absolute or relative, inside the workflow directory)
        <string>
      destination: # required
        # The file to copy to (relative, inside the workflow directory)
        # relative filepath
        <string>
      schedule: # required
        # The schedule on which to do the copying
        # any of
        [ # Haircut recurrence
          def: Time
          # any of
          [ # Time string, for example:
            #  2s
            #  2 seconds
            #  3m
            #  3 minutes
            #  4h
            #  4 hours
            #  5d
            #  5 days
            #  6w
            #  6 weeks
            #  7mo
            #  7 months
            #  8y
            #  8 years
            <string>
          , # Interpreted as a number of days
            <number> # between 0 and 18446744073709551615
          ]
        , # Rent recurrence
          # Cron schedule, see https://en.wikipedia.org/wiki/Cron#Overview
          <string>
        ]