251 lines
9.8 KiB
Markdown
251 lines
9.8 KiB
Markdown
# 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](https://nodejs.org/) 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)**
|
|
|
|
```bash
|
|
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
|
|
# 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
|
|
# 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
|
|
# 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
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Development Server starten
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Startet einen lokalen HTTPS-Server auf `https://localhost:3000` mit einem Dev-Zertifikat (nur für Entwicklung).
|
|
|
|
### Production Build
|
|
|
|
```bash
|
|
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.
|