os4k2excel

Export port, license and call-forwarding data from a Unify OpenScape 4000 / HiPath 4000 PBX to Excel.

PowerShell ETL tool. It queries the OpenScape 4000 database through the XIE Import/Export API (api2hipath.exe), joins the tables, calculates the license split and writes a formatted multi-sheet Excel workbook. A web interface for running the export from a browser is included.

Runs on Windows PowerShell 5.1 and PowerShell 7.x. Microsoft Excel is not required — the workbook is written through the ImportExcel module (EPPlus).

Deutschsprachige Kurzfassung weiter unten, vollständige deutsche Dokumentation im Wiki.

irm https://raw.githubusercontent.com/bhuertgen/os4k2excel/main/install.ps1 | iex

Installs into %LOCALAPPDATA%\Programs\os4k2excel, adds that folder to the user PATH and installs the ImportExcel module if it is missing.

With options:

$u = 'https://raw.githubusercontent.com/bhuertgen/os4k2excel/main/install.ps1'
& ([scriptblock]::Create((irm $u))) -InstallDir 'C:\Tools' -NoPath

Run the installer again over an existing installation — that is the intended update path. It overwrites the scripts, reports the version change (updated M29… -> M30…) and does not create a duplicate PATH entry.

# update to the current development state
irm https://raw.githubusercontent.com/bhuertgen/os4k2excel/main/install.ps1 | iex

# pin to a release instead — recommended for production
$u = 'https://raw.githubusercontent.com/bhuertgen/os4k2excel/main/install.ps1'
& ([scriptblock]::Create((irm $u))) -Ref v30.0

An already installed ImportExcel module is left untouched unless you pass -UpdateModule.

Many corporate machines restrict running downloaded scripts. The tool works without the installer — it has no dependencies apart from ImportExcel.

# single file
$url = 'https://raw.githubusercontent.com/bhuertgen/os4k2excel/main/os4k2excel.ps1'
Invoke-WebRequest -Uri $url -OutFile .\os4k2excel.ps1 -UseBasicParsing
Unblock-File .\os4k2excel.ps1

# or the whole repository
git clone https://github.com/bhuertgen/os4k2excel.git

If execution is blocked:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# or, without a permanent change
powershell -ExecutionPolicy Bypass -File .\os4k2excel.ps1 -ApiHost <host> -ApiUser <user>

Full step-by-step guide: Wiki — Installation (EN) · Installation (DE)

Script and installer are verified on both editions — same data, same workbook:

PowerShell 7 is the better choice for production: the exit code of api2hipath.exe is reported correctly and redirected console output stays readable. On 5.1 the result is functionally equivalent — details in PowerShell compatibility.

The two editions use separate module directories. Install-Module ImportExcel in one does not install it for the other; if you switch editions, install the module twice.

Command line tool by Unify/Mitel that accesses the OpenScape 4000 database through the XIE (Import/Export) API.

The tool must be installed on the machine running the script and needs network access to the OpenScape 4000 server.

Offline installation of ImportExcel (machine without internet):

# on a machine WITH internet
Save-Module -Name ImportExcel -Path C:\Transfer
# copy the ImportExcel folder to the target machine, into
#   %USERPROFILE%\Documents\WindowsPowerShell\Modules   (PowerShell 5.1)
#   %USERPROFILE%\Documents\PowerShell\Modules          (PowerShell 7.x)

# standard run
.\os4k2excel.ps1 -ApiHost "<IP>" -ApiUser "<USER>" -ApiPassword "<PASSWORD>" -OutputPath "C:\script"

# highlight duplicate PENs in orange
.\os4k2excel.ps1 -ApiHost "<IP>" -ApiUser "<USER>" -ApiPassword "<PASSWORD>" -MarkDuplicate

-ApiPassword may be given without a value, or left out entirely — either way the script prompts for it, masked. -ApiUser is prompted for as well when missing:

.\os4k2excel.ps1 -ApiHost "<IP>" -ApiUser "<USER>" -ApiPassword -ShowSecrets
.\os4k2excel.ps1 -ApiHost "<IP>"

Working at a customer site? The password is passed to api2hipath.exe on the command line, because the tool accepts it no other way. It is therefore readable in the process list while a query runs — no administrator rights needed. Let the customer type the password themselves, and use a read-only account whose password is rotated afterwards. See Security · Sicherheit.

The script queries these tables through api2hipath.exe:

Domain/switch combinations are discovered automatically from the SWITCH table (domain + switch_name). No manual site configuration is needed.

• joins all tables through hashtable lookups (domain + switch + key)
• maps codes to readable values (for example 841 → CFU, i90 → VOICE)
• calculates the license split between Flex and TDM

Base value per port:

Flex vs. TDM split:

Written to OutputPath, stamped with the current date:

• OS4K-PORT-YYYY-MM-DD.xlsx — main report
• OS4K-PORT-YYYY-MM-DD.log — execution log
• OS4K-{TABLE}-YYYY-MM-DD.csv — intermediate files of the API queries

These files contain extension numbers, subscriber names and system identifiers of a live PBX. The .gitignore of this repository excludes them; keep them out of any repository or shared location.

os4k2excel-server.ps1 provides a web interface to start, monitor and download the export from a browser.

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

# with e-mail delivery and a default recipient
.\os4k2excel-server.ps1 -ApiHost "<IP>" -ApiUser "<USER>" -ApiPassword "<PW>" -WebPassword "<WEBPW>" `
    -SmtpServer "mail.example.com" -SmtpFrom "os4k@example.com" -SmtpTo "admin@example.com"

Then open http://servername:8080 in a browser.

Features: password-protected login with session cookie (60 min timeout), dashboard with connection info and progress display, export as a background job (one run at a time), live progress polling every 2 seconds, direct download, optional e-mail delivery of the workbook, scheduler by weekday and time, and a history of recent runs.

Stopping the server — three ways: Ctrl+C in the terminal, the Server beenden button in the dashboard, or creating the stop file from another terminal:

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

Port reservation without admin rights — run once as administrator:

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

PowerShell-Werkzeug, das Port-, Lizenz- und Rufumleitungsdaten aus einer Unify OpenScape 4000 über die XIE-API (api2hipath.exe) ausliest und als formatierten Excel-Report mit mehreren Arbeitsblättern exportiert. Die Standorte werden automatisch aus der SWITCH-Tabelle erkannt, die Lizenzen nach Flex und TDM getrennt ausgewiesen. Ein Webserver für den Aufruf über den Browser liegt bei.

# Installation
irm https://raw.githubusercontent.com/bhuertgen/os4k2excel/main/install.ps1 | iex

# Aufruf — Passwort wird maskiert abgefragt
.\os4k2excel.ps1 -ApiHost "<IP>" -ApiUser "<BENUTZER>"

Voraussetzungen: Windows PowerShell 5.1 oder PowerShell 7.x — beide getestet (5.1.26100.8875 und 7.6.4), das Modul ImportExcel (wird vom Installer eingerichtet) und api2hipath.exe aus dem OpenScape 4000 Assistant/Manager. Microsoft Excel wird nicht benötigt.

Beim Kunden vor Ort: api2hipath.exe nimmt das Passwort ausschließlich über die Kommandozeile entgegen. Es ist deshalb während einer laufenden Abfrage in der Prozessliste lesbar — ohne Administratorrechte. Empfehlung: den Kunden das Passwort selbst eingeben lassen und ein Konto mit reinen Leserechten verwenden, dessen Passwort danach gewechselt wird. Details unter Sicherheit.

Vollständige deutsche Dokumentation: Wiki (DE) — Installation · Aufruf und Parameter · ETL-Pipeline · Lizenzberechnung · Webserver · API-Parameter · Sicherheit · PowerShell 5.1 / 7.x

• os4k-wabe2excel — dial plan of an OpenScape 4000 to Excel: free, assigned and undefined extension numbers from AMO WABE
• Estos-Location-Rules-Synchronizer — keeps the cross-site number resolution in Estos ProCall in sync with an OpenScape 4000

OpenScape 4000, HiPath 4000, Unify, Atos, Mitel, XIE API, api2hipath, Export Table Client, port list, license report, license count, Flex license, TDM license, call forwarding, hunt group, pickup group, numbering plan, PEN, MDF, main distribution frame, PBX inventory, PBX audit, telephony reporting — Rufumleitung, Sammelanschluss, Rufannahmegruppe, Rufnummernplan, Lizenzzählung, Hauptverteiler, Portliste, TK-Anlage, Telefonanlage, Anlagendokumentation.

MIT — see LICENSE.

Not affiliated with Unify, Mitel or Atos. OpenScape and HiPath are trademarks of their respective owners.