Release Notes

Im Rahmen der Produktpflege wurde der Java Service Wrapper, über den die Java Virtual Machine (Java VM) von FirstSpirit gestartet und beendet wird, an Änderungen von Java 16 angepasst. Darüber hinaus wird jetzt der seit Java 11 verfügbare Java Flight Recorder (JFR) unterstützt.
Die Änderungen werden mit den Installations- und Aktualisierungsarchiven des aktuellen FirstSpirit-Release ausgeliefert (Version 2.1.0).

• Sowohl im Falle von Neuinstallationen als auch bei Aktualisierung eines bestehenden FirstSpirit-Servers per Tar-Gzip-Aktualisierungsarchiv (Datei fs-update-[version].tar.gz) werden diese Änderungen automatisch angewendet. Für bestehende Installationen wird ein zeitnahes Update empfohlen.
  Bei Bedarf können die mit dem aktuellen Release ausgerollten Einstellungen manuell angepasst werden (siehe unten).
• Im Falle einer Aktualisierung des FirstSpirit-Servers per Auto-Update oder Inplace-Upgrade (Austausch der Datei fs-isolated-server.jar im Dateisystem) werden die Dateien des Java Service Wrappers nicht automatisch aktualisiert. Auch in diesem Fall sollte der Java Service Wrapper zeitnah über das Tar-Gzip-Aktualisierungsarchiv (Datei fs-update-[version].tar.gz) aktualisiert werden.

Änderung des Standardwerts von illegal-access

Der Parameter illegal-access steuert den Zugriff per Reflexion auf den Klassenpfad. Mit Java 16 wurde der Standardwert von permit auf deny geändert: Damit sind keine Zugriffe auf den Klassenpfad mehr möglich. Der Parameter ist deprecated und kann in einer späteren Version entfallen. Somit wären dann keine Zugriffe mehr auf den Klassenpfad erlaubt.
Um einen einfacheren Umstieg zu ermöglichen, wurde der entsprechende Parameter im FirstSpirit Wrapper jetzt von permit auf warn gesetzt:

wrapper.java.additional.32=--illegal-access=warn

Jeder entsprechende Zugriff auf Klassenpfade wird damit als Warnung im Log festgehalten:

WARNING: An illegal reflective access operation has occurred

Auf diese Weise können potenziell fehlende Angaben in kundenspezifischen FirstSpirit-Modulen ermittelt und dann ergänzt werden. Fehlen diese Angaben, kann dies in späteren Versionen potenziell zu Funktionsänderungen oder -verlusten führen.
Um die Meldungshäufigkeit zu reduzieren, ist es möglich, den Parameter manuell wieder auf permit zu setzen:

wrapper.java.additional.32=--illegal-access=permit

In diesem Fall werden lediglich beim ersten unerlaubten Zugriff eine Warnung ausgegeben, z. B.

WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective 
   access operations
WARNING: All illegal access operations will be denied in a future release

Ergänzung von add-opens in der Vendor-Datei

In der Vendor-Datei wurden add-opens ergänzt, damit aufgrund der neuen Konfiguration illegal-access=warn keine Warnungen für FirstSpirit-Server in der Standardkonfiguration ausgegeben werden.
Sollten Angaben fehlen, werden Warnungen in folgender Form im Log festgehalten:

WARNING: Illegal reflective access by de.espirit.firstspirit.common.xml.XmlSerializer 
  (file:/opt/firstspirit/.../fs-isolated-server.jar) 
  to field java.util.concurrent.atomic.AtomicReference.value

In diesem Fall ist zu prüfen, ob die Verwendung aus einem kundenspezifischen Modul stammt oder von FirstSpirit. Im Zweifelsfall wenden Sie sich bitte an den e-Spirit Technical Support.

Änderung am Garbage-Collection-Log

Mit der aktuellen Wrapper-Version erfolgt das Dateilogging des Garbage Collectors wieder rotierend, d. h. es werden maximal 9 Logdateien mit einer maximalen Größe von 10 Megabyte vorgehalten. Sind diese Werte erreicht, überschreiben neue Log-Dateien dann bestehende.
Der entsprechende Parameter lautet:

wrapper.java.additional.33=-Xlog:gc*,gc+age=trace,safepoint,heap*,phases*:
   file=log/fs-gc.log::filecount=9,filesize=10M

Um den vorherigen Stand wiederherzustellen (keine Rotation, kein Überschreiben von Dateien), sollte dieser Parameter in der Datei fs-wrapper.conf durch folgenden ersetzt werden:

