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 | `http://code:9980` (intern HTTP; fallback `http://<bridge-ip>: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 | `http://code:9980` — intern CODE är **HTTP**; fallback `http://<bridge-ip>:9980` efter `docker network connect bridge nextcloud-node-red` |
| collaboraPublicUrl | `https://docs.domain.name` (publik, browser/WOPI) |
| username + app password | Nextcloud login |

Intern CODE körs utan TLS (`http://`) — publik åtkomst går via reverse proxy (HTTPS).

### createAssetLink (assets)

`collabora-bridge createAssetLink` / `nc-office assets:create` POSTar form-urlencoded
(`path=Dokument/logotyp.png`, relativt användarens filrot) mot
`<nextcloudUrl>/apps/richdocuments/assets`. `200 {url}` = asset-URL skapad;
`404` = filen finns inte i användarens rot (eller fel `nextcloudUrl`) — felet innehåller status + svarskropp.

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