# Rainbow Extensions — Custo-Manifest

**Referenz S170 — April 2026**
*Quelle: S170-Roadmap-Präsentation + funktionale Spezifikation Rainbow custo-manifest*

---

## 1. Übersicht

Mit **Rainbow Extensions** (auch *Custo-Manifest* genannt) lässt sich Rainbow Web/Desktop **ohne Code** in das Geschäftsökosystem eines Kunden integrieren — allein durch das Bereitstellen einer JSON-Konfigurationsdatei. Eine Extension kann:

- auf ein Rainbow-Ereignis reagieren (eingehender Anruf, ausgehender Anruf …);
- eine Schaltfläche in einem UI-Bereich hinzufügen (Kontaktliste, Anrufjournal usw.);
- einen Inhalt (Markdown, JSON, Adaptive Card) an einer Rainbow-Stelle anzeigen;
- oder eine Drittanwendung in einem Frame oder Browser öffnen.

### Vorteile

- **No-Code**: nur JSON-Konfiguration
- Erhöht die **Anwenderproduktivität** (Aktionen mit einem Klick, kontextbezogene Daten)
- **Business Enabler** für Partner (CRM-, Ticketing-, Gebäudeautomation-Integrationen …)

### Unterstützte Interaktionsarten

| Typ | Wirkung |
|---|---|
| `commandType: "file"` | Liest eine Datei — lokal auf Desktop oder im Manifest-ZIP auf Web |
| `commandType: "rest"` | HTTP-GET- oder POST-Aufruf an eine API |
| Web öffnen | Öffnet eine URL im Browser |
| Native Ausführung (nur Desktop) | Startet eine lokale `.exe` oder ein Skript |

### Unterstützte Anzeigeformate

- **Markdown** (Standard) — kann auch über `displayJsonField` aus einem Feld einer JSON-Antwort extrahiert werden
- **Adaptive Card** (Template + Daten)

### Lizenzvoraussetzungen

Nur **Event**-Extensions werden mit einer **Essentials**-Lizenz unterstützt.
Alle anderen Extensions erfordern mindestens eine **Business**-Lizenz.

### Web vs. Desktop

Seit **S161** wird das Custo-Manifest schrittweise von Desktop nach Web migriert. Ab **S170** sind alle Extensions sowohl in Rainbow Web als auch in Desktop verfügbar, **mit Ausnahme der lokalen Ausführung von Anwendungen/Skripten** (`.exe` oder Skript starten), die weiterhin Desktop-exklusiv bleibt. Für `commandType: "file"` auf der Web-Seite muss die Datei im Manifest-ZIP enthalten sein.

**Mobile** *(BETA S183)*: In einem ersten Schritt steht `on-main-window-actions` in Rainbow Mobile zur Verfügung — siehe §6.2.

---

## 2. Aufbau der Manifest-Datei

Das Custo-Manifest ist ein JSON-Objekt nach folgendem Schema:

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "<EXTENSION-POINT-KEY>": [
      {
        "name": "...",
        "command": {
          "url": "...",
          "params": "...",
          "commandType": "rest",
          "method": "GET"
        },
        "icon": "...",
        "responseType": "markdown"
      }
    ]
  }
}
```

### Globale Regeln

- `version` muss `"2"` sein.
- `jsonType` muss `"Rainbow-custo-manifest"` sein. Über dieses Feld erkennt Rainbow innerhalb eines ZIP, welche JSON-Datei das Manifest ist.
- Jeder Schlüssel unter `extension-points` ist ein Array (maximal **3 Aktionen** je Extension Point).
- Jede Aktion enthält mindestens einen `name` (außer bei Events, wo er optional ist) und ein gültiges `command`-Objekt.
- `defaultDevicesSupported` *(BETA S183)* — optionales Array im Root des Manifests: die standardmäßig für alle Items anvisierten Rainbow-Clients (siehe §6.2).

---

## 3. Liste der Extension Points

### 3.1 Events — automatische Ereignisse (ohne Anzeige)

| Schlüssel | Wird ausgelöst, wenn … |
|---|---|
| `on-outgoing-pbx-call-actions` | Ein ausgehender Anruf gestartet wird |
| `on-incoming-pbx-call-actions` | Ein eingehender Anruf eintrifft |
| `on-answering-incoming-pbx-call-actions` | Ein eingehender Anruf angenommen wird |
| `on-releasing-incoming-pbx-call-actions` | Ein eingehender Anruf beendet wird |
| `on-makecall-insert-correlator` | Bei jedem makecall — fügt einen Korrelator ein (nur OXE) |

### 3.2 Buttons — klickbare Schaltflächen (mit optionaler Anzeige des Ergebnisses)

| Schlüssel | Position der Schaltfläche |
|---|---|
| `on-incoming-pbx-call-button-actions` | Pop-up des eingehenden Anrufs |
| `on-call-log-list-actions` | Jede Zeile des Anrufjournals |
| `on-contact-list-actions` | Jede Zeile der Kontaktliste |
| `on-contact-detail-actions` | Detailbereich eines Kontakts |
| `on-communication-card-actions` | Leiste des Anrufmanagers |
| `on-bubble-actions` | Eigenschaften-Menü der Bubble |
| `on-bubble-conference-actions` | Menü einer Telefonkonferenz |
| `on-user-menu-actions` | Benutzermenü (Desktop / Web — nicht Teams) |

### 3.3 Displays — automatische Anzeige von Informationen

| Schlüssel | Position |
|---|---|
| `on-incoming-pbx-call-display-actions` | Einfügung im Pop-up des eingehenden Anrufs |
| `on-contact-card-display-actions` | Einfügung im Detailbereich des Kontakts |
| `on-main-widget-display-actions` | Widget im Rainbow-Hauptpanel |
| `on-main-display-actions` | Nachricht in der Teams-Webapp |
| `on-conversation-tab-actions` *(Neu in S179)* | Benutzerdefinierter Tab in der Detailansicht eines Gesprächs (P2P oder Konferenz) |

### 3.4 Frame-Anzeige — Web-Drittanwendung

| Schlüssel | Beschreibung |
|---|---|
| `on-main-window-actions` | Zeigt eine Web-Drittanwendung in einem Rainbow-Frame an. Mit `popout: true` wird die Anwendung in einem Browserfenster geöffnet. |

---

## 4. Hauptfelder einer Aktion

| Feld | Position | Beschreibung |
|---|---|---|
| `name` | root | Angezeigter Text (Titel der Schaltfläche/des Widgets, Menübezeichnung). Je nach EP erforderlich. |
| `icon` / `iconId` | root | Symbol der Schaltfläche (URL, `${custo.path}\…` oder eingebautes Sprite). Pflicht für Icon-Buttons. |
| `tooltip` | root | Tooltip-Text. Optional. |
| `command` | root | Befehlsobjekt (siehe §5). **Immer Pflicht**. |
| `responseType` | root | `"markdown"` (Standard), `"json"` oder `"adaptiveCard"`. |
| Adaptive-Card-Felder | root | `adaptiveCardTemplate`, `adaptiveCardTemplateJsonField`, `adaptiveCardContentJsonField`, `adaptiveCardSubmitUrl` |
| `displayJsonField` | root | Name des Feldes mit dem anzuzeigenden Markdown (wenn die Antwort JSON ist) |
| `redirectUrl` *(BETA S183)* | root | **Anruf-Events und Buttons** — URL-Template, das nach Abschluss des REST-Aufrufs in einem neuen Browser-Fenster geöffnet wird; erfordert `responseType: "json"` (siehe §10.1 und §10.2). |
| `markdownTemplate` *(BETA S183)* | root | **Display- und Button-EPs** — Markdown-Template, das nach Ersetzung der Rainbow-Variablen und von `${response...}` (JSON-Body des REST-Aufrufs) angezeigt wird; erfordert `commandType: "rest"` und `responseType: "json"` (siehe §8.4). |

### Referenztabelle je EP

> Zusammenfassung der Regeln: `name` mandatory/n/a, icon mandatory/n/a, erlaubter commandType, erlaubter responseType usw.

| Extension Point | name | icon | commandType | responseType |
|---|---|---|---|---|
| `on-outgoing-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorisch** mit `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorisch** mit `redirectUrl` — BETA S183) |
| `on-answering-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorisch** mit `redirectUrl` — BETA S183) |
| `on-releasing-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorisch** mit `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-button-actions` | "Button text" | n/a | `rest` | optional |
| `on-contact-list-actions` | n/a | Pflicht | `rest`, `file` | optional |
| `on-contact-detail-actions` | n/a | Pflicht | `rest`, `file` | optional |
| `on-call-log-list-actions` | n/a | Pflicht | `rest`, `file` | optional |
| `on-communication-card-actions` | "menu text" | Pflicht | `rest`, `file` | optional |
| `on-bubble-actions` | "menu text" | Pflicht | `rest`, `file` | optional |
| `on-bubble-conference-actions` | "menu text" | Pflicht | `rest`, `file` | optional |
| `on-incoming-pbx-call-display-actions` | n/a | n/a | `rest`, `file` | **Pflicht** |
| `on-contact-card-display-actions` | n/a | n/a | `rest`, `file` | **Pflicht** |
| `on-main-widget-display-actions` | "widget title" | n/a | `rest`, `file` | **Pflicht** |
| `on-main-display-actions` | n/a | n/a | `rest`, `file` | **Pflicht** |
| `on-conversation-tab-actions` | "Tab-Name" | mandatory | `rest`, `file`, `app` | optional |
| `on-main-window-actions` | "Frame name" | Pflicht | Browse URL (Standard, `commandType` leer) | n/a |
| `on-user-menu-actions` | "menu item title" | n/a | `rest`, `file` | optional |

> `redirectUrl` *(BETA S183)* wird bei den 4 Anruf-Events (§10.1) und bei den 8 Button-EPs (§10.2) akzeptiert. Es erfordert `responseType: "json"` (obligatorisch) — die Kombination mit `"markdown"` oder `"adaptiveCard"` oder das Weglassen von `responseType` ist ungültig (eine Weiterleitung ersetzt die Anzeige).

---

## 5. Das `command`-Objekt

Das `command`-Objekt ist **immer Pflicht** und enthält mindestens eine `url`. Je nach gewähltem `commandType` sind weitere Unterfelder gültig.

```json
"command": {
  "url": "{{server}}/your-endpoint",
  "params": "user=${localUser.email}",
  "commandType": "rest",
  "method": "GET",
  "header": ["Authorization: Bearer TOKEN"],
  "bodyParameters": { "key": "value" }
}
```

| Feld | Verwendung |
|---|---|
| `url` | **Pflicht**. Anwendungs-Pfad, Web-URL, Datei oder REST-API. |
| `params` | Optional. Bei GET nach `?` angehängt oder als URL-Parameter. Variablen erlaubt. |
| `commandType` | Optional. Standard `"rest"`. Werte: `"rest"`, `"file"` (je nach EP). |
| `method` | Optional (nur bei `commandType: "rest"`). Werte: `"GET"`, `"POST"`. |
| `header` | Optional (bei REST). Array aus `"Header-Name: value"`-Strings, als HTTP-Header eingefügt. |
| `bodyParameters` | **Pflicht bei `method: "POST"`**. JSON-Objekt im Body. Variablen erlaubt. |

---

## 6. Sekundäre Felder (je EP)

| Feld | Betroffene EPs | Wirkung |
|---|---|---|
| `AnswerOnClick` | `on-incoming-pbx-call-button-actions` | `true` → führt die Aktion aus UND nimmt den Anruf in einem Klick an |
| `NoShortNumber` (boolean) | Anruf-Events | Löst das Event nicht aus, wenn die Anruferrufnummer eine Kurzwahl ist |
| `RaiseChangeCall` | eingehende Events | `true`, `false`, `"Only"` — Verhalten bei externem Transfer (siehe §6.1) |
| `redirectUrl` *(BETA S183)* | `on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions` sowie die 8 Button-EPs (§3.2) | URL-Template, das nach dem REST-Aufruf in einem neuen Browser-Fenster geöffnet wird. Variablen erlaubt (Rainbow-Variablen und `${response...}`, siehe §7.7). Erfordert `responseType: "json"`. |
| `popout` (boolean) | `on-main-window-actions` | `true` → öffnet die Web-Anwendung in einem Browserfenster (statt im Rainbow-Frame). |
| `alsoForTeams` (boolean) | `on-call-log-list-actions`, `on-main-display-actions` | Zeigt die Extension auch im Teams-Add-in an — **veraltet (deprecated)**, stattdessen `devicesSupported` verwenden (§6.2) |
| `markdownTemplate` *(BETA S183)* | alle EPs, die Markdown anzeigen (Display- und Button-EPs, §8.4) | Markdown-Template, gefüllt mit den Rainbow-Variablen und `${response...}`. Erfordert `commandType: "rest"` und `responseType: "json"`. |
| `devicesSupported` *(BETA S183)* | alle (`"mobile"` und `"teams"` nur bei einigen EPs — siehe §6.2) | Array der Rainbow-Clients, für die das Item gilt: `"web"`, `"desktop"`, `"mobile"`, `"teams"`. Überschreibt `defaultDevicesSupported` für dieses Item. |
| `scope` (array) | `on-conversation-tab-actions` | Gesprächskontexte, in denen der Tab erscheint: `"one_to_one"` (P2P), `"bubble"` (Konferenz). Fehlt → alle Kontexte. |
| `urlConfig` | `on-main-widget-display-actions` | HTTP/HTTPS-URL für die Widget-Konfiguration |
| `firstNameJsonField`, `lastNameJsonField`, `companyJsonField` | NUR `on-incoming-pbx-call-display-actions` | Identifikation des Anrufers (JSON-Antwort) |
| `linkJsonField` *(Neu in S179)* | NUR `on-incoming-pbx-call-display-actions` | JSON-Feld, dessen Wert als **Hyperlink** angezeigt wird, um die Geschäftsanwendung/das CRM des Anrufers zu öffnen (Link-Beschriftung = `name` der Aktion, falls vorhanden, sonst „Link“) |

### 6.1 Werte von `RaiseChangeCall`

| Wert | Verhalten |
|---|---|
| `false` (Standard) | Nur Direktanrufe werden gemeldet |
| `true` | Direkte **UND** weitergeleitete Anrufe |
| `"Only"` | Nur weitergeleitete Anrufe |

### 6.2 Ziel-Clients — `devicesSupported` *(BETA S183)*

> ⚠ **BETA (S183)** — dieses Feature befindet sich in der Beta-Phase und kann sich vor der allgemeinen Verfügbarkeit noch ändern.

Standardmäßig gilt jedes Item für **Rainbow Web und Desktop**. Zwei optionale Attribute legen fest, für welche Rainbow-Clients ein Item gilt:

| Attribut | Position | Rolle |
|---|---|---|
| `defaultDevicesSupported` | Root des Manifests (neben `version`, `jsonType`, `extension-points`) | Standardmäßig anvisierte Clients für **alle** Items des Manifests |
| `devicesSupported` | Root eines Items (gleiche Ebene wie `scope`) | **Überschreibt** `defaultDevicesSupported` nur für dieses Item (vollständige Überschreibung, kein Merge) |

Zulässige Werte für beide: `"web"`, `"desktop"`, `"mobile"`, `"teams"`.

**Auflösungsreihenfolge** für ein gegebenes Item: `devicesSupported` des Items (falls vorhanden) → sonst `defaultDevicesSupported` des Manifests (falls vorhanden) → sonst der integrierte Standardwert `["web", "desktop"]`. Ein Manifest, das keines der beiden Attribute verwendet, verhält sich exakt wie bisher: Es ist keine Migration nötig.

**Verfügbarkeit je Client**

| Client | Gültig bei |
|---|---|
| `"web"`, `"desktop"` | allen Extension Points |
| `"mobile"` | **nur** `on-main-window-actions` (erster Schritt) |
| `"teams"` | `on-call-log-list-actions`, `on-main-display-actions` |

**Regeln**
- Ein **explizit bei einem Item** (`devicesSupported`) angeforderter Client für einen Extension Point außerhalb der obigen Liste wird vom Rainbow Validator als **Warnung** gemeldet.
- Ein Client, der nur von `defaultDevicesSupported` **geerbt** wird und für den Extension Point des Items nicht gilt, wird **stillschweigend ignoriert** — ohne Warnung.
- `alsoForTeams` ist zugunsten von `devicesSupported` **veraltet (deprecated)**, funktioniert aber weiterhin: `alsoForTeams: true` fügt `"teams"` zu den effektiven Clients des Items hinzu. Der Rainbow Validator meldet einen Deprecation-Hinweis.

**Mobile (erster Schritt)**
- Nur **`on-main-window-actions`** ist auf Mobile verfügbar. Auf Mobile **öffnet es die externe Anwendung immer im Browser/Webview des Geräts**: Es gibt auf Mobile kein Einbetten in einen Frame, daher wird das Feld `popout` des Items dort **nicht gelesen** (es steuert weiterhin Frame oder Fenster auf Web/Desktop). Es wird außerdem **ohne Icon** angezeigt: `icon` / `iconId` wird auf Mobile nicht verwendet, daher braucht ein Item, das nur Mobile anspricht (`devicesSupported` ohne `"web"` und `"desktop"`), keines.
- Auf Mobile wird das Manifest **ausschließlich per Cloud-Deployment (Administrator)** geladen; ein lokaler Import wird nicht unterstützt.

**Beispiel**

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "defaultDevicesSupported": ["web", "desktop", "mobile"],
  "extension-points": {
    "on-main-window-actions": [
      {
        "name": "External reporting",
        "iconId": "settings",
        "popout": true,
        "command": { "url": "https://reporting.example.com/" }
      },
      {
        "name": "Internal only",
        "iconId": "settings",
        "popout": true,
        "devicesSupported": ["web", "desktop"],
        "command": { "url": "https://internal.example.com/" }
      }
    ],
    "on-main-display-actions": [
      {
        "devicesSupported": ["web", "desktop", "teams"],
        "command": { "url": "https://announcements.example.com/today" },
        "responseType": "markdown"
      }
    ]
  }
}
```

