diff --git a/READ_ME.md b/READ_ME.md new file mode 100644 index 0000000..96bb152 --- /dev/null +++ b/READ_ME.md @@ -0,0 +1,141 @@ +# Automation Workflow Status Portal + +A lightweight dashboard for monitoring Make.com (Celonis) automation scenarios. Built so non-Make users can see live status, success rates, run history, and (with the right token scopes) start scenarios or retry/remove incomplete runs — without ever logging into Make.com itself. + +## Quick start + +```bash +cd "Status portal" +npm install +cp .env.example .env # then edit .env with your token + host +npm start +``` + +Open . + +## Configuration + +### `.env` + +| Variable | Required | Description | +|---|---|---| +| `MAKE_API_TOKEN` | yes | API token from Make.com (see scopes below) | +| `MAKE_HOST` | yes | Full API host. Standard Make: `eu2.make.com`, `us1.make.com`, etc. Celonis-hosted orgs: `us1.make.celonis.com` | +| `SCENARIO_IDS` | fallback | Comma-separated scenario IDs (only used if `scenarios.json` is missing) | +| `POLL_MS` | no | Browser refresh interval in ms. Default `30000` (30 s) | +| `PORT` | no | Local port for the dashboard. Default `3000` | + +### `scenarios.json` + +This is the source of truth for which scenarios appear on the dashboard and what metadata is shown. Edit it freely and restart the server. + +```json +[ + { + "id": "110751", + "client": "3M", + "description": "This workflow updates the OMG workflow status." + }, + { + "id": "112565", + "client": "3M", + "description": "This workflow creates Masters / versions directly from OMG." + } +] +``` + +- `id` — the Make.com scenario ID (the number in the scenario's URL). +- `client` — used to group/filter cards by client. Appears as a chip on each card and as a filter button at the top. +- `description` — short human-readable summary shown under the workflow name. + +To add a new scenario: append an object to the array and restart (`npm start`). + +## Make.com API token + +In Make.com → avatar → **Profile** → **API/MCP access** → **Add token**. + +Tick these scopes: + +| Scope | Enables | +|---|---| +| `scenarios:read` | Live status, queue counts, run history, success rate — **required** | +| `scenarios:write` | The **▶ Start scenario** button | +| `dlqs:read` | Showing *why* a queued/failed run failed | +| `dlqs:write` | **🔁 Retry** and **🗑 Remove** buttons on incomplete runs | + +The dashboard works with just `scenarios:read` — other features degrade gracefully and show a clear error if a scope is missing. + +The token is read by the local server only; it is **never exposed to the browser**. + +## Branding + +Drop a PNG into the `Logo/` folder. The header expects: + +``` +Logo/Logotype White 72 dpi.png +``` + +If the file is missing, the heading text alone is shown. + +## Features + +**Views** + +- **Standard view** — up to 4 cards per row. Each card shows status, queue, success rate, average duration, and any active errors. The "Latest activity" feed is hidden for a quick overview. +- **Expanded view** — one full-width card per row including the 5 most recent runs with run name, status, ops count, and duration. +- The toggle (top-right of the controls bar) persists across page reloads. + +**Filtering & search** + +- Client filter chips at the top (auto-generated from `scenarios.json`). +- Free-text search across workflow name, description, and client. + +**Per-card features** + +- ▶ **Start scenario** — appears when a scenario is off. +- 📜 **View history** — opens a paginated modal showing 25 runs at a time, navigable with Newer/Older buttons. +- **Incomplete runs block** — when there are queued/failed items, shows the error reason and module name per item. With `dlqs:write`, each item has 🔁 Retry and 🗑 Remove buttons. + +## Architecture + +``` +Status portal/ +├── server.js Express proxy. Holds the API token. +├── scenarios.json Which scenarios to monitor + per-scenario metadata. +├── .env Token, host, port. +├── package.json +├── Logo/ +│ └── *.png Header logo. +└── public/ + ├── index.html Shell + modal markup. + ├── app.js Polling, rendering, view toggle, history, filters. + └── style.css Theme. +``` + +The dashboard never calls Make.com directly. The browser hits the local Express proxy, which forwards to `https://{MAKE_HOST}/api/v2/...` with the API token attached. This keeps the token off the client and lets us add scenario-allowlist guards to every write endpoint. + +## Endpoints exposed by the proxy + +| Method | Path | Purpose | Scope used | +|---|---|---|---| +| GET | `/api/config` | Poll interval, configured scenarios, client list | – | +| GET | `/api/status` | Live status for all scenarios (single call) | `scenarios:read`, `dlqs:read` | +| GET | `/api/scenarios/:id/history` | Paginated run history | `scenarios:read` | +| POST | `/api/scenarios/:id/start` | Turn on a scenario | `scenarios:write` | +| POST | `/api/scenarios/:id/run` | Trigger an ad-hoc run | `scenarios:write` | +| POST | `/api/scenarios/:id/dlqs/:dlqId/retry` | Retry an incomplete run | `dlqs:write` | +| DELETE | `/api/scenarios/:id/dlqs/:dlqId` | Remove an incomplete run | `dlqs:write` | + +Write endpoints reject any scenario ID not listed in `scenarios.json`. + +## Troubleshooting + +**`EADDRINUSE: address already in use :::4000`** — another process is on that port. Either stop it (`lsof -ti :4000 | xargs kill`) or change `PORT` in `.env`. + +**Cards show `"Access denied"` errors** — the token is missing a scope. Check the table above and edit the token in Make.com (Profile → API access → click token → Edit scopes). + +**`Make API 404: Not found` for a scenario** — the scenario ID exists on a different zone/host than `MAKE_HOST`. Confirm by opening the scenario in your browser and checking the URL. + +**Logo doesn't appear** — it must be a real PNG. macOS sometimes creates `.textClipping` files when you drag a filename instead of the file itself; those won't render. Right-click the PNG → Copy, then paste into `Logo/`. + +**Start button does nothing / 401** — `scenarios:write` scope missing (on Celonis-hosted instances this is the scope needed, not `scenarios:run`).