TSA-BUS-Integration CityGov3: Unterschied zwischen den Versionen

Version vom 6. August 2014, 10:07 Uhr

Integration der BUS-Schnittstelle der Firma TSA.

Der Im- und Export erfolgt über Kommandozeilenaufrufe. Die notwendigen Klassen stehen automatisch zur Verfügung, wenn das Modul 'CityGov3' installiert ist.

Import von Formularen

Die im BUS-System zentral gepflegten und zu Anliegen (Produkten) zugeordneten Formulare werden mit importiert. Die importierten Daten sind unveränderlich.

Export von lokalen Formularen

Formulare die in CityGov3 eingetragen wurden werden als URL in das BUS-System exportiert.

Konfiguration

Die Konfiguration der Schnittstelle erfolgt in einer Property-Datei (tsabus.properties). Dort werden die Konfigurationen für den Im- und Export gemeinsam Konfiguriert.

Beispiel für eine Konfiguration

ies.connection.login=Wartung
ies.connection.password=geheim
ies.connection.client=sg

tsabus.login=sitepark
tsabus.password=auchgeheim
tsabus.queryid=1234567

# Niedersachsen
tsabus.state=NDS
tsabus.district=KREISFREIE_STADT:Goldenberg

# sind die Datenbank Anpassungen bereits erfolgt (article to media-article: siehe CityGov-Changelog Hinweis Version 3.6.2)?
tsabus.products.converted.to.media=true

# Temporäres Verzeichnis für die zu importierenden XIP-Daten
tsabus.workdir=${sitepark.home}/work/tsabus

tsabus.export.organisationunits=${sitepark.home}/conf/tsabus.export.organisationunits.xml
tsabus.export.organisation.root=gui.vv.system.root.organisation.pool
tsabus.export.productregional=${sitepark.home}/conf/tsabus.export.productregional.xml
# Gibt an, in welchem Publikationsbereich die Organistionseinheit und das Produkt publiziert
# sein müssen, damit sie exportiert werden
tsabus.export.publisher=www

# Sollen die BUS-Organisationen, die Verknüpfungen auf BUS-Leistungen haben, die in diesem Mandaten mit 
# regionalen Erweiterungen versehen wurden, ebenfalls importiert werden?
# Diese Verknüpfungen werden anschließend auch in der eigenen Webseite mit den Daten der übergeordneten 
# Organisation ausgegeben. 
tsabus.import.superiorOrganisations=false

tsabus.import.syncfile=${sitepark.home}/conf/tsabus.import.syncfile
# Publikationsbereiche, in denen die Übergeordneten Organisationseinheiten publiziert werden sollen.
# Wenn kein Publisher angegeben wurde, werden die Organisationseinheiten in allen File-Publishern publiziert
#tsabus.import.publisher=www,preview

ies.connection.*: Verbindungsdaten zum IES.

tsabus.login, tsabus.password und tsabus.queryid: Verbindungsdaten zum TSABUS-System. Jeder Kunde erhält seinen eingenen Login, da dann auch nur für desse Gebiet Schreibrechte gesetzt werden.

tsaubs.state: Bundesland für die die Schnittstelle genutzt werden soll. Die hier angegebenen Kürzel (z.B. NDS für Niedersachsen) sind in der XML-Datei (im Source-Tree unter modules/city-gov/conf/tsabus.xml) angegeben. Für jedes Bundesland ist eine WSDL zum jeweiligen Web-Service konfiguriert. Hier müssen auch die ID-Mappings für die AnliegenBlock-Typen hinterlegt werden. Die tsabus.xml wird im Modul verpackt und steht automatisch zur Verfügung.; Die in diesem Beispiel angegebene Konfiguration nds-test verweist auf das Niedersachsen-Schulungssystem (für Testzwecke)

