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

Assistentmanual — Nextcloud Office + Collabora Node-RED

Version 1.0 — 22 augusti 2026

Gäller sidecaren nextcloud-collabora-nodered mot Nextcloud på cloud.hannesahlin.se och Collabora CODE 26.04.x (container code, 127.0.0.1:9980). Odds-scraper ignoreras.

Du är en flödesagent. Du skapar och modifierar Node-RED-flöden, inte LibreOffice-makron i webbläsaren. All fil-I/O går via Nextcloud WebDAV eller OCS. All dokumentmotor går via CODE REST.

---

1. Uppdrag och gränser

1. Använd app-lösenord i nc-collab-config. Aldrig vanligt kontolösen.
2. Skriv inte över original. Standardmål: /Dokument/OfficeOut/.
3. postMessage-API och CallPythonScript är iframe/webbläsare. Inte Node-RED.
4. WOPI PutFile är CODE:s jobb mot Nextcloud. Agenten använder WebDAV PUT.
5. Exponera inte port 9980 utanför loopback.
6. Rör inte odds-scraper eller Gitea-databaslösen i flöden.

---

2. Miljö

Nyckel	Värde
Nextcloud	https://cloud.hannesahlin.se (host 192.168.1.26)
CODE	container code, 127.0.0.1:9980, aliasgroup https://cloud.hannesahlin.se:443
Befintlig Node-RED	nextcloud-node-red :1880 — Collabora-noder integreras här
Sidecar :1881	Endast med INSTALL_MODE=sidecar (ej standard)
Intern CODE-URL från sidecar	http://172.17.0.2:9980 (Docker bridge, container code)
Auth	Basic + Nextcloud app-lösenord, header OCS-APIRequest: true

Se INFRASTRUCTURE.md för container- och nätverkskartor.

---

3. Kartan Nextcloud → Collabora

Nextcloud	Collabora-yta	Nod
WebDAV GET fil	input till convert/extract/transform	convert, extract, transform, bridge
WebDAV PUT	spara PDF/DOCX/PNG	samma + destNcPath
files convert OCS	samma motor via richdocuments	nc-office files:convert
richdocuments mallar	convert-to template= eller NC create-from-template	nc-office templates:*
template fields	content controls	extractFields / fillFields / transform
file versions	compare= på convert-to	bridge compareVersionsPdf
fileId + direct token	WOPISrc + editor iframe	nc-office document:direct, wopi buildEditor
assets API	linking / insert graphic URL	assets:create + klient postMessage
shares	public edit URL	document:public
preview	convert-to png	ncFileToPng
HTML/MD	convert-to office	htmlToOffice

Talk, Tables, Mail, Collectives ska konsumera resultatet (dela PDF, bifoga, lägg i collective) — de ersätter inte WOPI-host.

---

4. Noder och msg-kontrakt

4.1 nc-collab-config

En instans per miljö. Fält: nextcloudUrl, collaboraUrl, ev. collaboraPublicUrl, username, app-lösen, verifyTls (false i labb-VM tills certkedjan är ren).

4.2 Gemensamma msg-fält

Fält	Betydelse
ncPath	Sökväg i användarens filrot, t.ex. /Mallar/avtal.docx
fileId	Numeriskt Nextcloud-fileid
payload	Buffer eller text om källan inte ligger i NC
format	pdf | png | docx | odt | html | txt | xlsx | pptx …
destNcPath / destFolder / destName	Var resultatet skrivs
transform / fields	JSON för struktur-API eller mallfält
templateNcPath / compareNcPath	Extra filer till convert-to
operation	Överstyr dropdown
statusCode / error / filename / contentType	Utdata

4.3 Operationskatalog

