diff --git a/ci/clicks/journeys.mjs b/ci/clicks/journeys.mjs
index d34b86f2..1d9715f7 100644
--- a/ci/clicks/journeys.mjs
+++ b/ci/clicks/journeys.mjs
@@ -823,6 +823,25 @@ export const JOURNEYS = [
await page.getByText("Saved as a note in podcasts").first().waitFor();
},
},
+ {
+ id: "automation-starter",
+ module: "Automations",
+ feature: "Make an automation from a starter and turn it on",
+ note: "The starter fills the builder in (When an email from the school arrives, tell me); it is saved switched on.",
+ from: "/",
+ async run(ctx) {
+ const { page, meter } = ctx;
+ await go(ctx, "Automations");
+ await meter.click(page.getByRole("main").getByRole("link", { name: "New automation" }).first(), "New automation");
+ const starters = page.getByRole("group", { name: "Starters" });
+ await meter.click(starters.getByRole("button", { name: "Tell me about school emails" }), "the school starter");
+ await page.waitForFunction(() =>
+ [...document.querySelectorAll("input[aria-label=Name]")].some((i) => i.value === "Tell me about school emails"),
+ );
+ await meter.click(page.getByRole("button", { name: "Save and turn on" }), "Save and turn on");
+ await page.waitForURL(/\/automations\/\d+/);
+ },
+ },
{
// Last: it points Lens at a cloud model, which the stand-in model behind the journeys above isn't
id: "cloud-model",
diff --git a/docs/automations.md b/docs/automations.md
index bc39f35c..75ea810f 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -67,7 +67,8 @@ confirm first.
New automation opens the builder, with the cursor in **Describe it in words**: type a sentence ("when an email about
a school trip arrives, tell me") and press Enter, and the model fills the builder in, saying what it left out. Or
-build it yourself:
+pick one of the [starters](#starters) under it, which fills the builder in and says what to change first. Or build it
+yourself:
- **When**: one card per trigger. An activity kind has **Only when** rows (a field, a test that suits its type and
a value); a schedule has presets or a cron line, its time zone and its next few times; a time is a date and time;
@@ -1204,7 +1205,7 @@ used up.
Built (`app/domain/automation_starters.py`). `GET /api/v1/automations/starters` lists ready-made drafts, each
`{id, name, description, draft}`, with `draft` what `POST /automations` takes, switched off. Nothing is stored: a
starter is saved only when someone saves it, and runs only once it is turned on. The description says what to change
-first, such as the school's address.
+first, such as the school's address. In the web app they are under **Describe it in words** on a new automation.
| Starter | What it does |
| --- | --- |
diff --git a/docs/requirements.md b/docs/requirements.md
index 3abf92f6..462159c9 100644
--- a/docs/requirements.md
+++ b/docs/requirements.md
@@ -243,7 +243,7 @@ request, to another check that proves the same thing; loosening a requirement or
| Joins wait for an automation's triggers together: all of them, a number of times, one that doesn't come in time, or a batch, on timers that outlast a restart | [test_match_joins.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_match_joins.py) `test_all_waits_for_every_trigger_within_the_window_on_the_same_key`, `test_count_fires_once_per_crossing_then_counts_again`, `test_absent_waits_with_a_timer_and_the_missing_one_cancels_it`, `test_batch_collects_then_runs_once`, `test_two_writers_at_once_lose_nothing`; [test_automation_conditions.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_conditions.py) `test_an_absent_join_waits_on_a_timer_and_switching_off_drops_it` |
| Each automation has limits and budgets | [test_automation_runs.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/domain/test_automation_runs.py) `test_the_if_limits_and_dry_runs`, `test_a_run_over_budget_is_held_for_the_persons_pick` |
| Agents make, try and run automations over MCP and in the assistant, or draft one from a sentence | [test_automation_tools.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_tools.py) `test_agents_save_try_and_run_automations_over_mcp`, `test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_an_automation_is_drafted_from_a_sentence` |
-| Starter automations come switched off, each one saving as it is, and changing nothing until someone turns it on | [test_automation_starters.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_starters.py) `test_every_starter_saves_as_it_is_and_stays_off`, `test_the_school_starter_tells_me_at_once_and_asks_before_posting_to_the_family` |
+| Starter automations come switched off, each one saving as it is, and changing nothing until someone turns it on; in the builder one fills it in to save and turn on | [test_automation_starters.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_starters.py) `test_every_starter_saves_as_it_is_and_stays_off`, `test_the_school_starter_tells_me_at_once_and_asks_before_posting_to_the_family`; [automations-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automations-ui.test.tsx) `a starter fills the builder, and Save and turn on saves it switched on` |
| From an email to a yes: an automation tells you at once, asks before posting to the family, carries the post out on approval, and its run shows on the timeline | [test_automation_journey.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automation_journey.py) `test_an_email_runs_an_automation_that_tells_me_asks_before_posting_and_shows_on_the_timeline` |
| An automation's workflow is drawn and tried on the canvas: its actions in the palette, their settings drawn from each action's params, Decide's ports and the leaf rule | [workflow-canvas.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-canvas.test.ts) `give a decide node a port per option, then unsure`, `keep the leaf rule: nothing after an action that reaches outside Lens or waits`, `say what the backend would reject in their settings`; [automation-nodes-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automation-nodes-ui.test.tsx) `sets an action up from the catalog, its params drawn from its schema`; [schema-form.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/schema-form.test.tsx) `opens the variable picker on {{ and puts the pick in with Enter` |
| In the web app, automations are listed with what sets each off in words, and built in When, If and Then with a test on a recent activity, problems next to their fields | [automations-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/automations-ui.test.tsx) `the list reads each automation, and Delete is undone from its toast`, `the builder adds a trigger with a condition and an action, then saves it switched off`, `the test panel runs the draft on a recent activity and says what it would do`, `API problems go next to what they are about`; [test_automations.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_automations.py) `test_lists_read_the_triggers_in_words_and_say_when_it_runs_next` |
diff --git a/nextjs-frontend/__tests__/automations-ui.test.tsx b/nextjs-frontend/__tests__/automations-ui.test.tsx
index 1ef8eaaa..ca423555 100644
--- a/nextjs-frontend/__tests__/automations-ui.test.tsx
+++ b/nextjs-frontend/__tests__/automations-ui.test.tsx
@@ -23,6 +23,7 @@ jest.mock("@/app/openapi-client", () => ({
variableCatalog: jest.fn(),
testDraft: jest.fn(),
draftAutomation: jest.fn(),
+ listStarters: jest.fn(),
setPolicy: jest.fn(),
},
Activities: { listActivityKinds: jest.fn(), listActivities: jest.fn() },
@@ -123,6 +124,7 @@ function wrap(ui: ReactNode) {
}
beforeEach(() => {
+ m(Automations.listStarters).mockReturnValue(ok({ starters: [] }));
m(Automations.listActions).mockReturnValue(ok(ACTIONS));
m(Activities.listActivityKinds).mockReturnValue(ok(KINDS));
m(Automations.variableCatalog).mockReturnValue(
@@ -232,6 +234,38 @@ test("Describe it in words fills the builder and says what it left out", async (
expect(Automations.createAutomation).not.toHaveBeenCalled();
});
+test("a starter fills the builder, and Save and turn on saves it switched on", async () => {
+ m(Automations.listStarters).mockReturnValue(
+ ok({
+ starters: [
+ {
+ id: "school-emails",
+ name: "Tell me about school emails",
+ description: "Change “school” to your school’s address before turning it on.",
+ draft: {
+ name: "Tell me about school emails",
+ enabled: false,
+ join: { mode: "any" },
+ triggers: [{ as: "mail", on: "event", kinds: ["email.received"] }],
+ graph: ROW.graph,
+ },
+ },
+ ],
+ }),
+ );
+ m(Automations.createAutomation).mockReturnValue(ok({ id: 9, hooks: [] }));
+ wrap();
+ const starters = await screen.findByRole("group", { name: "Starters" });
+ fireEvent.click(within(starters).getByRole("button", { name: "Tell me about school emails" }));
+ expect(await screen.findByDisplayValue("Tell me about school emails")).toBeInTheDocument();
+ expect(screen.getByText("Change “school” to your school’s address before turning it on.")).toBeInTheDocument();
+ fireEvent.click(screen.getByRole("button", { name: "Save and turn on" }));
+ await waitFor(() => expect(Automations.createAutomation).toHaveBeenCalled());
+ const body = m(Automations.createAutomation).mock.calls[0][0].body;
+ expect(body).toMatchObject({ name: "Tell me about school emails", enabled: true });
+ expect(body.triggers[0].kinds).toEqual(["email.received"]);
+});
+
test("the test panel runs the draft on a recent activity and says what it would do", async () => {
m(Automations.testDraft).mockReturnValue(
ok({
diff --git a/nextjs-frontend/components/automations/automation-builder.tsx b/nextjs-frontend/components/automations/automation-builder.tsx
index 165d245a..b1aba309 100644
--- a/nextjs-frontend/components/automations/automation-builder.tsx
+++ b/nextjs-frontend/components/automations/automation-builder.tsx
@@ -2,7 +2,7 @@
/**
* The builder: When (triggers and the join line), If (conditions on the run) and Then (actions in order), read top to
- * bottom, with "Describe it in words" on a new one, a test panel, and Save and turn on. Ctrl/Cmd+Enter saves; Enter
+ * bottom, with "Describe it in words" and the starters on a new one, a test panel, and Save and turn on. Ctrl/Cmd+Enter saves; Enter
* on the last row adds the next.
*/
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -12,7 +12,7 @@ import { useEffect, useMemo, useState, type KeyboardEvent } from "react";
import { Automations } from "@/app/openapi-client";
import type { Automation } from "@/app/openapi-client/types.gen";
-import { useActions, useKinds } from "@/components/automations/data";
+import { useActions, useKinds, useStarters } from "@/components/automations/data";
import {
CLOCK,
draftProblems,
@@ -79,6 +79,7 @@ export function AutomationBuilder({
const toast = useToast();
const actions = useActions();
const kinds = useKinds();
+ const starters = useStarters(!automation);
const acts = actions.data;
const [draft, setDraft] = useState(() => (automation ? fromApi(automation as never, acts) : BLANK));
const [policy, setPolicy] = useState>(() => ({ ...(automation?.policy ?? {}) }));
@@ -147,6 +148,12 @@ export function AutomationBuilder({
},
onError: (e: Error) => toast({ tone: "red", title: "Couldn’t draft it", body: e.message }),
});
+ const start = (draftFrom: unknown, about: string) => {
+ const d = fromApi(draftFrom as never, acts);
+ setError(null);
+ setDraft({ ...d, steps: d.steps ?? [] });
+ setNotes([about]);
+ };
const save = useMutation({
mutationFn: async (turnOn: boolean) => {
@@ -230,8 +237,18 @@ export function AutomationBuilder({
The model fills the builder in; nothing is saved until you save.