Polling Triggers

A polling trigger starts a workflow run whenever something new happens in an external service. The platform calls your trigger on a fixed interval; you check the service, return the new events, and hand back a bit of state so the next poll knows where it left off. Each event you return becomes the inputs of a triggered workflow run.

The class

Subclass BasePollingTrigger[Config] and implement poll:

from noxus_sdk.triggers import BasePollingTrigger, TriggerConfiguration
from noxus_sdk.ncl import Parameter, ConfigText
from noxus_sdk.plugins.context import RemoteExecutionContext


class NewTicketConfig(TriggerConfiguration):
    queue: str = Parameter(
        default="",
        description="Queue to watch",
        display=ConfigText(label="Queue name"),
    )


class NewTicket(BasePollingTrigger[NewTicketConfig]):
    trigger_name = "NewTicket"          # stable id, unique within the plugin
    title = "New ticket"
    description = "Runs once per new ticket in a queue"
    integrations = ["helpdesk"]          # credentials this trigger needs
    polling_interval = 60.0              # seconds between polls
    outputs = {"ticket_id": "str"}       # event fields → type labels

    async def poll(
        self, ctx: RemoteExecutionContext, state: dict
    ) -> tuple[list[dict], dict]:
        seen: list[str] = list(state.get("seen", []))
        client = _client_from_ctx(ctx)

        tickets = await client.list_tickets(self.config.queue)
        events: list[dict] = []
        for ticket in tickets:
            ticket_id = str(ticket["id"])
            if ticket_id in seen:
                continue
            events.append({"ticket_id": ticket_id})   # keys must match `outputs`
            seen.append(ticket_id)

        return events, {"seen": seen}

def triggers(self) -> list[type[BasePollingTrigger]]:
    return [NewTicket]

How `poll` works

Called on a schedule

The platform invokes poll(ctx, state) every polling_interval seconds. state is whatever your previous poll returned (an empty dict on the first call).

Return new events

Return (events, new_state). Each event is a JSON-serializable dict whose keys match your outputs — those fields become the triggered run’s inputs.

Persist a cursor

Put a watermark (last-seen id/timestamp, or a set of processed ids) in new_state so the next poll only returns genuinely new events. The platform stores it for you between polls.

Return an empty list when nothing is new — that is the normal case, and it starts no runs. Only return an event the first time you see it; deduping via state is what keeps a run from firing twice for the same item.

Reading credentials

List the integration types the trigger needs in integrations, then read them from the context the same way a node does:

creds = ctx.get_integration_credentials("helpdesk") or {}
api_key = creds.get("api_key", "")

See Creating integrations for the credential model.

Errors

Raise IntegrationFailedError (from noxus_sdk.errors) when the external call fails — only the message crosses the sandbox boundary, so make it actionable. Don’t let an exception escape for an expected “nothing new” result; return an empty list instead.

from noxus_sdk.errors import IntegrationFailedError

resp = await client.list_tickets(self.config.queue)
if resp.status_code != 200:
    raise IntegrationFailedError(f"Failed to list tickets: {resp.status_code}")

Definition fields

Field	Required	Notes
`trigger_name`	yes	Stable id, unique within the plugin.
`title` / `description`	no	Shown in the editor; `title` defaults to `trigger_name`.
`integrations`	no	Credential types the trigger reads (`[]` if none).
`polling_interval`	no	Seconds between polls (default `300`).
`outputs`	no	`{field: "type label"}` — the shape of each event / the trigger’s run inputs.
`image`	no	Icon URL.

Overview

Tutorial

Reference

GitOps

The class

How `poll` works

Reading credentials

Errors

Definition fields

​The class

​How poll works

​Reading credentials

​Errors

​Definition fields

The class

How `poll` works

Reading credentials

Errors

Definition fields