# People in the loop

> Building flows · https://spoletta.com/docs/people

People take part in a flow through human processes. A person can fill in what a run needs, review work and decide its state, or both in one step. While they think, the run waits, for as long as it takes.

## Two things a person does

| Step | On the board | The person |
| --- | --- | --- |
| Entry | The human process yields an object it doesn't take. Its link reads **Filled in**. | Fills the object in: a form with its attributes, or text for an object without any. |
| Review | The human process takes an object and its link back to it lists states. | Reads the object and presses one of the states, optionally with instructions. |

### Entry

*Diagram: The usual first step of a flow started by hand.*

Press **+** under a human process (*Add an object the person fills in*) and the new object is filled in. Every field is required. For a list, the form has **Add item** and a **×** per item, kept within the list's bounds. A file attribute can't be filled in by hand, so turn those into text.

### Review

*Diagram: Approve takes Notes and decides its state. The Release manager handles it.*

Link the object to the human process, then the process back to the object. A human process starts out deciding between all of the object's states; press the pill on the link (**Choose states**) to narrow them. Processes waiting for a state, such as one that posts the notes once `approved`, run when the person picks it.

## The review dialog

When a human step is reached, its card turns orange and pulses, and a dialog opens for whoever is watching: *Waiting for your review*, *Waiting for your input*, or *Waiting for Release manager*.

-   The inputs to read are shown beside the form.
-   **Instructions** (optional) travel with the object to the processes that take it in the state you choose: “Cut the intro to two sentences.”
-   There is one button per state. A step with no states to decide shows **Done**, or **Submit** when there are objects to fill in.
-   Closing the dialog leaves the same form in the process's panel. Set **Instructions for the person** in the process's settings to tell them what to look for.

## Who decides: persons and roles

A person object, such as *Release manager* or *Finance*, says who carries out the step. Its name is also a **role**. An admin gives people roles under **Settings** → **People**, and only holders of the role decide the reviews that person handles. Anyone else sees *Only Release manager decides this*. A review no person handles is anyone's to decide, and admins can decide any. People who hold a role see the flows whose reviews they decide, read-only.

## Things to know

> **A next connection out of a person is not followed:** What follows a person must take what they entered or decided. A plain *next* from a human process does nothing when they finish.

-   Each decision starts a fresh pass of the run, so a review can send work back as often as the person likes.
-   A scheduled flow shouldn't start with a person filling something in: it would wait every time, and later times are skipped while it waits. See [Schedules](https://spoletta.com/docs/schedules.md).

OPL:

```text
Release manager handles Approve.
Approve decides whether Notes is approved, changes requested or rejected.
Enter ticket has a person fill in Ticket.
```