# -*- ispell-local-dictionary: "english" -*-

* Usage

By adding =cron= as a service, all other services in auto pair mode,
requiring a =schedule-command= will use it.

#+begin_src yaml
cron:
#+end_src

There are no options to set.

** =schedule-command= relation

If most other services will have default options and set these values
automatically. You probably don't need to configure anything in the
relation's options if defaults suits you.

Although, from the =schedule-command= relation towards this charm, in
your ~compose.yml~, you can explicitly add, replace, or override
parameters (if any default was set), and manage replace, add, or fine
tune command to be scheduled.

Please remember that commands will be run in =cron='s container.

*** Direct value, sequence or struct relations options

You can specify a ~schedule~ (required), ~command~ (there's a default
for run-once services, which is to run the service without any
arguments, otherwise you'll need to specify a command), optional
~lock~ options, and a ~label~ option.

The ~label~ option will help separate several commands by naming a
lock and naming the log file of the script:
~$CRON_DATASTORE/var/log/cron/launch-$SERVICE-$label_script.log~. If
empty or not provided the file name will be:
~$CRON_DATASTORE/var/log/cron/launch-$SERVICE-$label_script.log~.

Please notice that many charm will provide defaults for those values, and
you can override any settings.

**** Direct value for one command

#+begin_src yaml
myservice:
  # ...
  relations:
    # ...
    schedule-command:
      cron: !replace  ## could be also !prepend, or !append, note that !replace is default
        #schedule: */5 * * * *
        #command: |
        #  dc run --rm "$SERVICE_NAME" mycommand
        #label:
#+end_src

**** Sequences or struct for multiple commands

It can be a list of these:

#+begin_src yaml
myservice:
  # ...
  relations:
    # ...
    schedule-command:
      cron: !replace  ## could be also !prepend, or !append, note that !replace is default
        - schedule: "*/5 * * * *"
          command: dc run --rm "$SERVICE_NAME" mycommand1
          lock: !append -k
          label: command1
        - schedule: @daily
          command: dc run --rm "$SERVICE_NAME" mycommand
          label: command2
#+end_src

And this is the short form:

#+begin_src yaml
myservice:
  # ...
  relations:
    # ...
    schedule-command:
      cron: !replace  ## could be also !prepend, or !append, note that !replace is default.
        command1: (*/5 * * * *) {-k} dc run --rm "$SERVICE_NAME" mycommand1
        command2:
#+end_src


**** Short syntax or explicit syntax

This is supported in literal, sequence, and struct form:

#+begin_src yaml
myservice:
  # ...
  relations:
    # ...
    schedule-command:
      cron: !replace  (*/5 * * * *) {-k} dc run --rm "$SERVICE_NAME" mycommand
#+end_src

#+begin_src yaml
myservice:
  # ...
  relations:
    # ...
    schedule-command:
      cron: !prepend
        - labelfoo: */5 * * * * dc run --rm "$SERVICE_NAME" mycommand
#+end_src

#+begin_src yaml
myservice:
  # ...
  relations:
    # ...
    schedule-command:
      cron: !prepend
        labelfoo: */5 * * * * dc run --rm "$SERVICE_NAME" mycommand
#+end_src