NATS KV Trigger icon

NATS KV Trigger

Watch for changes in NATS KV buckets and trigger workflows
Join our community

Overview

This node watches for changes in NATS Key-Value (KV) buckets and triggers workflows when relevant events occur. It is designed to monitor specific KV buckets and key patterns within those buckets, enabling automation based on updates, deletions, or history of key-value entries.

Common scenarios where this node is beneficial include:

  • Reacting to configuration changes stored in a NATS KV bucket.
  • Monitoring user preferences or settings that are updated dynamically.
  • Triggering workflows on data updates or deletes in distributed systems using NATS as a messaging backbone.

For example, you can configure the node to watch all keys in a bucket or only keys matching a pattern like config.*. When a key's value changes, the node emits the new data, allowing downstream workflow nodes to process it.

Properties

Name Meaning
Bucket Name The name of the KV bucket to watch. Must contain only letters, numbers, underscores, and hyphens (no spaces or dots).
Key Pattern Key pattern to watch. Use > to watch all keys, or patterns like config.* to watch specific keys. Examples: > (all keys), config.* (keys starting with config.), user.*.settings (specific patterns).
Options Collection of additional options:
- Includes: What to include in the watcher. Options are: Last Value (default), History, or Updates.
- Ignore Deletes: Whether to skip delete events (boolean).

Output

The node outputs JSON objects representing KV bucket events. Each output item contains fields such as:

  • bucket: The name of the KV bucket.
  • key: The key within the bucket that triggered the event.
  • value: The value associated with the key (binary encoded if applicable).
  • revision: Revision number of the key entry.
  • created: ISO timestamp string when the entry was created.
  • operation: Type of operation triggering the event, e.g., "PUT", "GET".
  • delta: Numeric delta indicating change count or version increment.
  • timestamp: ISO timestamp string when the event was emitted.
  • size: Size of the value in bytes.
  • _sampleDataNote: A note indicating if the data is sample data (used when no real data is found).

If configured to include history or updates, the output may also contain historical versions or update streams of the key values.

The node does not output binary data directly but encodes values as strings or buffers depending on the underlying KV store data.

Dependencies

  • Requires connection to a NATS server with JetStream enabled.
  • Needs an API key credential for authenticating with the NATS server.
  • Uses the nats-bundled library internally for interacting with NATS JetStream and KV buckets.
  • Requires proper network access and permissions to open and watch the specified KV bucket.

Troubleshooting

  • KV bucket not found error: If the specified bucket does not exist, the node throws an error instructing to create the bucket first using the appropriate NATS KV node.
  • Connection issues: Errors related to connection loss, async errors, or permission problems are logged by the node. Ensure the NATS server is reachable and credentials are valid.
  • No entries found: If no keys match the pattern, the node emits sample data to allow workflow testing. This is indicated by the _sampleDataNote field.
  • Invalid bucket name: Bucket names must only contain letters, numbers, underscores, and hyphens. Spaces or dots will cause errors.
  • Pattern syntax: Incorrect key patterns may result in no matches. Use > for all keys or valid wildcard patterns like prefix.*.

Links and References

Discussion