- *External reporting* erbt den Manifest-Standard und wird daher auf Mobile bereitgestellt.
- *Internal only* überschreibt ihn und ist von Mobile ausgeschlossen.
- Das Item von `on-main-display-actions` ist das Äquivalent im neuen Stil zu `alsoForTeams: true`.

---

## 7. Rainbow-Variablen

**`$Variablen`** werden zur Laufzeit durch ihren tatsächlichen Wert ersetzt. Sie können auftreten in:

- `command.url`
- `command.params`
- `command.bodyParameters`
- `urlConfig`, `adaptiveCardSubmitUrl`
- `redirectUrl` *(BETA S183)* — nur Anruf-Events und Buttons (§10.1, §10.2)
- `markdownTemplate` *(BETA S183)* — die EPs, die Markdown anzeigen (§8.4)
- `${response...}` *(BETA S183)* ist **nur** in `redirectUrl` und `markdownTemplate` verfügbar (§7.7)
- dem **an die Extension zur Anzeige zurückgegebenen Inhalt**: kann ebenfalls Rainbow-Variablen enthalten, die vor der Anzeige ersetzt werden

### 7.1 Syntax

```
${object.attribute}
${object.attribute.regex(pattern)}
${object.attribute.regex(pattern, replacement)}
```

### 7.2 Verfügbare Objekte und Attribute

**Rainbow-Benutzer (ME)**
```
${localUser.firstName}        ${localUser.lastName}
${localUser.email}            ${localUser.canonicalNumber}
${localUser.phoneNumber}      ${localUser.internalNumber}
${localUser.phonePbx}         ${localUser.nickname}
${localUser.loginEmail}       ${localUser.id}          (Cpaas)
```

**Caller (Anrufer)**
```
${caller.firstName}   ${caller.lastName}   ${caller.phoneNumber}
```

**Called (Angerufener)**
```
${called.phoneNumber}
```

**Anruf-Kontext**
```
${call.callId}
${call.globalCallId}      (nur OXE)
${call.correlatorData}
${call.hexCorrelatorData}
```

**Contact (wenn identifiziert)**
```
${contact.firstName}     ${contact.lastName}
${contact.phoneNumber}   ${contact.email}
${contact.company}       ${contact.workNumber}
${contact.mobileNumber}  ${contact.personalNumber}
${contact.personalMobile}
${contact.tags}          (verkettet, durch ',' getrennt)
```

**Bubble (Gesprächsgruppe)**
```
${bubble.ownerEmail}   ${bubble.name}      ${bubble.shareLink}
${bubble.id}           (Cpaas)
${bubble.members}      → JSON {"organizersEmails":[…], "membersEmails":[…]}
                         **Nur mit einem REST-Aufruf nutzbar**
```

**Time (Zeitstempel)**
```
${time}             vollständiges Datum/Uhrzeit
${time.year}        ${time.month}
${time.hour}        ${time.minute}    ${time.second}    ${time.millisec}
${time.hex}         4 Bytes hex für Unix Epoch (nur mit hexCorrelatorData)
```

### 7.3 Kompatibilität je EP

Jeder EP erlaubt eine Teilmenge an Objekten. Zusammenfassung:

| EP | Erlaubte Variablenobjekte |
|---|---|
| Events ausgehender Anrufe | `localUser`, `called`, `call`, `contact` |
| Events eingehender Anrufe (incoming/answering/releasing) | `localUser`, `caller`, `called`, `call`, `contact` |
| Automatische OXE-Korrelator-Einfügung | `localUser`, `called` |
| Icon-Buttons (contact-list, contact-detail, call-log-list, contact-card-display) | `localUser`, `contact` |
| Anruf-Buttons (communication-card, incoming-button, incoming-display) | `localUser`, `caller`, `called`, `call`, `contact` |
| Bubbles | `localUser`, `bubble` |
| Gesprächs-Tab | `localUser`, `contact`, `bubble` |
| Display-Widget / main-display / main-window / user-menu | `localUser` |

### 7.4 Modifier `regex`

Wendet einen regulären Ausdruck auf den Variablenwert **vor der Ersetzung** an. ⚠ Rainbow entfernt **keine** Leerzeichen um das Komma zwischen `pattern` und `replacement` — ein Leerzeichen nach dem Komma landet wörtlich im Ergebnis (live bestätigt am 2026-10-02, z. B. erzeugt `regex(@.*$, @example.com)` `"name @example.com"` mit einem überflüssigen Leerzeichen). Kein Leerzeichen um das Komma verwenden:

```jsonc
// +33 oder +1 durch 0 ersetzen (Rufnummernormalisierung)
"params": "pbx=${localUser.phonePbx.regex(^\\+33|^\\+1,0)}"

// E-Mail-Domain ersetzen
"params": "byEmail=${localUser.email.regex(alcatel.com,al-enterprise.com)}"

// Die letzten 9 Ziffern behalten (regex ohne Ersetzung = Extraktion)
"params": "${called.phoneNumber.regex(.{0,9}$)}"
```

### 7.5 Variable `${time}` — Zeitstempel

Spezielle Zeitstempel-Variable, verfügbar für **alle EPs**. Wird zum Zeitpunkt der Aktionsausführung ersetzt.

| Variable | Wert | Format / Kommentar |
|---|---|---|
| `${time}` | Vollständige Datum-Uhrzeit | `YYYY/MM/DD HH:MM:SS`, z. B. `2026-05-18 15:30:45` (kein ISO 8601, keine Millisekunden — live bestätigt am 2026-10-02) |
| `${time.year}` | Jahr | 4 Ziffern, z. B. `2026` |
| `${time.month}` | Monat | 2 Ziffern, `01`–`12` |
| `${time.day}` | Tag des Monats | 2 Ziffern, `01`–`31` |
| `${time.hour}` | Stunde | 2 Ziffern, `00`–`23` |
| `${time.minute}` | Minute | 2 Ziffern, `00`–`59` |
| `${time.second}` | Sekunde | 2 Ziffern, `00`–`59` |
| `${time.millisec}` | Millisekunden | 3 Ziffern, `000`–`999` |
| `${time.hex}` | Unix Epoch in Hex (4 Bytes) | **Reserviert für `hexCorrelatorData`** — nicht in beliebigen Strings oder JSON verwenden |

#### Beispiele

```jsonc
// Log-Identifier erzeugen
"params": "logId=${time.year}-${time.month}-${time.day}_${time.hour}${time.minute}${time.second}"
// → logId=2026-05-18_153045

// POST-Body mit vollständigem Zeitstempel
"bodyParameters": { "ts": "${time}", "user": "${localUser.loginEmail}" }

// OXE-Korrelator mit Hex-Zeitstempel (nur on-makecall-insert-correlator)
"hexCorrelatorData": "O-${localUser.nickname}-${time.hex}"
```

