Schritt 4) Exportieren der Projektinhalte (über External Synchronization)

Vom FirstSpirit-Projekt ins Dateisystem

In diesem Schritt wird über External Synchronization:

• der Entwicklungsstand aus der lokalen FirstSpirit-Projektinstanz in den Zielordner im Dateisystem exportiert.

Dieser Schritt ist notwendig, um geänderte Inhalte anschließend in den zentralen Entwicklungsstand zu überführen.

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

Vergleiche Abbildung Schritt 4) Export.

Jeder der am Projekt beteiligten Entwickler sollte immer den gleichen Export-Aufruf verwenden. Der Aufruf ist abhängig vom Projekt und den Elementen, die innerhalb der Projektvorlagen referenziert werden.

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

Ausgangssituation

Was kann exportiert werden?

Exportiert 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.
• 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.

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.

Vor der Weiterentwicklung wurden alle Inhalte in die lokale FirstSpirit-Projektinstanz importiert (siehe 2) Import).

Anschließend wurden die Projektinhalte bearbeitet (siehe 3) Modification). Ist nach Abschluss der Bearbeitung ein stabiler Stand erreicht, ist der geänderte Entwicklungsstand aus der lokalen FirstSpirit-Projektinstanz bereit zum Export.

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

Export

Projektinhalte exportieren (fs-cli)

Im nächsten Schritt wird der aktuelle Stand aus der lokalen FirstSpirit-Projektinstanz in den Zielordner im lokalen Dateisystem exportiert (siehe Abbildung „Export“).

Der Export wird über das Kommando export gestartet, wobei die Platzhalter [connection_parameters] und [export_objects] durch die projektspezifischen Werte ersetzt werden müssen:

D:\fs-cli\bin>fs-cli [connection_parameters] export [export_objects] 

Beim Ausführen eines Exports werden im Dateisystem:

• neue Ordner und Dateien angelegt
• bestehende Ordner und Dateien geändert
• bestehende Ordner und Dateien verschoben
• bestehende Ordner und Dateien entfernt

Hilfefunktion (fs-cli)

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

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

Welcher Stand wird berücksichtigt?

Bei Vorlagen wird nicht unterschieden zwischen freigegebenem und aktuellem Stand: es wird immer der aktuelle Bearbeitungsstand der jeweiligen Vorlage exportiert.
Auch in den anderen Verwaltungen wird standardmäßig immer der aktuelle Stand des jeweiligen Objekts beim Export berücksichtigt. Bei einem Export ist es also unerheblich, ob die zu exportierenden Objekte freigegeben sind oder nicht.

Empfehlungen für den Export

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“).

Jeder Entwickler arbeitet darüber hinaus in seiner eigenen, lokalen Entwicklungsumgebung mit einem eigenen FirstSpirit-Server, einem eigenen, lokalen Repository und eigenen, lokalen FirstSpirit-Projektinstanzen (siehe Abbildung unten „Local Dev_Project“, „ Local Repository“).

Im Verlauf der verteilten Entwicklung werden FirstSpirit-Projektinhalte zwischen dem zentralen Entwicklungsstand und den lokalen Entwicklungsständen der einzelnen Entwickler transportiert, d.h.:

• Zu Beginn einer Überarbeitung holt sich der der Entwickler zunächst die Inhalte vom zentralen Entwicklungsstand in seine lokale Entwicklungsumgebung (vgl. Update des Repositorys - Import).
• Nach Abschluss einer Bearbeitung werden die Inhalte der lokale Entwicklungsstände dann wieder in den zentralen Entwicklungsstand übernommen. Dabei wird der lokale Entwicklungsstand der Projekte über External Synchronization in den Zielordner des lokalen Dateisystems exportiert (siehe Abbildung „Export“) und von dort über das VCS in den zentralen Stand übernommen.

Damit die Synchronisierung der Inhalte zwischen unterschiedlichen Projekten und in unterschiedlichen Umgebungen möglichst reibungslos funktioniert, werden Anforderungen an die Projekte und auch an die transportierten Inhalte gestellt.

Empfehlungen für Projekte

Projekteinstellungen:

Alle beteiligten FirstSpirit-Projektinstanzen (lokale Zielprojekte, zentrales Quellprojekt) sollten identische Einstellungen (Sprachmengen usw.) verwenden (vgl. Empfehlungen für den Import (Settings)).
Projekteigenschaften können über den Parameter projectproperty zum Export hinzugefügt werden.
Hinweis: Einige Projekteigenschaften sind abhängig von Servereigenschaften. Diese Abhängigkeiten werden automatisch berücksichtigt.

