---
title: "Function and trigger files"
slug: "dev-dataengine-reference-function-and-trigger-files"
description: "Learn how to create functions and triggers in your pipeline using YAML or JSON files, ensuring efficient event handling and deployment management."
tags: ["DataEngine"]
updated: 2026-10-28T02:14:59Z
published: 2026-10-28T02:14:59Z
canonical: "docs.vastdata.com/dev-dataengine-reference-function-and-trigger-files"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vastdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Function and trigger files

*Applies to VAST Cluster 5.5.*

Functions and triggers are objects you create before the pipeline that uses them. You can create each one from flags or from a YAML file. Keep the files in Git next to the [pipeline file](/develop/docs/dev-dataengine-reference-pipeline-yaml), so that the whole pipeline can be rebuilt from the repository.

| Object | Create | Update |
| --- | --- | --- |
| Function | `vastde functions create -f <file>` | `vastde functions update <name\\|GUID> -f <file>` |
| Element trigger | `vastde triggers create element --from-file <file>` | `vastde triggers update <name\\|GUID> [flags]` |
| Schedule trigger | `vastde triggers create schedule --from-file <file>` | `vastde triggers update <name\\|GUID> [flags]` |

`-f` is the short form of `--from-file` for both commands. Files can be YAML or JSON. When you give both a file and flags, the flags win.

