AWS Services URL Redirect, 1.5.1

Dokumentation

AWS Services URL Redirect

Systemvoraussetzungen

Das Modul kann nur in Kombination mit dem "aws-services-base"-Modul verwendet werden.

Überblick

Dieses Dokument beschreibt die Installation und Konfiguration des Moduls "aws-services-urlredirect" für die Realisierung von URL-Weiterleitungen in AWS CloudFront. Das Modul befüllt eine vordefinierte AWS DynamoDB, aus der sich eine AWS Lambda-Funktion bedient, um die eigentliche Weiterleitung durchzuführen. Die Spezifikation der Lambda-Funktion ist nicht Teil dieser Dokumentation.

Modul-Konfigurationsmöglichkeiten

Zentrale Konfiguration über die Projekt-Komponente

Screenshot: Hinzufügen der Projekt-Komponente

In den Projekt-Eigenschaften muss zuerst die Projekt-Komponente AWS-Services-Configuration-ProjectApp hinzugefügt werden.

Klicken Sie auf Konfigurieren, um die zentrale Konfiguration für installierte FirstSpirit AWS-Module anzulegen.
Klicken Sie auf +, um eine Konfiguration für das "aws-services-urlredirect"-Modul zu hinterlegen.
Erstellen Sie die IAM Credentials über die AWS-Konsole und hinterlegen Sie sie:

Screenshot: Konfiguration der Projekt-Komponente

Access-Key und Secret-Key werden automatisch ermittelt und eingetragen.

Feldname	Beschreibung	Beispiel-Wert
Access-Key	Anmeldename für die AWS-API	xxxxxxx
Secret-Key	Passwort für die AWS-API	xxxxxxx
AWS Region	Region der DynamoDB	Frankfurt (eu-central-1)
Table Name*	Name der zu benutzenden DynamoDB	E19S1P1IRITS3
DynamoDB MappingHandler	Handler für das Implementieren des Mappings von FirstSpirit nach DynamoDB	Dataset Mapping (Im Modul enthalten)
* Die ID der "DynamoDB Table" ist identisch zur ID der ausliefernden AWS-CloudFront ihres Projekts. Diese ID wird z. B. auch über das "aws-services-s3"-Modul verwendet.

Auftragskonfiguration

Für die Nutzung innerhalb eines Veröffentlichungs-Auftrags öffnen Sie das Projekt, das konfiguriert werden soll, mit dem FirstSpirit ServerManager und erstellen Sie einen neuen Auftrag oder bearbeiten Sie einen bestehenden Auftrag in der Auftragsverwaltung. Wenn im Mapping FirstSpirit-Objekte referenziert werden, deren Pfad über einen URL Creator erstellt wird, muss der Auftrag eine Generierungs-Aktion enthalten.

Nach der Generierungs-Aktion kann der Task "AWS Urlredirect (DynamoDB)" hinzugefügt werden. Die Konfiguration entspricht der Konfiguration der Projekt-Komponente.

Screenshot: Auswahl der

Anpassungen im SiteArchitect

Die notwendigen Anpassungen im FirstSpirit-Projekt hängen von der genutzten MappingHandler-Implementierung ab. Hier werden nur Änderungen am DefaultMappingHandler erläutert. Für die Konfiguration werden FirstSpirit-Kenntnisse vorausgesetzt.

Anlegen einer Datenbank-Tabelle

Für das Mapping innerhalb einer Datenquelle muss zuerst eine passende Datenbank-Tabelle angelegt werden.

Erstellen Sie dafür im Vorlagenbereich zunächst ein neues Datenbank-Schema, in dem die Mapping-Tabelle erstellt wird.

Die Tabelle muss folgende Spalten enthalten:

Spalten-Name	Datentyp	Länge
languageSpecific	Boolean
responseCode	String	3
targetDataset	FIRSTspirit-Editor
targetObject	FIRSTspirit-Editor
targetType	FIRSTspirit-Editor
targetUrl	String	1024
url_all	String	1024
url (Für alle Sprachen erzeugen)	String	1024

Anlegen einer Tabellen-Vorlage

Screenshot: Beispiel einer Tabellendefinition in der Vorlage

