Externe Datenquellen für Listen

Mit dem Add-On "Externe Datenquellen für Listen" ("ExternalListData") können Listen innerhalb der Personalisierung mit Inhalten von einer externen Schnittstelle gefüllt werden.

So ist es möglich, eine externe Datenquelle für diesen Bereich der Personalisierung zu nutzen.

Bei der Nutzung externer Datenquellen für Listen sollte die automatische Vorschauerzeugung bei der Auswahl einer Option (unter "Verwaltung » Shops » Softproof") deaktiviert werden.

Konfiguration einer externen Datenquelle

Um eine externe Datenquelle (bspw. eine REST-API) nutzen zu können, muss diese zunächst in den Einstellungen des Add-Ons konfiguriert werden.

Hierzu kann unter "Add-Ons » Externe Datenquellen für Listen" eine neue Datenquelle angelegt werden. Zu dieser Konfiguration gehören folgende Parameter:

Einstellung	Beschreibung
Bezeichnung	Interne Bezeichnung der Datenquelle
Basis-Endpunkt	Grundlegender Endpunkt der Schnittstelle (bspw. https://api.dev.local/)
Authorisierungs-Parameter	Name des Parameters für die Autorisierung
Authorisierungs-Key	Autorisierungsschlüssel / Passwort
Caching-Dauer	Angabe in Sekunden, wie lange die Antwort in einem temporären Cache vorgehalten werden soll, um Anfragen zu reduzieren (die Angabe "0" deaktiviert diesen Cache und erzwingt Anfragen in Echtzeit)

Nachdem eine externe Datenquelle angelegt wurde, kann diese jederzeit nachträglich bearbeitet oder gelöscht werden. Sie wird sofort in der tabellarischen Übersicht auf der Konfigurationsseite dargestellt.

Externe Datenquellen werde aktuell automatisch auf ein festes Schema geschlüsselt und die dazugehörigen Endpunkte automatisch angelegt. Um eine beliebige Anbindung mit weiteren Endpunkten nutzen zu können, muss der Support kontaktiert werden.

Verwendung einer Datenquelle innerhalb der Personalisierung

Um die einzelnen Endpunkte einer externen Datenquelle nutzen zu können, kann diese in den Feldspezialoptionen einer Druckvorlage ausgewählt werden.

Hierzu ist zum einen die Angabe der Datenquelle und auch der Name des gewünschten Endpunktes erforderlich.

Grundsätzlich werden alle Informationen der Schnittstelle in der Personalisierung als Variable bereitgestellt, so dass diese durch Auswahl der entsprechenden Option genutzt werden können.

Beispiel

Das Beispiel nutzt das Standardschema zur Erklärung der Funktionsweise. In diesem Standardschema sind die Endpunkte, die Rückgabewerte und Abhängigkeiten fest vorkonfiguriert.

Rückgabewert der Schnittstelle für den Endpunkt "brand"

{
  "_embedded": {
    "brand": [
      {
        "id": 123,
        "name": "Lead Print",
        "nameShort": "lp",
        "matchCode": "LP",
        "designVariant": "lp"
      },
      {
        "id": 142,
        "name": "Be.Beyond GmbH & Co KG",
        "nameShort": "bb",
        "matchCode": "BB",
        "designVariant": "bb"
      } 
     ]
   }
}

Rückgabewert der Schnittstelle für den Endpunkt "companyCode"

{
  "_embedded": {
    "companyCode": [
      {         
        "companyCode": "0100",
        "clientCodeHr": "100",
        "debitorNumber": "123456",
        "name1": "Mustermann KG",
        "name2": "",
        "name3": "",
        "name4": "",
        "countryIso3166Alpha3": "DEU",
        "city": "Willich"
      }
     ]
   }
}

Rückgabewert der Schnittstelle für den Endpunkt "person"

{
  "_embedded": {
    "person": [
      {                  
        "clientCodeHr": "100",
        "personalNumber": "12345",
        "sapCompanyCode": "0100",
        "sapLocationCode": "0100",
        "sdf": null,
        "name": "Mustermann",
        "firstname": "Max",
        "salutation": "Herr",
        "title": ""
      }
     ]
   }
}

Für die Optionen der Listenauswahl werden ausgewählte Parameter der jeweiligen Endpunkte genutzt, während für die Personalisierung alle verfügbaren Parameter (also bspw. "nameShort") bereitgestellt werden.

Auf diesen Parameter kann in der Druckvorlage dann wie auf eine normale Personalisierungsvariable zugegriffen werden (also bspw. "{$nameShort}").

Verfügbare Endpunkte des Standardschemas

In der Standardkonfiguration wird davon ausgegangen, dass die externe Schnittstelle die folgenden Endpunkte bereitstellt:

Endpunkt	Beschreibung
brands
companyCode	abhängig von brands
person	abhängig von companyCode