---
title: "Ready actions in automation tools"
url: /interfaces/automations
---

# Ready actions in automation tools

> Your product inside the automation tools a Customer's team wires by hand: each Verb a ready action, each move an instant trigger, generated from the file.

An [automation app](/interfaces/automations.md) puts your product inside the automation tools a Customer's team wires by hand, generated from the file and under your brand.

```mermaid title="One connection, from sign-in to revoked"
stateDiagram-v2
  [*] --> connected: a member signs in
  connected --> listening: trigger on
  listening --> paused: 3 days silent
  paused --> listening: it answers
  listening --> revoked: Key revoked
```

## What the tool shows, and where it comes from
Each tool reads the app in its own format. Every format holds the same parts, each from one line of the file.

| In the file | In the tool |
| --- | --- |
| A Verb in `actions` | A ready action, its input fields typed from the Noun, the required ones marked |
| A list or search Verb in `searches` | A step that finds one record by a field, for the next step to use |
| A move in `triggers` | An [instant trigger](/interfaces/automations.md#triggers), with a sample record from the docs' example |
| A [Relationship](/patterns/headless-saas.md) | A field filled from a list call, such as the record a link points to |
| An `enum` field | A drop-down of its values |
| The Offer | Each action's price beside its name, as the docs print it |
| A [Problem](/reference.md#errors) | The tool's error, with the cure link the Problem carries |

The app is generated at every deploy, so a new field appears in the tool with the [Version](/reference/platform.md#version) that adds it.

## Signing in
`auth: 'oauth'` puts a connect button in the tool. It opens your product's sign-in on your [Host](/reference/platform.md#host).

The sign-in carries your brand, and the member consents to the Verbs the app offers.

Each connection is an [app](/data/connectors.md#apps) in the Customer's org. It gets a [Key](/reference/platform.md#key) of its own, limited to those Verbs, which the member or an admin revokes from the portal.

With `auth: 'key'`, the member pastes a Key instead, and the tool checks it with one free call before it saves the connection.

## Instant triggers
A trigger holds a [Watch](/reference.md#events) while its workflow is on: the tool creates it when the workflow turns on, and deletes it after.

Each delivery is signed and retried for 3 days. It carries the Event's id, so the tool runs once per Event.

A hook unanswered for 3 days pauses its Watch, and the member hears of it in the tool and the portal.

A tool that cannot hold a hook reads the change feed instead, from the cursor of its last read, and misses nothing.

## The tracker, in every tool
The sales tracker offers every Verb as an action, one search, and each win as an instant trigger.

```ts title="definition.ts"
import { define } from 'apis.dev'

/** Deals for each Customer, ready in the automation tools its team already uses. */
export default define({
  name: 'pipeline', domain: 'pipeline.apis.dev',
  Company: { name: 'string', domain: 'url!#', deals: '<-Deal.company' },
  Deal: {
    title: 'string', amount: 'decimal(12,2)', company: '->Company.deals',
    stage: { open: [], qualify: 'opened', win: 'qualified', lose: ['opened', 'qualified'] },
  },
  offer: {
    Free: { month: 0, seats: 1, includes: { 'Deal.open': 25 } },
    Team: { month: 49, seats: 5, includes: { 'Deal.open': 1000 } },
    'Deal.open': 0.001,
  },
  automations: { actions: 'all', searches: ['Company.list'], triggers: ['Deal.win'], auth: 'oauth', list: true },
})
```

The tool reads one action and one trigger from the app like this.

```json title="The app · one action and one trigger"
{
  "app": "pipeline",
  "version": "4",
  "auth": { "type": "oauth2", "authorize": "https://pipeline.apis.dev/auth/authorize" },
  "actions": [
    { "key": "openDeal", "label": "Open a deal", "price": "0.001 USD a call",
      "fields": [
        { "key": "title", "type": "string", "required": true },
        { "key": "amount", "type": "number" },
        { "key": "company", "type": "string", "from": "listCompanies" }
      ] }
  ],
  "triggers": [
    { "key": "dealWon", "label": "Deal won", "event": "Deal.won", "hook": "/watches" }
  ]
}
```

## Versions, money and the directories
| What changes | What a connection meets |
| --- | --- |
| A deploy that adds a field or a Verb | The app's next version, read by every connection at its next run |
| A deploy that removes or retypes one | A new major version beside the old, which keeps working for 12 months |
| An action past the Customer's plan or balance | A 402 that stops that run, with the Checkout link in the tool's error |
| A refused or failed call | No charge, as on every [Interface](/every-product.md) |
| `list: true` | The app is submitted to each tool's public directory under your brand, from Launch |

`Automation.publish` sends the current version to every directory, and `Automation.list` shows each connection with its last delivery.