Introducing CXT
Introducing CXT

Introducing CXT / Installation / Module / Module installieren / FragmentCreator

FragmentCreator

Inhaltsverzeichnis

FragmentCreator ist ein CXT-Client, der auf das Anlegen und Bearbeiten von format-neutralen Fragmenten abgestimmt ist (siehe Introducing FragmentCreator).

Der FragmentCreator wird als Modul auf dem FirstSpirit-Server installiert. Anschließend muss der FragmentCreator explizit einem Projekt zugeordnet werden. Dazu muss für jedes Projekt im Bereich „Webapplikationen“ eine eigene Webanwendung definiert werden (s.u.).

Wichtig Herkömmliche FirstSpirit-Projekte können nicht nachträglich als Fragment-Projekte konfiguriert werden.

Download der Modul-Datei (.fsm)

Die Modul-Datei (Dateinamenerweiterung: .fsm) kann über den Technical Support angefordert werden:

fragment-creator-[version].fsm

Installieren des Moduls

Das Modul wird über den FirstSpirit ServerManager installiert, und zwar im Dialog „Servereigenschaften / Module“ über die Schaltfläche „Installieren“:

(Zu weiteren Informationen zur Installation von Modulen siehe auch Module (→Dokumentation für Administratoren).)

Globale Webanwendung erstellen

Die Webanwendung muss anschließend über den FirstSpirit ServerManager im Bereich „Web-Applikationen“ als eigene, globale Webanwendung definiert und konfiguriert werden (Schaltfläche „Hinzufügen“ bei „Globale Web-Apps konfigurieren“, siehe dazu auch Web-Applikationen (→Dokumentation für Administratoren), Abschnitt „Installieren von globalen Web-Applikationen“).

Web-Komponente hinzufügen

Für diese globale Web-Applikation muss ein geeigneter Webserver ausgewählt sein, dann die Web-Komponente „FragmentCreator“ hinzugefügt und deployed (Schaltfläche „Installieren“ / „Aktualisieren“) werden:

Wird der Dialog mit „OK“ geschlossen, wird das zur Web-Komponente „FragmentCreator“ gehörige „ApplicationPlugin: FragmentCreator (WebApp)“ automatisch der Web-Applikation „Startseite“ hinzugefügt (siehe Seite „Zugang über die FirstSpirit-Startseite“, Absatz Bereich "Web-Applikationen" / "Startseite"). Dies ist erforderlich, damit das Icon, mit dem der FragmentCreator über die FirstSpirit Startseite gestartet werden kann, erscheint.
Dort muss die Web-Komponente auch deployed werden (Schaltfläche „Installieren“ / „Aktualisieren“).

Schließlich muss das „ApplicationPlugin: FragmentCreator“ im Bereich „Startseite“ hinzugefügt werden. Siehe dazu Seite „Zugang über die FirstSpirit-Startseite“, Absatz Bereich "Startseite".

web.xml

Die web.xml wird im Regelfall durch eine automatische Ersetzung der Parameter auf die spezifischen Werte z. B. für Host und Port angepasst. Eine manuelle Anpassung ist nur bei Abweichungen von der Standard-Konfiguration notwendig, z. B. um ein erweitertes Logging zu konfigurieren (siehe Optionale Parameter).

Kommentare werden mit <!-- eingeleitet.

Parameter

firstSpiritHost: Hostname oder IP-Adresse des FirstSpirit-Servers.

firstSpiritPort: Port des FirstSpirit-Servers.

firstSpiritConnectionMode: Verbindungsmodus für die Kommunikation zwischen FragmentCreator und FirstSpirit-Server.

  • HTTP: normale Internetverbindung
  • SOCKET: direkter Verbindungsmodus (Standardeinstellung; Single-Sign-On nur im SOCKET-Modus)

firstSpiritDataServiceBaseUrl: Angabe der Adresse, unter der die DAP Bridge erreichbar ist.

externalBaseUrl: URL, über die der FragmentCreator erreichbar ist; im Produktivbetrieb ist dieser Parameter zwingend erforderlich.

Parameter für die Kommunikation der internen REST-Services

