Skip to main content
Skip table of contents

ene't Rest Webservices (Admin)

Verfügbare ene't Webservices in EVI

  • Fremdkosten/Netzentgelte:

    • Netzentgeltermittlung Gas

    • Netzentgeltermittlung Strom

  • Marktversorgung/Grundversorgung

    • Grundversorgungsermittlung Gas

    • Grundversorgungsermittlung Strom

  • Marktpartnerermittlung

    • Marktpartnerermittlung Gas

    • Marktpartnermittlung Strom

Die vorliegende Seite bietet eine Übersicht über die Funktionen der ene't Webservices inkl. allgemeinem Nutzungsschema, Administrations- und Übersteuerungsmöglichkeiten.
Detaillierte Informationen zu den einzelnen Webservices, befinden sich auf den jeweiligen Unterseiten.

Installation

Installationsaufwand

~0,25h

Einrichtung der kundenindividuellen LogIn-Daten in den globalen Variablen muss erfolgen.

Voraussetzungen für die Verwendung des Moduls

  • Modul-Lizenz EVI-BASIS liegt im System vor.

  • Nutzungsvereinbarung mit der Ene't liegt vor.

  • Einrichtung der kundenindividuellen LogIn-Daten in den globalen Variablen muss erfolgt sein. Sollte der Kunde keinen Zugang zu den ene't-Webservices haben, muss der Inhalt der globalen Variablen "C12EnetWsPassword" und "C12EnetWsUsername" leer sein. Der SLP-Angebotsprozess erkennt diese Situation und zeigt dem Anwender eine Suchmaske auf die im System hinterlegten ServiceProvider an.

Update

Zum 01.01.2021 wurden die SOAP Services durch die ene't abgeschaltet. Für EVI wurden daher ene't-Webservices implementiert, die bei einem Update folgendes Handeln nötig machen:

Im Rahmen eines Updates muss geprüft werden, ob die folgenden Methoden in Verwendung sind. Diese müssen dann geprüft und durch die passende neue Methode ersetzt werden.

  • SC12EnetUtils.callEnetNetztarif

  • SC12EnetUtils.getDefaultProviderRate

  • SC12EnetUtils.getGridOperator

  • SC12EnetUtils.getGridOperatorPkFromNumber

  • SC12EnetUtils.getNetNumber

  • SC12EnetUtils.getValueFromResultFirstLevel

  • SC12EnetUtils.getValueFromResultSecondLevel

  • SC12SLPUtils.getDefaultProviderRate

Es ist zu prüfen, ob die folgenden Methoden übersteuert wurden und ggf. wieder der Standard verwendet werden kann. Sollte nicht der Standard verwendet werden können, so ist die Verwendung der Methode SC12EnetUtils.debug zu prüfen.

  • createParameterBasicSuppliesElectricityV1

  • createParameterBasicSuppliesGasV1

  • createParameterLocationPropertiesV1

  • createParameterMarketPartnerGasV1

  • createParameterMarketPartnerGasV1

  • createParameterMarketPartnerGasV1

  • createParameterThirdPartyCostsRlmGasV1

  • createParameterThirdPartyCostsSlpElectricityV1

  • createParameterThirdPartyCostsSlpGasV1

  • createResponse

  • putTotalValueIfAbsent

Um die neue REST-basierte Variante der SLP- und RLM-Utils zu verwenden, müssen die Anmeldedaten des ene't-Maschinenkontos hinterlegt werden.

  • Die Anmeldedaten werden in den globalen Variablen C12EnetRestUser und C12EnetRestPassword hinterlegt. Die passenden Werte sind dem Enet-Navigator nach erfolgreicher Registrierung und Aktivierung der passenden Lizenz zu entnehmen.

  • Die Verwendung von HAUSHALT in den Prozessen und Skriptmethoden ist im Projekt zu prüfen und ggf. durch PRIVAT zu ersetzen.

Technische Dokumentation

Komponentenübersicht

Module

  • EVI-BASIS

Skriptbibliothek

  • SC12EnetUtils

Globale Variablen

  • C12EnetRestUser

  • C12EnetRestPassword

Administrationsmöglichkeiten

Administrationsmöglichkeiten über die globalen Variablen:

Globale Variable

Beschreibung

C12EnetRestPassword

Passwort der ene't-REST-Schnittstelle

C12EnetRestUser

Benutzer der ene't-REST-Schnittstelle

Übersteuerungsmöglichkeiten

