Welcome to the new DOCS.vastdata.com. We've added new menus and a version selector, plus new persona and resource pages to help customers get started. Looking for a previous article? Use the docs search.

Press CTRL+K to open search

Triggers

Prev Next

Applies to VAST Cluster 5.5.

A trigger is what starts a pipeline: it turns something that happens into an event on a topic. This guide shows how to create the two kinds with the CLI: element triggers, which fire when objects or files change in a bucket, and schedule triggers, which fire on a cron schedule. It shows the filters and event types the cluster accepts, and how the schedule syntaxes behave on a 5.5 cluster.

Commands use the environment variables from the quickstart. The outputs come from a lab cluster running VAST Cluster 5.5.0-SP6 with vastde v5.5.0-sp2, where the bucket is docs-src and the tenant's broker is the VAST Event Broker view docs-kafka. Your names, GUIDs, addresses and times will differ. Every field and flag is in function and trigger files.

Element triggers

An element trigger watches one bucket (a view set up as a trigger source by your platform team) and sends one event per matching change. This one fires for every object created under photos/:

vastde triggers create element --name docs-src-uploads --description "New objects under photos/ in docs-src" --source-bucket "$BUCKET" --event "ObjectCreated:*" --name-prefix photos/

Trigger created: docs-src-uploads
Name: docs-src-uploads
Description: New objects under photos/ in docs-src
Tags: []
GUID: 11f2e798-f6c6-427f-b30f-0f20bdb8172a
Owner: {4294967295 vid 0xc0002da020 map[]}
CreatedAt: 2026-10-08T12:24:39Z
UpdatedAt: 2026-10-08T12:24:39Z
VRN: vast:dataengine:triggers:docs-src-uploads
Type: Element
Events:
  -: ObjectCreated:*
Topic: vast:dataengine:topics:docs-kafka/default
SourceBucket: docs-src

vastde triggers get <name> -o yaml shows the stored configuration, the broker and topic it publishes to, and its status:

vastde triggers get docs-src-uploads -o yaml

broker:
    is_accessible_to_data_engine: true
    name: docs-kafka
    type: Internal
    url: 15.0.0.1:9092
config:
    events:
        - ObjectCreated:*
    name_filters:
        prefixes:
            - photos/
        suffixes: null
    source_bucket_name: docs-src
    tag_filters: null
created_at: "2026-10-08T12:24:39.524Z"
description: New objects under photos/ in docs-src
events:
    - ObjectCreated:*
guid: 11f2e798-f6c6-427f-b30f-0f20bdb8172a
id: 7.513937404856631e+18
name: docs-src-uploads
owner:
    id: "4294967295"
    id_type: vid
    name: root
source_bucket_name: docs-src
status: Ready
tenant_guid: da47bae0-aefd-4e85-a5a9-2020d6a2cb91
topic: vast:dataengine:topics:docs-kafka/default
topic_name: default
type: Element
updated_at: "2026-10-08T12:24:39.524Z"
vrn: vast:dataengine:triggers:docs-src-uploads

Choose the events

--event takes the S3-style event names, and you can repeat it. The CLI lists the ones it accepts if you give another:

vastde triggers create element --name bad-event --source-bucket "$BUCKET" --event "ObjectCreated:Put"

invalid arguments:
  - --event list invalid: 'ObjectCreated:Put' not allowed. Available events:
    - ObjectCreated:*
    - ObjectRemoved:*
    - ObjectTagging:Put
    - ObjectTagging:Delete
--event Fires when Delivered event type
ObjectCreated:* An object or file is created vastdata.com:Element.ElementCreated
ObjectRemoved:* An object or file is deleted vastdata.com:Element.ElementDeleted
ObjectTagging:Put A tag is added to an S3 object vastdata.com:Element.ElementTagCreated
ObjectTagging:Delete A tag is removed from an S3 object vastdata.com:Element.ElementTagDeleted

So the name you configure and the event type your handler sees differ: test event.subtype == "ElementCreated", not ObjectCreated. The S3-style name appears only inside the event's data (Records[0].eventName, for example ObjectCreated:Put). See element events.