### 7.6 Lokale Ressourcen — `${custo.path}`

Um ein Manifest mit lokalen Dateien (Icons, statische Inhalte) auszuliefern:

1. Jede Ressource per `${custo.path}\\dateiname.ext` referenzieren
2. Alles in ein **ZIP** packen:
   - `custo-manifest.json` im Root
   - die Ressourcendateien daneben

Beispiel:
```json
{
  "icon": "${custo.path}\\basketball.png",
  "command": {
    "commandType": "file",
    "url": "${custo.path}\\FileDisplay.txt"
  },
  "responseType": "markdown"
}
```

Das ZIP muss enthalten: `custo-manifest.json`, `basketball.png`, `FileDisplay.txt`.

#### Identifizierung des Manifests im ZIP

Rainbow identifiziert die Manifest-Datei in folgender Priorität:

1. **`custo-manifest.json`** — Datei mit genau diesem Namen im Root des ZIP
2. **Andernfalls** die **erste `.json`-Datei** im ZIP, die `"jsonType": "Rainbow-custo-manifest"` enthält

Wenn keine Datei eines der beiden Kriterien erfüllt, schlägt der ZIP-Import fehl.

> 💡 Um eine eindeutige Erkennung zu gewährleisten, benennen Sie Ihr Manifest `custo-manifest.json` und platzieren Sie es im Root des ZIP.

---


---

### 7.7 Die Variable `${response}` — REST-Antwort *(BETA S183)*

`${response}` repräsentiert den **JSON-Body, den der REST-Aufruf derselben Aktion zurückgibt**. Sie ist in `redirectUrl` der Anruf-Events (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) und der 8 Button-EPs verfügbar — siehe §10.1 und §10.2 — sowie in **`markdownTemplate`** der EPs, die Markdown anzeigen — siehe §8.4. In keinem anderen Feld ist sie verfügbar.

```
${response.contactId}               Feld der Antwort
${response.data.contact.id}         verschachtelter Pfad
${response[0].contactId}            Array-Index
```

**Tolerante Auflösung.** Manche REST-APIs liefern bei einem Treffer ein einzelnes Objekt und bei mehreren Treffern ein Array. Beide Syntaxen funktionieren daher unabhängig von der Form der Antwort:

| Syntax | Antwort ist ein Objekt | Antwort ist ein Array |
|---|---|---|
| `${response.contactId}` | das Feld des Objekts | das Feld des **ersten Elements** |
| `${response[0].contactId}` | das Objekt selbst wird als erstes Element betrachtet | das Feld des ersten Elements |

- Jeder andere Index auf einem Objekt (`${response[1]...}`) gilt als fehlendes Feld.
- Ein leeres Array (`[]`) gilt als fehlendes Feld.

Fehlt das angesprochene Feld, passiert nichts (siehe §10.1, *Fehlerbehandlung*).

---

## 8. Text-/Markdown-Anzeige

Wenn eine Extension eine Antwort anzeigen kann und `responseType: "markdown"` (oder fehlt — Standardwert), wird der Antwortinhalt als **Markdown-Text** in einem Rainbow-Popup gerendert. **Emojis** werden ebenfalls unterstützt (natives Unicode, direkt eingefügt — `:smile:`-Shortcodes werden **nicht** interpretiert, sie werden unverändert angezeigt).

### 8.1 Gängige Markdown-Syntax

Rainbow unterstützt eine Teilmenge des Standard-Markdown. Die nützlichsten Elemente in einem Extension-Popup:

| Syntax | Wirkung |
|---|---|
| `**fett**` | **fett** |
| `*kursiv*` | *kursiv* |
| `# Titel 1`, `## Titel 2`, `### Titel 3` | hierarchische Titel |
| `- Element` oder `* Element` | Aufzählung |
| `1. Element` | nummerierte Liste |
| `[Label](https://url.com)` | anklickbarer Link |
| ```` ```\nCode-Block\n``` ```` | Code-Block |
| `---` | horizontale Linie |
| `\| Spalte 1 \| Spalte 2 \|` | Tabelle (mit Trennzeile `\|---\|---\|`) |
| 🎉 ✅ 📞 | Unicode-Emojis (direkt einfügen) |

#### Beispiel — angereichertes Markdown aus REST-Ausgabe

Eine API liefert:

```markdown
## Kontakt identifiziert 📇

**Marie Curie** — *Université Paris-Sorbonne*

| Feld | Wert |
|---|---|
| Telefon | +33 1 42 34 56 78 |
| E-Mail | [marie.curie@example.com](mailto:marie.curie@example.com) |
| Status | ✅ Aktiver Kunde |

> 💡 Ein Klick auf die E-Mail öffnet Ihr Mail-Programm.
```

Das Rainbow-Popup zeigt den Titel, die formatierte Tabelle, die anklickbaren Links und die Emojis.

#### Beispiel — Demo der unterstützten Syntax (lokale Datei)