Daten für den DefaultMappingHandler haben das Format JSON. Definieren Sie deshalb vor dem Anlegen einer Tabellen-Vorlage im ServerManager einen Ausgabekanal für die JSON-Ausgabe.

Nachdem die Tabelle erzeugt wurde, können Sie im Schema eine Tabellen-Vorlage erstellen. Sie können für die Formulardefinition folgende Eingabekomponenten verwenden:

<CMS_MODULE>

  <CMS_GROUP>
    <LANGINFOS>
      <LANGINFO lang="*" label="source"/>
      <LANGINFO lang="DE" label="Quelle"/>
    </LANGINFOS>

    <CMS_INPUT_TOGGLE name="tt_languageSpecific" type="radio" useLanguages="no">
      <LANGINFOS>
        <LANGINFO lang="DE" label="URL sprachabhängig?"/>
        <LANGINFO lang="*" label="Language specific URL?"/>
      </LANGINFOS>
      <OFF>
        <LANGINFO lang="*" label="no"/>
        <LANGINFO lang="DE" label="nein"/>
      </OFF>
      <ON>
        <LANGINFO lang="*" label="yes"/>
        <LANGINFO lang="DE" label="ja"/>
      </ON>
    </CMS_INPUT_TOGGLE>

    <CMS_INPUT_TEXT name="tt_urlAll" hFill="yes" singleLine="no" useLanguages="no">
      <LANGINFOS>
        <LANGINFO lang="*" label="url (not language specific)"/>
        <LANGINFO lang="DE" label="URL (nicht sprachabhängig)"/>
      </LANGINFOS>
    </CMS_INPUT_TEXT>

    <CMS_INPUT_TEXT name="tt_url" hFill="yes" singleLine="no" useLanguages="yes">
      <LANGINFOS>
        <LANGINFO lang="*" label="url (language specific)"/>
        <LANGINFO lang="DE" label="URL (sprachabhängig)"/>
      </LANGINFOS>
    </CMS_INPUT_TEXT>

  </CMS_GROUP>

  <CMS_GROUP>
    <LANGINFOS>
      <LANGINFO lang="*" label="target"/>
      <LANGINFO lang="DE" label="Ziel"/>
    </LANGINFOS>

    <CMS_INPUT_RADIOBUTTON name="tt_targetType" allowEmpty="no" gridWidth="3" hFill="yes" useLanguages="no">
      <ENTRIES>
        <ENTRY value="object">
          <LANGINFOS>
            <LANGINFO lang="*" label="FirstSpirit object"/>
            <LANGINFO lang="DE" label="FirstSpirit Objekt"/>
          </LANGINFOS>
        </ENTRY>
        <ENTRY value="dataset">
          <LANGINFOS>
            <LANGINFO lang="*" label="FirstSpirit dataset"/>
            <LANGINFO lang="DE" label="FirstSpirit Datensatz"/>
          </LANGINFOS>
        </ENTRY>
        <ENTRY value="url">
          <LANGINFOS>
            <LANGINFO lang="*" label="url"/>
            <LANGINFO lang="DE" label="URL"/>
          </LANGINFOS>
        </ENTRY>
      </ENTRIES>
      <LANGINFOS>
        <LANGINFO lang="*" label="target type"/>
        <LANGINFO lang="DE" label="Zieltyp"/>
      </LANGINFOS>
    </CMS_INPUT_RADIOBUTTON>

    <FS_DATASET name="tt_targetDataset" hFill="yes" useLanguages="no">
      <LANGINFOS>
        <LANGINFO lang="*" label="target dataset"/>
        <LANGINFO lang="DE" label="Ziel-Datensatz"/>
      </LANGINFOS>
    </FS_DATASET>

    <FS_REFERENCE name="tt_targetObject" hFill="yes" sections="no" useLanguages="no">
      <FILTER>
        <ALLOW type="pagereffolder"/>
        <ALLOW type="pageref"/>
        <ALLOW type="mediafolder"/>
        <ALLOW type="media"/>
      </FILTER>
      <LANGINFOS>
        <LANGINFO lang="*" label="target object"/>
        <LANGINFO lang="DE" label="Ziel-Objekt"/>
      </LANGINFOS>
      <PROJECTS>
        <LOCAL name=".">
          <SOURCES>
            <FOLDER name="root" store="sitestore"/>
            <FOLDER name="root" store="mediastore"/>
          </SOURCES>
        </LOCAL>
      </PROJECTS>
    </FS_REFERENCE>

    <CMS_INPUT_TEXT name="tt_targetUrl" hFill="yes" singleLine="no" useLanguages="no">
      <LANGINFOS>
        <LANGINFO lang="*" label="target url"/>
        <LANGINFO lang="DE" label="Ziel-URL"/>
      </LANGINFOS>
    </CMS_INPUT_TEXT>

    <CMS_INPUT_TEXT name="tt_responseCode" allowEmpty="no" hFill="yes" singleLine="no" useLanguages="no">
      <LANGINFOS>
        <LANGINFO lang="*" label="response code"/>
        <LANGINFO lang="DE" label="Response Code"/>
      </LANGINFOS>
    </CMS_INPUT_TEXT>

  </CMS_GROUP>

