BTC Netzportal
Datenquellen
Allgemein
Datenquellen dienen dazu wiederverwendbare Listen im Netzportal aus Fremdschnittstellen zu erstellen. Dabei werden die Daten aus der Fremdschnittstelle im Netzportal gespeichert und können dort z.B. in generischen Feldern verwendet werden.
Verfügbar in KundenmarktplatzKonfiguration
Die Konfiguration von Datenquellen findet in der App "KundenmarktplatzKonfiguration" statt. Dort kann in der Seitenleiste der Menüpunkt "Datenquellen" ausgewählt werden.
Erstellen einer Datenquelle
Das Erstellen einer Datenquelle ist über den "Hinzufügen" Button rechts oben über der Tabelle möglich. Dieser öffnet den Dialog zum Erstellen einer Datenquelle. Eine Datenquelle kann erst angelegt werden, wenn alle Pflichtparameter gefüllt sind.
Erläuterung der Felder:
|
Feldname
|
Pflicht
|
Erläuterung
|
|---|---|---|
| Name | X | Der Name der Datenquelle. Dieser muss auf der Instanz einzigartig sein und kann im Nachhinein nicht verändert werden. |
| Typ | X | Zeigt den Typ der Datenquelle an. Aktuell wird nur "REST" unterstützt. |
| Schlüssel Property | X | Gibt an, welcher Wert aus den Fremddaten als Schlüsselwert der Liste importiert werden soll. |
| Anzeigewert Property | X | Gibt an, welcher Wert aus den Fremddaten als Anzeigewert der Liste importiert werden soll. |
| Filter Property | Dieser Wert aus den Fremddaten befüllt den Filterwert der Liste. | |
| Aktualisierung aktiv | Gibt an, ob die Daten der Datenquelle automatisch aktualisiert werden. Wenn nicht gesetzt, kann das Aktualisieren der Daten trotzdem manuell angestoßen werden. | |
| Aktualisierungsintervall (in Tagen) | Das Tagesintervall, in welchem die Daten automatisch aktualisiert werden. Ist kein Wert eingetragen, wird als Standardwert 1 verwendet. |
Rest spezifische Felder:
|
Feldname
|
Pflicht
|
Erläuterung
|
|---|---|---|
| Konnektor | X | Der Konnektor der für die Verbindung zum Drittsystem verwendet werden soll. Dieser muss im Simplifier konfiguriert werden. Als Vorschläge werden alle bereits existierenden REST Konnektoren angeboten. Es ist jedoch möglich einen Freitext einzutragen, um das Erstellen der Datenquelle nicht zu blockieren, sollte der Konnektor noch nicht angelegt sein. |
| Konnektor Call | X | Der Call innerhalb des Konnektors, welcher ausgeführt wird. Als Vorschläge werden alle existierenden Calls des angegebenen Konnektors angeboten. Es ist jedoch möglich einen Freitext einzutragen um das Erstellen der Datenquelle nicht zu blockieren, sollte der Call noch nicht angelegt sein. |
| Pfad Parameter | Spezifikation des Pfades. Dieser Wert wird an die URL des Rest Konnektors angehängt, um den Pfad zu erweitern. Es ist möglich mehrere Pfadbestandteile durch / getrennt anzugeben, z.B. "/netzportalData/devices/solarPanels". |
Allgemeine Funktionen an einer Datenquelle
Für jede Datenquelle stehen folgende Funktionen zur Verfügung:
- Ansehen
- Bearbeiten
- Kopieren
- Löschen
- Daten einsehen
- Aktualisieren der Daten
- Protokolle einsehen

Ansehen einer Datenquelle
Diese Funktion öffnet den Erstell- bzw. Bearbeitungsdialog in einem Read-Only Modus.

Bearbeiten einer Datenquelle
Diese Funktion öffnet den Bearbeitungsdialog. Hierbei können alle Werte, außer dem Namen, geändert werden.

Kopieren einer Datenquelle
Diese Funktion öffnet den Erstelldialog, welcher mit den Daten der ausgewählten Datenquelle vorbefüllt ist. Das Abspeichern der Daten erfolgt erst auf Drücken des Knopfes "Hinzufügen".
Löschen einer Datenquelle
Diese Funktion löscht die Datenquelle und alle dazu abgespeicherten Daten und Protokolle aus der Datenbank. Sie sind anschließend nicht wiederherstellbar.

