Export-/Import-Formate

Admin Power Pack exportiert Ruflisten und Adressbücher in dokumentierten, wieder einlesbaren Dateiformaten. Drittsysteme können diese Dateien auswerten (Abrechnung, Archivierung, DMS/BI) oder selbst erzeugen, um Daten in eine STARFACE zu übernehmen — etwa beim Anlagenwechsel oder für Testdaten. Ausgelöst werden Export und Import über die Moduloberfläche; die Formate selbst sind der stabile Vertrag dieser Schnittstelle.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Typ: Datei-Export/-Import (ZIP bzw. CSV)
• Zugang: Tab STARFACE Verwaltung, Karte Archivieren & Wiederherstellen — Kachel Ruflisten bzw. Adressbücher. Der Adressbuch-Export lässt sich alternativ direkt per E-Mail versenden.
• Authentifizierung: Anmeldung an der Moduloberfläche als STARFACE-Benutzer mit Administrationsrecht; Export und Import erfordern eine gültige Modullizenz (beim Adressbuch-Import ist die Analysephase lizenzfrei).
• Verfügbar seit: Ruflisten-Export/-Import Modulversion 26.6.2, Adressbuch-Export/-Import Modulversion 26.6.12

Formate

Ruflisten-ZIP (cdrsummary.csv, cdrdata.csv)

Der Export erzeugt ein ZIP-Archiv ruflisten-export-<JJMMTT-HHMMSS>.zip mit ein oder zwei CSV-Dateien:

Datei	Inhalt	Enthalten
cdrsummary.csv	Rufliste/Journal — eine Zeile je Anruf, einschließlich der denormalisierten Namen und Kommentare	immer
cdrdata.csv	Detailebene — mehrere Zeilen je Anruf (einzelne Rufschritte, callstepid)	wählbar beim Export

Der Export ist nicht destruktiv (es wird nichts gelöscht) und lässt sich beim Erzeugen auf einen Zeitraum eingrenzen (Gesprächsbeginn starttime, einschließlich). Zeilen beider Dateien gehören über die Spalte callid zusammen; die Primärschlüssel id sind dafür ohne Bedeutung.

CSV-Dialekt (RFC 4180): Trennzeichen Komma, Zeilenende \n, Kodierung UTF-8 ohne BOM. Felder mit Komma, Anführungszeichen oder Zeilenumbruch stehen in doppelten Anführungszeichen, enthaltene Anführungszeichen werden verdoppelt. Die Kopfzeile enthält die Spaltennamen in Kleinschreibung. Leere Felder entsprechen NULL, Wahrheitswerte true/false, Zeitstempel-Spalten sind Unix-Zeiten in Millisekunden, duration ist die Gesprächsdauer in Sekunden.

Der Spaltensatz entspricht dem nativen Tabellenschema der installierten STARFACE-Version — der Export übernimmt automatisch Schema-Erweiterungen künftiger STARFACE-Versionen. Stand STARFACE 10:

cdrsummary.csv (42 Spalten, in Dateireihenfolge):

Spalte	Typ	Bedeutung
id	Ganzzahl	Primärschlüssel der Zeile; beim Import ignoriert und neu vergeben
callid	Ganzzahl	Anruf-Kennung — verknüpft cdrsummary mit den cdrdata-Zeilen desselben Anrufs
callleguuid	Text	UUID des Rufabschnitts
cdraccountid	Ganzzahl	Konto, zu dessen Rufliste der Eintrag gehört (Verweis auf die Konto-ID, ohne Fremdschlüssel)
calleraccountid	Ganzzahl	Konto des Anrufers; 0/leer bei externen Anrufern
callercallerid	Text	übermittelte Caller-ID des Anrufers
callernumber	Text	Rufnummer des Anrufers
callername	Text	Anzeigename des Anrufers (denormalisiert gespeichert)
calledaccountid	Ganzzahl	Konto des Angerufenen
calledcallerid	Text	übermittelte Caller-ID des Angerufenen
callednumber	Text	Rufnummer des Angerufenen
calledname	Text	Anzeigename des Angerufenen (denormalisiert)
serviceid	Ganzzahl	STARFACE-Dienstkennung; anlagenübergreifend identisch, beim Import unverändert übernommen
starttime	Zeitstempel (ms)	Beginn des Anrufs — Bezugsfeld für Zeitfilter bei Export und Löschung
ringingtime	Zeitstempel (ms)	Klingelbeginn (leer, wenn nicht geklingelt)
linktime	Zeitstempel (ms)	Gesprächsbeginn (Verbindung hergestellt)
callresulttime	Zeitstempel (ms)	Zeitpunkt des Rufergebnisses
callresult	Text	Rufergebnis, z. B. CONNECTED
callresultcausedby	Ganzzahl	Konto, das das Rufergebnis verursacht hat (Verweis ohne Fremdschlüssel)
lineid	Ganzzahl	ID der verwendeten Leitung
linename	Text	Name der verwendeten Leitung
dialednumber	Text	ursprünglich gewählte Rufnummer
callbacknumber	Text	Rückrufnummer
answeredelsewhere	Text	Vermerk „anderweitig angenommen"
incoming	Boolean	eingehender Anruf
answered	Boolean	Anruf angenommen
hasvoicemail	Boolean	Voicemail-Anhang vorhanden (beim Import auf false gesetzt)
hasmonitor	Boolean	Aufzeichnungs-Anhang vorhanden (beim Import auf false gesetzt)
hasfax	Boolean	Fax-Anhang vorhanden (beim Import auf false gesetzt)
deleted	Boolean	im Journal als gelöscht markiert
privatecall	Boolean	privater Anruf
callbacknumberextern	Boolean	Rückrufnummer ist extern
duration	Ganzzahl (s)	Gesprächsdauer in Sekunden
comment	Text	Ruflistenkommentar
commentauthor	Text	Autor des Kommentars
commentmodified	Zeitstempel	letzte Änderung des Kommentars
calledback	Boolean	Rückruf-Markierung gesetzt
calledbackauthor	Text	Autor der Rückruf-Markierung
calledbackmodified	Zeitstempel	Zeitpunkt der Rückruf-Markierung
answeredbyusername	Text	Name des annehmenden Benutzers (denormalisiert)
hasaitranscription	Boolean	KI-Transkript vorhanden (beim Import auf false gesetzt)
deletedtimestamp	Zeitstempel	Zeitpunkt der Lösch-Markierung