Grundsätzlich können die mit dem Modul bereitgestellten Komponenten wie BPM-Prozesse, -teilprozesse, Suchen und Skriptbibliotheksmethoden übersteuert werden, um diese an individuelle Anforderungen und Bedürfnisse anzupassen. 

Nach dem Einspielen eines Moduls sollte geprüft werden, ob bereits Methoden im Projekt übersteuert wurden und ob die Methodenänderung aus dem Standard im Projekt übernommen werden sollte.

Webservice

Skriptklasse

Methodenname

Funktionalität


SC12EnetUtils







createParameterBasicSuppliesElectricityV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung des Grundversorgungstarifes Strom


createParameterBasicSuppliesGasV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung des Grundversorgungstarifes Gas


createParameterLocationPropertiesV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Standorteigenschaften


createParameterMarketPartnerElectricityV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Marktpartner Strom


createParameterMarketPartnerGasV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Marktpartner Gas


createParameterNetCostsRlmElectricityV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Netzkosten RLM Strom


createParameterNetCostsRlmGasV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Netzkosten RLM Gas


createParameterNetCostsSlpElectricityV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Netzkosten SLP Strom


createParameterNetCostsSlpGasV1

Generiert die Eingabeparameter für den Webservice zur Ermittlung der Netzkosten SLP Gas

  • Die Kernlogiken rund um den REST-Aufruf sind in der Klasse SC12EnetUtils abgebildet. Sie bietet die Möglichkeit, die Parameter aufzubereiten, zu validieren, den Aufruf abzusetzen und die Antwort auszuwerten. Alle diese Schritte sind elementar gestaltet, sodass diese wiederverwendet werden können. Der für den Anwendungsfall interessante Aufruf wird in der Klassen SC12RLMUtils und SC12SLPUtils unter Hilfenahme der SC12EnetUtils abgebildet.

  • Alle Methoden, die die REST-Schnittstelle bedienen, erwarten als Aufrufparameter eine vor gefüllte Map. Diese Map ist von jeweiligen Aufrufer im Vorfeld zu füllen. Welche Einträge erwartet werden ist der jeweiligen Methodendokumentation zu entnehmen. Dieser Ansatz - im Gegensatz zu explizit angegebenen Parametern - wurde gewählt, um eine Erweiterbarkeit zu gewährleisten. Sollte der Bedarf bestehen, die Methoden zu übersteuern, da kundenspezifische Anforderungen abgedeckt werden müssen, so können kundenspezifische Parameter über die Map an die Logik gereicht werden.

Skriptmethoden

Skriptklasse

Methodenname

Funktionalität

SC12EnetUtils




getNetCostsV1

Validierung der Eingabewerte und Aufruf des Webservices

createParameterNetCostsRlmElectricityV1

Diese und die folgenden drei Methoden schreiben die Eingabewerte in die von der ene't vorgesehene Struktur, damit diese an den Webservice übergeben werden kann. 

createParameterNetCostsRlmGasV1


createParameterNetCostsSlpElectricityV1


createParameterNetCostsSlpGasV1


readNetCostsV1

Liest Werte aus dem Webservice-Ergebnis aus und schreibt diese in einen virtuellen Container der Entität Preiskalkulation zur weiteren Verwendung in EVI.


Anmerkung für ene't Webservices

Jede Methode ist generell übersteuerbar, an dieser Stelle macht es aber wenig Sinn, da immer die gesamte Response geliefert wird.
Man sollte eher die entsprechenden Methoden aus SC12SLPUtils übersteuern, sollte man weitere Werte benötigen, als die, die die Methoden liefern.

Nutzungsschema

Design

Die Kernlogiken rund um den REST-Aufruf sind in der Klasse SC12EnetUtils abgebildet. Sie bietet die Möglichkeit, die Parameter aufzubereiten, zu validieren, den Aufruf abzusetzen und die Antwort auszuwerten. Alle diese Schritte sind elementar gestaltet, sodass diese wiederverwendet werden können.

Der für den Anwendungsfall interessante Aufruf wird in der Klassen SC12RLMUtils und SC12SLPUtils unter Hilfenahme der SC12EnetUtils abgebildet.

Aufrufparameter

Alle Methoden, die die REST-Schnittstelle bedienen, erwarten als Aufrufparameter eine vor gefüllte Map. Diese Map ist von jeweiligen Aufrufer im Vorfeld zu füllen. Welche Einträge erwartet werden ist der jeweiligen Methodendokumentation zu entnehmen.