webServiceBaseUrl: Das ist der interne Basis-URL des FragmentCreator. Der Standardwert WEB_SERVICE_BASE_URL wird automatisch aus der FirstSpirit WebApp-Konfiguration ermittelt und funktioniert in den meisten Fällen. Sind jedoch vorgeschaltete Proxy-WebServer aktiv, kann es nötig sein, auf eine interne URL (z. B. „http://localhost:8080/fragmentcreator“) umzustellen. 

oAuthClientSecret und jwtSigningKey: Diese Parameter enthalten Keys zur internen Verschlüsselung und sind ausschließlich zu Zwecken der Fehlerverfolgung konfigurierbar. Der Standardwert RANDOM_VALUE sorgt für eine sichere Zeichenfolge, die sich mit jedem Start ändert.

Optionale Parameter

Optional können weitere Parameter konfiguriert werden. Diese optionalen Parameter sind in der web.xml, die mit dem Modul ausgeliefert wird, standardmäßig auskommentiert. Damit sie berücksichtigt werden, müssen die Zeichen

!--

und

--

um die betroffenen Parameter entfernt werden und es muss der gewünschte Wert eingetragen werden.

Authentifizierung (OAuth)

FirstSpirit CXT verwendet das offene Sicherheitsprotokoll OAuth für die Autorisierung und Authentifizierung.
Es basiert auf dem Austausch von Tokens: Das so genannte Access-Token, welches nach erfolgreicher Authentifizierung vom OAuth-Server ausgegeben wird, ermöglicht Zugriffe auf Inhalte in CXT. Das so genannte Refresh-Token kann nach Ablauf eines Access-Tokens ein neues vom OAuth-Server anfordern, ohne dass eine erneute Authentifizierung notwendig ist. Das Refresh-Token kann nicht verlängert werden und ist nach dem Ablauf der Session nicht mehr nutzbar.
Die Tokens haben eine zeitlich begrenzte Gültigkeit, die standardmäßig von FirstSpirit vorgegeben wird. Mit den folgenden Parametern kann die Gültigkeit der Tokens bei Bedarf an die speziellen Anforderungen des jeweiligen Projekts angepasst werden.

accessTokenValiditySeconds: Legt den Gültigkeitszeitraum des OAuth-Access-Tokens fest (in Sekunden).
Standardwert: 3600 (1 Stunde)

refreshTokenValiditySeconds: Legt den Gültigkeitszeitraum des OAuth-Refresh-Tokens fest (in Sekunden). Der Wert sollte höher gewählt werden, als der des Parameters accessTokenValiditySeconds.
Standardwert: 43200 (12 Stunden).

Logausgaben

Optional können Parameter für erweiterte Logausgaben konfiguriert werden.
Siehe dazu Spring Boot Documentation (HowTo Logging).

logging.level: Spring Boot protokolliert Meldungen basierend auf dem Inhalt des Klassenpfades. Standardmäßig werden Meldungen mit dem Level WARN und höher geloggt. Zu Debug-Zwecken kann das Level über das Präfix logging.level in der web.xml aber temporär auch auf ein niedrigeres Level eingestellt werden. So können z. B. Logausgaben für CXT-Klassen über die Angabe des Packages de.espirit.cxt auf das Loglevel DEBUG eingestellt werden (siehe Beispiel web.xml „Increased logging level“).

logging.file: Über diesen Parameter können Logausgaben zusätzlich (zur Ausgabe in der Konsole) in eine Datei geschrieben werden (siehe Beispiel web.xml „Additional logging into file“).

Cross-Origin Resource Sharing (CORS)

Die Integrationsschnittstelle der CXT-Plattform stellt einzelne Funktionen aus der CXT-Welt in Form von MicroApps und über CXT-REST-Calls bereit, die dann in anderen Umgebungen verwendet werden können. Dazu gehören zum Beispiel klassische CRUD-Zugriffe auf Fragmente und Varianten, auch aus (Unternehmens-)WebApps, die nicht auf dem FirstSpirit Web-Server laufen („cross-origin resource sharing (CORS)“).

Liegen die aufrufende Stelle (z. B. Custom WebApp) und die CXT-Plattform nicht auf dem gleichen Web-Server („same-origin“), sondern auf unterschiedlichen Servern („cross-origin“), werden die Zugriffe vom Browser der externen WebApp normalerweise unterbunden (durch die Same-Origin-Policy (SOP)). Diese Einschränkung, kann für bestimmte URLs aufgehoben werden.

corsAllowedOrigins: Über den Parameter corsAllowedOrigins kann eine globale CORS-Konfiguration für CXT-MicroApps und für CXT-REST-Calls definiert werden. Mögliche Werte sind:

  • Leer (keine Zugriffe erlaubt)
  • * (alle Zugriffe erlaubt)
  • Kommaseparierte Liste von URLs (Zugriffe für einzelne Origins erlaubt)

Voreingestellter Standardwert ist die FIRST_SPIRIT_URL.

Content-Security-Policy Header (CSP)

cxt.platform.microapps.csp-origins: Über diesen Parameter kann das HTTP-Header-Feld Content-Security-Policy (CSP, siehe dazu auch https://content-security-policy.com/) angepasst werden. Dies ist z. B. dann erforderlich, wenn Zugriffe auf MicroApps von anderen Domains erlaubt werden sollen.
Bei inkorrekter bzw. fehlender Konfiguration des Parameters wird eine Fehlermeldung in der Browser-Konsole ausgegeben, z. B.

Refused to display 'http://myhost:8050/fragments/microapps/firstspirit-fragments-edit-by-reference' in a frame because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'".

und die entsprechende MicroApp wird nicht geöffnet.

Über den Parameter können die Origins angegeben werden, von denen ein Zugriff möglich sein soll. Dabei wird der vollqualifizierte Domänenname erwartet.
* kann als Wildcard verwendet werden, z. B. um alle URLs zuzulassen oder bestimmte Subdomains einer Domain.

Mehrere Einträge können per Leerzeichen getrennt voneinander angegeben werden.

Wird der Parameter nicht angegeben, wird der Standardwert 'self' verwendet. Damit werden ausschließlich Zugriffe vom selben Server erlaubt (derselbe Host und Port).

Beispiel:

cxt.platform.microapps.csp-origins='self' *.e-spirit.de:8050

erlaubt Zugriffe von der Domain, von der der Header gesendet wird, sowie von Subdomains von e-spirit.de:8050.

Markdown-Editor

Die Eingabe von formatierten Texten im FragmentCreator erfolgt über die Eingabekomponente FS_MARKDOWN (siehe dazu auch Seite FirstSpirit Markdown Editor).
Die Eingabekomponente basiert auf einem externen Markdown-Editor, je nach Konfiguration

markdownEditorType: Über diesen Parameter kann definiert werden, welcher Editor verwendet werden soll. „Quill“ bietet mehr WYSIWYG-Komfort und dadurch eine bessere User Experience für den Redakteur.
Standardmäßig wird aktuell „Quill“ verwendet. Soll „SimpleMDE“ verwendet werden, muss der Wert simplemde angegeben werden.

Konfiguration

Auswirkung

quill

Verwendung von „Quill“

leer / keine Angabe

Verwendung des Standard-Markdown-Editors
(aktuell „Quill“)

default

simplemde

Verwendung von „SimpleMDE“

  

Beispiel web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://java.sun.com/xml/ns/javaee"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">

<!-- This web.xml is only used when deployed as a FirstSpirit module -->

<display-name>FirstSpirit FragmentCreator</display-name>

<context-param>
<param-name>firstSpiritHost</param-name>
<param-value>${FIRST_SPIRIT_HOST}</param-value>
</context-param>

<context-param>
<param-name>firstSpiritPort</param-name>
<param-value>${FIRST_SPIRIT_SOCKET_PORT}</param-value>
</context-param>

<context-param>
<param-name>firstSpiritConnectionMode</param-name>
<param-value>SOCKET</param-value>
</context-param>

<!--
Please note that the default value of the variable FIRST_SPIRIT_HOST is localhost.
It should therefore be ensured that the variable allowedRedirectHosts in the
file fs-server.conf contains the value localhost.

This is already the case for the values ALLOW_ALL and FS_SERVER.
-->

<context-param>
<param-name>firstSpiritDataServiceBaseUrl</param-name>
<param-value>${FIRST_SPIRIT_URL}/cxt</param-value>
</context-param>

<context-param>
<param-name>webServiceBaseUrl</param-name>
<param-value>${WEB_SERVICE_BASE_URL}</param-value>
</context-param>

<context-param>
<param-name>oAuthClientSecret</param-name>
<param-value>${RANDOM_VALUE}</param-value>
</context-param>

<context-param>
<param-name>jwtSigningKey</param-name>
<param-value>${RANDOM_VALUE}</param-value>
</context-param>

<context-param>
<param-name>corsAllowedOrigins</param-name>
<param-value>${FIRST_SPIRIT_URL}</param-value>
</context-param>

<!--
A list of host names or (wildcard) domains used when setting the
Content-Security-Policy header for MicroApps. Entries are to be
separated by a whitespace character. Defaults to "'self'".
-->
<context-param>
<param-name>cxt.platform.microapps.csp-origins</param-name>
<param-value>'self'</param-value>
</context-param>

<!--
The markdown editor to be used in this FragmentCreator instance.
Set to "simplemde" or "quill" to use respective editor. Set to "default"
to use the default markdown editor.
-->
<context-param>
<param-name>markdownEditorType</param-name>
<param-value>default</param-value>
</context-param>

<!--
Optional - Increased logging level
-->

<context-param>
<param-name>logging.level.de.espirit.cxt</param-name>
<param-value>DEBUG</param-value>
</context-param>

<!--
Optional - Additional logging into file
-->

<context-param>
<param-name>logging.file</param-name>
<param-value>/var/log/tomcat/cxt.log</param-value>
</context-param>

</web-app>

Hinweis bei geändertem Parameter WEBAPP_ROOT_URL

Wichtig Wird die Konfiguration für den URL der Root-App geändert (über den Parameter WEBAPP_ROOT_URL), funktioniert die automatische Ersetzung für firstSpiritDataServiceBaseUrl nicht!
In diesem Fall muss der gewünschte Wert manuell angegeben werden.

Parameter WEBAPP_ROOT_URL (fs-server.conf):
URL zur Webanwendung Startseite (fs5root). Der hier hinterlegte Wert wird für das Mapping innerhalb der internen Servlet Engine benötigt. Der Wert muss immer mit einem / beginnen, dann folgt der symbolische Name der jeweiligen Webanwendung. Der URL wird für Verweise zu unterschiedlichen FirstSpirit-Anwendungen benötigt. Standard-Wert: WEBAPP_ROOT_URL=/

FirstSpirit-Server (web.xml ohne Ersetzung):

<context-param>
<param-name>firstSpiritDataServiceBaseUrl</param-name>
<param-value>${FIRST_SPIRIT_URL}/cxt</param-value> </context-param>

Ausgerolltes Modul auf dem Tomcat Webserver (automatische Ersetzung):

<context-param>
<param-name>firstSpiritDataServiceBaseUrl</param-name>
<param-value>http://example.com:2001/cxt</param-value>
</context-param>

Wird der Wert für WEBAPP_ROOT_URL geändert, z. B. auf WEBAPP_ROOT_URL=/fs5root, funktioniert die automatische Ersetzung nicht mehr. Dann ergibt sich:

<context-param>
<param-name>firstSpiritDataServiceBaseUrl</param-name>
<param-value>http://example.com:2001/fs5root/cxt</param-value>
</context-param>

Konfiguration per Properties-Datei

Alternativ kann zur Konfiguration des FragmentCreator-Moduls eine Properties-Datei verwendet werden (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.

Dazu muss im Classpath zunächst ein „config“-Verzeichnis erstellt und anschließend eine Datei

/config/cxt-fragment-creator.properties

angelegt werden. Bei Verwendung eines Tomcat z. B. im Verzeichnis

${TOMCAT_HOME}/lib

Innerhalb dieser Datei können die gewünschten Parameter konfiguriert werden, z. B.

markdownEditorType=simplemde

© 2005 - 2020 e-Spirit AG | Alle Rechte vorbehalten. | FirstSpirit 2020-07 | Datenschutz | Impressum | Kontakt