os4k2excel - OpenScape 4000 Port & Lizenz Export

Version: M29.20260324.1807

Beschreibung

PowerShell-basiertes ETL-Tool zum Extrahieren von Port-, Lizenz- und Rufumleitungsdaten aus dem Unify OpenScape 4000 Telefonsystem. Die Daten werden verarbeitet und als formatierter Excel-Report mit mehreren Arbeitsblättern exportiert.

Voraussetzungen

System

Komponente	Version	Beschreibung
Windows	10 / 11 / Server 2016+	Betriebssystem
PowerShell	5.1+	Windows PowerShell (in Windows enthalten)
.NET Framework	4.5+	Wird von PowerShell 5.1 und ImportExcel vorausgesetzt (in Windows enthalten)

PowerShell-Module

ImportExcel — Erzeugt Excel-Dateien ohne installiertes Microsoft Office (basiert auf EPPlus/OfficeOpenXml).

Online-Installation (mit Internetverbindung):

Install-Module -Name ImportExcel -Scope CurrentUser

Bei der ersten Installation wird ggf. nach der Berechtigung gefragt, das NuGet-Paket zu installieren und dem PSGallery-Repository zu vertrauen. Beides mit Y bestätigen.

Offline-Installation (PC ohne Internet):

# 1. Auf einem PC MIT Internet herunterladen:
Save-Module -Name ImportExcel -Path "C:\Temp\PSModules"

# 2. Ordner "ImportExcel" per USB-Stick auf den Ziel-PC kopieren nach:
#    - Aktueller Benutzer: %USERPROFILE%\Documents\WindowsPowerShell\Modules\
#    - Alle Benutzer (Admin): C:\Program Files\WindowsPowerShell\Modules\

Alternativ kann die .nupkg-Datei manuell von der PowerShell Gallery heruntergeladen werden (Tab "Manual Download"), in .zip umbenannt und entpackt werden.

Installierte Version prüfen:

Get-Module -ListAvailable ImportExcel | Select-Object Name, Version

Update (Online):

Update-Module -Name ImportExcel

Update (Offline): Neue Version erneut mit Save-Module herunterladen, alte Dateien im Modulpfad ersetzen.

Alte Versionen aufräumen: Nach Update-Module bleibt die alte Version parallel installiert. Diese kann entfernt werden:

# Alte Version gezielt deinstallieren (Versionsnummer anpassen!)
Uninstall-Module -Name ImportExcel -RequiredVersion 7.8.9

Detaillierte Schritt-für-Schritt Anleitung: siehe Wiki — Installation

Externe Software

api2hipath.exe - Kommandozeilen-Tool von Unify/Mitel zum Zugriff auf die OpenScape 4000 Datenbank via XIE (Import/Export) API.

Eigenschaft	Details
Hersteller	Unify / Mitel
Bestandteil von	OpenScape 4000 Assistant / Manager V11
Standardpfad	C:\Program Files (x86)\Unify\OpenScape 4000 Export Table\api2hipath.exe
Installation	Wird mit dem OpenScape 4000 Assistant/Manager installiert. Nicht separat verfügbar.
Dokumentation	OpenScape 4000 Assistant/Manager V11, Import/Export (XIE) API, Service Documentation (P31003-H34B0-S102-02-0020, 08/2024) — Mitel Document Center: DE | EN

Das Tool muss auf dem Rechner installiert sein, auf dem das Skript ausgefuehrt wird, und Netzwerkzugriff auf den OpenScape 4000 Server haben.

Aufruf

# Standardaufruf mit allen Parametern
.\os4k2excel.ps1 -ApiHost "<IP>" -ApiUser "<BENUTZER>" -ApiPassword "<PASSWORT>" -OutputPath "C:\script"

# Mit Duplikats-Markierung (orange Hervorhebung doppelter PENs)
.\os4k2excel.ps1 -ApiHost "<IP>" -ApiUser "<BENUTZER>" -ApiPassword "<PASSWORT>" -MarkDuplicate

