READ_ME.md edited online with Bitbucket
This commit is contained in:
Paul Johns
parent
4ab9868632
commit
186ea7e35d
1 changed files with 141 additions and 0 deletions
141
READ_ME.md
Normal file
141
READ_ME.md
Normal file
|
|
@ -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 <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`).
|
||||
Loading…
Add table
Reference in a new issue