Dokumentation „External Synchronization“

der Entwicklungsstand aus dem lokalen External-Sync-Verzeichnis (lokales Repository) im Dateisystem in die lokale FirstSpirit-Projektinstanz importiert.

Dazu wird das Kommandozeilenwerkzeug „FSDevTools“ (fs-cli) verwendet.

Vergleiche Abbildung Schritt 2) Import.

Es wird empfohlen, alle Export- und Import-Operationen ausschließlich über FSDevTools auszuführen.

Dieses Werkzeug automatisiert Export- und Importvorgänge zwischen FirstSpirit-Projekt und Dateisystem über vordefinierte Kommandos. Eine individuelle Implementierung der Schnittstellen ist nicht notwendig (siehe dazu auch Das Kommandozeilenwerkzeug "FSDevTools").

Ausgangssituation

Was kann importiert werden?

Prinzipiell können nur FirstSpirit-Inhalte importiert werden, die aus einem Export mit External Synchronization stammen.

Importiert werden können:

Projektinhalte (Objekte): Inhalte, die über SiteArchitect oder ContentCreator erstellt und gepflegt werden. Dazu zählen Vorlagen, Projektstrukturen, Teilbäume und komplette Verwaltungen.
Beim Exportieren über External Synchronization werden diese Projektinhalte nach einer festgelegten Struktur im Dateisystem abgelegt (siehe Struktur Sync Verzeichnis). Dabei wird versucht, die Strukturen aus dem Projekt auf eine Ordnerhierarchie im Dateisystem abzubilden. Zusätzlich werden weitere, interne Informationen zu den FirstSpirit-Objekten exportiert, z. B. über die storeelement.xml. Diese Datei enthält Informationen wie ID, Referenzname des FirstSpirit-Objekts usw.
Basierend auf diesen Informationen (Ordnerhierarchie und internen Meta-Informationen) können Objekte vom Dateisystem zurück in ein FirstSpirit-Projekt importiert werden.
Projektinhalte ohne diese internen Informationen können nicht importiert werden!
Es ist also nicht möglich, eine herkömmliche Bilddatei (außerhalb einer Ordnerhierarchie und zusätzlicher Informationen) aus dem Zielverzeichnis in ein FirstSpirit-Projekt zu importieren.
Projekteigenschaften: Einstellungen, die über den ServerManager für ein Projekt definiert werden. Diese Eigenschaften können projektspezifisch („Projekteigenschaften“) oder global („Servereigenschaften“) definiert sein (z. B. Sprachen).
Für einige Projekte (insbesondere im Kontext von FirstSpirit CaaS) können benutzerdefinierte Projekteigenschaften (Custom Properties) definiert sein. Diese Eigenschaften können ebenfalls exportiert werden.

Für alle Eigenschaften gilt: Sind diese Eigenschaften (z. B. eine bestimmte Sprache) auf einem Server nicht vorhanden, werden sie beim Importieren auf dem Server angelegt (als Server- und als Projekteigenschaft). In diesem Fall muss der technische Benutzer die entsprechenden Rechte zum Anlegen besitzen (siehe Projekteigenschaften importieren).

Vorbereitung

Das lokale Repository des Entwicklers wurde zuvor über das Versionskontrollsystem aktualisiert (siehe 1) Update). Dabei wurde der zentrale Entwicklungsstand aus dem Remote-Repository übernommen. Die Projektinhalte und ggf. Projekteigenschaften liegen anschließend im Sync-Verzeichnis (Dateisystem) und sind bereit zum Import.

Kommandozeilen-Tool starten (fs-cli)

Auf dem Verzeichnis „bin“ (im FSDevTools-Installationsverzeichnis) wird die Kommandozeile geöffnet. Alle Anweisungen über die Kommandozeile starten mit dem Aufruf fs-cli und der entsprechenden Anweisung.

D:\fs-cli\bin>fs-cli [command]

Verbindung zu FirstSpirit herstellen (fs-cli)

Um die Verbindung zum (lokalen) FirstSpirit-Server und zum (lokalen) Projekt herzustellen, werden die entsprechenden Parameter (für Host -h, Port-port, Projektname -p, Benutzername -u und Passwort -pwd) übergeben, z. B.:

