TSA-BUS-Integration CityGov3

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.

Wichtig Änderungen

CityGov Version 4.0: Anpassungen für die BUS-Schnittstelle Version 6.1:
Nur wenn die BUS-Schnittstelle angebunden ist:
Vor dem Import muss zunächst die Konfiguration erweitert werden. Konkret muss die Synchronisations-Datei für die importierten Mitarbeiter durch den folgenden Parameter angegeben werden:

tsabus.export.person=[pathToBUS-config]/export.persons.xml

Zum zweiten sollte angegeben werden, ab welchem Pool-Anker die Mitarbeiter exportiert werden sollen:

tsabus.export.person.root=[person.pool-anchor]   # alternativ werden alle Mitarbeiter exportiert

Anschließend muss der Export der Mitarbeiter einmalig durch den folgenden Aufruf initiiert werden.

 iesclient com.sitepark.tsabus.exporter.Exporter tsaBus/tsabus.properties  --initPersons

Im regelmäßigen Export werden die Daten anschließend automatisch regelmäßig 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 Zugangsdaten
#
ies.connection.login=Wartung
ies.connection.password=geheim
ies.connection.client=sg

#
# BUS Zugangsdaten
#
tsabus.login=sitepark
tsabus.password=auchgeheim
tsabus.queryid=1234567

#
# Konfiguration des Infodienstes (hier Niedersachsen)
#
tsabus.state=NDS

#
# Angabe des Gebiets (Ermittlung siehe unten)
#
tsabus.district=987654

#
# Angabe der Anliegen-Gruppen (Ermittlung siehe unten)
# Hier beispielsweise 'Gemeindeleistungen' und 'Landkreis, kreisfr.Stadt'
#
tsabus.import.productGroups=10923103,11083983

#
# Synchronisations-Datei, damit im BUS entfernte Objekte auch in diesem IES-Mandaten entfernt werden
#
tsabus.import.syncfile=${sitepark.home}/conf/tsabus.import.syncfile

#
# Übersicht und Synchronisation der Exportierten regionalen Ergänzungen
#
tsabus.export.productregional=${sitepark.home}/conf/tsabus.export.productregional.xml

#
# Anker der Organisation AB der exportiert werden soll
#
tsabus.export.organisation.root=gui.vv.system.root.organisation.pool

#
# Übersicht und Synchronisation der Exportierten Organisationen
#
tsabus.export.organisationunits=${sitepark.home}/conf/tsabus.export.organisationunits.xml

#
# Anker eines Mitarbeiter-Pools ab dem Mitarbeiterdaten exportiert werden sollen. 
#
tsabus.export.person.root=tsa.export.person.rootPool

#
# Übersicht und Synchronisation der Exportierten Mitarbeiter
#
tsabus.export.person=${sitepark.home}/conf/tsabus.export.persons.xml



# Gibt an, in welchem Publikationsbereich die Export-Objekte (regionale Anliegen/Organisationen/Mitarbeiter) publiziert sein müssen, damit sie exportiert werden
tsabus.export.publisher=www

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

# 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

# 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

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

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.district.addresses: In bestimmten Konstellationen kann die GebietsID (tsabus.district) nicht für die Angabe von Adressen verwendet werden. Für diesen Fall kann hier eine abweichende Id für die Verwendung innerhalb der Adressen und Anschriften angegeben werden.

tsabus.import.productGroups: Hier können eine oder mehrere Leistungs-Gruppen angegeben werden. Nur Leistungen, die den angegebenen Gruppen zugewiesen sind, werden importiert. Ist dieses Attribut leer, werden alle für das Gebiet zur Verfügung stehenden Leitungen importiert.

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

Ermittlung der Gebiets-ID (district)

Um die Gebiets ID zu ermitteln kann folgender Aufruf verwendet werden. Hierzu müssen allerdings tsabus.login, tsabus.password und tsabus.queryid bereist konfiguriert sein.

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

Ermittlung der Anliegengruppen-ID's

Eine Übersicht aller Anliegengruppen kann folgender Aufruf verwendet werden. Auch hier müssen die TSA-BUS Zugangsdaten in in der .properties-Datei angegeben sein.

iesclient com.sitepark.tsabus.Service conf/tsabus.properties  anliegenGruppen

Die für den jeweiligen Import nötigen Gruppen müssen von der Projektleitung der jeweiligen Kommune definiert werden.

Hier ein beispielhafte Liste der Anliegengruppen:

EG-DLRL Gemeinde (id:9609804)
EG-DLRL Landkreis / kreisfreie Stadt (id:9609806)
EG-DLRL Kammer (id:9609810)
Allgemein (Leistungen) (id:9617525)
D115 kommunal (id:9628732)
D115 Land (id:9628734)
D115 Bund (id:9628736)
QS_HKM (id:9720716)
QS_HMWK (id:9720718)
QS_HMDJ (id:9720732)
QS_HMSI (id:9720752)
QS_Bund (id:9765345)
LWV (id:9787913)
EG-DLRL Bund (id:9819616)
D115 TOP 100 (id:9939932)
EG-DLRL Land (id:10578797)
QS_Sonstige (id:10593740)
EG-DLRL Sonstige (id:10606845)
Landesleistungen (id:10913503)
Bundesleistungen (id:10913523)
Kammerleistungen (id:10913545)
Gemeindeleistungen (id:10923103)
Infoleistungen (id:10923131)
RP-Leistungen (id:10931343)
Landkreis, kreisfr. Stadt, Sonderstatusstadt (id:10931403)
Landkreis, kreisfr.Stadt (id:11083983)
Landkreis alleinzuständig (id:11087903)