At least one event is required:

vastde triggers create element --name no-event --source-bucket "$BUCKET"

invalid arguments:
  - events are required

Filter by name

--name-prefix and --name-suffix limit the trigger to objects whose key (or, for NFS, file path) starts or ends with a string. Use a prefix per pipeline, so that pipelines sharing a bucket don't see each other's objects: the lab used photos/, fail/ and env/ prefixes on one bucket for three pipelines. Filtering in the trigger is cheaper than filtering in your handler, because events that don't match are never sent.

Tag events have their own tag filters (--tag-prefix, --tag-suffix), allowed only on a trigger whose only event is ObjectTagging:Put. See tag filters.

S3 objects and NFS files

--source-types selects S3, NFS4 or both. The lab's triggers didn't set it and reported S3 uploads; for NFS the source view needs NFSv4 set up for triggers by your platform team. See source types.

What the cluster checks

The bucket must exist, and trigger names are unique in the tenant:

vastde triggers create element --name bad-bucket --source-bucket no-such-bucket --event "ObjectCreated:*"

400 Bad Request: Failed to create trigger: Bucket not found

vastde triggers create element --name docs-src-uploads --source-bucket "$BUCKET" --event "ObjectCreated:*"

409 Conflict: Trigger with (name=docs-src-uploads) already exists!

Schedule triggers

A schedule trigger sends an event each time its schedule comes due. --cron-schedule takes either a standard 5-field cron expression or a Quartz expression with 6 or 7 fields (seconds first, and an optional year). All four of these were accepted:

vastde triggers create schedule --name every-2-min --description "Every 2 minutes (crontab)" --cron-schedule "*/2 * * * *"

Trigger created: every-2-min
Name: every-2-min
Description: Every 2 minutes (crontab)
Tags: []
GUID: f846c90c-cbf4-4efa-9af8-1c9e546d7a75
Owner: {4294967295 vid 0xc000996520 map[]}
CreatedAt: 2026-10-08T12:57:56Z
UpdatedAt: 2026-10-08T12:57:56Z
VRN: vast:dataengine:triggers:every-2-min
Type: Schedule
Topic: vast:dataengine:topics:docs-kafka/default
Cron Schedule: */2 * * * *

vastde triggers create schedule --name every-3-min-quartz --description "Every 3 minutes (Quartz)" --cron-schedule "0 0/3 * * * ?"

Trigger created: every-3-min-quartz
Name: every-3-min-quartz
Description: Every 3 minutes (Quartz)
Tags: []
GUID: b4ec4c44-ae64-449e-9864-03307089e071
Owner: {4294967295 vid 0xc0006187c0 map[]}
CreatedAt: 2026-10-08T12:58:05Z
UpdatedAt: 2026-10-08T12:58:05Z
VRN: vast:dataengine:triggers:every-3-min-quartz
Type: Schedule
Topic: vast:dataengine:topics:docs-kafka/default
Cron Schedule: 0 0/3 * * * ?

vastde triggers create schedule --name quartz-7-field --cron-schedule "0 0 12 ? * MON-FRI 2027"

Trigger created: quartz-7-field
Name: quartz-7-field
Description: N/A
Tags: []
GUID: 68289b69-7eb4-4546-9bbc-8884fe14a5f8
Owner: {4294967295 vid 0xc00045e8c0 map[]}
CreatedAt: 2026-10-08T12:58:08Z
UpdatedAt: 2026-10-08T12:58:08Z
VRN: vast:dataengine:triggers:quartz-7-field
Type: Schedule
Topic: vast:dataengine:topics:docs-kafka/default
Cron Schedule: 0 0 12 ? * MON-FRI 2027

vastde triggers create schedule --name six-field-no-q --cron-schedule "0 */5 * * * *"

