Trigger reference for agents

A trigger starts one workflow. It can run on the clock (a cron or interval schedule) or when a message arrives on a queue. save_trigger creates and updates it. For background, see Triggers and Schedules.

Tools

Tool	Role	What it does
list_triggers	viewer	Triggers of a project: id, name, type, active, workflow, disabledReason. Args: projectId, workflowId, sandboxId, page, search. Triggers on other people's sandboxes are never listed.
get_trigger	viewer	Every setting of one trigger.
save_trigger	creator	Create (no triggerId) or update (triggerId).
delete_trigger	creator	Deletes the trigger. The workflow stays. Nothing starts it from this trigger again.

Types

type	Starts the workflow	Needs
schedule	On the clock.	schedule. Optional timezone.
internal	From inside Fluxify. It has no clock and no queue.	Nothing else.
redis	For each entry of a Redis stream.	A Redis KV integration, source.
rabbitmq	For each message of an existing RabbitMQ queue.	A RabbitMQ integration, source.
kafka	For each message on Kafka topics.	A Kafka integration, source.
nats	For each message of a NATS JetStream stream.	A NATS integration, source.
sqs	For each message of an SQS queue.	An SQS integration, source.
plugin:<kind>	When a trigger kind a plugin adds reports an event.	An approved plugin that is enabled in the environment, and source with that kind's params.

Every built-in trigger type works in every edition, with no licence.

Create a schedule trigger

Pass projectId, name, type, schedule and the workflow.

{
  "projectId": "<project id>",
  "name": "Nightly report",
  "type": "schedule",
  "schedule": "0 30 2 * * *",
  "timezone": "UTC",
  "workflowId": "<workflow id>",
  "active": true
}

The result is { "id": "<trigger id>", "warnings": [] }.

A new trigger is inactive. Pass active: true, or nothing runs. The workflow must also be active.

Create a queue trigger

Pass the integration and a source in the connector's terms. This example reads a Redis stream.

{
  "projectId": "<project id>",
  "name": "Orders stream",
  "type": "redis",
  "integrationId": "<Redis integration id>",
  "source": { "stream": "orders" },
  "workflowId": "<workflow id>",
  "batchSize": 10,
  "maxWaitMs": 2000,
  "active": true
}

On create, on enabling, and on any change to source or integrationId, Fluxify contacts the broker. It checks the credentials and that the topic, stream or queue exists. A failure is a 400 with the broker's message and nothing is saved.

warnings lists settings that work but need a look, for example a missing dead-letter queue. Read them.

Create a plugin trigger

A plugin can add a trigger kind, and the project creates triggers from it like any other source. The type is plugin: followed by the kind, and the kind's params go in source, not in integrationId:

{
  "projectId": "<project id>",
  "name": "Order poller",
  "type": "plugin:acme/shop/orders",
  "source": {
    "database": "<database integration id>",
    "table": "orders",
    "everySeconds": 10
  },
  "workflowId": "<workflow id>",
  "active": true
}

• The kind is the trigger's name as the plugin declares it, for example acme/shop/orders. The person who installed the plugin knows it, and the trigger wizard lists it.
• source is checked against the kind's params. A wrong or missing param is a 400 that names the field, such as source.table: param 'table' is required. A number param outside its min/max, or a fraction where it asks for integer, is refused the same way, such as source.everySeconds: param 'everySeconds' must be at least 1, got 0.
• A secret param holds an App config key as cfg:<KEY>, exactly as an integration stores it.
• An integration param holds the id of an integration in the same project, of the kind the param takes and one the plugin was granted. A wrong variant is refused with the variants it takes.
• integrationId is refused for a plugin trigger, with A plugin trigger takes its integrations as params, in source.
• A kind from a plugin that is not approved is refused with No approved plugin of this project provides trigger <kind>. Creating one while the plugin is disabled is refused with plugin <name> is disabled.
• batchSize, maxWaitMs, maxBytes, concurrency, commitMode and dead-letter settings do not apply. The plugin owns batching and delivery.
• maxAttempts and retryDelayMs apply only when the kind declares that Fluxify retries its runs. Otherwise they are unused.

The trigger runs wherever its workflow is live and the plugin is enabled. A trigger Fluxify turned off keeps the reason in disabledReason. Setting active: true clears the reason, re-checks the trigger and its params, and starts a fresh failure count.

Update a trigger

Pass triggerId and only the fields that change.

{ "triggerId": "<trigger id>", "active": false }

• type and projectId cannot change. If you pass them they are ignored.
• workflowId: null detaches the workflow. The trigger then idles.
• Turning a trigger on clears its disabledReason. The system sets that field when it switches a trigger off itself, for example when its queue was deleted.

Common fields

Field	Type	Rule	Default
projectId	string	Create only.	none
name	string	2 to 255 characters. Unique in the project.	none
description	string	Up to 2000 characters.	none
type	string	One of the types above. Create only.	none
workflowId	string or null	A workflow of the same project. May be left out: the trigger is then saved and idle.	none
sandboxId	string or null	One of your own sandboxes, run instead of a workflow, on development workers with development values. Never together with workflowId, never for schedule. Only you see such a trigger. null detaches it.	none
groupId	string	A trigger group of the same project. Leave it out for the default group.	default group
integrationId	string	Built-in queue types only. An integration of the right kind in this project. Never for schedule, internal or plugin:<kind>.	none
payload	any JSON	Static data handed to the workflow. Use it for sources that carry none.	none
active	boolean	Only active triggers run.	false

