Exporte

DirectoryHub exportiert den zusammengeführten Kontaktbestand in vier dokumentierten Dateiformaten: JSON und CSV für Skripte, Datenintegrationen und Tabellenkalkulationen, LDIF für die Übernahme in andere Verzeichnisdienste und ein nativer SQL-Dump für die vollständige Datensicherung. Ausgelöst wird der Export über die Moduloberfläche; die Formate selbst sind der stabile Vertrag dieser Schnittstelle — Ihre Daten bleiben jederzeit vollständig mitnehmbar.

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 (Download)
Zugang: Tab der Modulkonfiguration, mit Formatauswahl (siehe Datenbank)
Authentifizierung: Anmeldung an der Moduloberfläche als STARFACE-Benutzer mit Administrationsrecht
Auslieferung: Die Datei wird serverseitig erzeugt und über eine Einmal-Download-URL (/download/<Dateiname>?key=<Schlüssel>) genau einmal ausgeliefert; danach wird sie auf der Anlage gelöscht. Dateiname: directoryhub-dump-<JJMMTT-HHMMSS>-<Zufallskennung>.<json|csv|ldif|sql>
Kodierung: UTF-8
Editionen: Der CSV-Export steht in allen Editionen bereit; JSON, LDIF und SQL erfordern die Enterprise Edition.
Umfang: alle Kontakte des Bestands, quellenübergreifend zusammengeführt. Die logischen Formate (JSON, CSV, LDIF) lassen Foto-/Binärfelder aus (Feldnamen jpegPhoto, thumbnailPhoto, photo, avatar, picture, image); der native SQL-Dump enthält sie vollständig.

Die Feldnamen in allen Formaten sind die Zielfeldnamen der Feldzuordnungen (z. B. givenName, sn, o, telephoneNumber — siehe Attribut-Schema); die Alias-Verdopplung des LDAP-Servers (o/company …) findet in Exporten nicht statt. Rufnummern liegen normalisiert im E.164-Format vor.

JSON-Export

Ein JSON-Array mit einem Objekt je Kontakt (in der Datei: ein Kontakt je Zeile). Jedes Feld erscheint als eigener Eintrag inklusive Herkunft und Konfidenz — mehrwertige Felder als mehrere Einträge gleichen Namens.

Eigenschaft	Typ	Bedeutung
`id`	String	stabile Kontakt-ID (`<Quellen-ID>::<Primärschlüssel>`)
`displayName`	String, nullable	Anzeigename
`sourceIds`	Array von String	IDs aller Quellen, die zu diesem Kontakt beigetragen haben
`fields`	Array	Kontaktfelder, je Feld ein Objekt
`fields[].name`	String	Zielfeldname (LDAP-Attributname)
`fields[].type`	String	Feldtyp: `NAME`, `ADDRESS`, `NUMBER` oder `OTHER`
`fields[].value`	String, nullable	normalisierter Wert (bei `NUMBER`: E.164)
`fields[].sourceId`	String	Quelle, aus der dieses Feld stammt
`fields[].confidence`	Zahl	Konfidenz 0–1 (relevant bei Merge-Konflikten)

Beispiel (zwei Kontakte, umbrochen)
[
  {"id":"src-9f3a21c7::1042","displayName":"Petra Maier","sourceIds":["src-9f3a21c7"],
   "fields":[
     {"name":"givenName","type":"NAME","value":"Petra","sourceId":"src-9f3a21c7","confidence":1.0},
     {"name":"sn","type":"NAME","value":"Maier","sourceId":"src-9f3a21c7","confidence":1.0},
     {"name":"o","type":"OTHER","value":"Beispiel GmbH","sourceId":"src-9f3a21c7","confidence":1.0},
     {"name":"telephoneNumber","type":"NUMBER","value":"+49721556677","sourceId":"src-9f3a21c7","confidence":1.0},
     {"name":"mail","type":"OTHER","value":"p.maier@example.de","sourceId":"src-9f3a21c7","confidence":1.0}
   ]},
  {"id":"src-4c11e0b2::2001","displayName":"Max Beispiel","sourceIds":["src-4c11e0b2","src-9f3a21c7"],
   "fields":[
     {"name":"cn","type":"NAME","value":"Max Beispiel","sourceId":"src-4c11e0b2","confidence":1.0},
     {"name":"mobile","type":"NUMBER","value":"+491701234567","sourceId":"src-9f3a21c7","confidence":0.8}
   ]}
]

