Erstellen von Rainbow-GUI-Erweiterungen

Anhand dieses Artikels können Sie Rainbow-GUI-Erweiterungen erstellen, die Rainbow um Schaltflächen, Widgets und eingebettete Webanwendungen ergänzen. Sie erfahren, welche Erweiterungspunkte verfügbar sind und wie Sie die richtige Platzierung für Ihren Arbeitsablauf auswählen.

Übersicht

Mit GUI-Erweiterungen können Sie der Rainbow-Benutzeroberfläche benutzerdefinierte Schaltflächen, Widgets und eingebettete Webanwendungen hinzufügen. Für diese Erweiterungen ist mindestens eine Business-Lizenz erforderlich.

Was Sie mit GUI-Erweiterungen tun können:

• Fügen Sie anklickbare Aktionsschaltflächen in Kontaktlisten, im Anrufprotokoll, auf der Kommunikationskarte und in Bubbles hinzu
• Benutzerdefinierte Inhalte (CRM-Daten, Tickets, Berichte) automatisch in Anruf-Popups und Kontaktfenstern anzeigen
• Eine Webanwendung eines Drittanbieters direkt in das Rainbow-Hauptfenster einbetten

Arten von Erweiterungspunkten

Ein Erweiterungspunkt (EP) ist ein benannter Platzhalter in der Rainbow-Oberfläche, an den eine benutzerdefinierte Aktion angehängt werden kann. Jeder EP verfügt über einen eindeutigen Schlüssel (z. B. „on-contact-list-actions“), eine feste Position in der Benutzeroberfläche sowie Regeln, die festlegen, welche Felder und Variablen verfügbar sind. Das „custo-manifest“ deklariert unter jedem EP-Schlüssel eine oder mehrere Aktionen.

Schaltflächen – anklickbare Schaltflächen

Eine Symbolschaltfläche wird an einer bestimmten Stelle der Rainbow-Benutzeroberfläche eingefügt. Beim Klicken wird eine Aktion ausgeführt und optional das Ergebnis in einem Popup (Markdown oder Adaptive Card) angezeigt. Pro Erweiterungspunkt sind bis zu 3 Schaltflächen zulässig.

Anzeigen – automatische Informationsanzeige

Inhalte (Markdown oder Adaptive Card) werden automatisch an einer bestimmten Stelle der Benutzeroberfläche eingefügt – ohne Benutzereingriff. Der Inhalt wird abgerufen, sobald die Platzierung sichtbar wird.

Frame-Anzeige – Webanwendung eines Drittanbieters

Bettet eine Webanwendung eines Drittanbieters in einen Rainbow-UI-Frame ein. Bei „Popup: true“ wird die Anwendung in einem Browserfenster geöffnet, anstatt eingebettet zu werden.

Konfiguration einer GUI-Erweiterung

Das „custo-manifest“ ist ein JSON-Objekt mit folgender Struktur:

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

Globale Regeln:

• Die Version muss „2“ lauten.
• „jsonType“ muss „Rainbow-custo-manifest“ lauten. Innerhalb einer ZIP-Datei gibt dieses Feld an, welche JSON-Datei das Manifest ist.
• Jeder Schlüssel unter „extension-points“ ist ein Array – maximal 3 Aktionen pro Erweiterungspunkt.
• Jede Aktion muss ein gültiges Befehlsobjekt enthalten. „name“ und „icon“ sind je nach Erweiterungspunkt obligatorisch (siehe §3.4).

Aktionsfelder

Das Befehlsobjekt

Das Befehlsobjekt ist stets obligatorisch und enthält mindestens eine URL. Je nach gewähltem `commandType` sind zusätzliche Unterfelder zulässig.

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

Rainbow-Variablen

$Variablen werden zur Laufzeit durch ihren tatsächlichen Wert ersetzt. Sie können in „command.url“, „command.params“, „command.bodyParameters“ sowie in den an die Erweiterung zur Anzeige zurückgegebenen Inhalten vorkommen.

Syntax

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

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}

Kontakt (sofern identifiziert)

${kontakt.firstName} ${kontakt.lastName}
${kontakt.phoneNumber} ${kontakt.email}
${contact.company} ${contact.workNumber}
${contact.mobileNumber} ${contact.personalNumber}
${contact.personalMobile}
${contact.tags} (verkettet, durch Kommas getrennt)

Anrufer (nur bei EPs mit Anrufschaltfläche)

${caller.firstName} ${caller.lastName} ${caller.phoneNumber}

Angerufener (nur bei EPs mit Anrufschaltfläche)

${called.phoneNumber}

Anrufkontext (nur bei EP mit Anrufschaltfläche)

${call.callId}
${call.globalCallId} (nur OXE)
${call.correlator}

Bubble (nur bei Bubble-EPs)

${bubble.ownerEmail} ${bubble.name} ${bubble.shareLink}
${bubble.id}
${bubble.mitglieder} (JSON – nur bei commandType: „rest“)

Kompatibilität pro Erweiterungspunkt

Regex-Modifikator

Wendet vor der Ersetzung einen Regex-Modifikator auf den Wert der Variablen an:

// Eine Zahl normalisieren – +33 oder +1 durch 0 ersetzen
"params": "pbx=${localUser.phonePbx.regex(^\+33|^\+1, 0)}"
// E-Mail-Domäne ersetzen
"params": "byEmail=${localUser.email.regex(alcatel.com, al-enterprise.com)}"
// Die letzten 9 Ziffern extrahieren (kein Ersetzen = Extrahieren)
"params": "${kontakt.phoneNumber.regex(.{0,9}$)}"