Parameter

Parameter	Pflicht	Beschreibung
-ApiHost	Ja	IP-Adresse des OpenScape 4000
-ApiUser	Ja	API-Benutzername
-ApiPassword	Ja	API-Passwort
-ApiPath	Nein	Pfad zu api2hipath.exe
-OutputPath	Nein	Zielverzeichnis (Standard: Skriptverzeichnis)
-MarkDuplicate	Nein	Switch: Doppelte PENs im Gesamt-Tab orange markieren
-ShowSecrets	Nein	Switch: SIP-Secrets im Klartext exportieren (Standard: maskiert als ***)
-IncludePenData	Nein	Switch: PEN/HVT-Daten abfragen und exportieren (Hauptverteiler-Zuordnung)
-Debug	Nein	Switch: Detaillierte Diagnose-Ausgaben ins Log schreiben

Funktionsweise (ETL-Pipeline)

1. Extract (Datenextraktion)

Das Skript ruft via api2hipath.exe folgende Tabellen aus der OpenScape 4000 ab:

• SWITCH - Verfügbare Switches mit Domain-Zuordnung
• NUMBERING_PLAN - Rufnummernplan
• CFW - Rufumleitungen (Call Forwarding)
• HUNTGRP - Sammelanschluss-Gruppen
• HUNTGRP_SERVICE - Sammelanschluss-Dienste
• PICKUPGRP - Rufannahmegruppen
• PICKUP_SUB - Mitglieder der Rufannahmegruppen
• PERSPORT - Port-Verbindungstypen
• DEVCONST - Gerätekonfigurationen

Zusätzlich wird pro Standort (Domain/Switch) die PORT-Tabelle abgerufen.

Optional (mit -IncludePenData):

• PEN - Physical Equipment Numbers mit HVT-Zuordnung (Hauptverteiler)

2. Standort-Erkennung (automatisch)

Die Domain/Switch-Kombinationen werden automatisch aus der SWITCH-Tabelle ermittelt (Felder domain + switch_name). Es ist keine manuelle Konfiguration der Standorte notwendig.

3. Transform (Datenverarbeitung)

• Verknüpfung aller Tabellen über Hashtable-Lookups (Domain + Switch + Key)
• Mapping von Codes auf lesbare Werte (z.B. 841 -> CFU, i90 -> VOICE)
• Lizenzberechnung mit Flex/TDM-Aufteilung

4. Load (Excel-Export)

Export in eine Excel-Datei mit folgenden Arbeitsblättern:

Arbeitsblatt	Inhalt
{Domain}-{Switch}	Port-Daten pro Standort mit Lizenz-Summen
Gesamt	Alle Standorte zusammengefasst
Lizenz Dashboard	Zusammenfassung Flex- vs. TDM-Lizenzen pro Standort
Sammelanschluss	Hunting-Groups mit Auto-Fill Displaynames
NumberingPlan	Rufnummernplan
Devconst	Gerätekonfigurationen
HVT	Hauptverteiler-Zuordnung aller PENs (nur mit -IncludePenData)

Lizenzberechnung

Basis-Wert je Port

Bedingung	Lizenzwert
PEN leer	null (keine Lizenz)
Gerätetyp RADIO oder EXTLINE	0
Gerätetyp BASEST	4
Gerätetyp SET600	2
Sonstige	1

Flex vs. TDM Aufteilung

Verbindungstyp	Zuordnung
IP2 (Code 268)	Flex_Lizenz
Alle anderen	TDM_Lizenz

Ausgabedateien

Alle Dateien werden im OutputPath mit Datumsstempel erzeugt:

• OS4K-PORT-YYYY-MM-DD.xlsx - Hauptreport
• OS4K-PORT-YYYY-MM-DD.log - Ausführungsprotokoll
• OS4K-{TABELLE}-YYYY-MM-DD.csv - Zwischendateien der API-Abfragen

Webserver

