Triggers

A trigger starts runs without anyone clicking Start: at set times, when another system sends data, when someone submits a form, or when an integration module notices something, such as a new e-mail. This chapter explains which trigger to use, how it hands its data to the process, and what to keep in mind when you build a process for one. The Triggers page and the trigger's drawer, field by field, are described in Triggers.

The kinds of trigger

Trigger	Starts a run	Gives the process
Timer	At the times of its Schedule.	Nothing: the parameters keep their default values.
Webhook	When another system posts data to its address.	The data, in one parameter.
Form	When someone submits its form.	The form's fields, as the parameters.
From an integration module, such as an E-mail trigger	When the module finds something new, such as an e-mail, each time it looks.	Each item it found, in one parameter: a run for each.

Add one with Add trigger on the Triggers page, which needs the Manage definitions permission set. See Add Trigger.

What every trigger has

• One environment. A trigger's runs, and the process runs it starts, run in the trigger's Environment. To try a process out in Test while Production does the real work, give it a trigger in each.
• The latest version. Each time a trigger fires, it starts the latest published version of its process, or its draft when Use draft version is ticked. A version you publish is used from the next time on; you don't change the trigger for it.
• Enabled or Disabled. A disabled trigger doesn't fire: a timer skips its times, and a webhook answers that it is disabled. Disable a trigger to stop it for a while without losing its settings.
• A trigger run each time it fires. It shows what the trigger received and logged, and the process runs it started. See Trigger runs.

A trigger can start any process of the organization, whoever may run it: the permission to add triggers is a powerful one.

Timer

A timer starts its process at the times of its Schedule, a cron expression of five parts: minute, hour, day of the month, month, day of the week. The drawer writes out what it means below it.

Schedule	Starts a run
0 6 * * 1-5	At 6:00, Monday to Friday.
*/15 * * * *	Every quarter of an hour.
30 22 * * 0	At 22:30 on Sundays.
0 8 1 * *	At 8:00 on the first of every month.

• The times are Dutch time (Europe/Amsterdam), summer and winter time included, wherever you or the server are.
• A run may start up to a quarter of a minute late: Spider looks at the schedules every 15 seconds.
• Times missed are not made up. A time that passes while Spider is down, or the trigger disabled, starts nothing afterwards.
• A timer doesn't wait for the run it started before. When a run takes longer than the time between two firings, the next run starts anyway, next to it. Let the process check for itself whether there is work, so that two runs side by side do no harm.
• Start now, on the trigger's ribbon tab, fires it once by hand, also when it is disabled.

A timer gives its process no values. The process works with its parameters' default values, and finds its own work, such as the items of a collection or the files in a folder. Morning greeting starts Hello world at 6:00 on working days; it is disabled in the seeded organization.

Webhook

A webhook lets another system start a run by posting data to an address of its own:

POST https://<the Spider API>/organizations/<organization>/webhooks/<slug>?api_key=<key>
Content-Type: application/json

{ "Reference": "PO-2024-0414", "Customer": "C1004" }

• <organization> is the organization's key, or the short name in its address, such as HarbourLogistics.
• <slug> is the webhook's Slug, such as shipments. Give every webhook a slug of its own.
• The key is the webhook's Authentication, given as ?api_key= or as the password of Basic authentication. Give every webhook one: without it, anyone who knows the address can start runs.
• The data is JSON or XML, as the webhook's Data Type says, with a matching Content-Type.

Where the data goes

The data goes into one parameter of the process, picked under Parameter on the trigger's Process tab. Its type says what the data must look like: the seeded webhook New shipment puts the posted JSON into the parameter Shipment of Register shipment, of the type Shipment, so {Shipment.Reference} is PO-2024-0414 in the run.

• The data must fit the parameter's type: its properties, their types, and the rules of a simple type: a text where a number belongs is a mistake. Data that doesn't fit starts nothing, and the caller is told what is wrong, such as Shipment.Lines[0].Quantity. A parameter of the type Any takes anything.
• XML is turned into the same shape as JSON first. An element that occurs once fits a list of one.
• Data Schema adds a JSON or XML schema the data must fit too, when the type can't say everything.

So design the parameter's type to match the data the other system sends: From example on the Types page builds one from a sample. See Types.

What the caller gets back

Answer	When
200, with the trigger run's key	The trigger run started. Its process run is on the way.
400, with what is wrong	The data isn't JSON or XML, doesn't fit the schema or the parameter's type, or the Content-Type is wrong.
401	The key is missing or wrong.
404	No webhook has that slug in that organization.
503	The webhook is disabled.
500	The process run couldn't be started; the trigger run's log says why.

Every call that reaches the webhook makes a trigger run, also when it fails, so its log shows what was received and why it failed.

Form

A form trigger starts a run when someone submits a form: a claim, a request, a report of a fault. The form is a start form of the process: see Start forms. Its fields become the run's parameters, so a form trigger has no Parameter.

• Who can submit it: people signed in to Spider with the Submit forms permission set on the trigger. There is no anonymous form.
• Where they find it: on a dashboard, in a Form widget, or through Open form on the Triggers page. See A form trigger's form.
• The run is started by them: it shows their name under Started by.
• A form shown is the form submitted. When the process is published again while someone is filling in its form, their submit is refused, and the form opens anew, in the new version.

Claim an expense shows the start form Expense claim of Approve expense claim: an employee fills in their name, the amount and the reason, and a run starts that asks an approver to review it.

Triggers from integration modules

An integration module can bring triggers of its own, such as the E-mail trigger of Graph.Email, which reads a mailbox. Such a trigger runs on an agent, as an activity does:

• Its schedule says how often it looks, such as every five minutes. Without one, it looks only when you click Start now.
• Its inputs are the module's, such as the connection and the folder to read.
• Its demands say what an agent needs to run it: see Demands.
• Each item it finds starts a run, with the item in the Parameter of the process. An e-mail trigger starts a run per e-mail, with the e-mail as an Email.

One trigger, several processes

A trigger that finds several items at once has a Processes tab, where it can send each item to a different process. Each row has a Filter, an expression on the item, which is called {Item}:

Process	Filter
Process an invoice	contains({Item.Subject}, "invoice")
Process an order	contains({Item.Subject}, "order")
File the e-mail	(none)

For each item, the first row whose filter holds starts its process, and only that one. The row without a filter takes what no other row takes, and must be last. Without such a row, an item no filter takes starts nothing. See Processes.

Trigger runs

Each time a trigger fires, it makes a trigger run: on the Runs tab of the Triggers page, with what it received, its log, and the process runs it started on its Children tab. See Trigger run.

• A timer, a webhook and a form run inside Spider: their trigger run succeeds or fails at once. A failed one tells you why in its log; fire the trigger again once it is fixed.
• A trigger from an integration module runs on an agent, and can wait for one. When it fails, it can be retried, or aborted.

The process runs a trigger starts show it on their Details tab, under Trigger, and Go to › Parent opens the trigger run. A timer's or a webhook's runs have no Started by: no person started them.

Building a process for a trigger

• Give it parameters with default values that make sense when nobody fills them in: a timer gives none.
• Make the webhook's parameter of a type that fits the data exactly, and test it with a sample before the other system goes live.
• Try it on the draft first: a trigger in a test environment with Use draft version ticked starts your draft as you change it.
• Expect to run twice. A webhook can be called twice for the same thing, and a timer can overlap itself: check, for instance in a collection, whether the work was done already.

Related chapters

• Triggers: the page, and the trigger's settings, tab by tab.
• Trigger run: what a trigger run shows.
• Forms and user tasks: the start form of a form trigger.
• Types: the type of a webhook's data.