Daten einsehen
Diese Funktion ermöglicht eine Read-Only Ansicht auf die im Netzportal gespeicherten Daten zu dieser Datenquelle. Von hier ist es möglich das Aktualisieren der Daten manuell anzustoßen.

Aktualisieren der Daten
Diese Funktion kann über den "Daten einsehen" Dialog ausgeführt werden. Sie löst aus, dass die konfigurierte Fremdschnittstelle angesprochen wird und ein Vollupdate der Daten durchgeführt wird. Tritt beim Aktualisieren der Daten ein Fehler auf, wird die Fehlermeldung angezeigt und automatisch zur Ansicht der Protokolle navigiert. In der Protokoll Ansicht steht das neue Protokoll zur Analyse zur Verfügung.
Protokolle einsehen
Diese Funktion zeigt alle zur Datenquelle gespeicherten Protokolle an. Dies ermöglicht dem Benutzer zu erkennen, ob die Aktualisierungen erfolgreich waren und Fehlermeldungen auszulesen.

Konfiguration eines REST Konnektors zur Verwendung für Datenquellen
Allgemeine Konfiguration
Folgen Sie der aktuellen Anleitung im Simplifier um einen REST Connector zu erstellen. Die offizielle Dokumentation finden Sie hier: REST Connector (simplifier.io).
Wichtig: Es kann sein, dass Sie für das Anlegen von Konnektoren zusätzliche Berechtigungen benötigen. Wenden Sie sich hierzu bitte an Ihren Administrator oder an BTC.
Aktuell unterstützen Datenquellen keine dynamische Konfiguration des Body Parameters. Sie können hier allerdings einen Festwert angeben.

Konfiguration der Pfad Parameter
Beim Bearbeiten des Konnektor Calls können Sie die URL des Konnektors um beliebige feste Pfade erweitern. In der Konfiguration der Datenquelle können Sie ebenfalls einen Pfad Parameter konfigurieren. Damit dieser korrekt im Konnektor Call verwendet wird, muss dieser in den Pfad Parametern wie folgt konfiguriert werden. Die Bezeichnung "pathParameter" ist hierbei verpflichtend. Die Stelle des Parameters ist hierbei frei konfigurierbar.
Wichtig: Der Parameter wird standardmäßig vom Simplifier als Pflichtparameter angelegt. Somit muss der Pfad Parameter auch verpflichtend in der Konfiguration der Datenquelle angegeben sein. Ansonsten wird das Laden der Daten auf einen Fehler laufen. Um den Parameter als optional zu konfigurieren, klicken Sie oben rechts auf den Switch "Erweitert". Anschließend können Sie den Parameter über die gekreuzten Pfeile in die untere Tabelle zu "Optional" ziehen.


Konfiguration der Query Parameter
Aktuell unterstützen Datenquellen keine dynamische Konfiguration von Query Parametern. Sie können diese allerdings in der Konfiguration des Konnektor Calls fest hinterlegen.

Konfiguration der Header Parameter
Aktuell unterstützen Datenquellen keine dynamische Konfiguration von Header Parametern. Sie können diese allerdings in der Konfiguration des Konnektor Calls fest hinterlegen.

Konfiguration der Ausgabe
Damit die Daten aus der Fremdschnittstelle korrekt verarbeitet werden können, wird die Rückgabe in einem bestimmten Format erwartet. Dabei werden die Daten unter der Property "result" erwartet. Um dies festzulegen, geben Sie als Alias des Ausgabeparameters "result" an. Sollte Ihre Schnittstelle die Daten in einer Objektstruktur zurückgeben, können Sie unter dem Punkt "Parametername" an die korrekte Stelle der Objektstruktur navigieren. Die Konfiguration ist korrekt, wenn direkt unter "result" die gewünschten Daten als Array oder Objekt stehen. Sollte das Rückgabeformat ein Objekt sein, erwarten wir für jede Property einen Datensatz.
Wichtig: Um den Ausgabeparameter zu konfigurieren, klicken Sie oben rechts auf den Switch "Erweitert".
Format der Daten aus der Fremdschnittstelle
Damit die Daten korrekt verarbeitet werden können, muss das Format der jeweiligen Einträge mit der Konfiguration der Datenquelle zusammenpassen. Dabei müssen für jeden Datensatz innerhalb des Arrays die Properties die unter "Schlüssel Property" und "Anzeigewert Property" angegeben sind existieren. Fehlt eine dieser beiden Properties oder ist leer, wird der entsprechende Datensatz ignoriert. Sollte ein Schlüssel oder ein Anzeigewert mehrfach vorkommen, wird das erste Vorkommen genommen. Alle weiteren Vorkommen werden ignoriert.
Konfiguration der Datenquelle:

Rückgabe der Daten:

Abschließen der Konnektorkonfiguration
Damit der Konnektor korrekt zum Laden der Daten verwendet werden kann, muss er dem serverseitigen BusinessObjekt "NP_DataSources" als Abhängigkeit hinzugefügt werden. Dafür wählen Sie das BusinessObjekt aus der Liste aus und klicken im rechten Bereich auf den Stift. Anschließend kann links eine Suchhilfe für den Konnektor geöffnet werden. Nach Auswählen des Konnektors in der Liste klicken Sie rechts oben auf "Speichern".
Öffnen der Abhängigkeiten:

Hinzufügen des Konnektors:

Beispielkonnektor
Wichtig: Damit der Beispielkonnektor genutzt werden kann muss, abhängig von Ihrer eingestellten Tokengültigkeit, der Simplifiertoken in den Header Parametern des Konnektors ausgetauscht werden. Um an einen gültigen Simplifiertoken zu kommen, öffnen Sie im Simplifier Fenster die Entwicklertools mit "Rechtsklick" > "Untersuchen". Anschließend wechseln Sie im geöffneten Fenster/Bereich in der Kopfzeile auf "Netzwerk". Klicken Sie anschließend in der Simplifier Seitenleiste auf "Konnektoren". In den Entwicklertools erscheint nun ein Eintrag "connectors". Dort finden Sie unter dem Punkt "Request Headers" den Simplifiertoken.

Wir liefern standardmäßig einen Beispielkonnektor mit aus. Mit diesem können Sie eine Beispiel Datenquelle anlegen und direkt Daten laden. Dabei können Sie die Daten selber verändern und das Aktualisieren der Daten testen.
Konnektor: "SimplifierNewClient"
Konnektor Call: "executeBO_mockData"
Daten ändern können Sie in folgendem BusinessObjekt
BusinessObjekt: NP_DataSources
BusinessObjekt Methode: mockData
Hier finden Sie die benötigte Konfiguration der Datenquelle, mit der Sie den Konnektor testen können:

