Heimdall

Standard Emitters

Standard useful events on heimdall

Overview

Heimdall standard events allow you to listen for events like time events which allow for scheduling use cases.

In summary :

• You register for an event in the future that gets emitted at a specific time.
• The action you registered with will be triggered when the event is emitted.

The global path for all time events is global.time.zone.<timezone offset> The timezone offset is the offset from UTC in hours with negative offset prefixed with "neg" as explained in further detail below.

How to

To schedule an action at a specific time you can listen for the time event and then trigger the action when the event is received.
This allows a lot of flexibility in scheduling actions on stubs.
When registering for a time event we recommend setting the event to be removed and only triggered once, then use the action that is triggered to re-register for the event again. This makes sure that the event registration is not left in the system when the stub is closed.

Example :

• First we use the heimdall register task to register for the event. We could do this on a _create action or any other action that is called before the event is triggered.

        {
  "tasktype": "heimdall_register",
  "params": {
    "uuid": "{{#deterministicuuid stub.stubref \"time_event\"}}{{/deterministicuuid}}",
    "registration_name": "register_for_{{stub.stubref}}_time_event",
    "on_trigger_method": "remove",
    "events": {
      "wait_for_time_event": {
        "path": "global.time.minute.20240101153300",
        // "path": "global.time.zone.0.minute.20240101153300",
        "mechanism": "evt"
      }
    },
    "trigger_stubaction": {
      "action_name": "run_this_action",
      "stubref": "~~stub.stubref",
      "data": {
        "key": "~~stubpost.data.some_value"
      },
      "message": "Triggered from heimdall time event"
    }
  }
}

      

• Secondly in the action that gets called, we re-register for the event using the exact same registration name.

Should the stub that is listening for the event be closed, the run_this_action action would not be available and the event registration would be removed automatically.

Time Zones

Every event is emitted in the hierarchy of the timezone offset.
The timezone offset is the offset from UTC in hours with negative offset prefixed with "neg".
For example, UTC+2 would be 2 and UTC-5 would be neg5.

Time Based

Minute Fidelity Events

The minute event is emitted every minute at the start of the minute and done not incorporate time zone so the zone in the path is not used. The path for the minute event is global.time.minute.<timestamp> where <timestamp> is the timestamp of the minute event.

The timestamp is in the format YYYYMMDDHHMM00 (note the last 2 zeros are always 00 and reserved for seconds).
This is GMT Timezone.

Fidelity : Minute

Example at 15:33 on the 1st of January 2024 (UTC offset) : global.time.minute.20240101153300

Cron based events

Heimdall also emits some cron format based events. It is important to note that Heimdall uses the "#" as a wildcard in the cron format.
Day of the week is 0-6 with 0 being Sunday.

The general path format is : global.time.zone.<timezone offset>.cron.<minute>.<hour>.<day>.<month>.<day_of_week>
Use the heimdall single path wildcard "#" to match all values in a specific position in the path hierarchy.
Use the heimdall match all wildcard "*" to match all trailing values in the path hierarchy.

Some examples :

Every Sunday evening at 20:00 :

Heimdall Path : global.time.zone.0.cron.0.20.#.#.0

Every day at 15:00 :

Heimdall Path : global.time.zone.0.cron.0.15.#.#.#
Alternatively you could use the match all wildcard like this : global.time.zone.0.cron.#.15.*

Every Monday at 06:00 :

Heimdall Path : global.time.zone.0.cron.0.6.#.#.1

Every Hour on the 1st of the month :

Heimdall Path : global.time.zone.0.cron.0.#.1.#.#
Alternatively you could use the match all wildcard like this : global.time.zone.0.cron.0.#.1.*

Every evening at 23:00 :

Heimdall Path : global.time.zone.0.cron.0.23.#.#.#
Alternatively you could use the match all wildcard like this : global.time.zone.0.cron.0.23.*

Every minute for the 05:00 hour on the 1st of the month (advanced)

Heimdall Path : global.time.zone.0.cron.#.5.1.*

Every minute from 05:00 - 07:00 every day (advanced)

Heimdall Paths :

• global.time.zone.0.cron.#.5.*
• global.time.zone.0.cron.#.6.*
• global.time.zone.0.cron.#.7.*

Register like this :