Das Script os4k2excel-server.ps1 stellt eine Weboberflaeche bereit, ueber die der Export per Browser gestartet, ueberwacht und heruntergeladen werden kann.

Aufruf

# Minimal
.\os4k2excel-server.ps1 -ApiHost "<IP>" -ApiUser "<USER>" -ApiPassword "<PW>" -WebPassword "<WEBPW>"

# Mit Email-Versand und Standard-Empfaenger
.\os4k2excel-server.ps1 -ApiHost "<IP>" -ApiUser "<USER>" -ApiPassword "<PW>" -WebPassword "<WEBPW>" -SmtpServer "mail.firma.de" -SmtpFrom "os4k@firma.de" -SmtpTo "admin@firma.de"

Dann im Browser: http://servername:8080

Webserver-Parameter

Parameter	Pflicht	Beschreibung
-ApiHost	Ja	IP-Adresse des OpenScape 4000
-ApiUser	Ja	API-Benutzername
-ApiPassword	Ja	API-Passwort
-WebPassword	Ja	Passwort fuer die Web-Anmeldung
-Port	Nein	HTTP-Port (Standard: 8080)
-OutputPath	Nein	Zielverzeichnis (Standard: Skriptverzeichnis)
-SmtpServer	Nein	SMTP-Server fuer Email-Versand
-SmtpPort	Nein	SMTP-Port (Standard: 25)
-SmtpFrom	Nein	Absender-Adresse fuer Emails
-SmtpTo	Nein	Standard-Empfaenger (wird im Dashboard vorausgefuellt)

Funktionen

• Login - Passwortgeschuetzter Zugang mit Session-Cookie (60 Min. Timeout)
• Dashboard - Verbindungsinfo, Start-Button, Fortschrittsanzeige
• Export starten - Startet os4k2excel.ps1 als Background-Job (nur ein Lauf gleichzeitig)
• Fortschritt - Live-Anzeige mit Polling alle 2 Sekunden
• Download - Excel-Datei nach Abschluss direkt herunterladen
• Email - Excel als Attachment per SMTP versenden (optional)
• Zeitplaner - Automatische Ausfuehrung nach Wochentag und Uhrzeit, optional mit Email-Versand
• History - Uebersicht der letzten Ausfuehrungen (manuell/Zeitplaner)

Server beenden

Es gibt drei Moeglichkeiten den Server zu beenden:

1. Ctrl+C im Terminal-Fenster
2. Dashboard > "Server beenden" Button (oben rechts)
3. Stop-Datei aus einem anderen Terminal erstellen:

   echo.> "C:\pfad\os4k2excel-server.stop"

Port-Freigabe (nicht-Admin)

Falls der Server ohne Administratorrechte gestartet wird, muss einmalig als Admin ausgefuehrt werden:

netsh http add urlacl url=http://+:8080/ user=DOMAIN\USERNAME

Change History

Datum	Änderung
2025-06-30	Initiale Version
2025-11-28	Fixes (Lizenz, XML-Fehler, Farben)
2025-11-28	Sammelanschluss Auto-Fill Name (Master) + Graue Schrift
2025-12-05	Trennung Flex vs. TDM Lizenzen + Dashboard Erweiterung
2026-02-15	Standorte automatisch aus SWITCH-Tabelle (API), DOMAIN/SWITCH-Tabellen hinzugefügt, Entfernung kundenspezifischer Referenzen
2026-02-15	Webserver (os4k2excel-server.ps1) mit Login, Dashboard, Fortschritt, Download und Email-Versand
2026-03-10	PICKUPGRP und PICKUP_SUB Tabellen-Extraktion, verbesserte Logging-Struktur mit Phasen-Header, diagnostische Ausgaben mit -Debug Parameter
2026-03-17	PEN/HVT-Zuordnung via -IncludePenData (OS4K-4): HVT-Sheet, HVT-Spalten in Standort-/Gesamt-Sheets, vollständiges Board-Typ-Mapping (80+ Typen), DOMAIN-Tabelle entfernt (nicht funktional genutzt)