Explanation

Automation

On this page

An app can act on its own in two ways: with triggers and with scripts. Most apps only need triggers. This page is for builders who have a working app and now want it to react to what happens on a ticket.

Two ways to automate

Four ticket events passing through a condition and leading to declarative actions or, through a gate, to a script
Every automation starts from one of four events and passes the same optional conditions. Only what runs afterward differs.

Both start from the same events: onCreate, onComment, onEdit and onConclude. onCreate and onConclude fire once per ticket. onComment and onEdit fire on every comment or attribute change. See the lifecycle.

StyleWhat decides the outcomeUse it when
TriggerFixed actions written in YAMLThe rule is always the same, such as notify, set a field or conclude
ScriptStarlark code you writeThe rule has branches or timing that YAML cannot express

An app can use both, or neither. The triggers reference lists the actions and the dispatch order.

Triggers

A trigger names an event, optional conditions and one or more actions. They all sit on the same YAML object.

triggers:
  - onEdit:
      - attribute: severity
        ifMatch: critical
        alert: "#oncall"
  - onConclude:
      - email:
          to: ${initiator}
          subject: "Resolved: ${title}"
          body: ${conclusion}

A trigger can also sit on an attribute, or on one option of a select attribute. That is how a button or a status change acts. See per-attribute triggers. The Attributes tab has no control for these triggers. You edit them, and the top-level list, as YAML on the Expert tab. Triggers on the same event run in the order they appear in the YAML.

Scripts

A script is Starlark code under scripts:. A trigger’s script: action starts it. Its entry function onTrigger receives the ticket, a conclude object for side effects, and why it ran.

scripts:
  - name: route
    source: |
      def onTrigger(activity, conclude, trigger):
          category = activity.get("category")
          if category == "billing":
              activity.set("routed_to", "finance-team")
          elif category == "outage":
              activity.set("severity", "high")
              conclude.comment("Routed to oncall.")

triggers:
  - onCreate:
      - script: route

A script can read and set attributes, post and edit its own comments, and schedule itself to run again. The scripting reference lists the caps.

Agents

Agents belong to your organization. Deploy an agent to the app’s channel on the Agents tab. It responds to new tickets and comments according to its mode in that channel, without a trigger.

Use an agent when the response needs judgment or free text. An agent only posts comments. To set a field or conclude a ticket, use a trigger or a script. See Agents on tickets.

Conditions

Three keys hold a trigger back, whatever its action:

KeyEffect
attributeLimits an onEdit trigger to this attribute. Without it, the trigger fires on every edit.
ifMatchA regular expression the new value must match. On onComment, it matches the comment text.
ifNotMatchA regular expression the value must not match. With ifMatch, both must hold.

The full table is in the conditions reference.

Loop protection

Events caused by triggers do not start scripts or notify agents in the app’s channel. Anything a trigger changes carries a call-stack marker. The follow-up events it raises don’t start scripts or reach agents. A script that posts a comment therefore doesn’t start itself again.

An agent never answers its own comments. Its comments on one ticket are also rate-limited and capped. Declarative actions such as setAttribute, message and email can still chain, but the cascade stops at a fixed depth.

A script that schedules itself again with conclude.schedule gets past this guard. Only the length of its chain limits it. The numbers are in the triggers, scripting and agents references.