Trigger created: six-field-no-q
Name: six-field-no-q
Description: N/A
Tags: []
GUID: e299a8c7-b206-488b-974c-21d9f66f195e
Owner: {4294967295 vid 0xc00069a5d0 map[]}
CreatedAt: 2026-10-08T12:58:15Z
UpdatedAt: 2026-10-08T12:58:15Z
VRN: vast:dataengine:triggers:six-field-no-q
Type: Schedule
Topic: vast:dataengine:topics:docs-kafka/default
Cron Schedule: 0 */5 * * * *
Expression Syntax Fires
*/2 * * * * Cron, 5 fields (minute first) Every 2 minutes, on even minutes
0 0/3 * * * ? Quartz, 6 fields (second first) Every 3 minutes, at second 0
0 0 12 ? * MON-FRI 2027 Quartz, 7 fields (with year) At noon on weekdays in 2027
0 */5 * * * * 6 fields, no ? Every 5 minutes, at second 0

Watch the field count: with six fields, the first field is seconds, so 0 */5 * * * * is every five minutes, not every five hours. In files, use the 5-field form unless you need seconds or a year, and say which syntax you used in the trigger's description. The VAST Web UI's Advanced schedule takes Quartz syntax.

An expression neither syntax accepts is rejected. The message comes from the 5-field parser, so it says expected 5 even though 6 and 7 fields are fine:

vastde triggers create schedule --name bad-cron --cron-schedule "every 5 minutes"

400 Bad Request: Invalid cron schedule: Wrong number of fields; got 3, expected 5

vastde triggers create schedule --name bad-cron --cron-schedule "61 * * * *"

400 Bad Request: Invalid cron schedule: Error validating expression '61': the last value (61) is higher than the maximum value (59)

Run a function on a schedule

In the pipeline file, a schedule trigger is used like an element trigger. One link can take events from several triggers:

name: ticks
description: Log what schedule triggers deliver
kubernetes_cluster_vrn: vast:dataengine:kubernetes-clusters:test-cluster
namespace: dataengine-ns-da47bae0-aefd-4e85-a5a9-2020d6a2cb91
manifest:
  triggers:
    - name: crontab
      vrn: vast:dataengine:triggers:every-2-min
    - name: quartz
      vrn: vast:dataengine:triggers:every-3-min-quartz
    - name: six-field
      vrn: vast:dataengine:triggers:six-field-no-q
  function_deployments:
    - name: ticker
      function_vrn: vast:dataengine:functions:ticker
  links:
    - source: [crontab, quartz, six-field]
      destination: [ticker]

ticker is the handler from write a function, which logs each event. The runtime's START line for each call shows which trigger fired and when:

vastde logs get ticks --since 15m | grep START

2026-10-08 13:08:01.59 [ticker] [INFO]  [vast-runtime] START EventId: 17914648800015842651, TraceId: 17914648-8000-1584-0ed0-ef1c462b4c2c, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-2-min.f846c90c-cbf4-4efa-9af8-1c9e546d7a75, Timestamp: 1791464881.598185
2026-10-08 13:09:01.48 [ticker] [INFO]  [vast-runtime] START EventId: 17914649400006828057, TraceId: 17914649-4000-0682-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-3-min-quartz.b4ec4c44-ae64-449e-9864-03307089e071, Timestamp: 1791464941.4875693
2026-10-08 13:10:01.31 [ticker] [INFO]  [vast-runtime] START EventId: 17914650000017996932, TraceId: 17914650-0000-1799-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-2-min.f846c90c-cbf4-4efa-9af8-1c9e546d7a75, Timestamp: 1791465001.3172526
2026-10-08 13:10:06.67 [ticker] [INFO]  [vast-runtime] START EventId: 17914650000010471173, TraceId: 17914650-0000-1047-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:six-field-no-q.e299a8c7-b206-488b-974c-21d9f66f195e, Timestamp: 1791465006.6712043
2026-10-08 13:12:01.82 [ticker] [INFO]  [vast-runtime] START EventId: 17914651200009328570, TraceId: 17914651-2000-0932-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-3-min-quartz.b4ec4c44-ae64-449e-9864-03307089e071, Timestamp: 1791465121.8212316
2026-10-08 13:12:01.86 [ticker] [INFO]  [vast-runtime] START EventId: 17914651200014305951, TraceId: 17914651-2000-1430-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-2-min.f846c90c-cbf4-4efa-9af8-1c9e546d7a75, Timestamp: 1791465121.8693445
2026-10-08 13:14:01.41 [ticker] [INFO]  [vast-runtime] START EventId: 17914652400056088553, TraceId: 17914652-4000-5608-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-2-min.f846c90c-cbf4-4efa-9af8-1c9e546d7a75, Timestamp: 1791465241.4175737
2026-10-08 13:15:01.21 [ticker] [INFO]  [vast-runtime] START EventId: 17914653000009301541, TraceId: 17914653-0000-0930-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-3-min-quartz.b4ec4c44-ae64-449e-9864-03307089e071, Timestamp: 1791465301.2132173
2026-10-08 13:15:06.45 [ticker] [INFO]  [vast-runtime] START EventId: 17914653000022038797, TraceId: 17914653-0000-2203-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:six-field-no-q.e299a8c7-b206-488b-974c-21d9f66f195e, Timestamp: 1791465306.459798
2026-10-08 13:16:02.62 [ticker] [INFO]  [vast-runtime] START EventId: 17914653600008216970, TraceId: 17914653-6000-0821-bd29-322d7bfe46f1, EventType: vastdata.com:Schedule.TimerElapsed, EventSource: vastdata.com:every-2-min.f846c90c-cbf4-4efa-9af8-1c9e546d7a75, Timestamp: 1791465362.6236463

