make-scenario-status/README.md

# 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 <http://localhost:4000>.

## 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`).