Dieser Ansatz - im Gegensatz zu explizit angegebenen Parametern - wurde gewählt, um eine Erweiterbarkeit zu gewährleisten. Sollte der Bedarf bestehen, die Methoden zu übersteuern, da kundenspezifische Anforderungen abgedeckt werden müssen, so können kundenspezifische Parameter über die Map an die Logik gereicht werden.

Ergebniswerte

Die Ergebnisstruktur folgt immer einem Schema:

Map

{
    "status": <int>,
    "response": <Map>
}


Im Eintrag status lässt sich ein Statuswert auslesen, der den Staus des Aufrufs abbildet:

200

Erfolgreicher Aufruf

400

Kein gültiges Medium (momentan Gas oder Elektrizität)

401

Keine Anmeldedaten

404

Kein Ergebnis

500

Keine gültigen Aufrufdaten

Im Eintrag response findet sich das eigentliche Ergebnis des Aufrufes. Je nach Aufruf bildet diese Wert eine andere Struktur ab.

Aufrufschema

Den Einstieg bieten die SC12RLMUtils und SC12SLMUtils.

Die Methoden beinhalten die Logik, um einen kompletten Aufruf abzubilden. Möchte man selbst weitere Aufrufe konstruieren, so kann man sich am dem Schema orientieren.
Beispielablauf anhand getThirdPartyCosts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// Ermittlung, ob welches Modul genutzt werden soll.
if (LogicScriptUtils.isModuleActive("GetAG", true)) {
  return [ "status" : 503 ];
}
else {
  // Kann für das angefragte Medium eine Anfrage erstellt werden?
  String medium = thirdPartyCosts.get("medium")
 
  if (!SC12EnergyMarketUtils.isValidMedium(medium)) {
    return [ "status" : 400 ] // bad request
  }
   
  // Ermittelung Gas oder Elektrizität
  boolean isGas = SC12EnergyMarketUtils.isGas(medium);
 
  // Aufbereitung des Aufrufparameters der REST-Schnittstelle
  Integer zip         = thirdPartyCosts.get("zip");
  String city         = thirdPartyCosts.get("city");
  ...
 
  // Erstellung des Aufrufparameters über "createParameterXXX"
  Map<String, Object> thirdPartyCostsParameter = isGas
    ? SC12EnetUtils.createParameterThirdPartyCostsSlpGasV1(
        zip, city, street, streetNumber,
        ...    
    : SC12EnetUtils.createParameterThirdPartyCostsSlpElectricityV1(
        zip, city, street, streetNumber,
        thirdPartyCosts.get("voltageLevelShipment"),
        ...
 
  // Ermittelung des Servicenames
  String serviceName = isGas
    ? "/slp/gas"
    : "/slp/strom";
 
  // Aufruf der REST-Schnittstelle
  Map<String, Object> thirdPartyCostsResponse = SC12EnetUtils.getThirdPartyCostsV1(serviceName, thirdPartyCostsParameter);
 
  // Prüfung des Aufrufs
  if (thirdPartyCostsResponse.get("status") != 200) {
    return thirdPartyCostsResponse;
  }
 
  // Umwandlung in das passende EVI-Format mittels "readXXX"
  Map<String, Object> readThirdPartyCosts = SC12EnetUtils.readThirdPartyCostsV1(thirdPartyCostsResponse.get("response"), isGas, [:]);
 
  return readThirdPartyCosts; 
}

Logging
Debug-Logging

Innerhalb der Methoden sind mittels ScriptUtils.debug() Debug-Ausgaben eingebaut worden, die bei Bedarf aktiviert werden können, um einen Einblick in den technischen Ablauf zu erlangen.

Interface-Detail

Innerhalb der eigentlichen REST-Schnittstellen-Aufrufe in der Klasse SC12EnetUtils werden über die SC12EVIBaseUtils Log-Einträge angelegt, um die Kommunikation zwischen dem CRM und der REST-Schnittstelle zu protokollieren.

Allgemeiner Aufbau

  1. Einstieg in Services über Methoden in SC12SLPUtils

    1. Netzbetreiberermittlung: getGridOperator

    2. Grundversorgungstarif: getBasicSupplyRate

    3. Standorteigenschaften: getLocationProperties

    4. Fremdkostenermittlung: getThirdPartyCosts

  2. Methoden zum Erzeugen der Übergabedaten an den Webservice in SC12EnetUtils

    1. createParameter<Servicename><Medium>V1

      1. Grundversorgungstarif Strom: createParameterBasicSuppliesElectricityV1

  3. Methoden zum Abruf der einzelnen Services

    1. get<Servicename>V1

      1. getBasicSuppliesV1

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close