This page uses one running example: an element trigger, `uploads-created`, on the source bucket `media-uploads`, feeding the functions `thumbnailer` and `indexer`. The pipeline that connects them is the [complete example](/develop/docs/dev-dataengine-reference-pipeline-yaml#complete-example) on the pipeline YAML page.

## Function file

```
# functions/thumbnailer.yaml
name: thumbnailer
description: Writes a thumbnail for each new image
tags: [media]
container_registry_vrn: team-registry            # registry name or VRN
artifact_source: media/thumbnailer               # path of the image in the registry
image_tag: "1.3.0"
architecture: x86
is_published: true
revision_alias: thumbs-1-3
revision_description: Smaller JPEG output
```

| Key | Flag | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `name` | `--name`, `-n` | string | Yes | You can't change it after creation. On `update`, the name comes from the command's argument; a different `name` in the file is rejected (`cannot change function name from '…' to '…'`). |
| `description` | `--description` | string | No | The function's description. Changing only this doesn't make a new revision. |
| `tags` | `--tags` | list of strings | No | Up to 32. Lowercase letters, digits and hyphens. |
| `container_registry_vrn` | `--container-registry` | string | Yes | The registry that holds the image: its name or its VRN, `vast:dataengine:container-registries:<name>`. The CLI looks a name up for you. `vastde container-registries list` shows the registries your tenant can use. |
| `artifact_source` | `--artifact-source` | string | Yes | The image's path in the registry, without the registry's URL and without the tag. The full image reference is the registry, the artifact source and the image tag together. |
| `image_tag` | `--image-tag` | string | Yes (CLI) | The image tag. Quote numeric-looking tags in YAML. Use a new tag for every build; see [publish functions](/develop/docs/dev-dataengine-guides-publish-functions). |
| `artifact_type` | `--artifact-type` | string | No | `image`, the only value and the default. |
| `architecture` | `--architecture` | string | No | `x86` or `arm`. Other spellings such as `amd64` or `x86_64` don't match the API's values. |
| `is_published` | `--publish` | boolean | No | Publishes the revision. The API describes an unpublished revision as one other users can't use. Default `false`. |
| `default_revision_number` | `--default-revision-number` | integer | No | The revision a pipeline runs when its function deployment doesn't pin one. If it's not set, the latest revision is used. |
| `revision_alias` | `--revision-alias` | string | No | A human-readable name for this revision. Without one, the revision is named after its number. |
| `revision_description` | `--revision-description` | string | No | A description of this revision. |

- The CLI requires `name`, the registry, `artifact_source` and `image_tag` on create.
- The server checks that it can reach the image when the revision is created.  The API's `skip_image_validation` turns this off for registries whose credentials only the compute cluster holds; the CLI has no flag or key for it.
- The function file has no handler or entry point. The handler is chosen when you build the image (`vastde functions build --handlers`). See [build and test locally](/develop/docs/dev-dataengine-guides-build-and-test-locally).
- The API's `runtime` field (Python version) has no CLI flag or file key. The Python version is fixed when you build the image.
- Keys the CLI doesn't know are ignored without a warning, so check spelling.

### Revisions

A function has numbered revisions. Each revision records one image (`artifact_source` and `image_tag`) plus its registry, architecture and publish state.

- `functions create` makes revision 1.
- `functions update` makes a new revision when you change the image, registry, architecture, artifact type, publish state, tags or alias. Changing only the description updates the function without a new revision.
- A new revision doesn't change a running pipeline. A function deployment that pins a revision keeps it. One that doesn't pin picks up the function's default revision, or its latest revision if no default is set, the next time the pipeline is deployed. See [pinning a revision](/develop/docs/dev-dataengine-reference-pipeline-yaml#pinning-a-revision).
- `--publish` publishes the new revision. It doesn't make it the default revision; set `--default-revision-number` for that.
- `vastde functions get <name> -r` lists the revisions. `functions get` without `-r` doesn't show `artifact_source` or `image_tag`, because they belong to revisions, so its output isn't a function file you can re-apply.

Publish every revision a pipeline will run.

To release new code: build and push a new image tag, change `image_tag` in the file, run `vastde functions update thumbnailer -f functions/thumbnailer.yaml`, then change `revision` in the pipeline file if the deployment is pinned, and update and deploy the pipeline.

## Element trigger file

An element trigger turns changes to objects or files in a source view into events.

```
# triggers/uploads-created.yaml
name: uploads-created
description: New JPEGs in media-uploads
tags: [media]
source_types: [S3]
config:
  events: ["ObjectCreated:*"]
  source_bucket_name: media-uploads
  name_filters:
    prefixes: ["incoming/"]
    suffixes: [".jpg"]
broker:
  type: Internal
  name: media-broker               # the VAST Event Broker view's bucket name
topic_name: media-uploads-events
custom_extensions:
  team: media
```

The file has the shape of the API's element trigger.

| Key | Flag (`triggers create element`) | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `name` | `--name`, `-n` | string | Yes | `^[a-z0-9-]+$`: lowercase letters, digits and hyphens. |
| `description` | `--description` | string | No |  |
| `tags` | `--tags` | list of strings | No | Up to 32. Lowercase letters, digits and hyphens. |
| `source_types` | `--source-types` | list | No | `S3`, `NFS4`, or both. See [Source types](/develop/docs/dev-dataengine-reference-function-and-trigger-files#source-types). |
| `config.events` | `--event` (repeatable) | list | Yes | At least one event. See [Events](/develop/docs/dev-dataengine-reference-function-and-trigger-files#events). |
| `config.source_bucket_name` | `--source-bucket`, `-s` | string | Yes | The bucket name of the source view. `vastde buckets list` shows the buckets you can use. |
| `config.name_filters.prefixes`, `.suffixes` | `--name-prefix`, `--name-suffix` | lists of strings | No | Only elements whose name has one of these prefixes or suffixes produce events. For S3 the name is the object key; for NFS it's the file path. |
| `config.tag_filters.prefixes`, `.suffixes` | `--tag-prefix`, `--tag-suffix` | lists of strings | No | Filter tagging events by tag. See [Tag filters](/develop/docs/dev-dataengine-reference-function-and-trigger-files#tag-filters). |
| `broker.type` | `--broker-type`, `-b` | string | With `broker` | `Internal` (a VAST Event Broker view) or `External` (a third-party Kafka broker registered on the cluster). |
| `broker.name` | `--broker-name`, `-m` | string | With `broker` | For `Internal`, the bucket name of the broker's view. For `External`, the broker's name. At most 40 characters. |
| `broker.url` | `--broker-url`, `-u` | string | No | Deprecated in the API: the URL is looked up by broker name. The 5.5 CLI still asks for it with `External` and rejects it with `Internal`. |
| `broker.is_accessible_to_data_engine` |  | boolean | No | Default `true`: DataEngine checks the broker is reachable. Set `false` for an external broker DataEngine can't reach. |
| `topic_name` | `--topic-name`, `-t` | string | With `broker` | The topic the trigger publishes events to. |
| `custom_extensions` | `--custom-extension k=v` (repeatable, or `@file`) | map | No | Key-value pairs added to every event as CloudEvent extensions. Keys: lowercase letters and digits, starting with a letter, 1 to 20 characters. Values are flat; no nesting. |

Each flag on the command line replaces the matching key from the file. A filter flag sets a one-item list.

### Events

| API and CLI name | Web UI name | Fires when |
| --- | --- | --- |
| `ObjectCreated:*` | ElementCreated | An object or file is created in the source view. |
| `ObjectRemoved:*` | ElementDeleted | An object or file is deleted. |
| `ObjectTagging:Put` | ElementTagCreated | A tag is added to an S3 object. S3 only. |
| `ObjectTagging:Delete` | ElementTagDeleted | A tag is removed from an S3 object. S3 only. |

Quote the names in YAML (`"ObjectCreated:*"`); in a shell, quote them too. The events a trigger delivers use the Web UI names: with `ObjectCreated:*`, the event's type is `vastdata.com:Element.ElementCreated` and `event.subtype` is `ElementCreated`. See [events](/develop/docs/dev-dataengine-reference-events#element-events).

### Source types

| Value | Web UI | Events from |
| --- | --- | --- |
| `S3` | S3 | S3 objects in the source view. |
| `NFS4` | NFS | Regular files written over NFSv4 in the source view. NFSv3 and SMB activity produces no events. |

The source view must be set up for the source type you choose, which is a platform-team task. For what NFS triggers do and don't report, see [triggers](/develop/docs/dev-dataengine-guides-triggers).

### Tag filters

Tag filters work only on a trigger whose only event is `ObjectTagging:Put`. Any other combination is rejected with `Tag filters can only be used with ObjectTagging:Put by itself`.

### Broker and topic

- Give `broker` and `topic_name` together, or neither. The CLI rejects one without the other.
- With neither, the trigger publishes to your tenant's default topic on the tenant's default broker.
- If the topic doesn't exist on the broker, it's created. The API describes `topic_name` as "used with broker field for automatic topic creation".
- The dead-letter topic can't be a trigger's topic.
- The trigger's topic is the topic a pipeline link from this trigger uses. Its VRN is `vast:dataengine:topics:<broker>/<topic>`, here `vast:dataengine:topics:media-broker/media-uploads-events`. `vastde triggers create` prints it as `Topic:`. See [topics on links](/develop/docs/dev-dataengine-reference-pipeline-yaml#topics-on-links).

For creating and sizing topics, see [topics](/develop/docs/dev-event-broker-guides-topics) in the VAST Event Broker section.

## Schedule trigger file

A schedule trigger produces an event on a schedule.

```
# triggers/nightly-reindex.yaml
name: nightly-reindex
description: Rebuild the media index every night
config:
  cron_schedule: "0 2 * * *"       # 02:00 every day
broker:
  type: Internal
  name: media-broker
topic_name: media-schedule-events
custom_extensions:
  job: reindex
```

| Key | Flag (`triggers create schedule`) | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `name` | `--name`, `-n` | string | Yes | `^[a-z0-9-]+$` |
| `description`, `tags` | `--description`, `--tags` |  | No | As for element triggers. |
| `config.cron_schedule` | `--cron-schedule` | string | Yes | See below. |
| `broker`, `topic_name` | `--broker-type`, `--broker-name`, `--broker-url`, `--topic-name` |  | No | As for element triggers. |
| `custom_extensions` | `--custom-extension` | map | No | As for element triggers. |

`cron_schedule` accepts two syntaxes. The server tries the first, then the second:

| Syntax | Fields | Example |
| --- | --- | --- |
| Standard cron | 5: minute, hour, day of month, month, day of week | `0 2 * * *` (02:00 every day), `*/15 * * * *` (every 15 minutes) |
| Quartz | 6 or 7: second, minute, hour, day of month, month, day of week, optional year | `0 0 2 * * ?` (02:00 every day), `0 0/3 * * * ?` (every 3 minutes), `0 0 12 ? * MON-FRI 2027` (noon on weekdays in 2027) |

A 6-field expression doesn't need Quartz's `?`: `0 */5 * * * *` fires every 5 minutes, on the minute. The Web UI's Advanced schedule takes Quartz syntax. Use the 5-field form in files unless you need seconds or a year.

An expression that neither syntax accepts is rejected when you create the trigger. The message reports the 5-field parser's error, so it says `expected 5` even though 6 and 7 fields are accepted:

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

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

The first is from `--cron-schedule "every 5 minutes"`, the second from `--cron-schedule "61 * * * *"`. See the [error reference](/develop/docs/dev-dataengine-troubleshooting-errors#triggers).

Schedule triggers don't fire while the cluster's management service (VMS) is down, for example during an upgrade or failover. Element triggers aren't affected.

## The generic `triggers create` form

`vastde triggers create --type Element|Schedule --from-file <file>` also exists, and the CLI's shipped sample files are written for it. It reads a flatter file (`type`, `topic_name`, `source_bucket_name` at the top level) and its flags differ (`--topic` instead of `--topic-name`). In 5.5 it reads `source_types` from the file but doesn't send it. Use `triggers create element` and `triggers create schedule` with the file shape on this page.

## Updating a trigger

`vastde triggers update <name|GUID>` changes a trigger in place. It takes the same flags as create, except `--name` (you can't rename a trigger) and `--topic` in place of `--topic-name`. It reads the trigger, applies your changes and writes the whole trigger back.

`triggers update --from-file` expects a flatter file than `create` (`topic_name`, `source_bucket_name`, `events`, `name_prefix` and so on, at the top level), and doesn't read `custom_extensions` from it. Until that's resolved, use flags for updates, or delete and recreate the trigger from its file.

There's no version check on triggers or functions: the last update wins.

## See also

- [Pipeline YAML](/develop/docs/dev-dataengine-reference-pipeline-yaml)
- [Publish functions](/develop/docs/dev-dataengine-guides-publish-functions)
- [Triggers](/develop/docs/dev-dataengine-guides-triggers)
- [Events](/develop/docs/dev-dataengine-reference-events)
- [Coming from the Web UI](/develop/docs/dev-dataengine-reference-coming-from-the-ui)
- CLI reference
- [Creating a Trigger](/docs-5-5/docs/creating-a-trigger) and [Creating a DataEngine Function](/docs-5-5/docs/creating-a-dataengine-function) on the KB
- [Create a new Function](https://kb.vastdata.com/api-5-5/apidocs/create-a-new-function), [Create a new Element Trigger](https://kb.vastdata.com/api-5-5/apidocs/create-a-new-element-trigger) and [Create a new Schedule Trigger](https://kb.vastdata.com/api-5-5/apidocs/create-a-new-schedule-trigger) in the VAST DataEngine API reference