A group holds at most 5 triggers by default. The operator can change that. The 6th fails with A trigger group holds at most 5 triggers and this one has 5. Create another group for the rest. No tool creates groups, so ask a person.

Schedule fields

Field	Rule	Default
schedule	Required for schedule. Up to 255 characters. Not allowed on other types.	none
timezone	An IANA name such as Asia/Kolkata. A fixed offset such as +05:30 is refused. Up to 64 characters.	UTC

Ways to write a schedule

You write	It runs
@every 5m	Every 5 minutes from when it was saved. The shortest is 1s. Units: ns, us, ms, s, m, h. Parts can be joined, as in 1h30m.
@hourly, @daily, @midnight, @weekly, @monthly, @yearly, @annually	At the start of the hour, day, week (Sunday), month or year.
0 0 9 * * 1-5	Six-field cron: seconds first, then minute, hour, day of month, month, day of week. Weekdays at 09:00.
@at 2026-03-01T02:00:00Z	Once. A time already past never runs.

Five-field cron is refused: A cron expression needs six fields — seconds, minutes, hours, day of month, month, day of week. Got 5. Add a leading 0.

Behaviour

• @every and @at ignore timezone.
• A timezone with daylight saving can skip a run or run twice on the change days. Use UTC when a run must happen exactly once.
• Runs are spread over the minute. @daily may run at 00:00:37, and it uses that second every day. Name the seconds field in cron to pin it.
• A schedule is one run each time, never a batch. The batch settings below do not apply.
• After downtime, missed runs are dropped, not replayed. Only @at runs late.

Batch and retry fields

These apply to the built-in queue triggers. A plugin trigger owns batching and delivery, so its maxAttempts and retryDelayMs matter only when the kind declares that Fluxify retries its runs.

Field	Rule	Default	Meaning
batchSize	1 to 10000	1	Events handed to one run. 1 runs the workflow once per event.
maxWaitMs	0 to 300000	0	How long a part-filled batch waits. Values from 1 to 999 act as 1000.
maxBytes	1024 to 67108864	1048576	Memory limit of one batch.
concurrency	1 to 64	1	Batches running at once. Above 1, order is lost.
commitMode	auto or manual	auto	auto marks a message done after a successful run. manual leaves that to the workflow.
maxAttempts	1 to 5	3	Runs of one batch before it is dead-lettered (auto) or handed back (manual).
retryDelayMs	0 to 300000	1000	Delay before a retry. It doubles after each failure.

Source by type

source is an object. It is required for queue types and for a plugin trigger.

Type	Field	Rule
redis	stream	Required. 1 to 1024 characters, no spaces.
	consumerGroup	Optional. Default fluxify-<triggerId>.
	consumer	Optional. Default is the host name.
	fromBeginning	Optional. A new group starts at the first entry instead of new ones.
	claimIdleMs	Optional. 1000 to 86400000. How long an entry sits unacknowledged before another consumer takes it.
	dlqStream	Optional. Default <stream>:dlq.
rabbitmq	queue	Required. An existing queue, 1 to 255 characters. Fluxify never creates it.
kafka	topics	Required. 1 to 100 names, each up to 249 characters.
	consumerGroup	Optional. Letters, digits, ., _, -, up to 200.
	fromBeginning, createTopics, allowIdleConsumers	Optional booleans. createTopics makes missing topics on save. Off, a missing topic is a 400.
nats	stream	Required. No spaces, ., *, >, / or \. Up to 255.
	filterSubjects	Optional. Up to 100 subjects.
	consumerGroup, fromBeginning	Optional. Group: letters, digits, _, -, up to 200.
sqs	queueUrl	Required. A URL.
	waitTimeSeconds	Optional. 0 to 20.
	visibilityTimeoutSec	Optional. 1 to 43200.
plugin:<kind>	the kind's params	Each param the plugin declares, by name under source. A required one must be present, a secret is cfg:<KEY>, and an integration is an integration id of the param's kind.

Common errors

Message	Cause and fix
Invalid input: schedule: A schedule trigger needs a schedule	Add schedule.
Invalid input: schedule: A internal trigger is not fired on a schedule	Remove schedule. It is only for type: "schedule".
Invalid input: schedule: ...is not a known shorthand...	Use one of the shorthands, @every, @at or six-field cron.
Invalid input: timezone: Use an IANA timezone name like Asia/Kolkata, not a fixed offset	Use a name. Unknown timezone "X" means the name does not exist.
A schedule trigger has no source to authenticate	Remove integrationId. Same for internal.
A Redis trigger needs a valid stream key	source is missing or wrong. Same pattern for the other types.
A Redis trigger needs a Redis integration from this project	integrationId is missing, from another project, or the wrong variant.
Fluxify API error 409: trigger with that name already exists	Pick another name.
Fluxify API error 400: Workflow belongs to a different project	Use a workflow of the same project.
Not found: Workflow ... not found	Wrong workflowId. Use list_workflows.
Broker message, such as a missing stream or queue	The source does not exist or the credentials fail. Fix it and save again.

Nothing runs when the trigger is off, has no workflow, or the workflow is inactive. All three must be right. Check list_triggers for disabledReason. For a worked example see Recipe, workflow with a cron trigger.