Manifest:

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-contact-card-display-actions": [
      {
        "name": "SupportedMarkdown",
        "command": {
          "url": "${custo.path}\\SupportedMarkdown.txt",
          "commandType": "file"
        },
        "responseType": "markdown"
      }
    ]
  }
}
```

Inhalt der Datei `SupportedMarkdown.txt` (im ZIP neben dem Manifest geliefert):

```markdown
<!-- Comment: Supported markdown -->
---
**bold text**
*italic text*
# Titel 1,
## Titel 2,
### Titel 3
* Element 1️⃣
* Element 2️⃣
* Element 3️⃣
1. Element 1️⃣
2. Element 2️⃣
3. Element 3️⃣
---
<!-- Tables -->
| Table   |  Link |
|---------- |:------: |
| Rainbow | *[Rainbow](https://support.openrainbow.com/hc/en-us/articles/4706281095058)*|
| Teams | *[Rainbow Teams](https://support.openrainbow.com/hc/en-us/articles/11949840558098)*|
___
```

Darstellung in Rainbow:

![Markdown-Rendering in Rainbow](images/markdown.png)

### 8.2 Aus JSON-Antwort extrahiertes Markdown

Wenn `responseType: "json"` **und** `displayJsonField` definiert ist, interpretiert Rainbow die Antwort als JSON, extrahiert den Wert des durch `displayJsonField` bezeichneten Feldes und zeigt ihn als Text/Markdown an.

Nützlich, wenn der Server bereits ein strukturiertes JSON liefert (z. B. einen Business-API-Payload), in dem das anzuzeigende Markdown in einem Feld steckt.

#### Beispiel — Markdown in einem JSON-Feld

Manifest:

```json
"on-contact-list-actions": [{
  "name": "Quick info",
  "icon": "${custo.path}\\info.png",
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/info",
    "params": "email=${contact.email}"
  },
  "responseType": "json",
  "displayJsonField": "display"
}]
```

API-Antwort:

```json
{
  "id": 12345,
  "status": "active",
  "display": "## ${contact.firstName} ${contact.lastName}\n\nKunde seit **2019**\n\n- ✉️ contact@example.com\n- 📞 +33 1 42 34 56 78\n- 🎫 [Ticket öffnen](https://crm.example.com/12345)"
}
```

Rainbow extrahiert `display`, ersetzt die Variablen `${contact.*}` und zeigt das Ergebnis im Popup an.

### 8.3 Anzeige über Standardausgabe (nur Desktop)

Wenn ein EP Markdown-Anzeige als Rückgabe unterstützt, kann die **Standardausgabe** eines Skripts oder Programms erfasst werden:

```json
"command": {
  "commandType": "file",
  "url": "${custo.path}\\display.bat"
},
"responseType": "markdown"
```

Der vom Skript auf `stdout` ausgegebene Inhalt wird in einem Rainbow-Popup angezeigt. Ideal für einfache Integrationen oder Prototyping ohne REST-Infrastruktur.

> ⚠ **Nur Rainbow Desktop.** Auf Web kann das Skript nicht lokal ausgeführt werden; dieser Modus steht dort nicht zur Verfügung.

### 8.4 Markdown-Template — `markdownTemplate` *(BETA S183)*

> ⚠ **BETA (S183)** — diese Funktion befindet sich in der Beta-Phase und kann sich vor der allgemeinen Verfügbarkeit noch ändern.

Bisher konnte das Ergebnis eines REST-Aufrufs als **ein Feld der JSON-Antwort** (`displayJsonField`, §8.2) angezeigt oder mit einer **Adaptive Card** (§9) gestaltet werden. `markdownTemplate` fügt eine dritte Option hinzu: ein **im Manifest deklariertes Markdown-Template**, das mit den Rainbow-Variablen und den Feldern der JSON-Antwort des REST-Aufrufs gefüllt wird.

**Regeln**
- `command` ist vom Typ **`rest`** und die Antwort vom Typ **JSON** (`responseType: "json"`) — beides ist mit `markdownTemplate` **obligatorisch**.
- `markdownTemplate` (string, Markdown) steht im Root der Aktion. Sein Text wird nach einer **Variablenersetzung** angezeigt: die üblichen **Rainbow-Variablen** des EP (§7) und die Variable **`${response}`** (§7.7), d. h. der JSON-Body, den der REST-Aufruf derselben Aktion zurückgibt (`${response.contactId}`, `${response.data.contact.id}`, `${response[0].contactId}`; tolerante Objekt-/Array-Auflösung, §7.7).
- Die ersetzten Werte werden **unverändert** eingefügt: keine URL-Kodierung und kein Escaping von Markdown-Zeichen.
- **Ausführungsreihenfolge** — wenn mehrere dieser Elemente in derselben Aktion definiert sind, verarbeitet Rainbow sie in dieser Reihenfolge, und das erste zutreffende wird ausgeführt: `redirectUrl`, dann `markdownTemplate`, dann `displayJsonField`, dann Adaptive Card. Insbesondere gilt: Wenn ein `redirectUrl` vorhanden ist und eine gültige REST-Antwort zurückkommt, wird die Weiterleitung ausgeführt und `markdownTemplate` wird **nicht** angezeigt; wenn **kein `redirectUrl`** vorhanden ist oder dieser **leer ist, weil die REST-Antwort leer ist**, wird der Inhalt von `markdownTemplate` angezeigt.
- **Fehlerbehandlung** — wenn der REST-Aufruf fehlschlägt (Timeout, HTTP-Fehler), wenn die Antwort kein gültiges JSON ist oder wenn ein referenziertes Feld fehlt: **wird nichts angezeigt**.
- Ein Client, der `markdownTemplate` nicht kennt, ignoriert das Feld (kein Fehler).

**Verfügbar bei** allen Extension Points, die Markdown anzeigen:
- Display: `on-incoming-pbx-call-display-actions`, `on-contact-card-display-actions`, `on-main-widget-display-actions`, `on-main-display-actions`, `on-conversation-tab-actions`;
- Buttons, die ein Ergebnis anzeigen: `on-incoming-pbx-call-button-actions`, `on-contact-list-actions`, `on-contact-detail-actions`, `on-call-log-list-actions`, `on-communication-card-actions`, `on-bubble-actions`, `on-bubble-conference-actions`, `on-user-menu-actions`.

Die Anruf-Events zeigen nichts an und sind nicht betroffen.

**Beispiel — aus der Antwort aufgebaute Karte**

```json
"on-incoming-pbx-call-display-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "markdownTemplate": "## ${response.firstName} ${response.lastName}\n🏢 ${response.company}\n📞 ${caller.phoneNumber}"
}]
```

Bei einer Antwort `{"firstName":"Jane","lastName":"Doe","company":"ACME"}` zeigt das Pop-up die Überschrift *Jane Doe* gefolgt vom Unternehmen und der Telefonnummer an.


---

## 9. Adaptive Cards

**Adaptive Card** ist ein von **Microsoft** definierter offener Standard, um reichhaltige Inhalte (Text, Listen, Formulare, Buttons, Bilder) in einem portablen JSON-Format darzustellen, das von jeder integrierenden Anwendung konsistent gerendert wird.

📖 [Microsoft Adaptive Card-Referenz](https://adaptivecards.io/explorer/) — offizielle Dokumentation und Beispielbibliothek.

Das Adaptive-Card-Modell trennt zwei Dinge:
- ein **Template** (Layout), in JSON beschrieben — visuelle Struktur mit `${...}`-Variablen;
- **dynamische Daten** ebenfalls in JSON — die die Template-Variablen befüllen.

Rainbow übernimmt diese Trennung und rendert die Karte im Client (Desktop oder Web).
- Das **Template** kann im Manifest vordefiniert sein (`adaptiveCardTemplate`) oder in der JSON-Antwort eines REST-Aufrufs enthalten sein (Extraktion über `adaptiveCardTemplateJsonField`).
- Die **Daten** können ebenfalls im Manifest, in einer separaten Datei (nützlich zum Testen) liegen, stammen aber meist aus einer Business-REST-Antwort.

Vier Kombinationen werden auf Rainbow Desktop **und** Web unterstützt:

| Modus | Template | Content |
|---|---|---|
| **Alles im Manifest** | inline | inline |
| **Template im Manifest** | inline | in einer Datei |
| **Template im Manifest + REST-Daten** | inline | von einem REST-Aufruf zurückgegeben |
| **Alles über REST** | per REST zurückgegeben | per REST zurückgegeben |

### Betroffene Felder (im Root der Aktion)

| Feld | Rolle |
|---|---|
| `adaptiveCardTemplate` | Inline-JSON-Template im Manifest |
| `adaptiveCardTemplateJsonField` | Name des REST-Antwortfeldes, das das Template enthält |
| `adaptiveCardContentJsonField` | Name des REST-Antwortfeldes, das die Daten enthält. **Wenn leer oder fehlend, werden die Variablen direkt im Root des JSON-Antwortobjekts gesucht.** |
| `adaptiveCardSubmitUrl` | REST-URL, die bei einem `Action.Submit` der Karte per POST aufgerufen wird |

### Unterstützte Aktionen in einer Adaptive Card

- **`Action.OpenUrl`** — öffnet eine URL im Browser.
- **`Action.Submit`** — Rainbow wandelt diese Aktion in einen **POST** an die in `adaptiveCardSubmitUrl` definierte URL um. Der Request-Body enthält das `data`-Objekt der Aktion (zuzüglich der Werte etwaiger `Input.*`).
  - Wenn die REST-Antwort **aktualisierte Daten** zurückliefert (gleiches Format wie die Anfangsantwort oder ein neues Template), **aktualisiert** Rainbow die Karte automatisch mit den neuen Werten.

### Unterstützte Adaptive-Card-Tags (indikativ)

Referenztabelle zur Unterstützung der wichtigsten Adaptive-Card-Elemente in Rainbow. Der Status kann sich zwischen Versionen ändern — für eine präzise Prüfung mit Ihrer aktuellen Rainbow-Version nutzen Sie das in RainbowCustoServer integrierte **Adaptive Card**-Testwerkzeug.

| AC-Element | Unterstützung | Hinweise |
|---|:---:|---|
| `TextBlock` | ✅ | Basis-Textelement, reichhaltige Stiloptionen |
| `Image` | ✅ | http(s)-URL, Data-URI |
| `ColumnSet` / `Column` | ✅ | Spaltenlayout |
| `Container` | ✅ | Gruppierung, Hintergrundstile |
| `FactSet` | ✅ | Schlüssel-/Wert-Tabelle |
| `ImageSet` | ✅ | Bildergalerie |
| `ActionSet` | ✅ | Inline-Buttongruppe |
| `RichTextBlock` / `TextRun` | ✅ | Mehrfach-gestylter Text in einer Zeile |
| `Table` | ✅ | strukturierte Tabelle (AC 1.5+) |
| `Input.Text` | ✅ | Texteingabe |
| `Input.Number` | ✅ | Zahleneingabe |
| `Input.Date` | ✅ | Datumsauswahl |
| `Input.Time` | ✅ | Zeitauswahl |
| `Input.Toggle` | ✅ | Checkbox |
| `Input.ChoiceSet` | ✅ | Dropdown / Radio / Mehrfachauswahl |
| `Action.OpenUrl` | ✅ | öffnet URL im Browser |
| `Action.Submit` | ✅ | POST an `adaptiveCardSubmitUrl` |
| `Action.ToggleVisibility` | ✅ | Elemente dynamisch ein-/ausblenden |
| `Action.ShowCard` | ✅ | Inline-Subkarte |
| `Media` | ⚠️ | begrenztes Video-/Audio-Rendering |
| `Carousel` | ⚠️ | Navigation zwischen Karten — Rendering-Grenzen (AC 1.4+) |
| `Badge` | ❌ | AC 1.6+ — nicht unterstützt |
| `CodeBlock` | ❌ | AC 1.6+ — nicht unterstützt |
| `Icon` | ❌ | AC 1.6+ — nicht unterstützt |
| `CompoundButton` | ❌ | AC 1.6+ — nicht unterstützt |
| `ProgressRing` | ❌ | AC 1.6+ — nicht unterstützt |
| `ProgressBar` | ❌ | AC 1.6+ — nicht unterstützt |
| `Action.Popover` | ❌ | AC 1.6+ — nicht unterstützt |
| `Input.Rating` | ❌ | AC 1.6+ — nicht unterstützt |
| `Chart.*` (Donut, Line, Bar …) | ❌ | Chart-Erweiterungen nicht unterstützt |

Legende: ✅ unterstützt · ⚠️ unterstützt mit Einschränkungen · ❌ nicht unterstützt

### Beispiel: Widget mit Template und Daten aus REST

```json
"on-main-widget-display-actions": [{
  "name": "Domotic",
  "command": {
    "method": "GET",
    "commandType": "rest",
    "url": "http://localhost:3300/domotic/api/card"
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField": "data",
  "adaptiveCardSubmitUrl": "http://localhost:3300/domotic/card-submit"
}]
```

Erwartete REST-Antwort:
```json
{
  "card": { "type": "AdaptiveCard", "body": [ … ] },
  "data": { "lumiere": { "status": "on" }, … }
}
```

Darstellung in Rainbow:

![Adaptive-Card-Rendering in Rainbow](images/adaptive.png)

---

## 10. Referenz nach Extension-Typ

Dieser Abschnitt gruppiert die Extension Points nach funktionaler Familie. Vier Familien: **Telefonie-Events**, **Buttons**, **Display**, **Anwendung**.

---

### 10.1 Telefonie-Events

![Rainbow Telefonie-Events](images/telephony-events.svg)

**Prinzip**: keine eigene UI. Diese Extensions lösen automatisch eine Aktion aus (REST-Aufruf, lokale Ausführung, URL-Öffnung), wenn ein Telefonieereignis eintritt. Typische Anwendungsfälle: Anrufprotokollierung in einem ERP, Auslösen eines CRM-Workflows, Präsenz-Update in einem Business-System.

**Extension Points**:

| Schlüssel | Auslöser |
|---|---|
| `on-outgoing-pbx-call-actions` | Ein ausgehender Anruf wird initiiert |
| `on-incoming-pbx-call-actions` | Ein eingehender Anruf trifft ein |
| `on-answering-incoming-pbx-call-actions` | Ein eingehender Anruf wird angenommen |
| `on-releasing-incoming-pbx-call-actions` | Ein eingehender Anruf wird beendet |
| `on-makecall-insert-correlator` | Bei jedem makecall — fügt einen Korrelator ein (nur OXE) |

**Lizenzvoraussetzung**: Essentials (Events sind die einzige in dieser Lizenz unterstützte Familie).

#### Felder (Standardaktion)

| Feld | Position | Typ | Pflicht | Werte / Einschränkungen |
|---|---|---|---|---|
| `command` | root | object | **JA** | command-Objekt |
| `command.url` | command | string | **JA** | HTTP(S)-URL oder `{{server}}/…` |
| `command.params` | command | string | nein | URL-Parameter (nach `?` angehängt). Variablen erlaubt. |
| `command.commandType` | command | string | nein | `"rest"` (Standard, einziger unterstützter Wert für Events) |
| `command.method` | command | string | nein | `"GET"` (Standard) oder `"POST"` |
| `command.header` | command | array | nein | Array aus `"Header-Name: value"`-Strings |
| `command.bodyParameters` | command | object | **JA bei `method: "POST"`** | JSON im Body. Variablen erlaubt. |
| `NoShortNumber` | root | boolean | nein | Bei `true` wird das Event nicht ausgelöst, wenn der Anrufer eine Kurzwahl ist |
| `RaiseChangeCall` | root | `true` \| `false` \| `"Only"` | nein | (nur incoming-Events) — steuert die Propagation bei externem Transfer (§6.1) |
| `redirectUrl` *(BETA S183)* | root | string | nein | URL-Template, das nach dem REST-Aufruf in einem neuen Browser-Fenster geöffnet wird (siehe unten). Erfordert `responseType: "json"`. |
| `responseType` | root | `"json"` | **JA, wenn `redirectUrl`** | Obligatorisch mit `redirectUrl`. Andernfalls kein `responseType` bei Events. |

**Hinweis**:
- **Kein `name`, `icon`** — ein Event ist auf der Rainbow-UI lautlos
- **Kein `responseType`**, außer `"json"`, das zusammen mit `redirectUrl` *(BETA S183)* **obligatorisch** ist — siehe unten
- `commandType: "file"` nicht unterstützt

**Erlaubte Rainbow-Variablen je EP**

| EP | `localUser` | `caller` | `called` | `call` | `contact` *¹ | `time` |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `on-outgoing-pbx-call-actions` | ✓ | — | ✓ | ✓ | ✓ | ✓ |
| `on-incoming-pbx-call-actions` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `on-answering-incoming-pbx-call-actions` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `on-releasing-incoming-pbx-call-actions` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `on-makecall-insert-correlator` | ✓ | — | nur `phoneNumber` | — | — | ✓ |

*¹ — `${contact.*}` wird nur aufgelöst, **wenn ein Kontakt identifiziert wurde** (von Rainbow erkannte Nummer). Andernfalls sind `${contact.*}`-Variablen bei der Ersetzung leer.*

*Nur in `redirectUrl` (BETA S183) ist zusätzlich `${response...}` (JSON-Body des REST-Aufrufs derselben Aktion) verfügbar — siehe §7.7.*

#### Weiterleitung nach einem REST-Aufruf — `redirectUrl` *(BETA S183)*

**Prinzip**: einen REST-Aufruf mit dem Öffnen einer URL verketten, die aus dessen JSON-Antwort aufgebaut wird — typischerweise ein **CTI-Screen-Pop**: 1) eine REST-API wird mit der Rufnummer des Anrufers abgefragt, um einen Bezeichner zu erhalten (z. B. `contactId`), 2) eine mit diesem Bezeichner angereicherte „Screen-Pop"-Seite wird geöffnet. Die gesamte Kette wird im Manifest deklariert, ohne zwischengeschaltetes Backend.

Verfügbar bei den vier Anruf-Events (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) **und bei den Button-Extension-Points** (§10.2).

**Regeln**:
- **`redirectUrl`** (string, Template): wenn vorhanden, wird eine Weiterleitung ausgeführt. `responseType: "json"` ist dabei **obligatorisch** (die REST-Antwort wird als JSON gelesen, um `${response}` zu speisen); es ist kein neuer `responseType`-Wert.
- Rainbow führt lediglich eine **Variablenersetzung** in `redirectUrl` durch, sei es eine Rainbow-Variable (`${caller.phoneNumber}`, …) oder eine `${response...}`-Variable (§7.7). Zwei Verwendungen:
  - **die Antwort liefert einen Teil des Ziels**: `"redirectUrl": "http://server/screenPop?id=${response.contactId}"`;
  - **die Antwort liefert das gesamte Ziel**: `"redirectUrl": "${response.url}"` — das Feld `url` der Antwort ist die zu öffnende Seite.
- Der ersetzte Wert wird **automatisch URL-kodiert** (gleicher Mechanismus wie bei den anderen Manifest-Variablen).
- Die URL wird **immer** in einem **neuen Browser-Fenster** (Popup) geöffnet.
- **Fehlerbehandlung** — wenn der REST-Aufruf fehlschlägt (Timeout, HTTP-Fehler), wenn das angesprochene Feld in der Antwort fehlt oder wenn die Antwort kein gültiges JSON ist: **passiert nichts** (kein Popup, keine Fehlermeldung für den Benutzer); nur eine clientseitige Log-Spur wird zur Diagnose geschrieben.
- Ein Client, der `redirectUrl` nicht kennt, ignoriert das Feld (kein Fehler).

> ⚠ **BETA (S183)** — diese Funktion befindet sich in der Beta-Phase und kann sich vor der allgemeinen Verfügbarkeit noch ändern.

**Beispiel 1 — die Antwort liefert einen Teil des Ziels**

```json
"on-incoming-pbx-call-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "redirectUrl": "http://server/screenPop?id=${response.contactId}"
}]
```

**Beispiel 2 — die Antwort liefert das gesamte Ziel (Antwort `{"url":"https://crm.example.com/contact/42"}`)**

```json
"on-incoming-pbx-call-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "redirectUrl": "${response.url}"
}]
```

**Beispiel 3 — Rainbow-Variable und Antwortvariable kombiniert; die API antwortet mit einem Objekt *oder* einem Array (tolerante Auflösung, §7.7)**

```json
"on-answering-incoming-pbx-call-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "redirectUrl": "http://server/screenPop?id=${response[0].contactId}&user=${localUser.loginEmail}"
}]
```

#### Auflösung der Anrufer-ID
Die **Auflösung der Anruferidentität** (Name/Vorname/Firma) und der **anklickbare Link** zur CRM-Karte erfolgen **nicht** über die Telefonie-Events (die auf der UI lautlos sind), sondern über das Display **`on-incoming-pbx-call-display-actions`** — siehe **§10.3.1**.

#### Sondersch ema — `on-makecall-insert-correlator` (OXE)

Dieser EP folgt nicht dem Standard-`command`-Schema. Er fügt bei jedem makecall einen Korrelator (ASCII oder Hex) ein:

```json
"on-makecall-insert-correlator": [{
  "correlatorData":    "string-ascii-32-chars-max"
  // ODER
  "hexCorrelatorData": "O-${localUser.nickname}-${called.phoneNumber.regex(.{8}$)}-${time.hex}"
}]
```

Maximal 32 Zeichen. Nur ein Typ (`correlatorData` **oder** `hexCorrelatorData`) gleichzeitig.

#### Beispiel 1 — Protokollierung eines eingehenden Anrufs (POST mit Body)

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-incoming-pbx-call-actions": [{
      "command": {
        "commandType": "rest",
        "method": "POST",
        "url": "https://crm.example.com/calls/log",
        "header": [
          "Content-Type: application/json",
          "Authorization: Bearer eyJhbGc...",
          "X-Rainbow-User: ${localUser.loginEmail}"
        ],
        "bodyParameters": {
          "type":      "incoming",
          "from":      "${caller.phoneNumber}",
          "to":        "${localUser.phoneNumber}",
          "user":      "${localUser.loginEmail}",
          "timestamp": "${time}"
        }
      }
    }]
  }
}
```

