Hacker-Software
/
starface-outlook-sync-addin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 22 Wiki Activity
starface-outlook-sync-addin/README.md

9.8 KiB
Raw Blame History

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.