nextcloud-collabora-nodered/docs/AGENT-MANUAL.md

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 for network layout.

Nodes

Full reference: 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 for operation tables and examples.