nextcloud-nodered-zammad/README.md

# nextcloud-nodered-zammad

Node-RED nodes for the [Zammad](https://zammad.org/) helpdesk API. Part of the
[nextcloud-nodered](https://kode.hannesahlin.se/n3wk/) suite.

## Package

`node-red-contrib-nextcloud-zammad`

## Nodes

| Node | Type | Purpose |
|------|------|---------|
| `zammad-config` | config | Base URL + Token (or Basic auth) |
| `zammad-api` | function | Generic HTTP caller — any method + endpoint |
| `zammad-ticket` | function | list, search, get, create, update, articles, addArticle, tags, addTag |
| `zammad-user` | function | me, list, search, get, create |
| `zammad-organization` | function | list, search, get, create |

## Installation

### Prerequisites

- An existing [nextcloud-node-red](https://kode.hannesahlin.se/n3wk/nextcloud-nodered-ocs-api) installation.
- A Zammad API token with `ticket.agent` permission.

### Quick install (recommended)

```bash
git clone https://kode.hannesahlin.se/n3wk/nextcloud-nodered-zammad.git
cd nextcloud-nodered-zammad
export NODERED_DIR=/path/to/your/nextcloud-node-red
bash bootstrap-install.sh
cd $NODERED_DIR
docker compose build --no-cache
docker compose up -d
```

### Manual install

```bash
export NODERED_DIR=/path/to/your/nextcloud-node-red
bash integrate-into-nodered.sh
```

The integrate script:
1. Copies all `.js` and `.html` files into `$NODERED_DIR/nodes/`.
2. Copies the package to `$NODERED_DIR/opt/nextcloud-nodes/node-red-contrib-nextcloud-zammad/`.
3. Patches `$NODERED_DIR/entrypoint.sh` to install the nodes on container start.
4. Is idempotent — safe to run multiple times.

## Authentication

| Method | Header | Notes |
|--------|--------|-------|
| Token (preferred) | `Authorization: Token token=<your-token>` | Create token with `ticket.agent` permission |
| Basic | `Authorization: Basic base64(user:pass)` | Zammad username (may differ from email address) |

**Important:** Base URL is the Zammad API v1 URL, e.g. `https://example.com/api/v1/`.

## Node Details

### zammad-ticket

Operations: `list`, `search`, `get`, `create`, `update`, `articles`, `addArticle`, `tags`, `addTag`.

**Create from individual properties:**
```
msg.title      = "Order #12345 – John Doe (Acme Corp)"
msg.customer   = "john.doe@example.com"
msg.body       = product list + address + phone
msg.group      = "Orders"
msg.state      = "open"
msg.priority   = "2 normal"
```

**Create from full JSON payload:**
```
msg.payload = { title: "...", customer: "...", body: "...", group: "..." }
```

**Search syntax (Zammad query):**
```
state.name:open
title:order
customer.email:foo@example.com
```

### zammad-api

Generic HTTP caller. Override config via:
- `msg.method` — GET, POST, PUT, DELETE
- `msg.endpoint` — `/tickets`, `/users/search`, etc.
- `msg.payload` — request body
- `msg.headers` — additional headers

## Vertical Integration Flow: WooCommerce → Zammad → Nextcloud

This example creates a Zammad ticket from a WooCommerce order and organizes
the customer in Nextcloud.

```json
[
    {
        "id": "wc-trigger",
        "type": "inject",
        "name": "New Order",
        "topic": "",
        "payload": "",
        "payloadType": "date",
        "repeat": "",
        "crontab": "",
        "once": true,
        "x": 150, "y": 100
    },
    {
        "id": "wc-extract",
        "type": "function",
        "name": "Extract Order Info",
        "func": "msg.title = 'Order #' + msg.payload.number + ' – ' + msg.payload.billing.first_name + ' ' + msg.payload.billing.last_name;\nmsg.customer = msg.payload.billing.email;\nmsg.body = 'Products:\\n';\nfor (let item of msg.payload.line_items) {\n    msg.body += '- ' + item.name + ' x' + item.quantity + ' (' + msg.payload.currency + ' ' + item.total + ')\\n';\n}\nmsg.body += '\\nTotal: ' + msg.payload.currency + ' ' + msg.payload.total + '\\n';\nmsg.body += 'Address: ' + msg.payload.billing.address_1 + ', ' + msg.payload.billing.city + ' ' + msg.payload.billing.postcode + '\\n';\nmsg.body += 'Phone: ' + msg.payload.billing.phone;\nreturn msg;",
        "outputs": 1,
        "x": 350, "y": 100
    },
    {
        "id": "zammad-create",
        "type": "zammad-ticket",
        "name": "Create Ticket",
        "config": "zammad-config-id",
        "operation": "create",
        "x": 550, "y": 100
    },
    {
        "id": "zammad-tag",
        "type": "zammad-ticket",
        "name": "Add WooCommerce Tag",
        "config": "zammad-config-id",
        "operation": "addTag",
        "x": 750, "y": 100
    }
]
```

**Full flow with Nextcloud OCS nodes** (after Zammad ticket creation):

1. `woocommerce-order` (operation: list, status=processing) → trigger
2. Function node extracts `billing.email`, `billing.first_name`, `billing.last_name`, `billing.company`, `number`, `total`, `currency`, `line_items`
3. `zammad-ticket` (operation: create) — builds ticket from extracted data
4. `zammad-ticket` (operation: addTag) — tag `woocommerce-order`
5. Existing Nextcloud OCS nodes create/update:
   - Customer folder
   - Note or Deck card
   - Optional calendar event
   - Link back to Zammad ticket in ticket body or Nextcloud note

## Integration with Other Packages

- **nextcloud-nodered-woocommerce**: Polls WooCommerce API for new orders and triggers this flow.
- **nextcloud-nodered-ocs-api**: Provides Nextcloud OCS nodes for creating folders, notes, deck cards, etc.
- **nextcloud-nodered-agent**: Agent-based nodes for complex orchestration.

## Credentials Security

- Tokens and passwords are stored **only** in the Node-RED config node (encrypted at rest).
- Never commit credentials to git (`.gitignore` excludes them).
- The config node uses Node-RED's built-in credential encryption.

## License

MIT