Things to notice:

  • Each trigger kept its own schedule: every-2-min on even minutes, every-3-min-quartz every three minutes, six-field-no-q at 13:10 and 13:15.
  • Delivery takes a few seconds. The handler ran one to six seconds after the scheduled time. When your code needs the scheduled time, read event.timer_elapsed_timestamp, not the clock.
  • event.trigger tells you which one fired, from the event's source (vastdata.com:<trigger name>.<trigger GUID>).
  • When two schedules come due together, their events are separate calls.

Schedule triggers don't fire while the cluster's management service (VMS) is unavailable, for example during an upgrade. Don't use one where a missed run matters without a check in your code.

Brokers and topics

With no broker or topic flags, a trigger publishes to your tenant's default topic on the tenant's default broker: Topic: vast:dataengine:topics:docs-kafka/default above. Several triggers can share a topic. To give a trigger its own topic (for example, so that a busy bucket doesn't delay other pipelines), pass --broker-type, --broker-name and --topic-name together; the topic is created if it doesn't exist. See broker and topic, and for partitions and retention, the VAST Event Broker topics guide.

List, change and delete triggers

vastde triggers list shows every trigger in the tenant with its status and type:

vastde triggers list

Trigger Name     Status    Type        Description      GUID                  Updated at
--------------------------------------------------------------------------------------------
docs-src-cre...  Ready     Element     new objects ...  7d5e6227-d1bf-4bf...  2026-10-08 ...
docs-src-upl...  Ready     Element     New objects ...  11f2e798-f6c6-427...  2026-10-08 ...
docs-src-fail    Ready     Element                      a17df233-c00b-4d3...  2026-10-08 ...
every-2-min      Ready     Schedule    Every 2 minu...  f846c90c-cbf4-4ef...  2026-10-08 ...
every-3-min-...  Ready     Schedule    Every 3 minu...  b4ec4c44-ae64-449...  2026-10-08 ...
quartz-7-field   Ready     Schedule                     68289b69-7eb4-454...  2026-10-08 ...
six-field-no-q   Ready     Schedule                     e299a8c7-b206-488...  2026-10-08 ...
docs-src-env     Ready     Element                      ea98d94f-cb34-4e1...  2026-10-08 ...

A trigger exists on its own, whether or not a pipeline uses it, and one trigger can feed several pipelines. vastde triggers update <name> changes a trigger in place (you can't rename it), and vastde triggers delete <name> removes it; remove it from the pipelines that use it first. See updating a trigger. <!-- TODO: capture on devvm: triggers update --name-prefix and triggers delete, with output -->

Keep trigger definitions in Git with your pipeline file, as files for vastde triggers create element --from-file (see element trigger file) or as the commands in a script.

See also

Related articles