> ℹ Die **Auflösung der Anrufer-ID** (Name/Vorname/Firma + CRM-Link) ist **kein** Event: sie wird über `on-incoming-pbx-call-display-actions` deklariert — siehe **§10.3.1**.

#### Beispiel 2 — Web-App-Popup, Filterung von Kurzwahlen

```json
"on-outgoing-pbx-call-actions": [{
  "NoShortNumber": true,
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://reporting.example.com/outgoing",
    "params": "to=${called.phoneNumber}"
  }
}]
```

Das Event wird für interne Anrufe (kurze Durchwahlen) nicht ausgelöst.

#### Beispiel 3 — Ausführung eines lokalen Skripts bei Annahme

> **⚠ Nur Rainbow Desktop** — das Ausführen lokaler Skripte oder Anwendungen (`.exe`, `.bat` usw.) wird von Rainbow Web nicht unterstützt. Auf Web wird dieses Event ignoriert.

```json
{
  "version": "2",
  "extension-points": {
    "on-answering-incoming-pbx-call-actions": [{
      "command": {
        "commandType": "file",
        "url": "C:\\Tools\\log-call.bat",
        "params": "from=${caller.phoneNumber} called=${localUser.phonePbx}"
      }
    }]
  }
}
```

Das Skript `log-call.bat` wird lokal ausgeführt, wenn der Benutzer den Anruf annimmt. Rainbow-Variablen werden in `params` vor dem Kommandozeilenaufruf ersetzt.

#### Beispiel 4 — OXE-Korrelator bei makecall

> **⚠ Nur OXE** — dieser EP funktioniert ausschließlich auf einer Alcatel-Lucent OXE-Anlage.

Um jedem über makecall gestarteten ausgehenden Anruf einen Korrelator zuzuweisen:

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-makecall-insert-correlator": [{
      "hexCorrelatorData": "O-${localUser.nickname}-${called.phoneNumber.regex(.{8}$)}-${time.hex}"
    }]
  }
}
```

**Regeln**:
- Entweder `correlatorData` (ASCII) **ODER** `hexCorrelatorData` (Hex) — **nur ein Typ erlaubt**
- Maximal **32 Zeichen**
- Erlaubte Variablen: `${localUser.*}`, `${called.phoneNumber}`, `${time.*}`
- `${time.hex}` ist ein spezielles 4-Byte-Format — nur mit `hexCorrelatorData`

---

### 10.2 Buttons

![Buttons in der Rainbow-UI](images/buttons.png)

**Prinzip**: Ein Icon-Button wird an einer bestimmten Stelle der Rainbow-UI eingefügt. Beim Klick wird eine Aktion ausgeführt und optional das Ergebnis in einem Popup angezeigt (Markdown oder Adaptive Card). Maximal 3 Buttons je EP.

**Extension Points**:

| Schlüssel | Position der Schaltfläche |
|---|---|
| `on-incoming-pbx-call-button-actions` | Pop-up des eingehenden Anrufs |
| `on-call-log-list-actions` | Jede Zeile des Anrufjournals |
| `on-contact-list-actions` | Jede Zeile der Kontaktliste |
| `on-contact-detail-actions` | Kontakt-Detail-Panel |
| `on-communication-card-actions` | Leiste des Anrufmanagers (Menü) |
| `on-bubble-actions` | Eigenschaften-Menü einer Bubble |
| `on-bubble-conference-actions` | Menü einer Telefonkonferenz |
| `on-user-menu-actions` | Benutzermenü (Desktop / Web — nicht Teams) |

**Lizenzvoraussetzung**: mindestens Business.

#### Felder (alle Buttons)

| Feld | Position | Typ | Pflicht | Werte / Einschränkungen |
|---|---|---|---|---|
| `name` | root | string | siehe Spezifika | Button-Text / Tooltip oder Menü-Label |
| `icon` oder `iconId` | root | string | siehe Spezifika | URL `https://…`, `${custo.path}\datei.png` oder eingebauter Sprite-Name |
| `tooltip` | root | string | nein | alternativer Tooltip (auf manchen EPs ignoriert) |
| `command` | root | object | **JA** | command-Objekt |
| `command.url` | command | string | **JA** | HTTP(S)-URL, `{{server}}/…` oder Dateipfad |
| `command.params` | command | string | nein | URL-Parameter. Variablen erlaubt. |
| `command.commandType` | command | string | nein | `"rest"` (Standard) oder `"file"`. Auf Web erfordert `"file"` die Datei im ZIP. |
| `command.method` | command | string | nein | `"GET"` (Standard) oder `"POST"` |
| `command.header` | command | array | nein | Array `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **JA bei POST** | JSON im Body |
| `responseType` | root | string | siehe Spezifika | `"markdown"`, `"json"` oder `"adaptiveCard"`. Bei Vorhandensein → Popup. Sonst → Aktion wird ohne angezeigte Antwort ausgeführt. |
| `displayJsonField` | root | string | nein | Bei `responseType: "json"`: Name des JSON-Feldes mit dem Markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | root | — | je nach Modus | Bei `responseType: "adaptiveCard"` — siehe §8 |
| `AnswerOnClick` | root | boolean | nein | (nur `on-incoming-pbx-call-button-actions`) — bei `true` wird der Anruf zusätzlich angenommen |
| `alsoForTeams` | root | boolean | nein | (nur `on-call-log-list-actions`) — auch im Teams-Add-in anzeigen |
| `redirectUrl` *(BETA S183)* | root | string | nein | URL-Template, das nach dem REST-Aufruf in einem neuen Browser-Fenster geöffnet wird (siehe unten). Erfordert `responseType: "json"`. |
| `markdownTemplate` *(BETA S183)* | root | string | nein | Markdown-Template, das nach Ersetzung der Rainbow-Variablen und von `${response...}` angezeigt wird. Erfordert `commandType: "rest"` und `responseType: "json"` — siehe §8.4. |

#### Spezifika je EP

| EP | `name` | `icon` | `responseType` | Erlaubte Variablen |
|---|---|---|---|---|
| `on-incoming-pbx-call-button-actions` | "Button text" | nicht genutzt | optional | localUser, caller, called, call, contact |
| `on-call-log-list-actions` | tooltip | **JA** | optional | localUser, contact |
| `on-contact-list-actions` | tooltip | **JA** | optional | localUser, contact |
| `on-contact-detail-actions` | tooltip | **JA** | optional | localUser, contact |
| `on-communication-card-actions` | "menu text" | **JA** (Menü) | optional | localUser, caller, called, call, contact |
| `on-bubble-actions` | "menu text" | **JA** (Menü) | optional | localUser, bubble |
| `on-bubble-conference-actions` | "menu text" | **JA** (Menü) | optional | localUser, bubble |
| `on-user-menu-actions` | "menu item title" | **JA** (Menü) | optional | localUser |

#### Weiterleitung nach einem REST-Aufruf — `redirectUrl` *(BETA S183)*

Jeder Button-EP akzeptiert `redirectUrl`: Beim Klick wird der REST-Aufruf ausgeführt und die — aus der JSON-Antwort aufgebaute — URL in einem **neuen Browser-Fenster** geöffnet. Es gelten dieselben Regeln wie bei den Anruf-Events (siehe **§10.1**): `redirectUrl` erfordert `responseType: "json"`, Variablen (die Rainbow-Variablen des EP und `${response...}`, §7.7) werden ersetzt und URL-kodiert; es passiert nichts, wenn der REST-Aufruf fehlschlägt, wenn das Feld fehlt oder wenn die Antwort kein JSON ist.

Besonderheiten bei Buttons:
- Eine Weiterleitung **ersetzt die Anzeige**: `responseType` muss `"json"` sein (obligatorisch). Die Kombination von `redirectUrl` mit `"markdown"` oder `"adaptiveCard"` oder das Weglassen von `responseType` ist **ungültig** (wird vom Rainbow Validator als Fehler gemeldet).
- `command.commandType` muss `"rest"` (Standard) sein — die Antwort existiert nur bei einem REST-Aufruf, nicht bei `"file"`.

> ⚠ **BETA (S183)** — diese Funktion befindet sich in der Beta-Phase und kann sich vor der allgemeinen Verfügbarkeit noch ändern.

**Beispiel — Button in der Kontaktliste, der den per REST-Lookup ermittelten CRM-Datensatz öffnet**

```json
"on-contact-list-actions": [{
  "iconId": "settings",
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "email=${contact.email}"
  },
  "responseType": "json",
  "redirectUrl": "${response.url}"
}]
```

#### Beispiel 1 — Button in der Kontaktliste, der ein externes CRM öffnet

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-contact-list-actions": [{
      "name": "Open in CRM",
      "tooltip": "View this contact in our CRM",
      "icon": "${custo.path}\\crm.png",
      "command": {
        "url": "https://crm.example.com/contact",
        "params": "email=${contact.email}&phone=${contact.phoneNumber}"
      }
    }]
  }
}
```

Kein `responseType` → die URL wird in einem neuen Browser-Tab geöffnet, ohne Popup in Rainbow.

#### Beispiel 2 — Button beim eingehenden Anruf, der ein Ticket anlegt und annimmt

```json
"on-incoming-pbx-call-button-actions": [{
  "name": "Create ticket & answer",
  "AnswerOnClick": true,
  "command": {
    "commandType": "rest",
    "method": "POST",
    "url": "https://tickets.example.com/api/tickets",
    "header": [
      "Authorization: Bearer eyJhbGc...",
      "Content-Type: application/json"
    ],
    "bodyParameters": {
      "caller":    "${caller.phoneNumber}",
      "callId":    "${call.callId}",
      "createdBy": "${localUser.loginEmail}"
    }
  }
}]
```

Der Klick legt das Ticket an **und** nimmt den Anruf in einem Schritt entgegen (`AnswerOnClick: true`).

#### Beispiel 3 — Adaptive-Card-Menü im Bubble-Menü

```json
"on-bubble-actions": [{
  "name": "Bubble members report",
  "icon": "${custo.path}\\report.png",
  "command": {
    "commandType": "rest",
    "method": "POST",
    "url": "https://api.example.com/bubble/report",
    "header": ["Authorization: Bearer eyJhbGc...", "Accept: application/json"],
    "bodyParameters": {
      "bubbleId": "${bubble.id}",
      "members":  "${bubble.members}"
    }
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField":  "data"
}]
```