wrapper.java.additional.33=-Xlog:gc*,gc+age=trace,safepoint,heap*,phases*:log/fs-gc.log

Neu: Konfiguration für den Java Flight Recorder (JFR)

Der JFR kann ab Java 11 eingesetzt werden, um erweiterte Informationen zu erhalten (https://access.redhat.com/documentation/en-us/openjdk/11/pdf/using_java_flight_recorder_for_java_mission_control/using-java-flight-recorder-for-java-mission-control.pdf).
Die Installations- und Aktualisierungsarchive des aktuellen FirstSpirit-Release enthalten eine Standardkonfiguration für den JFR.
Standardmäßig ist der JFR deaktiviert. Um ihn zu aktivieren, muss die Datei fs-recording.conf.disabled im Verzeichnis conf umbenannt werden in

fs-recording.conf

Die in dieser Datei enthaltene Standardkonfiguration ist wie folgt:

#encoding=UTF-8
-XX:FlightRecorderOptions=repository=work/recording
-XX:StartFlightRecording=name=FirstSpirit,disk=true,dumponexit=true,
   filename=log/fs-recording.jfr,maxsize=50m,maxage=1d

Im JDK Mission Control erreicht man dadurch die relevanten JFR-Informationen unter „FirstSpirit“.
Bei einem unerwarteten Beenden des Servers wird ein Dump erstellt und in der Datei fs-recording.jfr abgelegt (Verzeichnis log). Sie ist auf eine maximale Größe von 50 Megabyte und ein maximales Alter von einem Tag konfiguriert.

JFR für bestehende Installationen nutzen: Die JFR-Datei ist im Aktualisierungsarchiv fs-update-[version].tar.gz unter conf/conf-all/fs-recording.conf.disabled.default.txt enthalten und befindet sich nach einer Aktualisierung dort im FirstSpirit-Server-Verzeichnis. Diese Datei muss dann entsprechend nach conf/fs-recording.conf.disabled bzw. conf/fs-recording.conf kopiert werden.

Weiterführende Dokumentation

• zum Java Service Wrapper (Handbuch für Administratoren)
• zur Aktualisierung des Java Service Wrappers (Installationsanleitung)
• zum Java Flight Recorder (JFR): https://access.redhat.com/documentation/en-us/openjdk/11/pdf/using_java_flight_recorder_for_java_mission_control/using-java-flight-recorder-for-java-mission-control.pdf

Moderne Web-Angebote verwenden heutzutage zunehmend Content aus unterschiedlichen Quellen. Um Kollisionen zwischen Markups, Skripten und Styles aus unterschiedlichen Quellen zu vermeiden, kann Shadow DOM (z. B. ... .attachShadow({mode: 'open'})...) eingesetzt werden: Dabei handelt es sich um eine Technologie, die eine Kapselung von HTML-Elementen ermöglicht. Auf diese Weise können einfach wiederverwendbare und interagierende Komponenten erstellt werden. Shadow DOM wird von den für FirstSpirit relevanten Browsern in aktuellen Versionen unterstützt.

Mit dem aktuellen Release können Inhalte in geschachtelten Shadow DOM-Komponenten jetzt auch im FirstSpirit ContentCreator per EasyEdit und InEdit bearbeitet werden.
Voraussetzung ist die Verwendung der editorId. An Komponenten, die bereits die editorId verwenden, muss nichts geändert werden, um den neuen Shadow DOM-Support zu nutzen.

Hinweis: Bei einem Neuladen kann es aus technischen Gründen dazu kommen, dass bei Verwendung von Shadow DOM-Elementen nicht nur geänderte Teilbereiche ausgetauscht werden, sondern dass die gesamte Vorschau neugeladen wird. Dies gilt für das automatische Neuladen sowie für gezielte Neulade-Operationen über die WE_API, wie WE_API.Preview.reload(Element) oder WE_API.Preview.reload(String).

Zu weiteren Informationen siehe

• https://www.w3.org/TR/shadow-dom u.a.
• https://docs.e-spirit.com/odfs/vorlagenentwick/content-highlig/index.html

Folgende Modul-Versionen für „FirstSpirit Content Experience Tools“ werden von FirstSpirit 2021-06 unterstützt:

* Diese Module benötigen ab dieser Version FirstSpirit 2020-03 oder höher.

Über den Parameter cxt.dataservice.url wird in der FragmentCreator-Konfiguration die Adresse angegeben, über den die DAP Bridge erreichbar ist.

Wird dort eine http-Adresse angegeben, darf für den HTTP-Konnektor des Tomcat das Attribut secure nicht auf true gesetzt werden (secure="true"), da in diesem Fall aus Sicherheitsgründen eine Verbindung zwischen DAP Bridge und Tomcat unterbunden wird.

Die Statusseite prüft jetzt (unter dem Punkt „Configuration check“), ob für cxt.dataservice.url http oder https gesetzt ist und ob für den HTTP-Konnektor des Tomcat das Attribut secure gesetzt wurde (secure="true"):

• Handelt es sich bei cxt.dataservice.url um eine http-Adresse und ist das Attribut secure des Konnektors auf true gesetzt, wird dies als ERROR visualisiert. Es ist dann keine Verbindung möglich.
• Ist das Attribut secure nicht gesetzt (oder auf false) oder wird eine https-Adresse mit dem Attribut secure="true" verwendet, ist eine Verbindung möglich.

Sind http-Adresse für cxt.dataservice.url und secure="true" für den Tomcat-Konnektor für das jeweilige Setup zwingend erforderlich, sollten zwei separate Tomcat-Konnektoren (auf unterschiedlichen Ports) erstellt werden:

• für die externe Kommunikation: Dieser kann https und / oder secure="true" verwenden. Auf den Port dieses Konnektors muss dann die DAP Bridge konfiguriert werden.
• für die interne Kommunikation: Dieser darf nur dann ein secure="true"-Attribut aufweisen, wenn für cxt.dataservice.url eine https-Adresse verwendet wird.

Zur Konfiguration von Tomcat HTTP-Konnektoren siehe u.a. https://tomcat.apache.org/tomcat-9.0-doc/config/http.html.

FirstSpirit Content Experience Tools ist von Beginn an als Microservice-Architektur konzipiert. Ziel des modularen Aufbaus und unabhängiger Prozesse sind u.a. verbesserte Verfügbarkeit, Skalierbarkeit und Wartbarkeit.

Bisher war die CXT-Plattform in den FragmentCreator integriert und wurde mit diesem ausgeliefert. Dienste, die für die Plattform erforderlich sind, wurden bei jedem Starten einer FragmentCreator-Instanz hochgefahren und verwaltet, auch wenn sie nicht benötigt wurden (z. B. OAuth, MicroService-Controller, Eureka usw.).
Um die Performanz und Steuerbarkeit zu verbessern, wurden CXT-Plattform und FragmentCreator jetzt voneinander getrennt. CXT-Plattform und FragmentCreator werden jeweils als eigenständige Webanwendungen betrieben. Damit wird auch der Microservice-Gedanke weiter verfolgt.
Mit dem aktuellen Release beinhalten folgende Versionen der betroffenen Module diese technologische Umstellung:

• „Platform“-Modul: Version 2.x
• „FragmentCreator“-Modul: Version 3.x

Die Module können über den Technical Support angefordert werden.

Voraussetzungen für die Verwendung der neuen Technologie:

• FragmentCreator und Plattform benötigen jeweils eine SOCKET-Verbindung zum FirstSpirit-Server.
• Beide Webanwendungen müssen über denselben externen Host erreichbar sein („same-origin“).

Konfiguration
Die Module bringen eine Standard-Konfiguration mit, in der ein Betrieb möglich ist. Eine spezifische Konfiguration der Module ist im Classpath unter

/config/cxt-platform.properties
/config/cxt-fragment-creator.properties

möglich.
Alternativ kann die Konfiguration über die Datei web.xml erfolgen. Diese wird allerdings bei einem automatischen FirstSpirit-Update überschrieben bzw. zurückgesetzt. Ebenso durch die Werte einer vorhandenen Properties-Datei.

Die Parameterwerte sind unter

• https://docs.e-spirit.com/odfs/edocs/cxt/installation-mo/module-installi/plattform/index.html#web_xml_1 (Plattform)
• https://docs.e-spirit.com/odfs/edocs/cxt/installation-mo/module-installi/fragmentcreator/index.html#web_xml (FragmentCreator)

beschrieben.

Migration
Für bestehende Installationen müssen wenige Anpassungen vorgenommen werden, um die neue Technologie nutzen zu können:

Installation des neuen „Platform“-Moduls

1) Datei installieren:

platform-[version].fsm

(FirstSpirit Server Manager / „Servereigenschaften / Module“, Schaltfläche „Installieren“, siehe dazu auch https://docs.e-spirit.com/odfs/edocs/admi/firstspirit-ser/server-eigensch/module/index.html)

2) Globale Webanwendung erstellen
Die Webanwendung muss anschließend im Bereich „Web-Applikationen“ als eigene, globale Webanwendung definiert und konfiguriert werden.
(FirstSpirit Server Manager / „Servereigenschaften / Web-Applikationen / Globale Web-Apps konfigurieren“, Schaltfläche „Hinzufügen“, siehe dazu auch https://docs.e-spirit.com/odfs/edocs/admi/firstspirit-ser/server-eigensch/web-applikation/index.html)

Der Wert, der in das Feld Web Context wird, muss

/cxt-platform

lauten, z. B.

3) Web-Komponente hinzufügen
Für diese globale Web-Applikation muss ein geeigneter Webserver ausgewählt sein und dann die Web-Komponente „CXT Platform“ hinzugefügt werden.

4) web.xml bearbeiten

cxt.dataservice.url=http://localhost:8080/cxt/
cxt.platform.internal-url=http://localhost:8080/cxt-platform/
cxt.platform.external-url=https://external/cxt-platform/
cxt.platform.internal-port=8080
cxt.platform.eureka.password=[...]
cxt.platform.firstspirit.hostname=localhost
cxt.platform.firstspirit.port=1088
cxt.platform.firstspirit.connection-mode=SOCKET
cxt.platform.cors-allowed-origins=[...]
cxt.platform.microapps.csp-origins=[...]
cxt.platform.oauth.client-secret=[...]
cxt.platform.oauth.jwt-signing-key=[...]
cxt.platform.oauth.access-token-validity-seconds=3600
cxt.platform.oauth.refresh-token-validity-seconds=43200

