NATS KV Trigger icon

NATS KV Trigger

Watch for changes in NATS KV buckets and trigger workflows

NATS KV Trigger

AI-generated

Overview

This node watches for changes in NATS Key-Value (KV) buckets and triggers workflows when updates occur. It is useful for real-time monitoring of configuration or state data stored in NATS KV buckets, enabling automation based on key changes.

Common scenarios include:

  • Reacting to configuration changes pushed to a KV bucket.
  • Monitoring user preference updates stored in KV keys.
  • Triggering workflows on specific key patterns or all keys within a bucket.

For example, you can watch a bucket named my-bucket for any key starting with config. and trigger a workflow whenever those keys are updated or deleted.

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). Example: my-bucket.
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: Last Value (default), History, Updates.
- Ignore Deletes: Boolean flag to skip delete events if set to true.

Output

The node outputs JSON objects representing KV key events matching the specified bucket and key pattern. Each output item contains fields such as:

  • bucket: The KV bucket name.
  • key: The key that triggered the event.
  • value: The value stored at the key (encoded as bytes).
  • revision: Revision number of the key.
  • created: Timestamp when the key was created.
  • operation: Type of operation (PUT, DELETE, etc.).
  • delta: Change count since last revision.
  • timestamp: Timestamp of the event.
  • size: Size of the value in bytes.
  • history: Number of historical revisions available.

If configured to include history or updates, the output will reflect those accordingly.

The node does not output binary data separately; the value field contains encoded text or binary data as part of the JSON.

Dependencies

  • Requires connection to a NATS server with access to JetStream and KV buckets.
  • Needs an API key credential for authenticating with the NATS server.
  • Uses bundled NATS client libraries internally.
  • No additional environment variables are required beyond the API key credential.

Troubleshooting

  • Bucket Not Found Error: If the specified KV bucket does not exist, the node throws an error indicating the bucket was not found. Solution: Create the bucket first using the appropriate NATS KV node or via your NATS management tools.
  • Connection Issues: Errors related to connection loss, async errors, or permission issues may appear in logs. Ensure network connectivity and correct API credentials.
  • Invalid Bucket Name: Bucket names must only contain letters, numbers, underscores, and hyphens. Avoid spaces or dots.
  • Key Pattern Syntax: Incorrect key patterns may result in no events being captured. Use > for all keys or valid wildcard patterns like prefix.*.

Links and References

Discussion