Weitere Informationen aus dem BUS

Alle Anliegen-Gruppen, die beim Import als Filter angegeben werden können

iesclient com.sitepark.tsabus.Service conf/tsabus.properties AnliegenGruppen

Anliegen innerhalb der einzelnen Gruppen anzeigen

iesclient com.sitepark.tsabus.Service conf/tsabus.properties anliegenInGruppen

Alle zentralen Anliegen auflisten

iesclient com.sitepark.tsabus.Service conf/tsabus.properties anliegen

Kategorien (Lebenslagen) auflisten

iesclient com.sitepark.tsabus.Service conf/tsabus.properties anliegenKategorien

Formulare (alle oder eines Anliegens) anzeigen

iesclient com.sitepark.tsabus.Service conf/tsabus.properties forms [anliegenId]

Ein Anliegen mit dem Schlüssel anzeigen

iesclient com.sitepark.tsabus.Service conf/tsabus.properties anliegenBySchluessel [schlüssel]

Die Anliegen einer Orga (ID) auflisten

iesclient com.sitepark.tsabus.Service conf/tsabus.properties anliegenVonOrga [orgaID]

Alle regionalen Anliegen auflisten

iesclient com.sitepark.tsabus.Service conf/tsabus.properties regionaleAnliegen

Weitere Administrative Anfragen

iesclient com.sitepark.tsabus.Service conf/tsabus.properties blocktypes
iesclient com.sitepark.tsabus.Service conf/tsabus.properties fristenSchlüssel
iesclient com.sitepark.tsabus.Service conf/tsabus.properties gebührenSchlüssel
iesclient com.sitepark.tsabus.Service conf/tsabus.properties gebietePfad 'gebiestId'
iesclient com.sitepark.tsabus.Service conf/tsabus.properties gebietsChildren 'gebiestId'
iesclient com.sitepark.tsabus.Service conf/tsabus.properties telefonTypen
iesclient com.sitepark.tsabus.Service conf/tsabus.properties adressTypen
iesclient com.sitepark.tsabus.Service conf/tsabus.properties inetAdressTypen
iesclient com.sitepark.tsabus.Service conf/tsabus.properties parkplatzTypen
iesclient com.sitepark.tsabus.Service conf/tsabus.properties contaktsystemtyps
iesclient com.sitepark.tsabus.Service conf/tsabus.properties zuständigkeitsTypen
iesclient com.sitepark.tsabus.Service conf/tsabus.properties zstoe

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  --module=citygov  /etc/tsabus.properties --init

Einmalige Datenimporte

Im BUS eingetragene Organisationen der Kommune

Optional könne initial die Organisationen, die dem Gebiet in dem BUS bereits untergeordnet sind, einmal initial als CityGov Struktur importiert werden.
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).

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

Im BUS hinterlegte Produktgruppen/Themenbereiche

Einmalig können auch die Produktgruppen wie 'Fahrzeug und Verkehr' oder 'Arbeit und Beruf' als Themenbereich in CityGov importiert werden. Die anschließen per --link-products oder --import-local-products importierten Produkte werden dann automatisch mit den Themenbereichen verknüpft.

iesclient com.sitepark.tsabus.importer.Importer  --module=citygov  /etc/tsabus.properties --import-themes

Im BUS erstellte 'regionale Ergänzungen' zu den zentralen Leistungsbeschreibungen

Ab der CityGov-Version 3.6.2 können initial auch alle regionale Ergänzungen in CityGov eingelesen werden, die von dem Kunden direkt in dem jeweiligen BUS-Portal erstellt wurden. Die auf diesem Weg erstellten Produkte der VirtuellenVerwaltung sind bereits mit dem entsprechenden BUS-Produkt (und den zuvor möglicherweise importierten Organisationen) verknüpft.

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

Im BUS konfigurierte Mitarbeiter von Organisationen

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

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

Import aller BUS-Leistungen als (regionale) CityGov-Produkte

Optional können auch ALLE Produkte einmalig in der Virtuellen Verwaltung angelegt werden. Die Verknüpfung zum zentralen TSA-BUS Anliegen wird in dem Fall automatisch gesetzt. Sollte in der Konfiguration das Attribut tsabus.import.productGroups angegeben sein, werden NUR Produkte dieser Leistungsgruppen importiert. Bei späteren Updates der zentralen Leistungsbeschreibungs-Texte aus dem BUS bleiben diese Daten unberührt.
Hinweis: Sollten mit --import-local-products bereits die lokalen regionalen Ergänzungen importiert worden sein, werden sie hier nicht erneut importiert und bleiben unverändert.

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

Regelmäßiger Import

Der regelmäßige Import der TSA-BUS Anliegen wird dann mit dem folgenden Kommando ausgeführt. Sollte in der Konfiguration das Attribut tsabus.import.productGroups angegeben sein, werden NUR zentrale Leistungen dieser Leistungsgruppen importiert.

iesclient com.sitepark.tsabus.importer.Importer  --module=citygov  /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  --module=citygov  /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