Triggers

A trigger starts the Package's entry point. A Package can declare several, each with a unique id, and all of them start the same entry point.

triggers:
  - id: every-weekday-morning
    type: schedule
    cron: '0 7 * * 1-5'
    timezone: Europe/Sofia
    description: Weekday mornings at 07:00 local time.
  - id: run-manually
    type: manual

Type	Starts the entry point when…	Fields
`schedule`	The schedule fires	`cron`, `timezone` (both required)
`webhook`	Something posts to the Package's webhook URL	`payload.fields[]` (optional)
`inbound-call`	A call arrives on the installer's number	`sipTrunkSlot`, `routing.ref` (both required)
`api`	Something calls it through the Elizon public API	`request.fields[]`, `response.fields[]` (optional)
`manual`	Someone runs it from Studio	—
`email`	New mail arrives in the watched mailbox	—
`knowledge-document`	A document finishes indexing in the watched Knowledge Base	—
`app`	Something happens in a connected app	`connectionSlot` (required)

Every trigger also takes an optional description.

Five trigger types need a Workflow entry point

A schedule, webhook, email, app or knowledge-document trigger can only start a Workflow. On a Package whose entry point is an Agent or a Team, it installs but stays unwired, and the wizard says so. Use a Workflow entry point (it can be a single step that calls your Agent or Team), or use the api or manual trigger.

`schedule`

cron: a standard five-field cron expression.
timezone: an IANA time-zone name (Europe/Sofia, America/New_York). It's required, because "08:00" without a zone is the most common way a scheduled Package silently runs at the wrong time. The schedule keeps local time across daylight-saving changes.
Add schedule to compatibility.requiredCapabilities, or validate refuses the trigger with MANIFEST_CAPABILITY_DISAGREEMENT.

The installer can confirm or change the time and zone in the wizard.

`webhook`

- id: new-invoice
  type: webhook
  payload:
    fields:
      - { name: invoiceId, type: string, required: true }
      - { name: amount, type: number, required: true }

The webhook address and its token are generated when the Package is activated (they can't exist earlier) and shown to the installer then. payload.fields documents what the caller should send. Field types are string, number, boolean and object.

`inbound-call`

- id: after-hours-line
  type: inbound-call
  sipTrunkSlot: phone-line
  routing:
    ref: ./sip/inbound.yaml

sipTrunkSlot must name a Slot of type sip-trunk. The routing template describes call handling only. See Voice and SIP. Add voice and sip to requiredCapabilities: validate refuses each one that is missing with MANIFEST_CAPABILITY_DISAGREEMENT.

routing.ref must name the same file as sip.ref, because install applies only the sip: template. validate and build refuse a different file, or an inbound-call trigger in a Package with no sip:, with MANIFEST_INVALID_FIELD at triggers[<i>].routing.ref.

Unlike schedule and webhook, an inbound-call trigger doesn't need a Workflow entry point: it is wired whether the entry point is an Agent, a Team or a Workflow. The call is answered by the voice configuration's agent, but install doesn't route the number to the Package's voice configuration: the installer does that in Studio → Phone Configurations. The trigger only goes live once the installer has bound the Slot to a trunk and given the number to answer; a trunk bound without a number (as a CLI install binds it) leaves the trigger unwired. See Voice and SIP → In the manifest for a whole phone-line manifest, and npx @elizon/cli example sip for a complete project.

`api`

Exposes the entry point through the Elizon public API the installer already uses. There's no new endpoint and no new key, and the address appears when the Package is activated. request.fields and response.fields document the shape.

`manual`

Runs on demand from Studio. It's also the easiest way to test a Package after installing it, even one whose real trigger is a call or a schedule.

`email`

- id: new-mail
  type: email

An email trigger declares nothing beyond id and description. The mailbox, its IMAP server and the account are the installer's: the installer sets them in their own Organization, on the Email trigger node of the entry point Workflow, and the manifest never carries a mailbox path, a host or a credential. What to read (the filters, the attachment rules, the poll settings) is configured on that node too. It needs a Workflow entry point, because its trigger node lives in that Workflow, and it needs no requiredCapabilities entry. See Workflow nodes → trigger_email.

`knowledge-document`

- id: new-document
  type: knowledge-document

A knowledge-document trigger declares nothing beyond id and description. The Knowledge Base it watches is named on the Knowledge Base document trigger node of the entry point Workflow, as knowledgeBase: knowledgeBases.<name>, where <name> is a Knowledge Base the Package declares. It needs a Workflow entry point, because its trigger node lives in that Workflow. See Workflow nodes → trigger_knowledge_document.

Add knowledge to compatibility.requiredCapabilities, or validate refuses the trigger with MANIFEST_CAPABILITY_DISAGREEMENT.

`app`

slots:
  - id: drive-account
    type: credential
    required: true
    scheme: oauth2
    app: google
    description: The Google account whose Drive folder is watched.

triggers:
  - id: new-drive-file
    type: app
    connectionSlot: drive-account

connectionSlot is required and must be the id of a declared type: credential Slot, or validate refuses the trigger with MANIFEST_TRIGGER_SLOT_UNRESOLVED. The operator binds that Slot to one of their own connected accounts at install. Which app, which trigger, which folder or calendar, and how often to poll are set on the App trigger node of the entry point Workflow, whose connection is the same Slot id. It needs a Workflow entry point, because its trigger node lives in that Workflow. See Workflow nodes → trigger_app.

Triggers only fire when the Package is live

Nothing is armed during the install. Schedules, webhooks, phone routing, mailbox (email) and app (app) polling, and Knowledge Base document (knowledge-document) triggers go live when the operator activates the Package, and stay live while it's installed or installed_incomplete. A failed or uninstalled Package's triggers don't fire.

For schedule, webhook, api, email, app and knowledge-document triggers, Activate publishes the entry point Workflow. For email and app it also starts polling, at the interval set on the trigger node of the published Workflow. If that Workflow has no Email or App trigger node, the trigger is reported as failed, with the reason, and the rest of the Package still goes live. An email trigger's mailbox, server and login don't travel in the Package: the operator sets them on the Email trigger node after install, and polling reports an error on the trigger until they are set and the Workflow is published. An app trigger whose connectionSlot was left unbound at install is reported as deferred, and starts polling once an account is picked on the App trigger node and the Workflow is published.

Activation is the last step of the Studio wizard, or --activate on npx @elizon/cli install. A Package installed from the CLI without --activate is created but inert until it's activated, from the CLI or with Activate on its page in Studio.

Sending the result

A Package doesn't declare where its output goes. To email a report, put a Send Email node in the Workflow, usually after a Convert to File node that turns the report into a PDF, Word or Excel attachment:

- id: send
  type: send_email
  data:
    subject: Morning brief
    body: '{{ upstream.write.output.text }}'
    bodyFormat: markdown
    attachments: ['{{ upstream.pdf.output.file }}']

Only the message travels in the Package. The SMTP server, the password (a {{secret.…}} reference) and the recipients belong to the installer, so they are never part of the artifact. After installing, the operator opens the Workflow and fills them in on the node, and can change them at any time. Until they do, a run fails that node with "Send Email isn't configured".

Earlier versions of the format had a delivery-channel Slot for this. It has been removed; a manifest that still declares one is refused with a message pointing here.

Triggers

On this page