tsabus.district: Hier wird das Gebiet Eingetragen, für das die Daten ausgetauscht werden sollen. Hier sollte die Gebiets-ID angegeben werden (Ermittlung der ID siehe untern). Alternativ, aber von TSA nicht empfohlen ist Gebiets-Type und Gebietsname mit einem Doppelpunkt getrennt anzugeben. Aus diese beiden Werten wird eine Suche nach Gebieten im TSA-System durchgeführt. Das gefundene Gebiet wird verwendet. Werden mehrere Gebiete gefunden kann der Import/Export nicht durchgeführt werden. Im Source-Tree liegt eine Datei modules/city-gov/tsabus.gebiete.txt in dem die Gebiete von Niedersachsen aufgelistet sind. Gebietstyp ist in Eckige Klammern gesetzt. Leerzeichen bei Gebeitstypen werden durch Unterstriche (_) ersetzt.

tsabus.workdir: Verzeichnis, in dem die XIP-Daten generiert werden um diese dann zu importieren.

tsabus.export.organisationunits: Pfad zur XML-Datei in dem die Organisations-Struktur des letzten Exports angegeben ist. Mit Hilfe dieser Datei werden neu anzulegende, zu ändernde oder zu löschende Organisationseinheiten ermittelt.

tsabus.export.organisation.root: Der Anker der Organisationseinheit, ab der die Organisationen exportiert werden sollen. Default ist gui.vv.system.root.organisation.pool.

tsabus.export.productregional: Pfad zur XML-Datei in dem die RegionalAnliegen des letzten Exports angegeben sind. Mit Hilfe dieser Datei werden neu anzulegende, zu ändernde oder zu löschende RegionalAnliegen ermittelt.

tsabus.export.publisher: Gibt an, in welchem Publikationsbereich die Organistionseinheit und die Produkte publiziert sein müssen, damit sie exportiert werden

tsabus.import.syncfile: Datei in dem die Anchor der Importierten Anliegen abgelegt werden. Hiermit wird ermittelt, welche Anliegen ein einem erneuten Import gelöscht werden müssen.

tsabus.import.publisher: Publikationsbereiche, in denen die Übergeordneten Organisationseinheiten publiziert werden sollen. Wenn kein Publisher angegeben wurde, werden die Organisationseinheiten in allen File-Publishern publiziert

Gebiets-ID (district)

Um die Gebiets ID zu ermitteln kann folgender Aufruf verwendet werden.

iesclient com.sitepark.tsabus.Service conf/tsabus.properties district KREISFREIE_STADT:Goldenberg

Hierzu müssen allerdings tsabus.login, tsabus.password und tsabus.queryid bereist konfiguriert sein.

Vorbereitung

Bei neu initialisierten Systemen, in den das CityGov-3.initial.stucture.xip bereits eingespielt wurde, müssen keine weiteren Vorbereitungen getroffen werden.

Bei älteren Systemen, die nachträglich mit der BUS-Schnittstelle ausgestattet werden, müssen noch folgende Punkt angepasst werden:

Der Artikel-Pool der Virtuellen-Verwaltung muss den anker gui.vv.system.root.pool bekommen.
Der Template-Pool der Virtuellen-Verwaltung (unterhalb von 'Seitentemplates') muss den anker gui.vv.tplp.output.root bekommen.
Das xip CityGov-3.only.initial.tsabus.stucture.xip muss importiert werden.

Import

Importiert werden alle Anliegen aus dem BUS-System. Diese Anliegen werden für diesen Zweck vom BUS-System bereit gestellt. Im IES werden diese Anliegen als Artikel im Pool TSABUS / Anliegen (anchor:tsabus.anliegen) (unterhalb des Pools gui.vv.system.root.pool) importiert. Diese Anliegen können dann über die Virtuelle Verwaltung mit Produkten aus dem IES verknüpft werden. Die Texte der BUS-Anliegen werden dann (wenn gewünscht) für die Produkte verwendet.