`${bubble.members}` benötigt `commandType: "rest"` (siehe §7).

---

### 10.3 Anzeige (Display)

![Automatische Informationsanzeige in Rainbow](images/displays.png)

**Prinzip**: Fügt automatisch Inhalt (Markdown oder Adaptive Card) an einer bestimmten Stelle der UI ein — ohne Benutzerinteraktion. Der Inhalt wird abgerufen, sobald die Stelle sichtbar wird.

**Extension Points**:

| Schlüssel | Anzeigeort |
|---|---|
| `on-incoming-pbx-call-display-actions` | Im Pop-up des eingehenden Anrufs |
| `on-contact-card-display-actions` | Im Kontakt-Detail-Panel |
| `on-main-widget-display-actions` | Widget im Rainbow-Hauptpanel |
| `on-main-display-actions` | Nachricht in der Teams-Webapp |
| `on-conversation-tab-actions` | Benutzerdefinierter Tab in einem Gespräch (P2P oder Konferenz) — siehe unten |

**Lizenzvoraussetzung**: mindestens Business.

#### Felder (alle Displays)

| Feld | Position | Typ | Pflicht | Werte / Einschränkungen |
|---|---|---|---|---|
| `name` | root | string | siehe Spezifika | Titel (nur Widget) |
| `command` | root | object | **JA** | command-Objekt |
| `command.url` | command | string | **JA** | HTTP(S)-URL, `{{server}}/…` oder Datei |
| `command.params` | command | string | nein | URL-Parameter. Variablen erlaubt. |
| `command.commandType` | command | string | nein | `"rest"` (Standard) oder `"file"`. Auf Web → Datei im ZIP. |
| `command.method` | command | string | nein | `"GET"` (Standard) oder `"POST"` |
| `command.header` | command | array | nein | Array `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **JA bei POST** | JSON-Body |
| `responseType` | root | string | **JA** | `"markdown"`, `"json"` oder `"adaptiveCard"` ¹ — bei Displays immer erforderlich |
| `displayJsonField` | root | string | nein | Bei `responseType: "json"`: Feld mit dem Markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | root | — | je nach Modus | Bei `responseType: "adaptiveCard"` — siehe §8 |
| `urlConfig` | root | string | nein | (nur `on-main-widget-display-actions`) — Widget-Konfigurations-URL |
| `alsoForTeams` | root | boolean | nein | (nur `on-main-display-actions`) — im Teams-Web-Add-in anzeigen |
| `markdownTemplate` *(BETA S183)* | root | string | nein | Markdown-Template, das nach Ersetzung der Rainbow-Variablen und von `${response...}` angezeigt wird. Erfordert `commandType: "rest"` und `responseType: "json"` — siehe §8.4. |

*¹ `adaptiveCard` wird von `on-incoming-pbx-call-display-actions` (Popup bei eingehendem Anruf) NICHT unterstützt — siehe §10.3.1.*

#### Spezifika je EP

| EP | `name` | Erlaubte Variablen |
|---|---|---|
| `on-incoming-pbx-call-display-actions` | nicht genutzt | localUser, caller, called, call, contact |
| `on-contact-card-display-actions` | nicht genutzt | localUser, contact |
| `on-main-widget-display-actions` | "widget title" | localUser |
| `on-main-display-actions` | nicht genutzt | localUser |
| `on-conversation-tab-actions` | "Tab-Name" | localUser, contact, bubble |

#### 10.3.1 `on-incoming-pbx-call-display-actions` (Detail)

**Rolle**: automatisch Informationen im **Pop-up des eingehenden Anrufs** anzeigen, ohne Benutzerinteraktion. Der Inhalt wird abgerufen, sobald das Pop-up erscheint, aus einer in `command` deklarierten Quelle.

**Mögliche Inhaltsquellen**:

| Quelle | `command` | Wirkung |
|---|---|---|
| **Datei** | `commandType: "file"`, `url` = Dateipfad | liest eine Datei und zeigt ihren Inhalt an |
| **Skript** | `commandType: "file"`, `url` = Ausführbare/Skript | führt das Skript aus und zeigt seine Ausgabe an |
| **Webseite** | `commandType: "rest"`, `url` = http(s) | öffnet die URL und zeigt ihren Inhalt an |
| **REST-API** | `commandType: "rest"`, `method` GET/POST | ruft eine REST-API auf und verwertet die Antwort |

**`responseType`**: `"markdown"` (Standard) oder `"json"`.

> ⚠️ **Adaptive Card ist für diesen Extension Point NICHT nutzbar**.

**Verwertung einer JSON-Antwort** (`responseType: "json"`) — mehrere Felder der Antwort können extrahiert werden:

| Manifest-Feld | Rolle |
|---|---|
| `displayJsonField` | Name des JSON-Feldes, **dessen Wert angezeigt wird** (Text / Markdown) im Pop-up |
| `firstNameJsonField` | **überschreibt/setzt den angezeigten Vornamen** des Anrufers |
| `lastNameJsonField` | **überschreibt/setzt den Nachnamen** des Anrufers |
| `companyJsonField` | **überschreibt/setzt die Firma** des Anrufers |
| `linkJsonField` | Name des JSON-Feldes, dessen Wert als **anklickbarer Link** im Pop-up hinzugefügt wird (Beschriftung = `name` der Aktion, falls vorhanden, sonst „Link“) — typischerweise um die Karte des Anrufers in der Geschäftsanwendung/im CRM zu öffnen |

Das Pop-up kann so in einem einzigen Aufruf die **Anruferidentität anreichern** (Name/Vorname/Firma aus dem CRM aufgelöst), **einen Inhalt anzeigen** und einen **Link** zur Karte anbieten.

**Beispiel — Auflösung der Anrufer-ID + Inhalt + Link aus einer REST-API**:

```json
"on-incoming-pbx-call-display-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/lookup",
    "params": "phone=${caller.phoneNumber}",
    "header": ["Authorization: Bearer eyJhbGc..."]
  },
  "responseType": "json",
  "displayJsonField":   "display",
  "firstNameJsonField": "firstName",
  "lastNameJsonField":  "lastName",
  "companyJsonField":   "company",
  "linkJsonField":      "crmUrl"
}]
```

Erwartete REST-Antwort (Beispiel):

```json
{ "display": "**VIP** — file #42", "firstName": "Marie", "lastName": "Curie", "company": "Sorbonne", "crmUrl": "https://crm.example.com/contacts/42" }
```

Rainbow zeigt den Wert von `display` an, ersetzt Vorname/Nachname und Firma des Anrufers durch die aufgelösten Werte und fügt den Wert von `crmUrl` als anklickbaren Link hinzu (Beschriftung = `name` der Aktion, sonst „Link“).

> **⚠ Begrenzte Persistenz** — die aufgelöste Identität **bleibt nicht über die aktuelle Rainbow-Sitzung hinaus erhalten**; nach Beenden der Sitzung zeigt das Call-Log nur noch die reine Rufnummer. Für dauerhafte Identifikation den Kontakt im Rainbow-Adressbuch hinterlegen.

**Konkretes Beispiel — Markdown in einem CRM-Textfeld gespeichert**

Tipp: **Markdown** direkt in einem CRM-Textfeld ablegen (hier `notes`). Rainbow zeigt es unverändert im Popup an — inklusive Fettdruck, Emojis und **klickbarem Link**. Die Felder liegen hier unter einem `contact`-Objekt (Pfade `contact.*`).

Manifest-Auszug:

```json
"responseType": "json",
"displayJsonField":   "contact.notes",
"firstNameJsonField": "contact.prenom",
"lastNameJsonField":  "contact.nom",
"companyJsonField":   "contact.compagnie"
```

REST-Antwort (das Feld `notes` enthält Markdown):

```json
{
  "contact": {
    "id": 18,
    "prenom": "SIP",
    "nom": "BOUSSEL",
    "telephone_pro": "+333xxxxxxx",
    "telephone_mobile": "",
    "compagnie": "SIPCOmpany",
    "notes": "🏭**Support for custo team**\n🌍[Personal site](https:linkperso.com)\n"
  }
}
```

Darstellung im Popup bei eingehendem Anruf:

![Markdown-Anzeige im Popup bei eingehendem Anruf](images/incomingCallDisplaySample1.png)

#### Beispiel 1 — Caller-ID-Markdown-Karte im Pop-up des eingehenden Anrufs

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-incoming-pbx-call-display-actions": [{
      "command": {
        "commandType": "rest",
        "method": "GET",
        "url": "https://api.example.com/lookup",
        "params": "phone=${caller.phoneNumber}",
        "header": ["Authorization: Bearer eyJhbGc..."]
      },
      "responseType": "markdown"
    }]
  }
}
```

#### Beispiel 2 — Adaptive-Card-Widget, das bei jedem Öffnen aktualisiert wird

```json
"on-main-widget-display-actions": [{
  "name": "My tickets",
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/tickets/me",
    "header": ["Authorization: Bearer ${localUser.id}"]
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField":  "data",
  "adaptiveCardSubmitUrl":         "https://api.example.com/tickets/submit"
}]
```

`adaptiveCardSubmitUrl` ermöglicht den `Action.Submit`-Buttons der Karte, ihre `data` per POST an diese URL zu senden.

#### Beispiel 3 — Anzeige auch für Teams deklariert

```json
"on-main-display-actions": [{
  "alsoForTeams": true,
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://announcements.example.com/today"
  },
  "responseType": "markdown"
}]
```

#### Gesprächs-Tab — `on-conversation-tab-actions`

> ℹ **Neu in S179.**

**Prinzip**: fügt einen **benutzerdefinierten Tab** in der Detailspalte eines Gesprächs hinzu, für ein P2P-Gespräch und/oder eine Konferenz (Bubble). Das Tab-Element wird durch `name`, `icon` und `tooltip` definiert. Bei Auswahl wird die Aktion ausgeführt — ein REST-Aufruf (`rest`), ein lokales Skript/Exec (`file`) oder eine Webseite (`app`) — und der zurückgegebene Inhalt wird im Tab angezeigt (`markdown` oder `adaptiveCard`). Während einer Konferenz wird der Tab in der Liste der **Meeting-Tools** angeboten.

**Lizenz**: alle Service-Pläne außer Essential.

Anders als bei den übrigen Displays ist `responseType` hier **optional**: ein Tab, der nur eine Webseite öffnet, gibt keinen anzuzeigenden Inhalt zurück.

**`scope`** (array, optional) — die Gesprächskontexte, in denen der Tab erscheint:

| Wert | Kontext |
|---|---|
| `"one_to_one"` | P2P-Gespräche |
| `"bubble"` | Konferenzen (Bubbles) |

Fehlt `scope`, wird der Tab in allen Kontexten angeboten.

**Zulässige Variablen**: `${localUser.*}`, alle `${contact.*}` und alle `${bubble.*}` (siehe §7.2). `${bubble.members}` ist nur mit einem REST-Aufruf nutzbar.

```json
"on-conversation-tab-actions": [{
  "name": "Conference Assistant",
  "scope": ["one_to_one", "bubble"],
  "tooltip": "Translation assistant",
  "icon": "${custo.path}\\assistant.png",
  "command": {
    "method": "GET",
    "commandType": "rest",
    "url": "http://www.confAssistant.com/api/lang-card?email=${localUser.email}"
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField": "data"
}]
```

---

### 10.4 Anwendung (Frame-Anzeige)

![Web-Drittanwendung in einem Rainbow-Frame](images/applications.png)

**Prinzip**: Bettet eine **Web-Drittanwendung** in einen Rainbow-UI-Frame ein. Kein REST-`command`-Objekt — es ist einfach eine URL, die als Iframe geladen wird. Mit `popout: true` öffnet sich die Anwendung in einem Browserfenster (statt eingebettet zu werden).

**Extension Point**:

| Schlüssel | Position |
|---|---|
| `on-main-window-actions` | Frame im Rainbow-Hauptfenster |

**Lizenzvoraussetzung**: mindestens Business.

#### Felder

