Skip to main content

Trigger Guide

The ideas behind starting are the same as in the SaaS edition (Trigger Guide). This page sets out what differs in the Marketplace edition.

What each type can use​

WorkflowCycle
Starting it by hand“Start case” (owners only)No
Starting it at a set timeTime triggers. Parameters cannot be passed at the startA sweep schedule set on each placement
Starting it from outsideThe external API (service account token). Parameters cannot be passed at the startThe external API calls a webhook trigger (registered first)
Starting it by emailNoNo

Starting a workflow​

To start from the screen, use “Start case”. You can enter the parameters, connections and instruction files for each placement for that case (Case Guide).

A case started from a time trigger or the external API cannot be given values at the start. Each agent's parameters are the contract's defaults overlaid with the step settings. A body attached to an external API call is ignored.

If the required parameters, connections and input files are not all in place from the step settings alone, that case does not start.

  • With a time trigger, that round does not start, and it moves on to the next scheduled time
  • With the external API, an error is returned

If you run it from a time trigger or the external API, put all the required values in the step settings (Agent Guide).

How to call the external API is in the Marketplace edition's API Reference. It cannot be called with a person's token. Use the token of a service account created in the admin console. A service account can operate every project in this environment.

Running a cycle​

How to set the sweep schedule is the same as in the SaaS edition. In the Marketplace edition, the following are fixed.

  • A round that comes while the same placement is running is skipped. Rounds are not piled up to be run together later
  • A round more than 5 minutes past its schedule is recorded once as skipped, and it moves on to the next scheduled time. Rounds from while the environment was stopped are not all run afterwards
  • For 60 seconds after the same placement's previous execution ends, the next sweep is skipped. Webhook calls wait 60 seconds before starting
  • While a webhook call is waiting to start on the same placement, sweeps are skipped too

If the agent does not exit after processing, the next round of that placement keeps being skipped. If skips continue, have the agent's developer check how it exits (Your First Agent).

Running it by webhook (cycles)​

Registering a webhook trigger works as in the SaaS edition. What differs is how the calls received are handled.

  • Calls are not merged. Each call received is passed to the same placement one at a time, in order. The number of calls and the number of runs are the same
  • Up to 20 can wait per placement. Beyond that, 429 queue_full is returned
  • A call that could not be started within 24 hours of being accepted is not started

Delete or disable a webhook trigger, change the placement it starts, change the placement's environment variables, or pause the project, and calls not yet started become invalid too (the delete confirmation shows “Start requests waiting to be accepted are also invalidated.”). A call made while paused is refused with 409.

When it does not go to plan​

The SaaS edition's “Handling of results” (when not allowed by rules, when the agent reports it could not finish) does not exist. A registered agent's step follows a fixed handling for each way it ends (workflows).

How it endsHandling
Completed, skipped as nothing to doIt moves on to the next step
Not completed, stoppedIt is not redone automatically; a review request is created (sending it back to the same step can be chosen)
Not allowed by rules, other skipsA review request is created
Failed, timed out (what happened is known, and the effect on external systems is “Read only” or “Writes (safe to retry)”)It is retried automatically. Once the retries are used up, the case closes as failed
Failed, timed out (the effect on external systems is “Writes (retry may duplicate)”)So that it does not write twice, it is not retried automatically; a review request is created
An ending where what happened is unknownWhatever the kind of effect on external systems, it is not retried automatically; a review request is created

  • Automatic retries go up to the smaller of the project's “Retries per step” and 2

  • “An ending where what happened is unknown” covers cases where the agent's process ended abnormally, the Pod disappeared, the result could not be fully received, or it was cut off at the contract's execution limit (900 seconds by default). A timeout due to the execution limit is not retried automatically

  • When the execution rules could not be read before starting (for example, when there is a forbidden operation pointing to a connector that does not exist), it checks again after a short while, and creates a review request once the attempts are used up

Stopping and resuming​

As in the SaaS edition, pausing the project stops every run from starting anew. The Marketplace edition adds the following ways to stop.

What you want to stopHow
A case in progress (workflows)“Cancel case” on the case screen (owners only). Case Guide
One execution of a cycle in progress“Stop” on that execution's run record (owners only)

Distinctions worth keeping straight​

  • Thinking the case settings can be entered from a time trigger or the external API too. They can be entered only from “Start case”. Other ways of starting run on the values in the step settings
  • Thinking a time trigger always starts at its time. When required values are missing, or the number that can be in progress at once (3) has been reached, and so on, that round does not start, and it is not made up
  • Thinking cycle webhooks are merged into one run. In the Marketplace edition, they run one at a time, in order
  • Thinking a review moves on at the deadline. It does not (Review Guide)
  • Thinking it can be started by email. The Marketplace edition does not have it