Starface Kontakt-Sync - Outlook Add-in

Outlook Add-in zur bidirektionalen Synchronisation von Kontakten zwischen Microsoft Outlook und einer Starface Telefonanlage.

Funktionen

• Bidirektionale Synchronisation von Kontakten zwischen Outlook und Starface
• Profil-System zum Verwalten mehrerer Sync-Konfigurationen (z.B. verschiedene Adressbücher oder Anlagen)
• Starface-Adressbücher: Zentrales Adressbuch, persönliches Adressbuch und Tag-basierte Adressbücher
• Outlook-Kontaktordner: Frei wählbarer Kontaktordner als Sync-Ziel
• Sync-Richtung konfigurierbar: Outlook → Starface, Starface → Outlook oder bidirektional
• Intelligentes Matching: Kontakte werden anhand von E-Mail-Adresse oder Name abgeglichen
• Änderungserkennung: Nur geänderte Kontakte werden übertragen (Hash-basiert)
• Kompatibel mit Outlook Classic und dem neuen Outlook (Office Web Add-in)
• Einfacher Installer mit automatischer Zertifikatskonfiguration

Voraussetzungen

• Node.js ab Version 18 (LTS empfohlen)
• npm (wird mit Node.js mitgeliefert)
• Microsoft Outlook (Classic oder Neu)
• Starface Telefonanlage ab Version 6.7 (REST-API)
• Windows 10/11 (für den Installer)

Installation beim Kunden

Schnellinstallation (empfohlen)

Der Installer richtet alles automatisch ein: Zertifikate, lokaler Webserver, Outlook-Registrierung.

Schritt 1: Add-in bauen (einmalig, auf dem Entwickler-PC)

npm install
npm run build

Schritt 2: Installer-Paket zum Kunden mitnehmen

Folgende Dateien/Ordner werden benötigt:

installer/
├── setup.ps1           # Installations-Script
├── uninstall.ps1       # Deinstallations-Script
├── local-server.js     # Lokaler HTTPS-Webserver
dist/                   # Build-Ausgabe (von Schritt 1)

Schritt 3: Beim Kunden ausführen (als Administrator)

# PowerShell als Administrator öffnen, dann:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\installer\setup.ps1

Das Setup fragt interaktiv ab:

Abfrage	Beispiel	Beschreibung
Starface Host/IP	192.168.1.100	IP-Adresse oder Hostname der Starface (nur für Zertifikat-Import)
Starface HTTPS-Port	443	Standard: 443
Lokaler Port	444	Port für den lokalen Webserver (Standard: 444)

Hinweis: Login-Daten werden beim Setup nicht benötigt. Diese werden später im Add-in selbst in den Sync-Profilen konfiguriert.

Was macht das Setup?

1. Starface-Zertifikat importieren - Verbindet sich zur Starface, extrahiert das SSL-Zertifikat und importiert es als vertrauenswürdig in den Windows-Zertifikatspeicher. Damit funktionieren die API-Aufrufe vom Add-in zur Starface.

2. Lokale Zertifikate erstellen - Erstellt eine lokale CA und ein davon signiertes localhost-Zertifikat. Die CA wird als vertrauenswürdig importiert. Damit läuft der lokale Webserver mit gültigem HTTPS.

3. Lokalen Webserver einrichten - Installiert einen minimalen Node.js HTTPS-Server als Windows Scheduled Task. Der Server startet automatisch beim Systemstart und liefert nur die statischen Add-in Dateien über https://localhost:444 aus.

4. Outlook Add-in registrieren - Registriert das Add-in automatisch für Outlook Classic (per Registry). Für das neue Outlook wird eine Anleitung zur manuellen Einrichtung angezeigt.

Nach der Installation

• Outlook Classic: Outlook neu starten. Im Ribbon erscheint der Button "Kontakt-Sync" in der Gruppe "Starface Sync".
• Neues Outlook: Manuell hinzufügen über Einstellungen → Add-Ins verwalten → Benutzerdefinierte Add-Ins → Aus Datei hinzufügen → C:\Program Files\StarfaceOutlookSync\manifest-catalog\manifest.xml

Deinstallation

# PowerShell als Administrator:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\uninstall.ps1
# oder direkt aus dem Installationsverzeichnis:
& "C:\Program Files\StarfaceOutlookSync\uninstall.ps1"

Die Deinstallation entfernt:

• Den lokalen Webserver (Scheduled Task)
• Die lokale CA und das localhost-Zertifikat
• Die Outlook-Registrierung
• Alle installierten Dateien

Das Starface-Zertifikat wird nicht entfernt, da es ggf. von anderen Anwendungen benötigt wird.

Weitere Starface-Anlagen hinzufügen

Wenn im Add-in ein Sync-Profil zu einer weiteren Starface-Anlage eingerichtet wird, deren Zertifikat noch nicht importiert ist, schlägt der Verbindungstest fehl. Das Add-in zeigt dann einen entsprechenden Hinweis an.

Um das Zertifikat einer weiteren Anlage zu importieren:

# PowerShell als Administrator:
cd "C:\Program Files\StarfaceOutlookSync"
.\import-cert.ps1 -StarfaceHost 192.168.2.200
# oder mit anderem Port:
.\import-cert.ps1 -StarfaceHost pbx2.firma.local -Port 8443

Danach funktioniert die Verbindung im Add-in sofort - kein Neustart nötig.

