Spezifikation des Schnittstellenimportes

Aus OpenEstate-Wiki

Inhaltsverzeichnis

1 Wie funktioniert der Schnittstellenimport?
2 Schnittstellen-Dateien
3 Dokumentation der verwendbaren Keys
4 Fragen oder Probleme?
5 Letzte Änderungen

Die Einrichtung von Immobilienexport-Schnittstellen führt in der Praxis immer wieder zu Problemen beim Anwender und damit zu erhöhtem Support-Aufwand beim Datenlieferanten (Software-Hersteller) bzw. Datenempfänger (Portal). Im folgenden Artikel erfahren Sie, wie dieses Problem zwischen ImmoTool und iHanse.de gelöst wurde. Der verwendete Austauschstandard wird im Folgenden dokumentiert, sodass jeder interessierte Dienstleister & Entwickler darauf zurückgreifen kann.

Wie funktioniert der Schnittstellenimport?

Der allgemeine Ablauf

Das ImmoTool gibt seinen Anwendern eine halbautomatische Lösung zum Import von Schnittstellendaten an die Hand. Die Daten werden automatisch importiert, ohne dass der Anwender sich über Dinge wie FTP, XML, ZIP oder Base64 Gedanken machen müsste. Vom Datenempfänger (in der Regel ein Immobilienportal) muss lediglich eine Schnittstellen-Datei (XML oder INI) heruntergeladen, die vom Anwender direkt ins ImmoTool importiert werden kann.

Teilnahme erwünscht!

Jeder Portalbetreiber, Software-Entwickler, Franchiser, etc. ist dazu eingeladen diesen Mechanismus in seinem Angebot umzusetzen. Reduzieren Sie damit unnötigen Supportaufwand und bieten Sie Ihren Kunden eine zuverlässige und problemlose Schnittstelleneinrichtung!

Unter welchen Lizenzbedingungen kann diese Spezifikation verwendet werden?

Die Schnittstellen-Spezifikation kann unter den Bedingungen der LGPL-Lizenz (siehe inoffizielle Übersetzung) frei verwendet werden. Die Implementierung des Standards ist mit keinerlei Lizenzkosten oder Verpflichtungen für Sie verbunden! Details entnehmen Sie bitte den Lizenztexten oder können via Ticketsystem erfragt werden.

Schnittstellen-Dateien

Die Datei sollte so einfach wie möglich gestaltet werden, um den Implementierungsaufwand so gering wie möglich zu halten. Aus diesem Grund haben wir uns dazu entschieden die Daten durch einfache Paare aus Key = Value abzubilden.

Beispiel einer Schnittstellen-INI

# Diese Datei wurde automatisch von iHanse.de erzeugt.
 
# Allgemein
title=iHanse.de
active=true
limit=0
 
# Export
export=openestate_xml
export.imagemode=file
export.zipped=true
 
# Transport
transport=ftp
transport.ftp.host=import.ihanse.de
transport.ftp.port=21
transport.ftp.path=/
transport.ftp.user=*********
transport.ftp.pass=*********
transport.ftp.anonymous=false
transport.ftp.passive=false

Hinweis: Damit eine solche Datei vom ImmoTool importiert werden kann, muss der Dateiname auf .properties oder .ini enden.

Beispiel einer Schnittstellen-XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <comment>Diese Datei wurde automatisch von iHanse.de erzeugt.</comment>
 
  <!-- Allgemein -->
  <entry key="title">iHanse.de</entry>
  <entry key="active">true</entry>
  <entry key="limit">0</entry>
 
  <!-- Format -->
  <entry key="export">openestate_xml</entry>
  <entry key="export.zipped">true</entry>
  <entry key="export.imagemode">file</entry>
 
  <!-- Transport -->
  <entry key="transport">ftp</entry>
  <entry key="transport.ftp.host">import.ihanse.de</entry>
  <entry key="transport.ftp.port">21</entry>
  <entry key="transport.ftp.path">/</entry>
  <entry key="transport.ftp.user">*********</entry>
  <entry key="transport.ftp.pass">*********</entry>
  <entry key="transport.ftp.anonymous">false</entry>
  <entry key="transport.ftp.passive">false</entry>
</properties>

Hinweis: Damit eine solche Datei vom ImmoTool importiert werden kann, muss der Dateiname auf .xml enden.

Schnittstellen-Datei in Java einlesen

Durch Verwendung der Java-Properties können die Schnittstellen-Formate mit wenigen Zeilen Java-Code eingelesen und weiterverarbeitet werden.

java.io.File xml = new java.io.File( "import.xml" );
java.util.Properties p = new java.util.Properties();
if (xml.getName().toLowerCase().endsWith( ".xml" ))
  p.loadFromXML( new java.io.FileInputStream( xml ) ); // XML-öffnen
else
  p.load( new java.io.FileInputStream( xml ) ); // INI-öffnen

Dokumentation der verwendbaren Keys

Eine Schnittstellen-XML-Datei ist momentan ein einfaches Key-Value-Mapping. Die verwendeten Keys werden im Folgenden zusammengefasst.

Allgemeine Parameter