Nod.operation	När
bridge.ncFileToPdf/Png/Html	Standardkonvertering NC-fil → NC-fil
bridge.htmlToOffice	Agentgenererad HTML/MD → office
bridge.fillTemplateSave	Fyll content controls/fält och spara kopia
bridge.compareVersionsPdf	Ny + gammal fil → PDF med ändringar
bridge.extractToPayload	Struktur-JSON till nästa nod
bridge.createAssetLink	Engångs-URL för insert i öppet dokument
nc-office.templates:list|create	Office-mallar i richdocuments
nc-office.template:extractFields|fillFields	Föredra när fileId finns
nc-office.document:direct|public	Engångs redigerings-URL
nc-office.files:convert	Konvertera via Nextcloud (CODE bakom)
convert + extract + transform	Låg nivå när bridge inte räcker
wopi.discovery|capabilities	Hälsokoll och mime→urlsrc
wopi.buildEditor	Bygg editorUrl om token redan finns
wopi.checkFileInfo|getFile	Endast felsökning av WOPI-host

---

5. Recept

A. NC-fil till PDF

inject {ncPath} → collabora-bridge ncFileToPdf → ev. filesharing createShare (OCS :1880)

Kontrollera destNcPath i svaret.

B. Avtalsmall

extractFields eller extract contentcontrol
  → mappa data till fields/transform
  → fillTemplateSave eller template:fillFields med destination
  → valfritt ncFileToPdf
  → document:direct för mänsklig granskning

C. Versionsdiff

{ncPath: ny, compareNcPath: gammal} → compareVersionsPdf
  → skicka PDF via Talk eller Mail-noden i OCS-paketet (:1880)

D. Generera dokument

HTML i payload → htmlToOffice format docx eller pdf. Använd mall via convert templateNcPath om typografi måste följa husmall.

---

6. Vad du inte ska bygga

• En Node-RED-nod som postMessage:ar in i Collabora-iframe (kräver webbsida utanför iframen).
• Dynamisk Python mot share/Scripts/python (kräver paket på CODE och omstart).
• Andra CODE-container i compose (code körs redan med aliasgroup1).
• Portkrock på 1880 mot nextcloud-node-red.

---

7. Felsökning

Symptom	Orsak	Åtgärd
ECONNREFUSED :9980	Sidecar inte på bridge / fel IP	Använd http://172.17.0.2:9980, kontrollera docker network inspect bridge
Tomt convert-svar	CODE storage / fel URL	Anropa intern 9980, inte publik host
WebDAV 401	App-lösen / user	Nytt app-lösen, samma uid som sökvägen
WebDAV 404	Fel sökväg	Leading slash, rätt folder, URL-encode segment
extract tomt	Filter / capability	capabilities, prova documentproperties
WOPI 401/proof	Sessionstoken	Lämna WOPI. Använd WebDAV.
TLS-fel mot NC	Cert i containern	verifyTls=false

---

8. Acceptanskriterier för ett flöde

• capabilities mot CODE returnerar JSON.
• En känd testdokumentsökväg konverteras till PDF under /Dokument/OfficeOut/.
• Originalfilen är oförändrad.
• Fel hamnar i msg.error och nodstatus röd, flödet kraschar inte tyst.
• Inga hemligheter i debug-payload till Talk.

---

9. Installation (Ubuntu)

# /home/ncadmin/nextcloud-collabora-nodered
chmod +x install.sh
./install.sh
# UI: http://192.168.1.26:1881

Överföring från Windows:

./package.sh   # skapar artifacts/nextcloud-collabora-nodered-1.0.0.tar.gz
scp artifacts/*.tar.gz ncadmin@192.168.1.26:/home/ncadmin/
# på servern:
tar -xzf nextcloud-collabora-nodered-1.0.0.tar.gz -C nextcloud-collabora-nodered
cd nextcloud-collabora-nodered && ./install.sh

---

10. Arkitektur

Befintligt (orört):
  nextcloud-ocs 16 noder + nextcloud-config
  container nextcloud-node-red :1880
  CODE "code" :127.0.0.1:9980

Ny yta (det här paketet):
  nc-collab-config
  nc-office          richdocuments OCS
  collabora-convert  /cool/convert-to
  collabora-extract  /cool/extract-document-structure
  collabora-transform /cool/transform-document-structure
  collabora-wopi     discovery, capabilities, editor-URL
  collabora-bridge   agent-pipelines

---

cloud.hannesahlin.se · nextcloud-collabora-nodered v1.0