Zusätzlich werden noch Übergeordnete Organisationseinheiten importiert. Dies ist nötig da Anliegen z.B. mit einem Landes-Amt-Organisationseinheit verknüpft sein können. Diese Verknüpfung muß bestehen bleiben.

Der Import erfolg in 3 Schritten

Über den TSABUS-WebService werden alle Anliegen abgefragt und als XML im XIP-Format im Dateisystem gespeichert
Über den TSABUS-WebService werden alle zuständigen übergeordneten Organisationseinheiten abgefragt und als XML im XIP-Format im Dateisystem gespeichert
Die erzeugten XIP-Daten werden in den IES importiert

Initialisierung

Bevor der Import als Cron-Job ausgeführt werden kann muss dieser zunächst einmal initialisiert werden

iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties --init

Einmaliger Datenimport

Optional können alle Produkte einmalig in der Virtuellen Verwaltung angelegt und mit den TSA-BUS Anliegen verknüpft werden. Bei späteren Updates bzw Synchronisation mit dem BUS werden NUR die internen BUS-Daten aktualisiert.

iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties --link-products

Weiter können auch die Organisationen, die dem Gebiet untergeordnet sind, einmal initial als CityGov Struktur importiert werden.

iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties --import-organisations

Ab der CityGov-Version 3.6.1 werden bei dieser Aktion auch die tsabus_id's übernommen. Über die URL ([cmsl-url]/ies/module/city-gov/tsabus/oe.tree.spml?mustPublishedIn=www;rootOrganisation=root.organisation.anker) kann dann eine initiale tsabus.export.organisations.xml (entsprechend der Konfiguration tsabus.export.organisationunits) angelegt werden. In dem Fall werden beim anschließenden Export der Organisationen die bereits in dem BUS existierenden Organisationen aktualisiert (und nicht erneut angelegt).

Anschließend besteht die Möglichkeit auch die Mitarbeiter einmal initial als CityGov Objekte zu importieren. Die Mitarbeier werden indem BUS über die Organisationen des Gebietes ermittelt.

iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties --import-persons

Ab der CityGov-Version 3.6.2 können initial auch regionale Ergänzungen in CityGov eingelesen werden, die direkt in dem jeweiligen BUS-Portal eingegeben wurde. Die auf diesem Weg erstellen Produkte der VitruellenVerwaltung sind bereits mit dem entsprechenden BUS-Produkt verknüpft.

 iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties --import-local-products

Regelmäßiger Import

Der regelmäßige Import der TSA-BUS Anliegen wird dann wie folgt ausgeführt

iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties

Für die regelmäßige Aktualisierung wird ein Cron-Job benötigt. Dieser lautet etwa wie folgt:

# m h  dom mon dow   command

# jede Nacht TSA-BUS-Daten aktualisieren
15 2 * * * iesclient com.sitepark.tsabus.importer.Importer /etc/tsabus.properties 2>/dev/null

Parameter

-v[v[v]]: Verbose modes
-s: Silentmode / keine Konsolenausgaben
<config>: Import Konfiguration (gemeinsame Import/Export-Konfiguration)

Dieser Aufruf muss als Cron-Job eingetragen werden (Für Cron-Jobs müssen absolute Pfade angegeben werden)

Export

Exportiert werden alle Organisationseinheiten und regionale Ergänzungen zu den Anliegen Über den Aufruf des Export-Scriptes werden beide Exporte durchgeführt. Getrenntes exportieren ist nicht möglich.

Export von Organisationseinnheiten

Es wird die komplette hierarchische Struktur der Organisationseinheiten exportiert. Das Export-Script wird regelmäßig ausgeführt. Nach jedem Export wird eine XML mit der insgesamt exportieren Struktur abgelegt.

Beispiel:

<root>
  <oe id="100010100000010200-2001" version="1247488486610" name="Dezernat I" tsabus-id="9160780">
    <oe id="100010100000010208-2001" version="1246957696911" name="0140 Rechnungsprüfungsamt" tsabus-id=""></oe>
  </oe>
  <oe id="100010100000010217-2001" version="1247487045832" name="Dezernat III" tsabus-id="9160786">
    <oe id="100010100000010220-2001" version="1247211342529" name="0630 Baurecht" tsabus-id="9160804">
      <oe id="100010100000010223-2001" version="1247211342529" name="0630.11 Bauaufsicht" tsabus-id=""></oe>
    </oe>
  </oe>
</root>

Vor jedem Import wird die aktuelle Struktur über die SPML-Seite

/ies/module/city-gov/tsabus/oe.tree.spml?mustPublishedIn=www;rootOrganisation=root.organisation.anker

abgefragt und mit der gespeicherten XML-Struktur verglichen. Hier wird der Publikationsbereich angegeben, in dem die Organisationseinheit publiziert sein muß, damit sie exportiert wird (Konfiguration tsabus.export.publisher). Alle Änderungen (neu, geändert, gelöscht) können so ermittelt werden. Für jede neu anzulegende oder zu aktualisierende Organisationseinheit wird die SPML-Seite

/ies/module/city-gov/tsabus/oe.spml?oe=100010100000010200-2001

aufgerufen. Dieses XML-Dokument enthält alle zu exportierenden Daten

Export von regionalen Ergänzungen zu den Anliegen

Für alle Produkte aus der Virtuellen Verwaltung, die mit einem BUS-Anliegen verknüpft sind und in dem entsprechenden Publikationsbereich publiziert sind (Konfiguration tsabus.export.publisher), werden die regionalen Ergänzungen in das BUS-System exportiert. Dazu werden über

/ies/module/city-gov/tsabus/anliegen-regional-list.spml?mustPublishedIn=www

alle zu exportierenden Produkte ermittelt

Die XML-Struktur wird nach jedem Export gespeichert.

Beispiel

<anliegen-regional-list>
  <anliegen-regional name="Expressreisepass" id="100010100000010203-1015" version="1247575427796" tsabus-product-id="100010100000009864-1015" tsabus-id="8668928" regional-tsabus-id=""/>
  <anliegen-regional name="Reisepass" id="100010100000010205-1015" version="1247651153217" tsabus-product-id="100010100000009861-1015" tsabus-id="8665432" regional-tsabus-id=""/>
  <anliegen-regional name="Baugenehmigung." id="100010100000010230-1015" version="1247211304527" tsabus-product-id="100010100000009779-1015" tsabus-id="8664280" regional-tsabus-id=""/>
</anliegen-regional-list>

Produkte sind mit den BUS-Anliegen verknüpft. Für die regionalen Ergänzungen wird im BUS-System ein neues Objekt angelegt. Die ID dieses Objektes (regional-tsabus-id) wird an dem Importierten TSABUS-Anliegen gespeichert (regional_tsabus_id). Sollte die Verknüpfung zwischen Produkt und TSABUS-Anliegen aufgelöst werden, wird dies regionale Objekt im BUS-System gelöscht und das Feld regional_tsabus_id des Importierten Anliegen gelöscht.

Alle Änderungen werden durch den abgleich der XML-Struktur erkannt.

Die zu exportiertenden Daten werden über die SPML-Seite

/ies/module/city-gov/tsabus/anliegen-regional.spml?anliegen=100010100000010205-1015

ermittelt

Bevor der Export als Cron-Job ausgeführt werden kann muss er zunächst initialisiert werden

iesclient com.sitepark.tsabus.exporter.Exporter /etc/tsabus.properties --init

Hierbei wird die XML-Datei die mit der Konfiguration tsabus.export.organisationunits angegeben wurde erzeugt. Existiert diese Datei nicht und wird ein Export ohne --init ausgeführt, wird er export abgebrochen.

Export der Organisationseinheiten in das TSA-BUS-System

iesclient com.sitepark.tsabus.exporter.Exporter /etc/tsabus.properties