cdrdata.csv (30 Spalten, in Dateireihenfolge): enthält je Anruf die einzelnen Rufschritte. Die Spalten id, callid, callleguuid, cdraccountid, calleraccountid, callercallerid, calledaccountid, calledcallerid, serviceid, starttime, ringingtime, linktime, callresulttime, callresult, callresultcausedby, lineid, linename, callbacknumber, answeredelsewhere, incoming, answered, hasvoicemail, hasmonitor, hasfax, deleted, privatecall, callbacknumberextern und duration entsprechen den gleichnamigen Spalten aus cdrsummary.csv; hinzu kommen:

Spalte	Typ	Bedeutung
callstepid	Ganzzahl	laufende Nummer des Rufschritts innerhalb des Anrufs
summarystep	Boolean	markiert den Rufschritt, der den Anruf in der Rufliste repräsentiert

Import-Verhalten (Ruflisten)

Der Import akzeptiert das Export-ZIP oder eine einzelne CSV-Datei (sie wird als cdrsummary.csv behandelt); in einem ZIP ist cdrsummary.csv Pflicht, cdrdata.csv optional. Er läuft zweiphasig — Analyse (zählt Einträge, sammelt Konten-Verweise samt Namen, schlägt eine Zuordnung per Namensvergleich vor; kein Schreibzugriff) und Import (eine Transaktion). Dabei gilt:

• Spaltenzuordnung über die Kopfzeile: importiert werden die Spalten, die es in der Zieltabelle gibt; unbekannte Spalten und id werden ignoriert. Ältere Exporte mit weniger Spalten bleiben dadurch importierbar.
• Neue Primärschlüssel: id wird über die Datenbanksequenzen neu vergeben.
• callid-Neuvergabe: je Quell-Anruf ein neues, kollisionsfreies callid — identisch auf Summary- und Detailzeilen angewendet, die Verknüpfung bleibt erhalten.
• Konten-Zuordnung: die Spalten cdraccountid, calleraccountid, calledaccountid und callresultcausedby werden gemäß der bestätigten Zuordnung auf Konten der Zielanlage umgeschrieben; nicht zugeordnete Verweise werden 0 (Anzeige „---"). Optional gleicht der Import die Namensspalten an die Ziel-Konten an (Kontrollkästchen im Dialog); sonst bleiben die exportierten Namen erhalten.
• serviceid wird unverändert übernommen.
• Anhänge werden entkoppelt: hasvoicemail, hasfax, hasmonitor und hasaitranscription werden auf false gesetzt — Sprachnachrichten, Faxe, Aufzeichnungen und Transkripte selbst sind nicht Teil des Formats.
• Verwaiste Detailzeilen: cdrdata-Zeilen, deren callid in cdrsummary.csv fehlt, werden nicht importiert und im Ergebnis als übersprungen gezählt.

Anwendungsbeispiel

Beim Wechsel von einer Appliance in die Cloud sollen die Gesprächsnachweise erhalten bleiben. Sie exportieren auf der Altanlage das Ruflisten-ZIP (inklusive cdrdata.csv), importieren es auf der neuen Anlage und ordnen im Dialog die Konten per Namensvorschlag zu — die Rufliste der neuen Anlage zeigt die komplette Historie mit Namen, Kommentaren und Rückruf-Markierungen.

Adressbuch-CSV

Der Export erzeugt je Adressbuch eine Datei adressbuch-<name>-<JJJJ-MM-TT>.csv mit allen Kontakten — als Download oder direkt per E-Mail-Versand.

CSV-Dialekt: Trennzeichen Semikolon, Kodierung UTF-8 mit BOM (Excel-kompatibel), Zeilenende \r\n. Felder mit Semikolon, Anführungszeichen oder Zeilenumbruch stehen in doppelten Anführungszeichen, enthaltene Anführungszeichen werden verdoppelt.

Kopfzeile: Die Spaltenköpfe verwenden die Syntax der STARFACE-Importvorlage —

<Anzeigename> [<Block>:<feldname>]

also z. B. Nachname [contact:familyname]. Je konfiguriertem Datenfeld des Adressbuchs entsteht eine Spalte; für Felder mit Kurzwahl-Unterstützung zusätzlich eine Zusatzspalte mit dem Kopf <Anzeigename> [<Block>:<kurzwahlfeld>(<feldname>)]. Der konkrete Spaltensatz folgt damit der Adressbuch-Konfiguration der Anlage (Standardfelder u. a. firstname, familyname, company, phone, mobile, homephone, fax, street, postalCode). Durch diese Kopfzeilensyntax lassen sich Exporte unverändert wieder einlesen — sowohl im Modul als auch über den nativen Adressbuch-Import der STARFACE-Weboberfläche.

Import-Verhalten (Adressbücher)

Der Import läuft zweiphasig: Analyse (erkennt Trennzeichen und Kodierung, zeigt Beispielzeilen, schlägt die Spaltenzuordnung vor und schätzt Duplikate) und Import. Dabei gilt:

• Trennzeichen Semikolon, Komma oder Tabulator — automatisch aus der Kopfzeile erkannt.
• Kodierung: UTF-8 (mit oder ohne BOM); Dateien, die kein gültiges UTF-8 sind, werden als Windows-1252 gelesen (ältere Excel-Exporte).
• Spaltenzuordnung: zuerst über die Importvorlagen-Syntax der Kopfzeile, dann über Namensgleichheit mit Feld- oder Anzeigenamen, zuletzt über gängige deutsche/englische Synonyme (z. B. „Nachname", „Firma", „Mobil", „PLZ"). Die Zuordnung ist im Dialog je Spalte änderbar; Kurzwahl-Zusatzspalten werden beim Import nicht übernommen.
• Pflichtangaben: je Kontakt Vor-/Nachname oder Firma; Telefonfelder dürfen nur gültige Rufnummernzeichen enthalten. Fehlerhafte Zeilen werden übersprungen und einzeln gemeldet (maximal 20 Fehlermeldungen).
• Duplikate: erkannt über die normalisierte Kombination aus Nachname, Vorname und Firma (Groß-/Kleinschreibung unerheblich) — gegen den Zielordner und innerhalb der Datei. Wahlweise werden Duplikate übersprungen.
• Importziele: das öffentliche Standard-Adressbuch und beschreibbare eigene Ordner — niemals das Systemadressbuch der Benutzer und keine privaten Adressbücher.
• Voraussetzung: das STARFACE-interne Adressbuch (Datenbank). Ist das Adressbuch an LDAP angebunden, stehen Import und Export nicht zur Verfügung.

Fehlerbehandlung

Situation	Verhalten
ZIP ohne cdrsummary.csv	Import bricht mit Fehlermeldung ab.
Datei leer oder ohne Datenzeilen	Abbruch mit Fehlermeldung.
cdrdata-Zeilen ohne zugehörige Summary-Zeile	Werden übersprungen und im Ergebnis gezählt.
Konten-Verweis ohne Zuordnung (Ruflisten)	Wird 0; die Rufliste zeigt „---".
Kontakt ohne Name und Firma, ungültige Telefonwerte	Zeile wird übersprungen; bis zu 20 Fehler werden mit Zeilennummer gemeldet.
Duplikat (Adressbuch)	Wird bei aktivierter Option übersprungen und gezählt.
Adressbuch an LDAP angebunden	Import/Export nicht verfügbar; die Oberfläche weist darauf hin.
Fehler während des Ruflisten-Imports	Die Transaktion wird zurückgerollt — es entstehen keine Teilbestände.

Versionierung & Kompatibilität

Die Dateinamen im ZIP, der CSV-Dialekt und die Verknüpfung über callid sind stabile Verträge. Der Spaltensatz der Ruflisten-Dateien folgt dem nativen Schema der installierten STARFACE-Version und kann mit STARFACE-Updates wachsen; da der Import über die Kopfzeile zuordnet und unbekannte Spalten ignoriert, bleiben ältere Exporte importierbar. Beim Adressbuch-CSV ist die Kopfzeilensyntax der STARFACE-Importvorlage der Vertrag; der Spaltensatz folgt der Adressbuch-Konfiguration. Änderungen dokumentieren die Release Notes der jeweiligen Modulversion.