Ein Kontakt mit mehreren Einträgen in sourceIds wurde quellenübergreifend zusammengeführt; die Feld-Herkunft zeigt, welche Quelle welchen Wert geliefert hat.

CSV-Export

Eine Tabelle mit einer Zeile je Kontakt — zur Sichtung in Tabellenkalkulationen und für einfache Weiterverarbeitung.

Dialekt (RFC 4180): Trennzeichen Komma, Zeilenende \r\n, UTF-8 ohne BOM. Felder mit Komma, Anführungszeichen oder Zeilenumbruch stehen in doppelten Anführungszeichen; enthaltene Anführungszeichen werden verdoppelt.
Spalten: id, displayName, danach die Vereinigung aller im Bestand vorkommenden Feldnamen (Reihenfolge des ersten Auftretens). Der Spaltensatz folgt damit den konfigurierten Feldzuordnungen.
Werte: je Zelle der erste Wert des Feldes; weitere Werte mehrwertiger Felder sind nur im JSON-, LDIF- und SQL-Export enthalten. Herkunft und Konfidenz werden nicht exportiert.

Beispiel
id,displayName,givenName,sn,o,telephoneNumber,mail
src-9f3a21c7::1042,Petra Maier,Petra,Maier,Beispiel GmbH,+49721556677,p.maier@example.de
src-4c11e0b2::2001,Max Beispiel,Max,Beispiel,"Beispiel GmbH, Werk 2",+49721998877,m.beispiel@example.de

LDIF-Export

Ein Verzeichnis-Export nach RFC 2849 — je Kontakt ein Eintrag, Einträge durch Leerzeilen getrennt. Das Format eignet sich für den Import in andere Verzeichnisdienste (ldapadd/ldapmodify, estos MetaDirectory, OpenLDAP & Co.).

DN: uid=<Kontakt-ID>,<Basis-DN> — flach unter dem konfigurierten Basis-DN (Standard dc=directory), ohne die Baumknoten-Struktur des LDAP-Servers.
Objektklassen: top, inetOrgPerson.
Attribute: uid, cn (Anzeigename), danach alle Felder mit nicht-leerem normalisiertem Wert unter ihrem Zielfeldnamen.
Attributnamen werden LDAP-konform bereinigt: unzulässige Zeichen werden durch - ersetzt; beginnt ein Name nicht mit einem Buchstaben, wird x- vorangestellt.
Werte mit Nicht-ASCII-Zeichen oder unsicherem Beginn (Leerzeichen, :, <) werden Base64-kodiert und mit :: ausgegeben.

Beispiel
dn: uid=src-9f3a21c7::1042,dc=directory
objectClass: top
objectClass: inetOrgPerson
uid: src-9f3a21c7::1042
cn: Petra Maier
givenName: Petra
sn: Maier
o: Beispiel GmbH
telephoneNumber: +49721556677
mail: p.maier@example.de
description:: TcO8bmNobmVyIEJlemlyaw==

dn: uid=src-4c11e0b2::2001,dc=directory
objectClass: top
objectClass: inetOrgPerson
uid: src-4c11e0b2::2001
cn: Max Beispiel
givenName: Max
sn: Beispiel
o: Beispiel GmbH
telephoneNumber: +49721998877

SQL-Dump (nativ)

Der rohe Datenbank-Inhalt des Bestands als portable INSERT-Anweisungen — inklusive aller Binärdaten (Kontaktbilder, hex-kodiert). Der Dump enthält keine CREATE-Anweisungen; Ziel ist ein bereits migriertes DirectoryHub-Schema (Standardname directoryhub), wie es das Modul beim Start anlegt.

Tabelle	Spalten	Inhalt
`contact`	`id` (PK), `display_name`, `sort_sn`, `sort_given`, `sort_company`	ein Datensatz je Kontakt; die `sort_*`-Spalten sind denormalisierte, kleingeschriebene Sortierschlüssel
`contact_field`	`contact_id` (FK), `name`, `type`, `value`, `raw_value`, `source_id`, `confidence`	textuelle Kontaktfelder — `value` normalisiert (max. 500 Zeichen, indiziert), `raw_value` Originalwert der Quelle
`contact_field_blob`	`contact_id` (FK), `name`, `type`, `source_id`, `confidence`, `value_data`, `raw_data`	Binär-/Großfelder (z. B. `jpegPhoto`) als `BYTEA`/`BLOB`
`match_key`	`contact_id` (FK), `key`	Dedup-Schlüssel der quellenübergreifenden Zusammenführung