Alternativ kann die Konfiguration auch über eine Properties-Datei vorgenommen werden, im Classpath unter

/config/cxt-platform.properties

Die dort hinterlegte Konfiguration überschreibt alle anderen Propertys (u.a. auch die Konfiguration über die Datei web.xml). Bei einem automatischen FirstSpirit-Update bleiben die in der Properties-Datei hinterlegten Einstellungen unverändert und werden nicht überschrieben bzw. zurückgesetzt.

5) Deployen
Die wie oben beschrieben konfigurierte Web-Applikation für die CXT-Plattform muss anschließend per Schaltfläche „Installieren“ auf dem gewählten Webserver ausgerollt werden.
(Siehe dazu auch https://docs.e-spirit.com/odfs/edocs/admi/firstspirit-ser/server-eigensch/web-applikation/index.html.)

Installation und Anpassung der Konfiguration des „FragmentCreator“-Moduls

1) Datei in aktuellster Version (3.x) installieren:

fragmentcreator-[version].fsm

2) Web-Komponente aktualisieren
Unter „Web-Applikationen“ auf dem Register der globalen Web-App des FragmentCreator die Web-Komponente „FragmentCreator“ aktualisieren (Schaltfläche „Aktualisieren“):

3) web.xml bearbeiten

Die bisher verwendeten Parameter

firstSpiritDataServiceBaseUrl=http://localhost:8080/cxt/
webServiceBaseUrl=http://localhost:8080/FragmentCreator/
externalBaseUrl=https://external/FragmentCreator/
firstSpiritHost=localhost
firstSpiritPort=1088
firstSpiritConnectionMode=SOCKET
oAuthClientSecret=[...]
corsAllowedOrigins=*
eurekaPassword=[...]
accessTokenValiditySeconds=3600
refreshTokenValiditySeconds=43200

wurden jetzt in einer Package-Struktur organisiert und die Benamung vereinheitlicht:

cxt.fragmentcreator.internal-url=http://localhost:8080/FragmentCreator/
cxt.fragmentcreator.external-url=https://external/FragmentCreator/
cxt.fragmentcreator.platform.oAuth-client-secret=[...]
cxt.fragmentcreator.platform.eureka-password=[...]
cxt.fragmentcreator.cors-allowed-origins=*
cxt.platform.firstspirit.hostname=localhost
cxt.platform.firstspirit.port=1088
cxt.platform.firstspirit.connection-mode=SOCKET

Die bisherigen Parameter

firstSpiritDataServiceBaseUrl
accessTokenValiditySeconds
refreshTokenValiditySeconds
cxt.platform.microapps.csp-origins

