Déclencheurs d'événements programmés récurrents

Trois déclencheurs différents vous permettent de programmer une automatisation à l'avance :

1. Time.ScheduledTimeEvent
2. Time.RecurringClockTimeScheduledEvent
3. Time.RecurringSolarTimeScheduledEvent

Le premier, Time.ScheduledTimeEvent, vous permet de programmer le démarrage d'une automatisation à un moment précis dans le futur ou de manière récurrente, en fonction de l'heure ou d'un événement solaire (lever ou coucher du soleil).

Par exemple, ce déclencheur lance l'automatisation tous les jours à 22h :

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(22, 0, 0, 0)))
}

Vous pouvez également spécifier un événement d'heure solaire au lieu d'une heure d'horloge. Le paramètre de ce type de déclencheur est un SolarTimeStruct composé des éléments suivants :

1. type, qui est soit SolarTimeType.Sunrise, soit SolarTimeType.Sunset.
2. offset, qui vous permet de décaler l'heure de début par rapport à l'événement solaire de n'importe quelle durée. Les valeurs positives introduisent un délai après l'événement solaire, et les valeurs négatives déclenchent le déclencheur avant l'événement solaire.

L'exemple suivant est un déclencheur qui lance l'automatisation 15 minutes avant le lever du soleil tous les jours :

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(
    Time.ScheduledTimeEvent.solarTime(
      SolarTimeStruct(SolarTimeType.Sunrise, java.time.Duration.ofMinutes(-15))
    )
  )
}

Les deux autres déclencheurs sont des déclencheurs d'événements programmés récurrents, qui vous permettent de créer des automatisations qui s'exécutent périodiquement selon des critères plus spécifiques pouvant inclure des conditions basées sur l'heure et le calendrier.

Time.RecurringClockTimeScheduledEvent vous permet de planifier une automatisation en fonction d'une ou de plusieurs conditions de date ou d'heure. Ce déclencheur utilise une syntaxe semblable à celle de l'utilitaire Unix cron pour spécifier la programmation d'une automatisation récurrente.

Time.RecurringSolarTimeScheduledEvent vous permet de planifier une automatisation en fonction de l'heure du lever ou du coucher du soleil, éventuellement en combinaison avec une condition basée sur l'agenda.

cron expression

Vous connaissez peut-être déjà cron, une commande utilisée sur les systèmes Unix et Linux pour planifier des tâches récurrentes.

Les déclencheurs d'événements planifiés récurrents utilisent une syntaxe d'expression de planification semblable à celle utilisée par cron. C'est pourquoi les expressions de planification utilisées avec ces déclencheurs sont appelées expressions cron.

Il existe plusieurs "variantes" de cron et plusieurs variantes de syntaxe dans ces implémentations. Les expressions cron du déclencheur d'événement planifié récurrent utilisent la même syntaxe que le planificateur Quartz. La syntaxe des expressions Quartz cron est expliquée dans la documentation de CronExpression de Quartz.

Exemples

Voici quelques exemples pour illustrer ce point.

RecurringClockTimeScheduledEvent

Dans un déclencheur RecurringClockTimeScheduledEvent, la chaîne d'expression cron est attribuée au champ Time.RecurringClockTimeScheduledEvent.cronExpression.

Voici un exemple de déclencheur RecurringClockTimeScheduledEvent qui lance l'automatisation à 20h, tous les mercredis d'avril :

starter<_>(structure, event = Time.RecurringClockTimeScheduledEvent) {
  parameter(Time.RecurringClockTimeScheduledEvent.cronExpression("0 0 20 ? 4 4 *"))
}

RecurringSolarTimeScheduleEvent

Le lanceur RecurringSolarTimeScheduleEvent comporte deux paramètres :

1. Un SolarTimeStruct.
2. cronExpression : sous-ensemble d'une expression cron composée uniquement des champs "Jour du mois", "Mois", "Jour de la semaine" et "Année". L'heure solaire détermine l'heure exacte à laquelle l'automatisation démarrera. Par conséquent, les champs "Seconde", "Minute" et "Heure" sont omis.

L'exemple suivant est un déclencheur qui lance une automatisation une heure après le lever du soleil, tous les mercredis d'avril :

starter<_>(structure, event = Time.RecurringSolarTimeScheduledEvent) {
  parameter(
    Time.RecurringSolarTimeScheduledEvent.solarTime(
      TimeTrait.SolarTimeStruct(SolarTimeType.Sunrise, Duration.ofHours(1))
    )
  )
  parameter(Time.RecurringSolarTimeScheduledEvent.cronExpression("? 4 4 *"))
}