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.

  --config-file Path to the configuration file
  check Check that all schedules are valid
  sample Produce a sample scheduled project being filled in
      FILE_PATH     template to fill in                                                            
      --destination destination path template. Note that the rendered template will be written here
  schedule Run the schedules
  next List the next times that scheduled will be activated
  --workflow-dir The workflow directory
  --archive-dir The archive directory
  --projects-dir The projects directory
  --archived-projects-dir The archived projects directory

  SMOS_CONFIG_FILE FILE_PATH                  Path to the configuration file 
  SMOS_WORKFLOW_DIR DIRECTORY_PATH            The workflow directory         
  SMOS_ARCHIVE_DIR DIRECTORY_PATH             The archive directory          
  SMOS_PROJECTS_DIR DIRECTORY_PATH            The projects directory         
  SMOS_ARCHIVED_PROJECTS_DIR DIRECTORY_PATH   The archived projects directory

  The workflow directory
  workflow-dir:
    # or null
    <string>
  The archive directory
  archive-dir:
    # or null
    <string>
  The projects directory
  projects-dir:
    # or null
    <string>
  The archived projects directory
  archived-projects-dir:
    # or null
    <string>
  Table background colours
  default: UseTableBackground (Bicolour (Just (Colour8Bit 234)) (Just (Colour8Bit 235)))
  colour.background:
    # 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
        <integer> # 8 bit unsigned integer
      , # Colour24Bit
        red: # required
          # The red component, [0..255]
          <integer> # 8 bit unsigned integer
        green: # required
          # The green component, [0..255]
          <integer> # 8 bit unsigned integer
        blue: # required
          # The blue component, [0..255]
          <integer> # 8 bit unsigned integer
      ]
    , # 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
    ]
  Schedule on which to schedule projects
  default: []
  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
            <integer> # 64 bit unsigned integer
          ]
        , # Rent recurrence
          # Cron schedule, see https://en.wikipedia.org/wiki/Cron#Overview
          <string>
        ]

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

All settings:
  Show this help text
  switch: -h|--help

  Output version information
  switch: --version

  Path to the configuration file
  option: --config-file FILE_PATH
  env: SMOS_CONFIG_FILE FILE_PATH

  The workflow directory
  option: --workflow-dir DIRECTORY_PATH
  env: SMOS_WORKFLOW_DIR DIRECTORY_PATH
  config:
    workflow-dir: # or null
      <string>

  The archive directory
  option: --archive-dir DIRECTORY_PATH
  env: SMOS_ARCHIVE_DIR DIRECTORY_PATH
  config:
    archive-dir: # or null
      <string>

  The projects directory
  option: --projects-dir DIRECTORY_PATH
  env: SMOS_PROJECTS_DIR DIRECTORY_PATH
  config:
    projects-dir: # or null
      <string>

  The archived projects directory
  option: --archived-projects-dir DIRECTORY_PATH
  env: SMOS_ARCHIVED_PROJECTS_DIR DIRECTORY_PATH
  config:
    archived-projects-dir: # or null
      <string>

  Table background colours
  config:
    colour.background: # 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
          <integer> # 8 bit unsigned integer
        , # Colour24Bit
          red: # required
            # The red component, [0..255]
            <integer> # 8 bit unsigned integer
          green: # required
            # The green component, [0..255]
            <integer> # 8 bit unsigned integer
          blue: # required
            # The blue component, [0..255]
            <integer> # 8 bit unsigned integer
        ]
      , # 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
      ]
  default: UseTableBackground (Bicolour (Just (Colour8Bit 234)) (Just (Colour8Bit 235)))

  Schedule on which to schedule projects
  config:
    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
              <integer> # 64 bit unsigned integer
            ]
          , # Rent recurrence
            # Cron schedule, see https://en.wikipedia.org/wiki/Cron#Overview
            <string>
          ]
  default: []

All commands:
  Check that all schedules are valid
  command: check
  
  Produce a sample scheduled project being filled in
  command: sample
    template to fill in
    argument: FILE_PATH
    
    destination path template. Note that the rendered template will be written here
    option: --destination PATH_TEMPLATE
    
  
  Run the schedules
  command: schedule
  
  List the next times that scheduled will be activated
  command: next
  

Options:
  -h|--help Show this help text
  --version Output version information
  --config-file Path to the configuration file
  check Check that all schedules are valid
  sample Produce a sample scheduled project being filled in
      FILE_PATH     template to fill in                                                            
      --destination destination path template. Note that the rendered template will be written here
  schedule Run the schedules
  next List the next times that scheduled will be activated
  --workflow-dir The workflow directory
  --archive-dir The archive directory
  --projects-dir The projects directory
  --archived-projects-dir The archived projects directory

Environment Variables:
  SMOS_CONFIG_FILE FILE_PATH                  Path to the configuration file 
  SMOS_WORKFLOW_DIR DIRECTORY_PATH            The workflow directory         
  SMOS_ARCHIVE_DIR DIRECTORY_PATH             The archive directory          
  SMOS_PROJECTS_DIR DIRECTORY_PATH            The projects directory         
  SMOS_ARCHIVED_PROJECTS_DIR DIRECTORY_PATH   The archived projects directory

Configuration Values:
  The workflow directory
  workflow-dir:
    # or null
    <string>
  The archive directory
  archive-dir:
    # or null
    <string>
  The projects directory
  projects-dir:
    # or null
    <string>
  The archived projects directory
  archived-projects-dir:
    # or null
    <string>
  Table background colours
  default: UseTableBackground (Bicolour (Just (Colour8Bit 234)) (Just (Colour8Bit 235)))
  colour.background:
    # 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
        <integer> # 8 bit unsigned integer
      , # Colour24Bit
        red: # required
          # The red component, [0..255]
          <integer> # 8 bit unsigned integer
        green: # required
          # The green component, [0..255]
          <integer> # 8 bit unsigned integer
        blue: # required
          # The blue component, [0..255]
          <integer> # 8 bit unsigned integer
      ]
    , # 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
    ]
  Schedule on which to schedule projects
  default: []
  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
            <integer> # 64 bit unsigned integer
          ]
        , # Rent recurrence
          # Cron schedule, see https://en.wikipedia.org/wiki/Cron#Overview
          <string>
        ]