entfallen an dieser Stelle und werden durch die Plattform konfiguriert:

cxt.fragmentcreator.platform.internal-url=http://localhost:8888/cxt-platform/
cxt.fragmentcreator.platform.external-url=https://external/cxt-platform/

(siehe web.xml zum Plattform-Modul oben)

Waren bisher für den FragmentCreator kundenspezifische Werte konfiguriert, müssen diese auch in die Konfiguration des neuen FragmentCreator-Moduls übernommen werden.
Alternativ kann die Konfiguration auch über eine Properties-Datei vorgenommen werden, im Classpath unter

/config/cxt-fragment-creator.properties

Die dort hinterlegte Konfiguration überschreibt alle anderen Propertys (u.a. auch die Konfiguration über die Datei web.xml). Bei einem automatischen FirstSpirit-Update bleiben die in der Properties-Datei hinterlegten Einstellungen unverändert und werden nicht überschrieben bzw. zurückgesetzt.

4) Deployen
Die wie oben beschrieben konfigurierte Web-Applikation für den FragmentCreator muss anschließend per Schaltfläche „Aktualisieren“ auf dem gewählten Webserver ausgerollt werden.
(Siehe dazu auch https://docs.e-spirit.com/odfs/edocs/admi/firstspirit-ser/server-eigensch/web-applikation/index.html.)

Anpassung von API-URLs

Wird das Fragment DAP im ContentCreator verwendet, wird dieser zu einem MicroApp-Client, d.h. er bindet die CXT-MicroApp-API api.js ein.
(Siehe dazu auch https://docs.e-spirit.com/odfs/edocs/cxt/installation-mo/module-installi/fragment-dap/index.html#fragment_dap_for_contentcreator)

Die „CxtMicroApp API URL“ muss angepasst werden auf:

https://external/cxt-platform/microapps/api.js

Auch für andere Clients, die die CXT-MicroApp-API api.js laden, muss der Pfad entsprechend angepasst werden.

Damit ist die Konfiguration der Module abgeschlossen.

Weitere Hinweise

Cloud-Kunden müssen in diesem Kontext keine Maßnahmen ergreifen: e-Spirit übernimmt alle erforderlichen Konfigurationsänderungen.

Alternativ kann für eine Übergangszeit das „FragmentCreator“-Modul weiterhin in einer Version < 3.x verwendet werden.

Folgende Module und Erweiterungen sind kompatibel mit FirstSpirit 2021-06:

Mit dem aktuellen FirstSpirit-Release wurde folgende intern verwendete Software aktualisiert:

• Java Service Wrapper (Konfiguration und Überwachung der FirstSpirit Java VM)
  Aktualisierung von Version 3.5.44 auf Version 3.5.45.
  Hinweis: Bei einer Aktualisierung des FirstSpirit-Servers (Auto-Update, Inplace-Upgrade) werden die Dateien des Java Service Wrappers nicht automatisch aktualisiert. Der Java Service Wrapper kann gemäß FirstSpirit Installationsanleitung über das Tar-Gzip-Aktualisierungsarchiv (Datei fs-update-[version].tar.gz) aktualisiert werden.
  Weiterführende Dokumentation:
  • zum Java Service Wrapper (Handbuch für Administratoren)
  • zur Aktualisierung des Java Service Wrappers (Installationsanleitung)

Mit der aktuellen FirstSpirit-Version wurde die Ausgabe von Referenzen aus Remote-Projekten verbessert. Zusätzlich zum Remote-Objekt selbst sind nun auch Informationen zum Remote-Projekt in der JSON-Ausgabe enthalten. Für alle Remote-Referenzen (vom Typ IDProvider, z. B. Medien und Seitenreferenzen) wird jetzt zusätzlich der FirstSpirit-eigene, eindeutige Bezeichner (UUID) des Remote-Projektes über das neue Attribut remoteProject ausgegeben.

Die Ausgabe eines Remote-Mediums über:

$CMS_VALUE(json(ref(media:"st_reference_MEDIA",remote:"remote-project").node))$

zeigt jetzt in der JSON-Ausgabe das neue Attribut remoteProject an:

    "fsType":"Media",
      "name":"UPS",
      "displayName":"UPS",
      "identifier":"68baba6f-2d9c-422c-abe7-b339a3844d48",
     "remoteProject":"eef72dea-d4fc-49b8-af51-80d3940713b7",
      "uid":"UPS",
      "uidType":"MEDIASTORE_LEAF",
      (....)