Parameter	Typ	Beschreibung
title	`String`	Eine frei wählbare Bezeichnung der Immobilien-Schnittstelle. In der Regel sollte hier der Name des Empfängerportals angegeben werden.
active	`Boolean`	Die Immobilien-Schnittstelle kann nach dem Import in der Software aktiviert / deaktiviert werden. In der Regel sollte hier true angegeben werden.
limit	`Integer`	Immobilienkontingent, dass im Empfängerportal gebucht wurde. Dieses Limit wird beim Datenexport von der Software nicht überschritten. Wenn 0 angegeben wurde, findet ein unlimitierter Immobilientransfer statt. In der Regel sollte hier das gebuchte Kontingent des Anbieters im Portal angegeben werden.

Parameter zum Datenexport

Parameter	Typ	Beschreibung
export	`String`	Dieser Wert gibt an, in welchem Format die Immobiliendaten exportiert werden sollen. Mögliche Werte sind: openestate_xml: Zum Export im OpenEstate-XML-Format openimmo_xml: Zum Export im OpenImmo-XML-Format
export.imagemode	`String`	Dieser Wert gibt an, in welchem Format die Bildanhänge aufbereitet werden sollen. Mögliche Werte sind: file: Die Bilder werden als separate Dateien ausgeliefert. base64: Die Bilder werden im Base64-Format in die Export-Datei integriert. (Insofern die Schnittstelle in export dies unterstützt.) disabled: Keine Bildanhänge werden ausgeliefert.
export.zipped	`Boolean`	Die erzeugten Exportdateien sollen zu einer ZIP-Datei zusammengefasst werden.

Parameter zum Datenexport via OpenImmo-XML

Diese Parameter werden nur verwendet, wenn export = openimmo_xml gewählt wurde.

Parameter	Typ	Beschreibung
export.openimmo.agent_id	`String`	In der erzeugten OpenImmo-XML wird dieser Wert im XML-Element /openimmo/anbieter/anbieternr eingetragen. Einige Datenempfänger benötigen diese Information zur automatischen Verarbeitung.
export.openimmo.openimmo_agent_id	`String`	In der erzeugten OpenImmo-XML wird dieser Wert im XML-Element /openimmo/anbieter/openimmo_anid eingetragen. Einige Datenempfänger benötigen diese Information zur automatischen Verarbeitung.
export.openimmo.techn_mail	`String`	In der erzeugten OpenImmo-XML wird dieser Wert im XML-Attribut /openimmo/uebertragung/@techn_email eingetragen. Einige Datenempfänger benötigen diese Information zur Versendung von Fehlerprotokollen.

Parameter zum Datentransport

Parameter	Typ	Beschreibung
transport	`String`	Der Art des Transport wird hier angegeben. Mögliche Werte sind: ftp: Transport der erzeugten Daten via FTP http: Transport der erzeugten Daten via HTTP-POST

Parameter zum Datentransport via FTP

Diese Parameter werden nur verwendet, wenn transport = ftp gewählt wurde.

Parameter	Typ	Beschreibung
transport.ftp.host	`String`	Hostname / IP-Adresse des FTP-Servers.
transport.ftp.port	`Integer`	Port-Nr des FTP-Servers.
transport.ftp.path	`String`	Zielpfad auf dem FTP-Server.
transport.ftp.user	`String`	Login-Name zur Anmeldung am FTP-Server.
transport.ftp.pass	`String`	Login-Passwort zur Anmeldung am FTP-Server.
transport.ftp.anonymous	`Boolean`	Anonymen FTP-Transfer aktivieren. (kein Login nötig)
transport.ftp.passive	`Boolean`	Passiven FTP-Transfer aktivieren.

Parameter zum Datentransport via HTTP

Diese Parameter werden nur verwendet, wenn transport = http gewählt wurde.

Parameter	Typ	Beschreibung
transport.http	`String`	Die Art der HTTP-Anfrage wird hier spezifiziert. Mögliche Werte sind: put: Sendet einen HTTP-PUT-Request. (siehe auch mod_actions, mod_put) post: Sendet einen HTTP-POST-Request.
transport.http.url	`String`	URL zum HTTP-/HTTPS-Server.
transport.http.user	`String`	Benutzername zur Basic Authentifizierung.
transport.http.pass	`String`	Passwort zur Basic Authentifizierung.
transport.http.anonymous	`Boolean`	Keine Authentifizierung am HTTP-Server durchführen (anonyme Übertragung).

Parameter zum Datentransport via HTTP-POST

Diese Parameter werden nur verwendet, wenn transport = http und transport.http = post gewählt wurde.

Parameter	Typ	Beschreibung
transport.http.post.multipart	`Boolean`	Dateiübertragung als multipart/form-data durchführen.
transport.http.post.multipart.key	`String`	Name der Variablen im Uploadformular bei multipart/form-data-Übertragungen.

Fragen oder Probleme?

Bei Unklarheiten, Fehlerhinweisen oder Korrekturbedarf, helfen wir Ihnen gern weiter – eine Mitteilung via Ticketsystem genügt.

Letzte Änderungen

22.06.2009: Spezifikation erstmaligst als v1.0 veröffentlicht.