root
d3d3f33ec6
README, NODES.md, install scripts, palette help text, and example flows — node .js logic unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>
75 lines
2.4 KiB
Markdown
75 lines
2.4 KiB
Markdown
# Agent manual — Nextcloud Collabora Node-RED nodes
|
|
|
|
For flow agents building automations on Nextcloud + Collabora CODE. You edit Node-RED flows, not LibreOffice macros in the browser. File I/O goes through WebDAV or OCS. Document conversion goes through CODE REST.
|
|
|
|
## Rules
|
|
|
|
1. Use **app passwords** in `nc-collab-config`. Never account passwords.
|
|
2. Do **not overwrite originals**. Default output: `/Dokument/OfficeOut/`.
|
|
3. `postMessage` and iframe APIs are browser-only — not Node-RED.
|
|
4. Save files with **WebDAV PUT**, not WOPI PutFile.
|
|
5. Do not expose port 9980 beyond loopback on the host.
|
|
6. Do not touch odds-scraper or unrelated services in flows.
|
|
|
|
## Environment
|
|
|
|
| Key | Value |
|
|
|-----|-------|
|
|
| Nextcloud | `https://cloud.example.com` |
|
|
| Existing Node-RED | `nextcloud-node-red` on `:1880` — Collabora nodes integrate here |
|
|
| Internal CODE | `https://172.17.0.2:9980` on Docker bridge (container `code`) |
|
|
| Auth | Basic + app password, header `OCS-APIRequest: true` |
|
|
|
|
See [INFRASTRUCTURE.md](INFRASTRUCTURE.md) for network layout.
|
|
|
|
## Nodes
|
|
|
|
Full reference: [NODES.md](NODES.md).
|
|
|
|
**Config:** one `nc-collab-config` per environment — all six flow nodes need it.
|
|
|
|
**Common msg fields:** `ncPath`, `fileId`, `payload`, `format`, `destNcPath`, `fields`, `transform`, `operation`.
|
|
|
|
**Prefer `collabora-bridge`** for everyday tasks (`ncFileToPdf`, `fillTemplateSave`). Use low-level `collabora-*` nodes when bridge is not enough.
|
|
|
|
## Example flows
|
|
|
|
### A. NC file → PDF
|
|
|
|
```
|
|
inject { ncPath: "/Documents/contract.docx" }
|
|
→ collabora-bridge (ncFileToPdf)
|
|
→ debug destNcPath
|
|
```
|
|
|
|
### B. Template fill
|
|
|
|
```
|
|
extractToPayload or template:extractFields
|
|
→ function (map data to fields)
|
|
→ fillTemplateSave or template:fillFields
|
|
```
|
|
|
|
### C. Open in browser
|
|
|
|
```
|
|
nc-office (document:direct) → debug editorUrl
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
|---------|-----|
|
|
| ECONNREFUSED :9980 | Connect Node-RED to Docker bridge; use detected CODE IP |
|
|
| Empty convert response | Use HTTPS to internal CODE; check CODE is healthy |
|
|
| WebDAV 401 | New app password; same user as file path |
|
|
| WebDAV 404 | Leading slash on path; URL-encode segments |
|
|
|
|
## Acceptance criteria
|
|
|
|
- Test document converts to PDF under `/Dokument/OfficeOut/`
|
|
- Original unchanged
|
|
- Errors in `msg.error`, node status red — no silent failure
|
|
|
|
See also [NODES.md](NODES.md) for operation tables and examples.
|