Alle Projekteigenschaften eines Projektes (inkl. der benutzerdefinierten Eigenschaften) können über
export projectproperty:ALL exportiert werden.

Einzelne Projekteigenschaften können über definierte Schlüsselbegriffe exportiert werden, z. B. Sprachen und Auflösungen über:
export projectproperty:LANGUAGES projectproperty:RESOLUTIONS

Weitere Schlüsselbegriffe zum Exportieren von Projekteigenschaften:

• COMMON (allgemeine Projekteigenschaften (im ServerManager unter Projekteigenschaften / Optionen))
• FONTS (Fonts, die für das Projekt verfügbar sind; Abhängigkeit zu Servereigenschaften)
• LANGUAGES ( Sprachen, die im Projekt verfügbar sind; Abhängigkeit zu Servereigenschaften)
• RESOLUTIONS (Bildauflösungen des Projekts)
• USERS (Benutzer, die Zugriff auf das Projekt besitzen; Abhängigkeit zu Servereigenschaften)
• GROUPS (Gruppen, die Zugriff auf das Projekt besitzen)
• SCHEDULE_ENTRIES (Aufträge und Aktionsvorlagen des Projekts; Abhängigkeit zu Servereigenschaften)
• TEMPLATE_SETS (Vorlagensätze des Projekts; Abhängigkeit zu Servereigenschaften)
• MODULE_CONFIGURATIONS (Konfigurationen von Projekt- und Web-Komponenten des Projekts; Abhängigkeit zu Servereigenschaften)
  Hinweis: Es werden keine Projekt- bzw. Web-Komponenten ex- bzw. importiert! Die betreffende Komponente muss im Zielprojekt entweder manuell oder über die API hinzugefügt werden
  (Interface ModuleAdminAgent, Package: de.espirit.firstspirit.agency, FirstSpirit Access-API).
• CUSTOM_PROPERTIES (Benutzerdefinierte Projekteigenschaften)
  Hinweis: Diese Eigenschaften können ausschließlich über die API (über die Methode setCustomProperties) definiert werden (nicht über den FirstSpirit ServerManager).
  (Interface Project, Package: de.espirit.firstspirit.access.project, FirstSpirit Access-API)

Projektstruktur:
Alle beteiligten FirstSpirit-Projektinstanzen sollten eine einheitliche Struktur besitzen.
Für eine möglichst einfache und übersichtliche Synchronisierung von Projektinhalten sollten außerdem alle für die Vorlagenentwicklung relevanten Inhalte im Projekt in eigenen Ordnern verwaltet werden (siehe Getting started - Aufbau und Konfiguration des Projekts).

Empfehlungen für Projektinhalte

Speziell Vorlagen haben in der Regel verschiedene Abhängigkeiten (Referenzen) zu anderen FirstSpirit-Objekten. Dies können andere Vorlagen sein oder auch Objekte aus anderen Verwaltungen, z. B. CSS-Dateien aus der Medien-Verwaltung.

In der Regel müssen bei einem Export auch diese referenzierten Objekte berücksichtigt werden. Ein Export sollte daher möglichst vollständig sein und alle Abhängigkeiten berücksichtigen, die zwischen den einzelnen, exportierten Objekten bestehen.

Jeder der am Projekt beteiligten Entwickler sollte immer den gleichen Export-Aufruf verwenden. Der Aufruf ist abhängig vom Projekt und den Elementen, die innerhalb der Projektvorlagen referenziert werden.

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

Vorlagen:
Es sollten immer alle Vorlagen eines Projekts exportiert werden, z. B. die gesamte Vorlagen-Verwaltung über den Parameter templatestore.

Strukturen (Seitenreferenzen):
Zusätzlich sollten alle Seitenreferenzen exportiert werden, die innerhalb der Vorlagen referenziert sind, z. B. die Vorschauseiten der Vorlagen (Register „Eigenschaften“). Liegen diese Seitenreferenzen in einem eigenen Ordner „preview“ im Projekt vor, kann der gesamte Ordner z. B. über den Parameter pagereffolder:preview zum Export hinzugefügt werden.

Inhalte (Seiten):
Zusätzlich sollten alle Seiten exportiert werden, die in exportierten Objekten referenziert sind, z. B. Seiten, die mit den Seitenreferenzen (s.o.) verbunden sind. Liegen diese Seiten in einem, eigenen Ordner „previewp“ im Projekt vor, kann der gesamte Ordner z. B. über den Parameter pagefolder:preview zum Export hinzugefügt werden.

Medien:
Zusätzlich sollten alle Medien exportiert werden, die in exportierten Objekten referenziert sind, z. B.:

• Bild-Dateien für Icons
• Bild-Dateien für Buttons
• Bild-Dateien für Navigationselemente
• CSS-Dateien
• JavaScript-Dateien

Eine Referenz zu diesen Medien wird in der Regel auf den Ausgabekanal-Registern hergestellt (z. B. über $CMS_REF(media:"...")$). Liegen die Medien in einem eigenen Ordner „layout“ im Projekt vor, kann der gesamte Ordner z. B. über den Parameter mediafolder:layout zum Export hinzugefügt werden.

Datenquellen:
Zusätzlich sollten alle Datenbankinhalte exportiert werden, die in exportierten Objekten referenziert sind. Dabei müssen sowohl Datensätze als auch die zugehörigen Datenquellen exportiert werden.
Liegen die Datensätze in einem eigenen Ordner „glossary“ im Projekt vor, kann der gesamte Ordner z. B. über den Parameter path:/ContentStore/glossary zum Export hinzugefügt werden und die entsprechende Datenquelle z. B. über den Parameter entities:glossar.

In Ausnahmefällen (siehe unten: Unterstützung für den gemeinsamen Zugriff auf eine Datenbank) kann der Einsatz einer zusätzlichen Mapping-Datei sinnvoll sein.

Der Ex- bzw. Import von (umfangreichen) Datenbankinhalten kann hohe Last erzeugen!