-h example.com.de -port 4242 -c HTTP -p "DevProject" -u userA -pwd mypwd

Optional kann der Parameter -sz für die Angabe einer Servlet Zone übergeben werden.

Für die Verbindung zum Dateisystem muss außerdem der Pfad zum Zielordner -sd im (lokalen) Dateisystem angegeben werden, z. B.: -sd D:/Git/DevProject

Die Verbindung kann optional über den Aufruf test geprüft werden, wobei der Platzhalter [connection_parameters] durch die projektspezifischen Verbindungseinstellungen ersetzt werden muss:

D:\fs-cli\bin>fs-cli [connection_parameters] test

Logausgabe bei erfolgreichem Test:

#########
Test was successful
#########
User: userA
Host: example.com
Port: 4242
Servlet zone: null
Connection Mode: HTTP
Project: DevProject
Connection to FirstSpirit closed!
Execution time: 10.591s

Import

Projektinhalte importieren (fs-cli)

Im nächsten Schritt wird der aktuelle Stand aus dem lokalen Dateisystem in die lokale FirstSpirit-Projektinstanz importiert (siehe Abbildung „Import“).

Ein Import wird über das Kommando import gestartet, wobei der Platzhalter [connection_parameters] durch die projektspezifischen Werte ersetzt werden muss:

D:\fs-cli\bin>fs-cli [connection_parameters] import

Beim Ausführen eines Imports wird der Inhalt des gesamten Sync-Ordners importiert!

Dabei werden im Projekt:

neue Objekte angelegt
bestehende Objekte geändert
bestehende Objekte verschoben
bestehende Objekte entfernt

Ein Import bedeutet nicht immer, dass FirstSpirit-Objekten oder Projekteigenschaften geändert oder hinzugefügt werden. Über einen Import können auch Inhalte aus dem Projekt gelöscht werden.

Für importierte Projektinhalte gilt: Wird ein Objekt exportiert und anschließend neu importiert (in ein weiteres FirstSpirit-Projekt), enthält die Versionshistorie nur die entsprechenden Anlege- bzw. Import-Operationen – nicht aber die gesamte Versionshistorie des Objektes aus dem Quellprojekt.

Hinweise zur Konfliktbehandlung: Durch die gleichzeitige Bearbeitung von Elementen durch mehrere Entwickler können Konflikte beim Importieren ins Projekt auftreten, die nicht auf Ebene des VCS erkannt werden (z. B. Namensraumkonflikte in FirstSpirit). Mögliche Konflikte und Lösungsstrategien werden unter Konfliktbehandlung beschrieben.

Hilfefunktion (fs-cli)

Weitere projektspezifische Einstellungen zum Import können über die Hilfefunktion von FSDevTools eingesehen werden:

D:\fs-cli\bin>fs-cli help import

Empfehlungen für den Import

Grundlage der Verteilten Entwicklung ist eine zentrale FirstSpirit-Instanz (bzw. ein zentrales Repository), in dem die geänderten Artefakte aller Entwickler zusammenfließen (siehe Abbildung unten „Dev_Project“, „Remote-Repository“). Der aus diesem Projekt bereitgestellte Export muss vollständig sein und alle Abhängigkeiten zwischen den einzelnen exportierten Objekten berücksichtigen (siehe Empfehlungen für den Export).

Das Importieren von FirstSpirit-Projektinhalten über External Synchronization muss ebenfalls vollständig und möglichst übersichtlich nach definierten Abläufen erfolgen.

Konkrete Empfehlungen:

Alle beteiligten FirstSpirit-Projektinstanzen (lokale Zielprojekte, zentrales Quellprojekt) sollten identische Einstellungen (Sprachmengen usw.) verwenden (vgl. Empfehlungen für den Import (Settings)).
Alle beteiligten FirstSpirit-Projektinstanzen sollten eine einheitliche Struktur besitzen (vgl. Aufbau des Projekts).
Es sollte immer ein vollständiger Import erfolgen (kein Import einzelner Verwaltungen oder Objekte).