Entwicklung

Dependencies installieren

npm install

Development Server starten

npm run dev

Startet einen lokalen HTTPS-Server auf https://localhost:3000 mit einem Dev-Zertifikat (nur für Entwicklung).

Production Build

npm run build

Die fertigen Dateien liegen anschließend im Ordner dist/.

Manuelles Sideloading (zum Testen)

1. npm run dev starten
2. In Outlook: Datei → Add-Ins verwalten → Meine Add-Ins → "Benutzerdefiniertes Add-In hinzufügen" → manifest.xml auswählen

Benutzung

1. In Outlook auf den Button "Kontakt-Sync" in der Ribbon-Leiste klicken
2. Ein neues Sync-Profil anlegen:
   • Profilname vergeben (z.B. "Firmenkontakte Hauptanlage")
   • Starface-Verbindung konfigurieren: Host/IP, Port, Login-ID und Kennwort eingeben
   • Verbindung testen um die Zugangsdaten zu prüfen
   • Adressbücher laden um die verfügbaren Starface-Adressbücher abzurufen
   • Starface-Adressbuch auswählen (Zentral, Persönlich oder Tag)
   • Outlook-Kontaktordner auswählen
   • Synchronisationsrichtung festlegen
3. Profil speichern
4. Über "Jetzt synchronisieren" die Kontakte abgleichen

Es können beliebig viele Profile angelegt werden, auch für unterschiedliche Starface-Anlagen.

Projektstruktur

outlook-sync/
├── manifest.xml                  # Office Add-in Manifest
├── package.json                  # Dependencies & Scripts
├── webpack.config.js             # Build-Konfiguration
├── assets/                       # Add-in Icons
├── dist/                         # Build-Ausgabe
├── installer/
│   ├── setup.ps1                 # Installations-Script
│   ├── uninstall.ps1             # Deinstallations-Script
│   ├── import-cert.ps1           # Zertifikat-Import für weitere Anlagen
│   └── local-server.js           # Lokaler HTTPS-Webserver
└── src/
    ├── models/
    │   └── types.ts              # Datenmodelle
    ├── services/
    │   ├── starface-api.ts       # Starface REST API Client
    │   ├── outlook-contacts.ts   # Outlook REST API Client
    │   ├── sync-engine.ts        # Sync-Logik
    │   └── profile-manager.ts    # Profilverwaltung
    └── taskpane/
        ├── index.tsx             # Entry Point
        ├── taskpane.html         # HTML Template
        ├── styles/taskpane.css   # Styling
        └── components/
            ├── App.tsx           # Hauptkomponente
            ├── ProfileList.tsx   # Profilübersicht
            ├── ProfileEditor.tsx # Profil-Editor
            └── SyncView.tsx      # Sync-Ansicht

Synchronisierte Kontaktfelder

Feld	Outlook	Starface
Vorname	GivenName	NAME
Nachname	Surname	SURNAME
Firma	CompanyName	COMPANY
Position	JobTitle	JOB_TITLE
E-Mail	EmailAddresses	EMAIL
Telefon (Büro)	Business Phone	OFFICE_PHONE_NUMBER
Mobiltelefon	Mobile Phone	MOBILE_PHONE_NUMBER
Telefon (Privat)	Home Phone	PRIVATE_PHONE_NUMBER
Fax	Business Fax	FAX_NUMBER
Straße	Street	STREET
Stadt	City	CITY
PLZ	PostalCode	POSTAL_CODE
Bundesland	State	STATE
Land	CountryOrRegion	COUNTRY
Webseite	Websites	URL
Notizen	PersonalNotes	NOTE
Anrede	Title	SALUTATION
Titel	—	TITLE
Geburtstag	Birthday	BIRTHDAY

Technische Details

Architektur

Das Add-in ist ein Office Web Add-in (funktioniert in Classic und New Outlook). Outlook lädt das Add-in als Webseite in einem eingebetteten Browser (WebView). Die Webseite kommuniziert dann direkt mit der Starface REST-API und der Outlook REST-API:

Outlook
  └── WebView (eingebetteter Browser)
        ├── Lädt UI von:         https://localhost:444  (lokaler Webserver)
        ├── Spricht direkt mit:  Starface REST-API
        └── Spricht direkt mit:  Outlook REST-API (Office.js)

Zertifikate

Der lokale Webserver und die Starface verwenden HTTPS. Da die Starface typischerweise ein self-signed Zertifikat hat und der lokale Webserver ebenfalls ein lokales Zertifikat braucht, erstellt das Setup:

• Importiert das Starface-Zertifikat in den Windows Trusted Root Store → Outlook/WebView vertraut den API-Aufrufen zur Starface
• Erstellt eine lokale CA → wird in den Trusted Root Store importiert
• Erstellt ein localhost-Zertifikat, signiert von der lokalen CA → der lokale Webserver hat gültiges HTTPS

Datenspeicherung

• Sync-Profile: localStorage im Outlook WebView
• Sync-Mappings: localStorage im Outlook WebView (Zuordnung Outlook-ID ↔ Starface-ID)
• Server-Konfiguration: C:\Program Files\StarfaceOutlookSync\config.json
• Zugangsdaten: Werden nur im Add-in (localStorage) gespeichert, nicht auf dem Dateisystem

Lizenz

Proprietär - Alle Rechte vorbehalten.