Variable ${time}

Verfügbar an allen Erweiterungspunkten – wird zum Zeitpunkt der Ausführung der Aktion ersetzt.

Lokale Ressourcen — ${custo.path}

So verteilen Sie ein Manifest mit lokalen Dateien (Symbole, statische Inhalte):

1. Verweisen Sie auf jede Ressource als ${custo.path}\\Dateiname.ext
2. Packen Sie die Datei „custo-manifest.json“ und die Ressourcendateien in eine ZIP-Datei (das Manifest im Stammverzeichnis)

{
"icon": "${custo.path}\\crm.png",
"command": {
"commandType": "file",
"url": "${custo.path}\\content.txt"
},
"responseType": "markdown"
}

Erweiterungsspezifische Felder

Einbinden lokaler Ressourcen (ZIP-Archiv)

Falls die Aktion auf lokale Dateien (Symbole oder Anzeigedateien) verweist, packen Sie die Datei „custo-manifest.json“ zusammen mit diesen Dateien vor dem Import in ein ZIP-Archiv.

Erforderliche ZIP-Struktur – die Manifestdatei muss sich im Stammverzeichnis befinden:

my-manifest.zip
├── custo-manifest.json
├── icon.png
└── display-content.txt

Bereitstellung des Manifests

Sobald das Manifest konfiguriert ist, stellen Sie es über die Rainbow-Verwaltungskonsole oder lokal bereit. Siehe „Bereitstellen eines custo-manifest in Rainbow“.

Beispiele für die Konfiguration

Schaltflächen

Unterstützt von Rainbow Desktop und Rainbow Web – erfordert CORS für REST-Aufrufe.

Beispiel 1 – „on-contact-list-actions“ fügt in jeder Kontaktzeile eine Schaltfläche hinzu, die den Kontakt in einem externen CRM öffnet (kein Popup innerhalb von Rainbow):

{
"version": "2",
"jsonType": "Rainbow-custo-manifest",
"extension-points": {
"on-contact-list-actions": [
{
"name": "In CRM öffnen",
"tooltip": "Diesen Kontakt in unserem CRM anzeigen",
"icon": "${custo.path}\\crm.png",
"command": {
"url": "https://crm.example.com/contact",
"params": "email=${contact.email}&phone=${contact.phoneNumber}"
}
}
]
}
}

Beispiel 2 – „on-incoming-pbx-call-button-actions“ fügt dem Popup-Fenster für eingehende Anrufe eine Schaltfläche hinzu, mit der Sie mit einem Klick ein Ticket erstellen und den Anruf annehmen können:

{
"version": "2",
"jsonType": "Rainbow-custo-manifest",
"extension-points": {
"on-incoming-pbx-call-button-actions": [
{
"name": "Ticket erstellen & annehmen",
"AnswerOnClick": true,
"command": {
"commandType": "rest",
"method": "POST",
"url": "https://tickets.example.com/api/tickets",
"header": [
„Authorization: Bearer TOKEN“,
"Content-Type: application/json"
],
"bodyParameters": {
"caller": "${caller.phoneNumber}",
"callId": "${call.callId}",
"createdBy": "${localUser.loginEmail}"
}
}
}
]
}
}

Anzeigen

Unterstützt von Rainbow Desktop und Rainbow Web – erfordert CORS für REST-Aufrufe.

Beispiel 1 – „on-incoming-pbx-call-display-actions“ zeigt automatisch eine Markdown-Karte mit der Anrufer-ID im Popup-Fenster für eingehende Anrufe an:

{
"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 TOKEN"]
},
"responseType": "markdown"
}
]
}
}

Beispiel 2 – „on-main-widget-display-actions“ zeigt ein Adaptive-Card-Widget im Rainbow-Hauptbereich an, das bei jedem Öffnen aktualisiert wird:

{
"version": "2",
"jsonType": "Rainbow-custo-manifest",
"extension-points": {
"on-main-widget-display-actions": [
{
"name": "Meine Tickets",
"command": {
"commandType": "rest",
"method": "GET",
"url": "https://api.example.com/tickets/me",
"header": ["Authorization: Bearer TOKEN"]
},
"responseType": "adaptiveCard",
"adaptiveCardTemplateJsonField": "card",
„adaptiveCardContentJsonField“: „data“,
„adaptiveCardSubmitUrl“: „https://api.example.com/tickets/submit“
}
]
}
}

Anzeige im Frame

Unterstützt von Rainbow Desktop und Rainbow Web.

Beispiel 1 – „on-main-window-actions“ bettet ein CRM-Dashboard in das Rainbow-Hauptfenster ein:

{
"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}"
}
}
]
}
}

Beispiel 2 – identisch, jedoch mit „Popup: true“, um das Fenster in einem Browserfenster zu öffnen (nützlich, wenn die App die Einbettung in Iframes nicht zulässt):

{
"version": "2",
"jsonType": "Rainbow-custo-manifest",
"extension-points": {
"on-main-window-actions": [
{
"name": "Externe Berichterstellung",
"icon": "${custo.path}\\report.png",
"Popup": true,
"command": {
"url": "https://reporting.example.com/",
"params": "user=${localUser.loginEmail}"
}
}
]
}
}