Tasks

Heimdall Register – Event-Driven Task Triggering

Register tasks with Heimdall to execute actions based on event triggers

Heimdall Paths and Mechanisms form the basis of the registration task and are explained further in the Heimdall documentation.

# Basic Usage

In the following example, we register a task with Heimdall to update the subject of a stub whenever a customer's balance is updated. The task will be triggered each time the specified event occurs.

# Detailed Description

Task Type

• tasktype: Specifies the type of task to be registered. In this case, it is a Heimdall task registration.

Parameters (params)

• uuid: A unique identifier for the task, generated deterministically using the stub reference. This ensures that the same task has the same UUID every time it is registered.

{{#deterministicuuid stub.stubref}}{{/deterministicuuid}}: Template syntax used to generate the UUID based on the stub reference.

If you are doing multiple registrations on the same stub for different purposes, this UUID needs to be unique for each purpose. This is done by adding a string to the helper, eg. {{#deterministicuuid stub.stubref "some string"}}{{/deterministicuuid}}

• registration_name: A human-readable name for the task registration. In this case, it's named heimdall_customer_account_balance_update to reflect the nature of the task.

• on_trigger_method: Specifies how the task should behave when triggered. The value keep indicates that the task should remain registered and active even after being triggered.

Events (events) This section defines the events that will trigger the task. In this example, it listens for updates to customer account balances.

• wait_for_customer_account_balance:
  • path: The event path that the task will listen to. It monitors updates to the balance of customer accounts.
    The {{stubpost.data.customer_account_id}} placeholder will be dynamically replaced with the actual customer account ID.
  • mechanism: Specifies the event mechanism. Here, evt indicates that the event is an asynchronous event.
  • timeout_seconds: Defines the timeout period for the event in seconds. In this case, the timeout is set to 3600 seconds (1 hour).

Trigger Stub Action (trigger_stubaction) This section defines the action to be performed when the event is triggered.

• action_name: The name of the action to be executed. _set_subject_on_stub is a predefined action that sets the subject on a stub.
• stubref: A reference to the stub that will be updated. ~~stub.stubref uses a template to dynamically reference the stub.
• data: Contains the data to be used in the action.
  • subject: The new subject to be set on the stub. It uses template syntax to include the customer account ID and the updated balance.

{{stubpost.data.customer_account_id}}: Template placeholder for the customer account ID.

{{stubpost.data.balance}}: Template placeholder for the updated account balance.

# Parameters Reference

# uuid

required

string

Unique identifier linked to this Heimdall registration.

# registration_name

required

string

Human-readable name for the registration.

# on_trigger_method

optional

string

Determines whether the registration persists after triggering.

Options: keep | remove

# events.[event_name].path

required

string

Path that Heimdall monitors for triggers. * can be used as a wildcard.

# events.[event_name].mechanism

required

string

Mechanism used to fire the trigger.

Options: evt | cbh | rra | rnd | evb

# events.[event_name].timeout_seconds

required

integer

Duration (in seconds) that the registration stays active.

# trigger_stubaction.action_name

required

string

Name of the stub action to execute when triggered.

# trigger_stubaction.stubref

required

string

The stubref of the stub on which the action will run.

# trigger_stubaction.bulk_action

required

boolean

Available From: 2025-06-09

Indicates whether the action executes as a bulk (asynchronous) or normal (synchronous) action.

# trigger_stubaction.data

required

object

Data passed to the stub action.

# trigger_stubaction.message

required

string

Stub post message passed to the stub action.

# Result

# Examples

# Send a minutely update to a stub

# Register a reminder using sugartime

See also: Heimdall: Standard Emitters