Auf diese Weise können Probleme durch unvollständige Projektinhalte (in den lokalen Entwicklungsumgebungen) und dadurch verursachte Konflikte bereits im Vorfeld vermieden werden.

Datenbankinhalte importieren (fs-cli)

Beim Import eines Datenbank-Schemas über FSDevTools in ein Projekt (in dem das zu importierende Schema noch nicht enthalten ist), muss ein Datenbank-Layer angegeben werden. Über den Parameter {-lm | --layerMapping} wird beim Import der gewünschte Layer konfiguriert, z. B. über:

D:\fs-cli\bin>fs-cli import -lm *:CREATE_NEW

Dabei (Beispiel oben) wird die mit FirstSpirit ausgelieferte Standard-Datenbank (Derby) für das Projekt aktiviert.

Ist das Schema im Projekt (in das importiert wird) bereits vorhanden, ist die Angabe eines Layermappings nicht erforderlich.

Weitere Konfigurationsmöglichkeiten können über die interne Hilfe von FSDevTools eingesehen werden (siehe „Examples“).

Logausgabe bei fehlender Mapping-Konfiguration:

Importing...
Layer mapping is empty!
getLayer() with context -> schema: Products
Closing connection to FirstSpirit ...
(...) 
Missing mapping for source layer 'null'! 
Please specify a layer mapping. 
For more information type 'fs-cli help import'.

Logausgabe bei erfolgreicher Mapping-Konfiguration:

Importing...
Layer mapping: *:CREATE_NEW
Create a default derby layer 'derby_project48910_0' for project 
Import operation successful 
Import done.

Die Zuordnung wird für spätere Importvorgänge beibehalten.

Projekteigenschaften importieren (fs-cli)

Neben Projektinhalten, die über den SiteArchitect und/oder ContentCreator erfasst werden, können auch Projekteigenschaften über External Synchronization ex- bzw. importiert werden, auch server-übergreifend. Auf diese Weise können beispielsweise die Eigenschaften eines Projektes (wie Spracheinstellung und Auflösungen) auf ein leeres Projekt übertragen werden sowie die Projektkonfiguration mehrerer Projekte synchronisiert werden.

Einige Projekteigenschaften sind abhängig von Servereigenschaften, z. B. Benutzer, Gruppen, Aufträge usw. Diese Abhängigkeiten werden automatisch berücksichtigt.

Für den Im- und Export von Projekteigenschaften sind mindestens die Rechte eines Projekt-Administrators erforderlich, für den Import von Servereigenschaften die Rechte eines Server-Administrators.

Empfehlungen für den Import (Settings)

Alle am Projekt beteiligten Entwickler und Systeme müssen ein einheitliches Setting verwenden.
Das bedeutet: Die lokalen Projekte müssen einen einheitlichen Aufbau und identische Projekteinstellungen besitzen!

Warum ist das wichtig? - ein Beispiel:

In einer Verteilten Entwicklungsumgebung arbeiten mehrere Entwickler an einem FirstSpirit-Projekt. Die geänderten Projektinhalte und -einstellungen werden über ein Versionskontrollsystem auf mehrere Systeme verteilt, z. B.:

auf weitere, lokale Entwicklungsumgebungen („Development“)
auf ein Testsystem („Test“)
auf ein Produktivsystem („Productive“)

Haben in diesem Szenario die einzelnen Systeme z. B. unterschiedliche Sprachmengen, wird das immer dann zu Konflikten führen, wenn zusätzlich die Projekteigenschaft projectproperty:LANGUAGES über External Synchronization transportiert wird (also ein Bestandteil der Export- bzw. Import-Operation ist).

In diesem Fall führt ein „Check-in / Export“ vom Entwicklungssystem (Sprachmenge: 2) ins VCS und ein anschließender „Check-out / Import“ auf dem Testsystem (Sprachmenge: 10) dazu, dass die Inhalte der nicht berücksichtigten 8 Sprachen entfernt werden.

Weiteres Vorgehen

Projektinhalte bearbeiten

Nach dem erfolgreichen Import können die Projektinhalte in der lokalen Entwicklungsumgebung bearbeitet werden.

Weiter zu Schritt 3) Modification.

Druckversion | Seitenanfang