</CMS_MODULE>

Hinterlegen Sie folgende Regeln, damit sich das Beispielformular mit der Eingabe verändert:

<RULES>
 <RULE>
  <IF>
   <NULL>
    <PROPERTY name="VALUE" source="tt_languageSpecific"/>
   </NULL>
  </IF>
  <WITH>
   <TRUE/>
  </WITH>
  <DO>
   <PROPERTY name="VALUE" source="tt_languageSpecific"/>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <NOT>
    <PROPERTY name="VALUE" source="tt_languageSpecific"/>
   </NOT>
  </WITH>
  <DO>
   <PROPERTY name="VISIBLE" source="tt_urlAll"/>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <PROPERTY name="VALUE" source="tt_languageSpecific"/>
  </WITH>
  <DO>
   <PROPERTY name="VISIBLE" source="tt_url"/>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <NOT>
    <MATCHES regex="^http(s)?:\/\/$">
     <PROPERTY name="VALUE" source="tt_url"/>
    </MATCHES>
   </NOT>
  </WITH>
  <DO>
   <VALIDATION scope="SAVE">
    <PROPERTY name="VALID" source="tt_url"/>
    <MESSAGE lang="*" text="Specification without 'http(s)://'"/>
    <MESSAGE lang="DE" text="Angabe ohne 'http(s)://'"/>
   </VALIDATION>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <NOT>
    <MATCHES regex="^http(s)?:\/\/$">
     <PROPERTY name="VALUE" source="tt_urlAll"/>
    </MATCHES>
   </NOT>
  </WITH>
  <DO>
   <VALIDATION scope="SAVE">
    <PROPERTY name="VALID" source="tt_urlAll"/>
    <MESSAGE lang="*" text="Specification without 'http(s)://'"/>
    <MESSAGE lang="DE" text="Angabe ohne 'http(s)://'"/>
   </VALIDATION>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <OR>
    <EQUAL>
     <PROPERTY name="ENTRY" source="tt_targetType"/>
     <TEXT>object</TEXT>
    </EQUAL>
    <EQUAL>
     <PROPERTY name="ENTRY" source="tt_targetType"/>
     <TEXT>dataset</TEXT>
    </EQUAL>
   </OR>
  </WITH>
  <DO>
   <PROPERTY name="VISIBLE" source="tt_targetObject"/>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <EQUAL>
    <PROPERTY name="ENTRY" source="tt_targetType"/>
    <TEXT>dataset</TEXT>
   </EQUAL>
  </WITH>
  <DO>
   <PROPERTY name="VISIBLE" source="tt_targetDataset"/>
  </DO>
 </RULE>
 <RULE>
  <WITH>
   <EQUAL>
    <PROPERTY name="ENTRY" source="tt_targetType"/>
    <TEXT>url</TEXT>
   </EQUAL>
  </WITH>
  <DO>
   <PROPERTY name="VISIBLE" source="tt_targetUrl"/>
  </DO>
 </RULE>
</RULES>

Die Tabelle ist nun erfolgreich erstellt und gespeichert worden.

