nextcloud-collabora-nodered/docs/NODES.md

Nodes — nextcloud collabora

Six flow nodes in the palette plus one config node. All six point at the same nc-collab-config (gear menu, not in the palette). Without config, nothing works.

Backends

Backend	Typical URL	Role
Nextcloud	https://cloud.example.com	Files (WebDAV) + Office API (OCS)
Collabora CODE	https://172.17.0.2:9980	Conversion (/cool/...) on Docker bridge

Auth: username + app password. Not your account password.

Default output folder if you omit a path: /Dokument/OfficeOut/ (or set your own via destNcPath).

---

How they fit together

nc-collab-config (URLs + app password)
        │
   ┌────┼────┬────────────┐
   ▼    ▼    ▼            ▼
collabora-*  nc-office  collabora-wopi  collabora-bridge
(direct CODE) (NC OCS)  (health/WOPI)   (pipelines + save)

Rules of thumb

• PDF in Nextcloud → collabora-bridge ncFileToPdf
• Fill template in NC → fillTemplateSave or nc-office template:fillFields
• Open in browser → nc-office document:direct
• Convert in memory only → collabora-convert
• List field names → collabora-extract or bridge extractToPayload
• Check CODE is alive → collabora-wopi capabilities

---

Common msg fields

Field	Meaning
ncPath	Path in the user's files, e.g. /Documents/contract.docx
fileId	Nextcloud numeric file id (resolved from ncPath if missing)
payload	Raw data already in the flow (Buffer or HTML string)
format	pdf, png, docx, html, …
destNcPath	Exact destination path
destFolder / destName	Folder + name (default folder /Dokument/OfficeOut/)
fields / transform	JSON to merge into a template
templateNcPath	Extra template file for convert
compareNcPath	Older version for diff PDF
operation	Overrides the node dropdown

Errors go to msg.error and turn the node red. The flow does not fail silently.

---

1. collabora-convert

Convert a file to another format via CODE. Does not save to Nextcloud — output is msg.payload (Buffer).

In: msg.payload or WebDAV GET msg.ncPath. Optional templateNcPath, compareNcPath, format.

Out: payload, filename, format, contentType, statusCode.

inject { ncPath: "/Documents/contract.docx", format: "pdf" }
  → collabora-convert → debug

---

2. collabora-extract

List structure inside a document (content controls, fields, etc.). JSON out, no file.

In: same as convert. Filter: node dropdown or msg.filter (default contentcontrol).

inject { ncPath: "/Templates/contract.docx" }
  → collabora-extract → function → collabora-transform

---

3. collabora-transform

Write values into a document via CODE. Requires msg.fields or msg.transform.

msg.ncPath = "/Templates/contract.docx"
msg.fields = { "Customer": "ACME Ltd", "Date": "2026-08-22" }
  → collabora-transform

Save yourself afterwards if the file should live in Nextcloud.

---

4. collabora-wopi

Health checks and WOPI helpers — not conversion.

Operation	Purpose
capabilities	First test that CODE responds
discovery	mime → editor URL
buildEditor	wopiSrc + token → editorUrl
checkFileInfo / getFile	Debugging

Public editor URLs go through Nextcloud (collaboraPublicUrl), not the internal CODE IP.

---

5. nc-office

Nextcloud richdocuments OCS — templates, fields, editor URL, assets.

Operation	Summary
templates:list	List templates
templates:create	New file from template
template:extractFields	Field JSON via NC
template:fillFields	Fill + save in NC
document:direct	editorUrl for logged-in user
document:public	Same with shareToken
files:convert	NC → NC conversion
assets:create	One-shot insert URL for open editor

inject { ncPath: "/Documents/contract.docx" }
  → nc-office (document:direct) → debug editorUrl

---

6. collabora-bridge

Ready-made pipelines — what you'll use most day to day.

Operation	Does
ncFileToPdf	NC file → PDF in OfficeOut
ncFileToPng	Preview PNG
ncFileToHtml	HTML export
htmlToOffice	HTML → docx/pdf …
fillTemplateSave	Template + fields → save in NC
compareVersionsPdf	Diff PDF
extractToPayload	Field JSON in msg
createAssetLink	assetUrl

inject { ncPath: "/Documents/contract.docx" }
  → collabora-bridge (ncFileToPdf)
  → debug destNcPath

Chain your existing OCS nodes (Talk, Mail, share link) after bridge: PDF lands in /Dokument/OfficeOut/, then share or send.

---

Config: nc-collab-config

Create under the gear icon in Node-RED. All six flow nodes pick the same config instance.

Field	Example
nextcloudUrl	https://cloud.example.com
collaboraUrl	https://172.17.0.2:9980 (bridge IP, verifyTls=false)
collaboraPublicUrl	https://cloud.example.com
username + app password	Nextcloud login

CODE IP is detected when you run ./install.sh — see .env.example.