Die Kopfzeilen des Dumps nennen Schema und Dialekt. Binärwerte werden dialektgerecht ausgegeben — PostgreSQL: decode('<hex>','hex'), H2: X'<hex>'; Wahrheitswerte als TRUE/FALSE, fehlende Werte als NULL.

Beispiel (gekürzt)
-- DirectoryHub Datenbank-Dump (schema=directoryhub, dialect=POSTGRES)
-- Wiederherstellen in ein migriertes Schema (Tabellen contact, contact_field, contact_field_blob, match_key).

INSERT INTO directoryhub.contact ("id", "display_name", "sort_sn", "sort_given", "sort_company") VALUES ('src-9f3a21c7::1042', 'Petra Maier', 'maier', 'petra', 'beispiel gmbh');
INSERT INTO directoryhub.contact_field ("contact_id", "name", "type", "value", "raw_value", "source_id", "confidence") VALUES ('src-9f3a21c7::1042', 'telephoneNumber', 'NUMBER', '+49721556677', '0721 / 55 66 77', 'src-9f3a21c7', 1.0);
INSERT INTO directoryhub.contact_field_blob ("contact_id", "name", "type", "source_id", "confidence", "value_data", "raw_data") VALUES ('src-9f3a21c7::1042', 'jpegPhoto', 'OTHER', 'src-9f3a21c7', 1.0, decode('ffd8ffe000104a464946…','hex'), NULL);
INSERT INTO directoryhub.match_key ("contact_id", "key") VALUES ('src-9f3a21c7::1042', 'nn:petramaier|+49721556677');

Anwendungsbeispiel

Ein Unternehmen speist sein Türsprechstellen-System aus dem Meta-Verzeichnis: Ein nächtliches Skript lädt den JSON-Export, filtert auf Kontakte der CRM-Quelle (fields[].sourceId) und schreibt Name und Rufnummer in die Fremdanwendung — ohne LDAP-Anbindung und ohne Zugriff auf die Quellsysteme.

Fehlerbehandlung

Schlägt ein Export fehl, liefert die Moduloberfläche die Fehlermeldung des Servers; es entsteht keine (Teil-)Datei:

Situation	Verhalten
Kein oder unbekanntes Format angewählt	Abbruch mit Fehlermeldung („Kein Format angegeben." / „Unbekanntes Format: …").
Speicher nicht bereit (Modul startet gerade, Datenbank nicht erreichbar)	Abbruch mit Fehlermeldung „Der Speicher ist nicht bereit."
JSON/LDIF/SQL ohne Enterprise Edition	Abbruch mit Fehlermeldung „Dieses Exportformat erfordert die Enterprise-Edition."
Schreibfehler während der Erzeugung	Abbruch mit Fehlermeldung; die angelegte Temporärdatei wird entfernt.
Download-URL erneut aufgerufen	Kein Treffer — jede Export-Datei wird genau einmal ausgeliefert und danach gelöscht. Für einen weiteren Download den Export erneut erzeugen.

Versionierung & Kompatibilität

Die Struktur der logischen Formate ist ein stabiler Vertrag: JSON-Eigenschaftsnamen, die CSV-Spalten id/displayName samt Dialekt sowie DN-Aufbau und Objektklassen des LDIF-Exports bleiben erhalten; Erweiterungen erfolgen additiv (neue Eigenschaften, neue Spalten). Der konkrete Feld-/Spaltensatz folgt den konfigurierten Feldzuordnungen der Installation. Der native SQL-Dump bildet das interne Tabellenschema ab und kann sich mit Modulversionen weiterentwickeln — für maschinelle Weiterverarbeitung sind JSON und CSV die richtige Wahl, der SQL-Dump dient der Sicherung. Änderungen dokumentieren die Release Notes der jeweiligen Modulversion.

Grundlagen​

JSON-Export​

CSV-Export​

LDIF-Export​

SQL-Dump (nativ)​

Fehlerbehandlung​

Versionierung & Kompatibilität​