Kontrollieren Sie im Tab Mapping im Fenster Zuordnung und Darstellung die korrekte Zuordnung zwischen Eingabekomponenten und Tabellenspalten.

Befüllen Sie einen passenden Ausgabekanal, z. B. einen JSON-Ausgabekanal:

<CMS_HEADER>
</CMS_HEADER>
$CMS_TRIM(level:4)$
$CMS_IF(#cs.isFirstContentRow)$
	$CMS_SET(set_jsonArray,[])$	
$CMS_END_IF$
$CMS_SET(set_jsonObject, {:})$
 
$-- Check if the url is language specific --$
$CMS_IF(tt_languageSpecific)$
	$CMS_SET(void, set_jsonObject.put("source", tt_url))$
$CMS_ELSE$
	$CMS_SET(void, set_jsonObject.put("source", tt_urlAll))$
$CMS_END_IF$
 
$-- check the type of the target --$
$CMS_IF(tt_targetType.value.equals("object"))$
	$CMS_SET(void, set_jsonObject.put("target", ref(tt_targetObject,templateSet:"html",abs:2).url))$
$CMS_ELSIF(tt_targetType.value.equals("dataset"))$
$CMS_IF(tt_targetDataset.dataset.isEmpty())$
		$CMS_SET(set_warningText,"The URL redirect entry with ID " + #cs.dataset.entity.get("fs_id") + " references a dataset that has been deleted. This URL redirect entry should be corrected or deleted. ")$
$CMS_VALUE(#global.logWarning(set_warningText))$
$CMS_SET(void, set_jsonObject.put("target",""))$
$CMS_ELSE$
$CMS_SET(void, set_jsonObject.put("target", ref(tt_targetObject,contentId:tt_targetDataset.getEntity().get("fs_id"),templateSet:"html",abs:2).url))$
$CMS_END_IF$
$CMS_ELSE$
	$CMS_SET(void, set_jsonObject.put("target", tt_targetUrl))$
$CMS_END_IF$

$CMS_SET(void, set_jsonObject.put("response_code", tt_responseCode))$

$CMS_SET(void, set_jsonArray.add(set_jsonObject))$
 
$CMS_IF(#cs.isLastContentRow)$
	$CMS_VALUE(set_jsonArray.toJSON())$
$CMS_END_IF$
$CMS_END_TRIM$

Beim Verwenden von Referenzen muss das templateSet, z. B. HTML, mitgeliefert werden: So kann die URL aus dem richtigen Ausgabekanal genommen werden.

Für die Verwendung des DefaultMappingHandler müssen im Ausgabekanal JSON-Daten im folgenden Format erstellt werden:

[
  {
    "source":"sourceURL",
    "target":"targetURL",
    "response_code":"302"
  },
  { //… }
]

Dabei kann der äußere Array beliebig viele Einträge enthalten.

Die Felder source und target sind Pflichtfelder. Das Feld response_code ist optional.

Im Modul wird für die Weiterleitung der Wert 302 als Standard festgelegt. Hier sind alle Werte erlaubt, die einem HTTP-Statuscode für Weiterleitungen entsprechen. In der FirstSpirit Cloud sind nur die Werte 301 und 302 relevant.

Bei einer falschen Strukturierung der Daten wird im Zuge der Generierung eine Fehlermeldung angezeigt, in der der Syntaxfehler benannt wird.

Anlegen einer Datenquelle

Nach der Erstellung einer Tabellenvorlage kann auf ihrer Basis im Datenquellenbereich eine neue Datenquelle angelegt werden. Diese Datenquelle wird für die Pflege der Weiterleitungen verwendet.

Anlegen einer Seite mit Seitenreferenz

Für das Generieren wird eine Seitenreferenz benötigt, auf welcher später die URL-Weiterleitungen im JSON-Format zu finden sind.

Legen Sie im Inhaltsbereich eine neue Seite an. Sie können eine neue oder existierende Seitenvorlage verwenden, welche die zuvor erzeugte Datenquelle in einem Inhaltsbereich einbindet (Content-Projektion). Wenn ein JSON-Ausgabekanal ausgewählt wurde, prüfen Sie dessen korrekte Darstellung.

Erstellen Sie nun eine neue Seitenreferenz im Strukturbereich. Diese Seitenreferenz können Sie nun auch in anderen angelegten Objekten für die Vorschau verwenden.

Anlegen der Projekteigenschaften

Für die Generierung werden vor einer Bearbeitung der Datenquelle weitere Informationen benötigt:

Vorlagensatz-Name des Ausgabekanals (z. B. JSON)
Name der verwendeten UrlFactory bei der Generierung (z. B. “Defaults URLs”)
Erstellte Seitenreferenz der Content-Projektion

Erweitern Sie dafür im Vorlagenbereich die technische Seite für die Pflege von Projekteinstellungen.

Folgende Eingabekomponenten müssen verwendet werden:

<CMS_GROUP>
 <LANGINFOS>
  <LANGINFO lang="*" label="Mapping Handler"/>
 </LANGINFOS>
 <CMS_INPUT_TEXT name="ps_mappingOutputChannel" hFill="yes" singleLine="no" useLanguages="no">
  <LANGINFOS>
   <LANGINFO lang="*" label="Output Channel which contains the Mapping Overviewpage"/>
  </LANGINFOS>
 </CMS_INPUT_TEXT>
 <CMS_INPUT_COMBOBOX name="ps_mappingUrlFactoryPublicName" hFill="yes" singleLine="no" useLanguages="no">
  <ENTRIES>
   <ENTRY value="Default URLs"/>
   <ENTRY value="Advanced URLs"/>
  </ENTRIES>
  <LANGINFOS>
   <LANGINFO lang="*" label="UrlFactory"/>
  </LANGINFOS>
 </CMS_INPUT_COMBOBOX>
 <FS_REFERENCE name="ps_mappingOverviewPage" hFill="yes" useLanguages="no">
  <FILTER>
   <ALLOW type="pageref"/>
  </FILTER>
  <LANGINFOS>
   <LANGINFO lang="*" label="Mapping Overview Page"/>
  </LANGINFOS>
  <PROJECTS>
   <LOCAL name=".">
    <SOURCES>
     <FOLDER name="root" store="sitestore"/>
    </SOURCES>
   </LOCAL>
  </PROJECTS>
 </FS_REFERENCE>
</CMS_GROUP>

Nun können Sie im Bereich Globale Einstellungen die für das Modul benötigten Einstellungen vornehmen. Stellen Sie vor Generierung sicher, dass für alle Sprachen korrekte Werte hinterlegt sind.

URL-Weiterleitungen

Ein Redakteur kann nun mithilfe der im Beispiel erstellten Datenquelle Weiterleitungen einpflegen.

Prüfen Sie die Rechte von Redakteuren. Diese müssen die Anforderung oder Erteilung von Freigaben für die angelegten Objekte beinhalten.


	Datenquelle
	Tabellentemplate

Nach dem Eingeben von Daten können diese in der Content-Projektion bzw. in der Vorschau eingesehen werden.

Beispiel JSON-Ausgabe:

[
    {"source":"/homepage","target":"/fs5preview/preview/28/site/DE/current/2787/430"},
    {"source":"/test-in/","target":"/test-out/", “response_code”: “302”}
]

Datenpflege

Im Beispiel wird in den Eingabekomponenten der Tabellenvorlage keine komplexe Datenprüfung vorgenommen. Das Anlegen von Duplikaten von URL-Weiterleitungen durch das "aws-services-urlredirect"-Modul ist in der DynamoDB nicht möglich. Einträge in der Datenquelle werden als Duplikate identifiziert, wenn ihre Quell-URLs identisch sind. Dabei wird die Sprach-Einstellung der Quell-URL nicht berücksichtigt.

Beispiel für ein Duplikat:

Quell-URL (source)	Ziel-URL (target)	HTTP-Status (response_code)
/my/homepage	/your/homepage	302
/my/homepage	/nowhere	301
/konflikt-frei	/weiterleitung	302

Beim Anlegen eines Duplikats wird im Zuge einer Generierung eine Warnung angezeigt und eine Liste erzeugt, die alle angelegten, gelöschten und übersprungenen Daten beinhaltet.