| Feld | Position | Typ | Pflicht | Werte / Einschränkungen |
|---|---|---|---|---|
| `name` | root | string | **JA** | "Frame name" — Anwendungsname in der Rainbow-Leiste |
| `icon` oder `iconId` | root | string | **JA** (nicht nötig für ein Item, das nur Mobile anspricht) | URL `https://…`, `${custo.path}\datei.png` oder Sprite |
| `tooltip` | root | string | nein | Tooltip |
| `command` | root | object | **JA** | command-Objekt — mindestens `url` |
| `command.url` | command | string | **JA** | HTTP(S)-URL der einzubettenden Web-Anwendung |
| `command.params` | command | string | nein | URL-Parameter. Variablen erlaubt. |
| `command.commandType` | command | string | nein | Standardmäßig leer → "Browse URL"-Verhalten (URL wird einfach geladen) |
| `popout` | root | boolean | nein | `true` → öffnet die Anwendung in einem Browserfenster statt im Rainbow-Frame |
| `devicesSupported` *(BETA S183)* | root | array | nein | Vom Item anvisierte Rainbow-Clients (`"web"`, `"desktop"`, `"mobile"`) — siehe §6.2 |

**Hinweis**:
- **Keine `method`, `bodyParameters`, `header`, `responseType`** — es ist ein URL-Ladevorgang, kein API-Aufruf
- **Keine anderen Variablen als `localUser.*`** — der EP befindet sich auf Rainbow-Anwendungsebene, nicht an einen Kontakt/Anruf gebunden

**Erlaubte Rainbow-Variablen**: `${localUser.*}`

#### Mobile *(BETA S183)*

`on-main-window-actions` ist der erste Extension Point, der in Rainbow Mobile verfügbar ist (`devicesSupported` mit `"mobile"`, §6.2). Auf Mobile wird die Anwendung **immer im Browser/Webview des Geräts geöffnet**, unabhängig vom Wert von `popout`, das dort nicht gelesen wird, und **ohne Icon** (das Icon wird auf Mobile nicht verwendet). Das Manifest muss über den Administrator-Mechanismus (Cloud) bereitgestellt werden.

#### Sicherheit

Die geladene URL muss in der Rainbow-Konsole als **Trusted Domain** deklariert sein (Company → Customization → Custo-manifest domains). Andernfalls verweigert der Browser die Einbettung (CSP). Siehe §12.

> **⚠ Die Web-Drittanwendung muss akzeptieren, in einem Frame angezeigt zu werden.**
> Viele Websites verbieten das Einbetten in einem Iframe standardmäßig durch:
> - den HTTP-Header `X-Frame-Options: DENY` oder `SAMEORIGIN`
> - oder die CSP-Direktive `Content-Security-Policy: frame-ancestors 'self'`
>
> Wenn die Zielanwendung eine dieser Schutzmaßnahmen verwendet, bleibt der Frame **leer** (weiße Seite) oder zeigt eine Browser-Fehlermeldung an, ohne Hinweis in Rainbow. Prüfen Sie diese Header serverseitig der Anwendung vor der Einbettung. Wenn die Anwendung nicht änderbar ist, ist die Alternative `popout: true`, um die App in einem Browserfenster statt in einem Frame zu öffnen.

#### Beispiel 1 — eine Business-Web-Anwendung einbetten

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-main-window-actions": [{
      "name": "Mein CRM",
      "icon": "${custo.path}\\crm.png",
      "command": {
        "url": "https://crm.example.com/dashboard",
        "params": "user=${localUser.email}"
      }
    }]
  }
}
```

Die Anwendung erscheint in Rainbow unter dem Namen „Mein CRM". Beim Klick wird das CRM-Dashboard in den Frame geladen, mit der E-Mail des Benutzers als Parameter.

#### Beispiel 2 — Öffnen im Browser (statt im Frame)

```json
"on-main-window-actions": [{
  "name": "External reporting",
  "icon": "${custo.path}\\report.png",
  "popout": true,
  "command": {
    "url": "https://reporting.example.com/",
    "params": "user=${localUser.loginEmail}"
  }
}]
```

`popout: true` → die Anwendung öffnet sich in einem Browserfenster. Nützlich, wenn die Anwendung das Einbetten verweigert (restriktive CSP `frame-ancestors`) oder wenn ein großer Arbeitsbereich gewünscht ist.

#### Beispiel 3 — Anwendung ohne Benutzerauthentifizierung (statisch)

```json
"on-main-window-actions": [{
  "name": "Wiki",
  "icon": "${custo.path}\\wiki.png",
  "command": {
    "url": "https://wiki.example.com/"
  }
}]
```

## 11. Erstellung & Bereitstellung

Ein Manifest kann auf zwei Arten bereitgestellt werden:

- **Lokal**, durch Import der Datei (oder des ZIP) durch den Endbenutzer im Rainbow-Client.
- **Automatisch aus der Cloud**, wenn der Administrator das Manifest dem Benutzer über die Rainbow-Konsole zugewiesen hat. Der Client lädt es dann beim Start ohne Benutzeraktion herunter.

Die lokale Bereitstellung wird für die **Testphase** oder bei **wenigen Benutzern** empfohlen. Der Administrator kann diesen Modus über ein **Profil-Flag** deaktivieren: In diesem Fall verschwindet die Import/Export-Option auf der Benutzerseite.

**Die Administrator-Bereitstellung hat Vorrang**: Ein vom Admin zugewiesenes Manifest ersetzt jedes lokale Manifest, und der Benutzer kann es nicht überschreiben.

**Umfang**: Die Administrator-Bereitstellung gilt für **alle Instanzen** des Rainbow-Clients des Benutzers (Desktop, Web, auf allen Maschinen/Sitzungen). Die lokale Bereitstellung dagegen betrifft nur **die für den Import verwendete Maschine oder den verwendeten Browser** — sie folgt dem Benutzer nicht auf andere Arbeitsplätze.

### 11.1 Erstellung

Es gibt mehrere Wege, eine erste Manifest-Datei zu erhalten:

**Aus dem Rainbow-Desktop-Client (Template-Export)**

Eine Template-Datei kann lokal beschafft werden, indem ein Export angefragt wird, **solange noch kein Manifest importiert wurde**. Der Client erstellt dann eine Beispieldatei mit allen unterstützten Extension Points.

1. Im Rainbow-Desktop-Client: **Settings → Telephony → Customization → Export**
2. Nicht benötigte Extension Points entfernen (nur die behalten, die konfiguriert werden sollen)
3. Inhalt jedes beibehaltenen EP ausfüllen (`name`, `icon`, `command` usw.)
4. Importieren, um lokal zu testen

**Aus einem Generator oder Beispiel**

Manifest-Generatoren (z. B. der **Rainbow Generator** von ALE) oder die in dieser Dokumentation enthaltenen **Beispiele** können ebenfalls als Ausgangspunkt dienen — JSON-Struktur kopieren, an den Geschäftskontext anpassen und importieren.

### 11.2 ZIP mit Ressourcen

Wenn das Manifest lokale Dateien referenziert (Icons, Texte, Skripte), erstellen Sie ein ZIP mit dem Manifest **und** den Ressourcendateien und importieren Sie es in den Client.

**Hinweise** (siehe §7.6):
- Jede ZIP-Ressource per `${custo.path}\\dateiname.ext` im Manifest referenzieren.
- Das Feld `"jsonType": "Rainbow-custo-manifest"` im Root des Manifests setzen — dadurch erkennt Rainbow die Manifest-Datei innerhalb des ZIP. Andernfalls sucht Rainbow nach einer Datei mit dem genauen Namen `custo-manifest.json`.

**Web-/Desktop-Kompatibilität**: Das ZIP ist mit beiden Rainbow-Clients kompatibel. Auf Desktop werden die Ressourcen auf die Festplatte geschrieben; auf Web werden sie aus dem heruntergeladenen ZIP in den Speicher geladen. Dasselbe ZIP kann daher gleichermaßen für beide Plattformen bereitgestellt werden.

### 11.3 Mass Provisioning (durch Administrator)

**Company → Information → Customization → Custo-manifest**

1. Manifest in die zentrale Rainbow-Administration importieren
2. Einem Benutzer ein Manifest zuweisen:
   - über das Admin-Web (Member → Information → custo-manifest)
   - per CSV
   - per LDAP-Konnektor: das Feld `selectedManifestName` auf das passende LDAP-Attribut mappen
3. Der Rainbow-Client lädt das Manifest beim Start automatisch herunter:
   - Die `/Custom`-Option des Setup wird **ignoriert**
   - Der Eintrag Import/Export in den Settings ist für den Benutzer **ausgeblendet**

### 11.4 Setup-CLI

> **⚠ Veraltetes Verfahren** — bevorzugen Sie die **Administrator-Bereitstellung** (§11.3), die Vorrang vor diesem alten Modus hat und eine zentrale Verwaltung bietet. Dieser CLI-Modus bleibt aus Rückwärtskompatibilität mit alten Desktop-Integrationen erhalten.

Beim Start des Rainbow-Setup:
```
RainbowSetup.exe /Custom=C:\path\to\manifest.json
```
Hinweis: `/Custom` blendet ebenfalls den Import/Export im Benutzer aus.

---

## 12. Sicherheit (S170)

### 12.1 Standard-Webmechanismen

Die Extensions werden von der Rainbow-Web-Anwendung ausgeführt (auch wenn sie in den Desktop-Client eingebettet sind). Die Standard-Webschutzmechanismen gelten:

- **CSP** (Content-Security-Policy) — Rainbow kann nur eine Seite laden oder eine API aufrufen, wenn die Domain auf der Whitelist steht
- **CORS** (Cross-Origin) — der REST-Server muss Rainbow ausdrücklich als Origin akzeptieren
- **LNA** (Local Network Access) — der Zugriff auf lokale Maschinen/Server kann vom Browser verweigert werden
- **CSP auf der Gegenseite** — der Server kann sich der Einbettung in einen Rainbow-Frame widersetzen

### 12.2 Trusted Domains (neu in S170)

#### Was kontrolliert wird

Jede in einem Manifest referenzierte URL (REST-Aufruf oder iframe) muss ihren **Origin** als trusted in der Rainbow-Konsole deklariert haben. Dies gilt für:

- `command.url` auf allen Extension Points (REST-Aufrufe, Datei-Browsing)
- `command.url` auf `on-main-window-actions` (in den Frame eingebettete Web-App)
- `adaptiveCardSubmitUrl`
- `urlConfig` (Widget-Konfigurations-URL)

Die Deklaration gilt **unternehmensübergreifend**: Sie deckt alle im Unternehmen bereitgestellten Manifeste und alle Benutzer ab.

> **Ausnahme `popout: true`** — wenn `on-main-window-actions` `popout: true` verwendet, öffnet sich die URL in einem **dedizierten Browserfenster**, nicht im Rainbow-Frame. Die Trusted-Domain-Prüfung ist in diesem Fall **deaktiviert**: Die native Browsersicherheit greift und Rainbow erzwingt sein eigenes CSP für diese URL nicht.

> **SSO / OAuth-Flows** — wenn die eingebettete Web-Anwendung einen Authentifizierungsflow (SSO, OAuth, SAML…) auslöst, befindet sich der Identity Provider oft auf einer **anderen Domain** als die Anwendung selbst (z. B. `login.microsoftonline.com`, `accounts.google.com`, ein interner IdP…). Rainbow versucht, diese Redirect-URLs im selben Frame zu laden, daher muss **jede am Authentifizierungsflow beteiligte Domain ebenfalls als trusted deklariert sein** — nicht nur der Origin der Anwendung. Wird die IdP-Domain nicht deklariert, bleibt der Frame beim Login leer, selbst wenn die URL der Anwendung korrekt whitegelistet ist.

#### Konfigurationsort

**Company → Information → Customization → Custo-manifest domains**

Pro Origin einen Eintrag hinzufügen. Jeder Eintrag muss folgendem Format entsprechen:

```
<Protokoll>://<Domain>[:<Port>]
```

| Teil | Regeln |
|---|---|
| `Protokoll` | `https` oder `http` — **obligatorisch** |
| `Domain` | Exakter Hostname oder Wildcard (`*.example.com`) |
| `Port` | Optional. Weglassen für Standardports (443 für https, 80 für http). |
| Abschließendes `/` | **Nicht erlaubt** — Eintrag wird abgelehnt oder passt nicht, wenn er mit `/` endet |

#### Protokoll-Einschränkungen (HTTP / HTTPS)

Einen Origin als trusted zu deklarieren, **genügt nicht**: Der Browser erzwingt zusätzlich eigene Regeln zum Protokoll. Die Rainbow-Web-Anwendung wird über **HTTPS** ausgeliefert, daher:

- **`http://` wird nur für `localhost` / `127.0.0.1` (Loopback) akzeptiert.** Jeder andere HTTP-Origin (LAN-IP, Rechnername, öffentliche Domain) wird vom **Browser blockiert** (*Mixed-Content*-Regel), selbst wenn der Eintrag in der Konsole korrekt deklariert ist. Ein Eintrag wie `http://192.168.1.100:3300` wird als Format akzeptiert, der REST-Aufruf schlägt jedoch zur Laufzeit stillschweigend fehl.
- **`https://` erfordert ein gültiges Serverzertifikat.** Das Zertifikat muss von einer **vertrauenswürdigen Instanz** ausgestellt sein (öffentliche CA oder eine auf dem Rechner installierte Unternehmens-CA) und zum Hostnamen passen. Ein **selbstsigniertes, abgelaufenes oder namensfalsches** Zertifikat wird vom Browser abgelehnt: Der REST-Aufruf schlägt fehl und ein eingebetteter Frame bleibt **leer**, ohne Fehlermeldung in Rainbow.