Globale Inhalte:
Zusätzlich sollten Globale Inhalte exportiert werden, die in exportierten Objekten referenziert sind, z. B. Globale Inhalte, die auf den Ausgabekanal-Registern der Vorlagen referenziert sind (z. B. über $CMS_VALUE(#global.gca("..."))$). Liegen diese Inhalte in einem eigenen Ordner „global_export“ im Projekt vor, kann der gesamte Ordner z. B. über den Parameter path:/GlobalStore/GlobalContentArea/global_export zum Export hinzugefügt werden.

Optional: Unterstützung für den gemeinsamen Zugriff auf eine Datenbank (Mapping.xml)

Über die Funktionalität „FirstSpirit External Synchronization“ können Datenbank-Inhalte (Datensätze) und die zugehörigen Datenbank-Strukturen (Schemata, Tabellen, Spalten) eines FirstSpirit-Projekts (Quellprojekt) exportiert und in weitere FirstSpirit-Projekte (Zielprojekte) importiert werden. Die dbnames der Spaltennamen und Tabellen werden beim Synchronisieren neu berechnet. Dieses Verhalten kann, unter den folgenden Voraussetzungen, dazu führen, dass in den Zielprojekten, Spalten und Tabellen der Datenbank nicht gefunden werden können:

• die FirstSpirit-Schemata der beteiligten Projekte referenzieren dieselben Datenbanktabellen (und zeigen nicht auf jeweils eigene Datenbank-Tabellenräume) und
• die dbnames entsprechen nicht den automatisch berechneten dbnames

Für diesen speziellen Anwendungsfall kann beim Exportieren und Importieren von Datenbank-Schemata eine zusätzliche Mapping-Datei (Mapping.xml) verwendet werden, in der die Datenbanknamen des Quellprojekts zusammen mit den FirstSpirit-eigenen, eindeutige Bezeichnern (UUIDs) gespeichert werden, z. B.:

<xs:gid dbName="j_categories_spalte_x" uuid="66843bbe-da0d-46e3-a136-76bd93d782bb"/>
<xs:gid dbName="j_categories_spalte_y" uuid="4ba29641-26af-4edd-bac0-5a352913974d"/>
...

Über diese eindeutige Zuordnung ist es möglich, die Datenbank-Schemata von lesend angebundenen Datenbanken („Kein Schema Sync“) über „External Synchronization“ wie folgt zu synchronisieren:

• Wird ein Schema im Quellprojekt geändert und über „External Synchronization“ in weitere FirstSpirit-Projekte synchronisiert, so werden die Namen von Datenbanktabellen und Datenbankspalten aus dem Quellprojekt in die Zielprojekte übernommen.
• Werden Datenbanktabelle oder Datenbankspalte im Zielprojekt neu angelegt, so wird bevorzugt der entsprechende dbname des Ursprungsschemas verwendet.

Bei einer Verwendung von „FirstSpirit External Synchronization“ kann die Mapping-Datei (Mapping.xml) über eine Option im Interface ExportOperation.SchemaOptions (setExportGidMapping=true) zur Export-Datei hinzugefügt werden:

ExportOperation exportOperation = ... // get the export operation via agent; 
ExportOperation.SchemaOptions schemaOptions = exportOperation.addSchema(schema); 
schemaOptions.setExportGidMapping(true); 
ExportOperation.Result result = exportOperation.perform(...); 

Das Kommandozeilenwerkzeug FSDevTools unterstützt die Option ab Version 2.6. In der Standardeinstellung wird bei der Verwendung von FSDevTools keine Mapping-Datei erzeugt (setExportGidMapping=false).

Ohne Mapping-Datei (Standardverhalten beim Einsatz von FirstSpirit External Synchronization) werden die dbnames der Spaltennamen und Tabellen beim Synchronisieren neu berechnet.

Die Mapping-Datei sollte nur verwendet werden, um vorhandene Konflikte in den Zielprojekten aufzulösen, die beim gemeinsamen Zugriff auf eine Datenbank entstehen können (siehe „Voraussetzungen“ oben). Für alle anderen, regulären Anwendungsfällen wird eine Verwendung der Mapping-Datei nicht empfohlen.

Nach dem Export

Abbildung der Inhalte im Dateisystem

Nach einem erfolgreichen Export über External Synchronization werden die FirstSpirit-Inhalte im Zielverzeichnis als Dateien abgelegt, die dort auch editiert werden können (siehe Bearbeiten im Dateisystem). Beim Exportieren wird versucht, die Strukturen aus dem Projekt auf die Ordnerhierarchie im Dateisystem abzubilden. Dabei werden Dateien mit inhaltlichen (fachlichen) Informationen zu den FirstSpirit-Objekten von Dateien mit Meta-Informationen (Checksummen, Referenztabellen usw.) unterschieden.

Für jedes FirstSpirit-Element werden folgende Dateien abgelegt:

• ein Ordner
  Für jedes FirstSpirit-Element wird ein Ordner im lokalen Dateisystem angelegt. Dabei wird der Pfad vom in FirstSpirit gewählten Objekt bis zum jeweiligen Wurzelknoten nach oben in Ordnern abgebildet. Der Dateiname leitet sich dabei vom Referenznamen des jeweiligen FirstSpirit-Elements ab.
• StoreElement.xml
  Für jedes FirstSpirit-Element wird eine XML-Datei mit dem Namen StoreElement.xml abgelegt. Diese Datei enthält Informationen wie ID, Referenzname des FirstSpirit-Objekts usw. und kann extern bearbeitet werden.
• weitere XML-Dateien
  Je nach FirstSpirit-Objekttyp können darüber hinaus weitere XML-Dateien abgelegt werden, z. B. zu Inhalten von Absätzen (data.EN.xml), Datensätzen einer Datenquelle (Entities.xml), zu den einzelnen Registern von Vorlagen (beispielsweise Formularbereich, Regel-Definition) usw.
• eine Inhaltsdatei
  Für einige FirstSpirit-Elemente werden fachliche Inhalte, die nicht im XML-Format dargestellt werden können, gesonderten abgelegt. Der Dateiname leitet sich dabei vom Referenznamen des jeweiligen FirstSpirit-Elements ab. Das Format variiert dabei abhängig vom Typ des FirstSpirit-Elements:
  • für Medien beispielsweise die Binärdateien des Bildes oder der Datei,
  • für den HTML-Ausgabekanal einer Vorlage eine HTML-Datei.
• fachliche TXT-Dateien
  Zu einigen Objekten werden TXT-Dateien mit fachlichen Inhalten abgelegt, z. B. Schnipsel-Definitionen von Vorlagen (SnippetHeader.txt).
• Meta-TXT-Dateien (FS_....txt, „meta files“)
  TXT-Dateien mit dem Präfix FS_ (FS_Files.txt, FS_Info.txt, FS_References.txt usw.) enthalten Meta-Informationen. Diese Dateien sollten nicht extern bearbeitet werden.

Prinzipiell werden nur Dateien angelegt, wenn entsprechende Informationen im Projekt hinterlegt wurden, beispielsweise das jeweilige Feld gefüllt ist. In einem Export müssen also nicht alle aufgelisteten Dateien zwingend enthalten sein bzw. es werden – bis auf wenige Ausnahmen – keine leeren Dateien angelegt.

Weitere Informationen siehe Konfiguration - Hinweis zur Versionierung.

Schematische Darstellung

Weiteres Vorgehen

Änderungen in den zentralen Stand übernehmen

Die geänderten Artefakte werden nach Abschluss der Arbeit an einem Arbeitspaket in den zentralen Entwicklungsstand (Remote-Repository) übernommen. Damit stehen sie allen Entwicklern zur Verfügung.

Weiter zu Schritt 5) Commit/Push.