Aktualisierungsprotokolle
Für jede Aktualisierung der Daten einer Datenquelle wird ein Aktualisierungsprotokoll geschrieben. Dieses beinhaltet die Information, ob die Aktualisierung erfolgreich war oder ob ein Fehler aufgetreten ist. Im Erfolgsfall stehen in der rechten Spalte Debug Informationen, im Fehlerfall der exakte aufgetretene Fehler.
Mögliche Fehlermeldung:
| Fehlermeldung | Beschreibung | Behebung |
| Diese Funktion steht nur eingeloggten Benutzern zur Verfügung. | Sie sind nicht eingeloggt oder Ihre Benutzersession ist mittlerweile abgelaufen. | Loggen Sie sich (erneut) in die KundenmarktplatzKonfiguration ein. |
| Bitte geben Sie eine Datenquell Id an. | Die Datenquelle zum Aktualisieren wurde nicht an den Server übergeben. | Bitte wenden Sie sich an den Support. Geben Sie dabei bitte ihre Instanz und die verwendete Datenquelle an. |
| Der Typ ... der Datenquelle wird aktuell nicht unterstützt. | Die Datenquelle verwendet einen Typen, welcher noch nicht oder nicht mehr unterstützt wird. | Die Datenquelle und das Fremdsystem müssen umgestellt werden, um die Aktualisierung erneut durchführen zu können. |
| Es ist kein Konnektor für die Datenquelle angegeben. | In der Konfiguration der Datenquelle wurde kein Konnektor angegeben. | Geben Sie einen Konnektor in der Konfiguration der Datenquelle an. |
| Es ist kein Konnektor Call für die Datenquelle angegeben. | In der Konfiguration der Datenquelle wurde kein Konnektor Call angegeben. | Geben Sie einen Konnektor Call in der Konfiguration der Datenquelle an. |
| Der Konnektor steht für die Aktualisierung nicht zur Verfügung. Bitte überprüfen Sie, dass der Konnektor im Simplifier existiert und im BO NP_DataSources zu den Abhängigkeiten hinzugefügt ist. | Das BusinessObjekt welches die Aktualisierung durchführt kann den Konnektor nicht finden. | Überprüfen Sie, ob der konfigurierte Konnektor im Simplifier existiert und dem serverseitigen BusinessObjekt NP_DataSources als Abhängigkeit hinzugefügt wurde. Folgen Sie hierzu dem Punkt "Abschließen der Konnektorkonfiguration". |
| Der Konnektor Call steht für die Aktualisierung nicht zur Verfügung. Bitte überprüfen Sie, dass der Call im Konnektor existiert. | Das BusinessObjekt, welches die Aktualisierung durchführt kann den Konnektor Call nicht ausführen, da er nicht im Konnektor existiert. | Überprüfen Sie, dass der konfigurierte Konnektor Call im Konnektor angelegt wurde. |
| Beim Laden der Daten vom Konnektor ist ein unerwarteter Fehler aufgetreten. | Der Konnektor Call wurde ausgeführt, ist jedoch in einen Fehler gelaufen. | Sie können die Fehlermeldung im Aktualisierungsprotokoll nachlesen. Für eine genauere Analyse können Sie im Simplifier im Bereich "Monitoring" > "Monitoring") über die Filter "Benutzer" und "Artefakt" nach der genauen Ausführung des Konnektor Calls suchen und die Eingabeparameter und Rückmeldung auswerten. |
| Das Ergebnis des Konnektor Calls ist nicht iterierbar. | Die Rückgabe des Konnektor Calls unter dem Parameter "result" ist weder ein Objekt noch ein Array. | Passen Sie die Rückgabe des Konnektor Calls entsprechend den Vorgaben unter dem Punkt "Konfiguration der Ausgabe" an. Sie können die Rückgabe selber mit dem Testdialog des Konnektors überprüfen |
| Beim Aktualisieren der Daten ist ein Fehler aufgetreten. Bitte überprüfen Sie das Protokoll. Weitere Informationen finden Sie im Simplifier Log. | Beim Lösch-, Aktualisierungs- oder Hinzufügevorgang ist ein Fehler aufgetreten. Es wurden alle drei Vorgänge ausgeführt. Die Daten wurden somit nicht vollständig aktualisiert. | Wenden Sie sich an den Support. Geben Sie dabei bitte die Datenquelle, den Zeitpunkt der Aktualisierung und die Debug Informationen des Aktualisierungsprotokolls an. |
| Beim Aktualisieren der Daten der Datenquelle ist ein unerwarteter Fehler aufgetreten. | Es ist ein unerwarteter Fehler aufgetreten für den es keine eigene Fehlerbehandlung gibt. | Wenden Sie sich an den Support. Geben Sie dabei bitte die Datenquelle, den Zeitpunkt der Aktualisierung und die Debug Informationen des Aktualisierungsprotokolls an. |
Debug Information im Erfolgsfall
| Name | Beschreibung |
| aDuplicateKeys | Beinhaltet eine Liste aller Schlüsselwerte, welche mehrmals vorkamen. Hierzu wird pro Schlüssel geloggt, wie oft dieser aufgetreten ist. |
| aDuplicateValues | Beinhaltet eine Liste aller Anzeigewerte, welche mehrmals vorkamen. Hierzu wird pro Anzeigewert geloggt, wie oft dieser aufgetreten ist. |
| iInvalidKeys | Gibt die Anzahl an Datensätzen mit ungültigen Schlüsselwerten an. Dabei war der Schlüsselwert entweder leer oder nicht definiert. |
| iInvalidValues | Gibt die Anzahl an Datensätzen mit ungültigen Anzeigewerten an. Dabei war der Anzeigewert entweder leer oder nicht definiert. |
| oDeleteResult | Beinhaltet die Anzahl an gelöschten Werten und ob der Löschvorgang erfolgreich durchgeführt wurde. |
| oUpdateResult |
Beinhaltet die Anzahl an aktualisierten Werten und ob der Updatevorgang erfolgreich durchgeführt wurde. Hinweis: Es werden alle Datensätze aktualisiert, welche in den Bestandsdaten und den neuen Daten anhand des Schlüsselwertes existieren. Es erfolgt keine Prüfung, ob Änderungen für die Datensätze vorliegen. |
| oAddResult | Beinhaltet die Anzahl an neu hinzugefügten Datensätzen und ob das Hinzufügen für alle Datensätze erfolgreich war. |