# Workflows and jobs

A **workflow** is a chain of steps that your agents run for you: read the new
messages of a context every morning and post a summary, read the documents
that arrive and extract the data, answer a webhook from another system. You
build it once in SweetHive and it runs by itself.

Workflows run **on your own computers**, not in the cloud: on your
[SweetHive Agents Node](agents-node) or on your company's
[Agents Server](agents-server). The AI models, the documents and the data they
process stay on those machines.

Everything that runs for you is listed in **My agents, Jobs**: your workflows
and the requests coming from SweetHive apps (for example SweetTimetable
reading your receipts, or SweetReach rendering a video).

## Create a workflow

1. Open **My agents** and choose the **Workflows** tab.
2. Click **New workflow**. The editor opens with a canvas:
   - on the left, the list of **steps** you can add;
   - in the middle, the **canvas** with your steps and the links between them;
   - on the right, the **settings** of the selected step.
3. Click a step in the list to add it after the selected one. To link two
   steps, drag from the dot on the right of a step to another step.
4. Choose the **agent** the workflow runs as (top bar). Steps that read or
   post in your hives use that agent, so the workflow never sees more than
   the agent can.
5. **Save**. Every change to the steps saves a new version; runs already
   started keep the version they began with.
6. Press **Run** to try it: each step on the canvas shows its state live
   (waiting, running, done, failed) and, once finished, its result.

## When a workflow starts

Select the first step (the trigger) to choose how the workflow starts:

- **Manual** - when you press Run, in the editor or in the Workflows list.
- **Scheduled** - at fixed times: every hour, every day at 8:00, Monday to
  Friday at 9:00, or any schedule you write (cron) in your time zone.
- **Hive event** - when there is a new message, file, task, event or email in
  a hive (optionally in one context).
- **Webhook** - when another system calls the workflow's URL. The secret is
  shown once: copy it when you create it.
- **App event** - when a connected app emits an event (for example a new lead
  in SweetCRM).

You can pause a workflow at any time with its **Active** switch.

## The steps

| Group | Steps |
|---|---|
| SweetHive | **Read context** (messages, files, tasks of a context), **Post to context** |
| AI on your computer | **Generate text**, **Extract data** (text to structured data), **Read document** (PDF, scans and photos to text and data), **Render video** |
| Integrations | **HTTP request** (https only; private networks are blocked) |
| Data | **Set values**, **Map list**, **Filter list** |
| Flow | **If** (two branches), **Switch** (one branch per case), **Wait** |

A step can use the results of the previous ones. In any text field, insert
a variable with the buttons under the settings, for example
`{{ $steps.summary.output.text }}` (the text generated by the step called
*summary*) or `{{ $trigger }}` (what started the workflow). There is no code
to write.

## Where the steps run

Each step runs on one of your computers:

- by default it stays on the **same computer as the previous step** (the
  model is already loaded, the files are already there);
- it moves to **another computer** when it needs something the first one
  does not have: a model that sees images, a larger context, a render
  worker. You can also let a step run on **any available computer**
  (*Where it runs* in its settings).

If none of your computers can run a step right now, the job waits and tells
you why (for example *Waiting for one of your computers: open the SweetHive
Agents Node*). It starts by itself as soon as a suitable computer is online.

## Follow your jobs

**My agents, Jobs** lists what is running and what ran, newest first. Each
job shows who started it (a workflow or an app), how many steps are done,
which computer is running it and, when something goes wrong, the reason in
plain words: the model is not installed, the document is too long for the
model, the file link expired, the computer stopped responding.

- **Cancel** stops a job that is waiting or running.
- **Retry** runs a failed or cancelled job again.
- Open a job to see every step, the computer and model it used, how long it
  took and its result.

When the problem is on the computer (a missing model, a context too small,
the computer turned off), the job does not use up its attempts: it moves to
another computer or waits. When the problem is in the input (an unreadable
document, an answer the model could not format), it is retried once and then
reported.

The SweetHive Agents Node shows the same list in its **Jobs** section:
what it is doing now and what it did recently.

## Privacy

- A workflow runs **as one of your agents**: it sees only the hives and
  contexts that agent can see, and it can post only if that agent can post.
- AI steps run **on your computers** with local models.
- Files passed between steps are kept for 7 days and then deleted. Links to
  documents sent by apps are never shown in the job lists.