> **Kurz gesagt**: HTTPS mit gültigem Zertifikat überall, außer `localhost`/`127.0.0.1`, wo HTTP toleriert wird (nur für die lokale Entwicklung nützlich).

#### Gültige Beispiele

| Eintrag | Trifft auf |
|---|---|
| `https://crm.example.com` | `https://crm.example.com/beliebiger/Pfad` |
| `https://crm.example.com:8443` | `https://crm.example.com:8443/beliebiger/Pfad` |
| `https://*.example.com` | `https://crm.example.com`, `https://api.example.com`, … |
| `http://localhost:3300` | Lokaler Entwicklungsserver — einziger Fall, in dem HTTP zur Laufzeit akzeptiert wird |

#### Ungültige Beispiele

| Eintrag | Problem |
|---|---|
| `crm.example.com` | Protokoll fehlt |
| `https://crm.example.com/` | Abschließender Schrägstrich — abgelehnt |
| `https://crm.example.com/api` | Pfad nicht erlaubt — nur den Origin deklarieren |
| `http://192.168.1.100:3300` | Format akzeptiert, aber **zur Laufzeit blockiert** — HTTP außerhalb von `localhost` nicht erlaubt (Mixed Content) |
| `https://` mit selbstsigniertem Zertifikat | Vom Browser abgelehnt — nicht vertrauenswürdiges Zertifikat |

#### Verhalten wenn eine Domain nicht deklariert ist

| Situation | Auswirkung |
|---|---|
| Manifest wird vom Client geladen | **Warnung wird dem Benutzer angezeigt** — das Manifest enthält nicht vertrauenswürdige Domains |
| REST-Aufruf (`commandType: "rest"`) | Aufruf vom Browser blockiert (CSP / CORS) — keine Popup-Meldung, keine Fehlermeldung in Rainbow |
| Frame (`on-main-window-actions`) | Der Frame wird angezeigt, aber die Seite ist **leer** (oder zeigt einen Browser-Sicherheitsfehler) |

> **⚠ Die Warnung erscheint beim Laden des Manifests, bevor eine Extension ausgelöst wird.** Ignoriert der Benutzer die Warnung, schlagen Extensions, die auf nicht deklarierte Domains zeigen, zur Laufzeit lautlos fehl.

### 12.3 CORS

Auch wenn eine Domain in Rainbow als trusted deklariert ist, erzwingt der **Browser** unabhängig davon CORS. Der REST-Server muss folgende Header zurückgeben:

```
Access-Control-Allow-Origin: https://web.openrainbow.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```

Der genaue Wert von `Access-Control-Allow-Origin` hängt von der Rainbow-Plattform ab. Die Browser-Entwicklertools (Netzwerk-Tab) verwenden, um den `Origin`-Header zu identifizieren, den Rainbow bei der blockierten Anfrage sendet. Alternativ den Wildcard verwenden:

```
Access-Control-Allow-Origin: *
```

> **Wildcard-Einschränkung** — nicht kompatibel mit Browser-Credentials (`withCredentials: true`, Session-Cookies). Für Rainbow-Erweiterungen, die ein Token über das Manifest-Feld `header` übergeben (z.B. `Authorization: Bearer …`), funktioniert der Wildcard, da Rainbow das Token als Standard-HTTP-Header sendet. Für Cookie-basierte Authentifizierung die Rainbow-Origin explizit deklarieren und `Access-Control-Allow-Credentials: true` hinzufügen.

> **Breaking Change** — ein Manifest, das vor S170 funktioniert hat, kann brechen, wenn der REST-Server keine CORS-Header zurückgibt. In Rainbow wird kein Fehler angezeigt — der Aufruf schlägt still fehl.

### 12.4 Local Network Access (LNA)

Wenn der REST-Server auf einem **lokalen oder privaten Netzwerk** läuft (z.B. `https://192.168.1.100:8443`), erzwingen Chrome und Edge die **Private Network Access**-Richtlinie.

> **HTTP wird vorher blockiert** — ein lokaler Server über HTTP (z.B. `http://192.168.1.100:3300`) wird bereits durch die *Mixed-Content*-Regel (siehe §12.2) blockiert, **bevor** LNA greift. In der Praxis betrifft LNA daher nur lokale Server, die über **HTTPS** ausgeliefert werden (oder die `localhost`-Ausnahme).

> **Rainbow Desktop ist nicht betroffen** — nur Rainbow Web unterliegt den LNA-Regeln des Browsers.

> **Betroffene Browser** — LNA wird nur von **Chrome und Edge (Chromium-basiert)** durchgesetzt. Firefox und Safari implementieren diese Richtlinie nicht.

Der Browser sendet ein preflight OPTIONS mit `Access-Control-Request-Private-Network: true`. Der Server muss antworten mit:

```
Access-Control-Allow-Private-Network: true
```

zusätzlich zu den Standard-CORS-Headern.

> **Benutzerberechtigung (Chrome/Edge)** — selbst mit korrekten Server-Headern kann Chrome eine Berechtigungsanfrage anzeigen: *„[Website] den Zugriff auf Ressourcen in Ihrem lokalen Netzwerk erlauben?"*. Der Benutzer muss diese Berechtigung explizit erteilen. Sie kann auch unter `chrome://settings/content/privateNetworkDevices` verwaltet werden.

### 12.5 Sicherheit eingebetteter Anwendungen

Wenn `on-main-window-actions` eine URL im Rainbow-Frame lädt, kann die Zielanwendung die Einbettung über Server-Header verweigern:

| Header | Typischer Wert | Auswirkung |
|---|---|---|
| `X-Frame-Options` | `DENY` oder `SAMEORIGIN` | Browser verweigert die Darstellung der Seite im iframe — leerer Frame |
| `Content-Security-Policy` | `frame-ancestors 'self'` oder `'none'` | Gleiche Auswirkung, moderner Mechanismus |

Dies ist unabhängig von der Trusted-Domain-Deklaration — eine deklarierte Domain kann dennoch Iframe-Einbettung verweigern.

**Lösung:** Die Anwendung so konfigurieren, dass sie die Rainbow-Origin in `frame-ancestors` zulässt, oder `popout: true` bei `on-main-window-actions` verwenden.

> **SSO / OAuth-Flows** — der Identity Provider setzt aus Sicherheitsgründen typischerweise `X-Frame-Options: DENY`. In diesem Fall kann SSO unabhängig von Domain-Deklarationen nicht im iframe abgeschlossen werden. `popout: true` verwenden.

### 12.6 Sonderfall der lokalen Ausführung

`commandType: "file"` (Ausführung einer `.exe` oder eines lokalen Skripts) **wird von diesen Mechanismen nicht kontrolliert**. Um diesen Erweiterungstyp auf Unternehmensebene zu verbieten: den Benutzer daran hindern, ein Manifest zu laden, und nur über die Rainbow-Cloud bereitstellen.

---

## 13. Best Practices

### 13.1 Erstellung

1. **Mit einem aus Rainbow Desktop exportierten Template starten**, nicht benötigte EPs entfernen
2. Vor der zentralen Bereitstellung einen **lokalen Import** zur Syntax-Validierung durchführen
3. Sicherstellen, dass alle Referenzen **portabel** sind (kein hartcodierter Pfad zur Entwicklermaschine)
4. Für lokale Ressourcen: konsequent `${custo.path}\…` + ZIP verwenden
5. Auf **Web** und **Desktop** testen (sofern der EP nicht ausschließlich Desktop ist)

### 13.2 Sicherheit

- **Alle** Ziel-REST-Domains vor Bereitstellung in der Rainbow-Konsole deklarieren
- Die **CORS-Header** des REST-Servers prüfen (`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`)
- Immer **HTTPS mit gültigem Zertifikat** (nicht selbstsigniert) verwenden — HTTP wird nur für `localhost`/`127.0.0.1` akzeptiert (siehe §12.2)
- Für REST-Server in einem **lokalen/privaten Netzwerk** (über HTTPS ausgeliefert): `Access-Control-Allow-Private-Network: true` hinzufügen — Chrome/Edge erzwingen LNA (siehe §12.4)
- **Niemals** Geheimnisse im Klartext im Manifest ablegen (es wird von jedem Client heruntergeladen)
- Für eingebettete Apps, die Iframe-Einbettung verweigern: `popout: true` verwenden oder `frame-ancestors` auf der Ziel-App konfigurieren (siehe §12.5)

### 13.3 Variablen

- Nur die für den EP dokumentierten Variablen verwenden — nicht unterstützte Variablen werden stillschweigend leer
- Bei Regex: `\` im JSON verdoppeln (`\\+33` für `\+33`)
- Korrelatoren unter **32 Zeichen** halten

### 13.4 Adaptive Cards

- Das Muster „Template im Manifest + Daten per REST" bevorzugen: erlaubt, die Daten serverseitig zu ändern, ohne das Manifest erneut bereitzustellen
- `${variable}` im Template verwenden und die Werte im Content liefern
- `Action.Submit` sendet das gesamte `data`-Objekt der Aktion

---

## 14. Validierung und Debugging

Ein **Custo-Manifest-Validator** steht auf ALE-Seite bereit, um zu prüfen:
- Manifest-Struktur (`version`, `jsonType`, `extension-points`)
- Feldkonformität je EP
- Vorhandensein der erforderlichen Icons
- für den EP erlaubte Rainbow-Variablen
- Syntax `${object.attribute}` (gegen `$(object.attribute)` oder `$[object.attribute]`)
- absolute Pfade vs. `${custo.path}`-Ressourcen
- Kompatibilität `commandType` / `method` / `bodyParameters` / `header` / `responseType`

Er bietet auch automatische Korrekturen (Hinzufügen eines fehlenden Icons, Verschieben von fehlplatzierten Feldern zurück in root oder unter `command`, Entfernen nicht unterstützter Felder, Umwandlung absoluter Pfade in Ressourcen).

---

## 15. Versionshistorie

| Version | Wichtigste Neuerungen |
|---|---|
| **S156** | Event `on-outgoing-pbx-call-actions` · Admin-Mass-Provisioning · makecall-Korrelator · Multi-Extensions (bis zu 3) |
| **S161** | Custo-Manifest teilweise auf WEB unterstützt · Variable `contact` (Card-Info) |
| **S170** | Custom-Widget-Extension (freier Widget-Bereich) · **Vollständiges** Custo-Manifest auf Web und Desktop · REST-Härtung (Trusted Domains + CORS) |
| **S179** | Extension `on-conversation-tab-actions` (benutzerdefinierter Tab in der Gesprächsdetailansicht, P2P oder Konferenz — `scope`) · `linkJsonField` (Hyperlink zur Fachanwendung/zum CRM des Anrufers) |
| **S183** | `redirectUrl` *(Preview Beta)* — bei den Anruf-Events und den Schaltflächen wird ein Browserfenster mit einer aus der JSON-Antwort eines REST-Aufrufs berechneten URL geöffnet (`${response}`) · `devicesSupported` / `defaultDevicesSupported` *(Preview Beta)* — Ziel-Clients eines Items (Web, Desktop, Mobile, Teams); erster Mobile-Schritt bei `on-main-window-actions` · `markdownTemplate` *(Preview Beta)* — Markdown-Template, gefüllt mit den Rainbow-Variablen und der JSON-Antwort eines REST-Aufrufs, bei den EPs, die Markdown anzeigen |

---

---

*Dokument generiert aus der S170-Präsentation (April 2026) und der funktionalen Spezifikation Rainbow custo-manifest. Für Korrekturen oder Ergänzungen wenden Sie sich an das Rainbow Product Management Team.*
