EVI-Schleupen Datenaktualisierung bei Änderung Schleupen2EVI

Allgemein Funktionsweise

Die Integration der Datenaktualisierung bei Änderung Schleupen2EVI überträgt per REST-Service Daten von Schleupen CS.VA nach EVI. Die Übertragung erfolgt über eine Jobsteuerung in der Schleupen CS.VA.

Als Endpunkt in EVI wird die REST-API und die darin enthaltenen Services zur Entgegennahme von Zeitereignissen verwendet, um definierte Eventtypen und deren Datenstrukturen im JSON Format zu verarbeiten.

Folgende Eventtypen kommen zum Einsatz:

CreateOrUpdate
Neuanlage eines neuen Datensatzes, oder Update eines bestehenden und identifizierbaren Datensatzes im CRM
Delete
Löschen eines identifizierbaren Datensatzes anhand eines eindeutigen Löschattributes

Die Daten werden aus der Schleupen CS.VA sequentiell gesendet und bauen dabei aufeinander auf. D.h. es wird bei Änderung einer Rechnungseinheit immer erst die zugrunde liegende Person und dann die Rechnungseinheit übermittelt. Wurde der Vorgang quittiert, erfolgt die nächste Übermittlung eines Änderungsvorgangs.

Innerhalb von EVI werden die Daten der eingehenden Aufrufe synchron verarbeitet. Im Zeitereignis erfolgt zunächst eine Prüfung auf Plausibilität der Daten, darauf folgenden die Verarbeitung des Payloads in die CRM-Struktur über generische Funktionen im EVI-Basis-Modul. Anschließend die Quittierung des Vorgangs, der an Schleupen CS.VA zurück übermittelt wird.

Voraussetzungen

EVI RESTful API

Dokumentationen:
- https://www.cursor.de/software/erweiterungen/rest-api
- Entgegennahme von Zeitereignissen
- Endpunkt techn. Doku: https://Server.Domain:{Portrange}8443/rest/doc/v1/services/event
Endpunkt Rest Service: https://Server.Domain:{Portrange}8443/rest/api/event/v1/events
Authentifizierung:
- Alle CURSOR REST-Endpunkte benötigen eine gültige Authentifizierung. Als Methode wird Basic Auth mit Benutzername und Passwort verwendet
- Der Benutzer 3C-SCHLEUPEN wird im Auslieferungsstand bei Neuinstallationen ausgeliefert.
  - Benutzer: 3C-SCHLEUPEN
  - Passwort: Das Passwort im Auslieferungszustand kann durch den CURSOR-Projektleiter in Erfahrung gebracht werden, sollte aber vor der Erstinbetriebnahme geändert werden.
- Der Benutzername für den Webservice ist in der globalen Variable C12SchleupenRestUserName zu hinterlegen.
- Andernfalls muss dieser angelegt oder alternativ ein entsprechend anderer User angelegt werden. Bei Anmeldung am CRM via Active Directory Authentifizierung ist ein Domain-User zu verwenden
- Wird ein User ungleich 3C-SCHLEUPEN verwenden, ist dieser in der Methode zur Übertragung von Änderungen aus EVI an Drittsysteme zu ändern, um zu vermeiden, dass Änderungen aus Schleupen direkt zurück an Schleupen übertragen werden. Diese Konfiguration erfolgt in der globalen Variable C12SchleupenRestUserName und wird an die Methode SC12SCHLEUPENCallUtils.isStartCheckEvi2Schleupen() zur Prüfung durchgereicht.
Verschlüsselung / Zertifikate
- Die Kommunikation zwischen Server und Server erfolgt verschlüsselt.
- Entsprechende Zertifikate müssen auf den jeweiligen Systemen ausgetauscht und installiert sein.
- Erfolgt die Kommunikation außerhalb des Netzwerkes sind entsprechende Kommunikationswege via VPN / Reverse Proxy projektindividuell aufzubauen

Schleupen CS.VA

Die Übertragung erfolgt über eine Jobsteuerung in der Schleupen CS.VA, die über den Jobserver automatisiert werden kann. Das Übertragungsintervall kann dabei durch den Kunden sinnvoll gewählt werden (bspw. 1x stündlich).

Für etwaige Voraussetzungen für den Betrieb der Schnittstelle seitens Schleupen CS.VA steht Ihnen Ihr Schleupen Ansprechpartner gerne zur Verfügung.

Eventtypen

Eventtype	Schleupen Quellobjekte	EVI Zielobjekte	Abhängigkeiten	Fachliche Beschreibung / Bemerkungen
de.schleupen.createOrUpdatePerson	Person / Debitor	Geschäftspartner Ansprechpartner Adresse Kommunikation	-	Neuanlage oder Update eines Geschäftspartners mit Adresse und Kommunikation, als Vertragspartner, Rechnungsempfänger oder Marktteilnehmer. Zu einem Geschäftspartner wird in EVI immer ein Default-Ansprechpartner erzeugt.
de.schleupen.deletePerson	Person / Debitor	Geschäftspartner Ansprechpartner Adresse Kommunikation	de.schleupen.createOrUpdatePerson	Löschen eines zuvor angelegten Geschäftspartners
de.schleupen.createOrUpdateServiceprovider	Marktpartner	Serviceprovider	de.schleupen.createOrUpdatePerson	Information zu Marktrollen eines Marktteilnehmers. Innerhalb der Schleupen CS.VA muss im Schnittstellen-Konfigurator das jeweilige Marktpartner-Konto entsprechend ausgeprägt werden.
de.schleupen.deleteServiceprovider	Marktpartner	Serviceprovider	de.schleupen.createOrUpdateServiceprovider	Löschen eines zuvor angelegten Serviceprovider
de.schleupen.createOrUpdateLocation	Abnahmestelle	Anschlussobjekt	-	Adressinformation zur Markt- und Messlokation. Innerhalb der Schleupen CS.VA kann es zu einer Adresse mehrere Abnahmestellen geben, die über die ID unterschieden werden.
de.schleupen.createOrUpdateInstallationMelo	Messlokation	Anlage Strukturtyp = MELO	de.schleupen.createOrUpdateLocation
de.schleupen.createOrUpdateInstallationMalo	Marktlokation	Anlage Strukturtyp = MALO	de.schleupen.createOrUpdateLocation de.schleupen.createOrUpdateInstallationMelo
de.schleupen.createOrUpdateMeasuringDevice	Mengenpunkt Zähler Zählwerk	Messeinrichtung Zählwerke	de.schleupen.createOrUpdateInstallationMelo	Messeinrichtungen werden, wenn Sparte Strom / Gasd zur Messlokation (Anlage mit Strukturtyp = Melo) zugeordnet. bei nicht regulierten Sparten erfolgt die Zuordnung zum Anschlussobjekt. Abgebildet werden Zähler und die jeweils eingebauten Zählwerke.
de.schleupen.createOrUpdateMeterread	Ablesung	Zählerstand	de.schleupen.createOrUpdateMeasuringDevice	Zählerstände je Zählwerk
de.schleupen.deleteMeterread	Ablesung	Zählerstand	de.schleupen.createOrUpdateMeterread	Löschen von übermittelten Zählerständen
de.schleupen.createOrUpdateContractAccount	Rechnungseinheit Bankverbindung Massnahmenhistorie	Vertragskonto Konto Bank Mahnhistorie	de.schleupen.createOrUpdatePerson	Vertragskonto zum Geschäftspartner mit Informationen zur Bankverbindung, abw. Rechnungsempfänger / Rechnungsadresse und Mahnhistorie
de.schleupen.deleteContractAccount	Rechnungseinheit	Vertragskonto Mahnhistorie	de.schleupen.deleteContractAccount	Löschen eines zuvor übermittelten Vertragskontos inklusive Mahnhistorie
de.schleupen.createOrUpdateRatetype	Tarifkopf Tarif	Tarif Tarifzeitscheibe	-	Tarifkopf und Liste der Tarifzeitscheiben-Informationen Aufgrund von individuellen Preiskonfigurationen in den Kundenprojekten werden die Preiszeitscheiben und Preisdarstellungen zunächst nicht abgebildet. Diese können bei Bedarf durch den Kunden im Tarifmanagement in EVI manuell hinterlegt werden.
de.schleupen.createOrUpdateBillingContract	Vertrag	Abrechnungsvertrag	de.schleupen.createOrUpdateInstallationMalo de.schleupen.createOrUpdateContractAccount	Abrechnungsvertrag zum Vertragskonto mit Verknüpfung zur Anlage.
de.schleupen.createBillingData	Rechnungsdaten	Abrechnungsdaten	de.schleupen.createOrUpdateInstallationMalo de.schleupen.createOrUpdateContractAccount de.schleupen.createOrUpdateBillingContract	Die Abrechnungswerte werden aus dem Rechnungsdruck extrahiert und bereitgestellt und beziehen sich auf den Rechnungszeitraum. Dabei werden nur Daten aus abgeschlossenen Rechnungsvorgängen verarbeitet. Übermittelt werden Verbrauch, Erlös und Leistung. Kosten werden aufgrund des fehlenden Energiepreises nicht abgebildet.
de.schleupen.deleteBillingDatae	Rechnungsdaten	Abrechnungsdaten	de.schleupen.createBillingData	Stornieren oder Löschen einer zuvor übermittelten Rechnungsinformation

Liegt eine Information in Schleupen nicht vor, wird dieses Leer-Element im Rahmen der Serialisierung der Übergabe nicht in die Struktur eingearbeitet. Der Elementname ist dann nicht in dem Payload enthalten. Nicht übermittelte Informationen werden somit als leer oder nicht vorhanden gewertet und in EVI ebenfalls gelöscht.

Verarbeitung EVI

Innerhalb von EVI werden die Daten der eingehenden Aufrufe synchron verarbeitet.

Im Zeitereignis erfolgt zunächst eine Prüfung auf Plausibilität der Daten, darauf folgenden die Verarbeitung des Payloads in die CRM-Struktur über generische Funktionen im EVI-Basis-Modul und anschließend die Quittierung des Vorgangs, der an Schleupen CS.VA zurück übermittelt wird. Folgende Methoden kommen dabei zum Einsatz:

SC12SCHLEUPENUtils.createOrUpdate* bzw. SC12SCHLEUPENUtils.delete*: Für jeden Eventtypen erfolgt die Bearbeitung in der jeweilig zur Verfügung gestellten Hauptmethode SC12SCHLEUPENUtils.createOrUpdate* bzw. SC12SCHLEUPENUtils.delete*
SC12SCHLEUPENUtils.checkMandatoryFields*:In der Untermethode SC12SCHLEUPENUtils.checkMandatoryFields* wird zunächst eine Pflichtfeldprüfung auf den Payload ausgeführt. Als Pflichtfelder sind in der Regel für die Verarbeitung relevante IDs sowie in EVI als Pflichtfeld markierte Felder definiert.
SC12SCHLEUPENUtils.read*: Das Feldmapping zur Verarbeitung des Payloads in die EVI-Tabellen ist in den Methoden SC12SCHLEUPENUtils.read* ausgeführt
SC12EnergyMarketUtils.createOrUpdate* SC12EnergyMarketUtils.delete* führt die eigentliche Verarbeitung in das EVI Datenmodell aus.

Schlüsselhandling

Schlüssel werden aus Schleupen immer mit Kürzel und Bezeichnung übertragen. Die Verarbeitung nach EVI erfolgt fallspezifisch.

Ist ein Mapping von Schleupen Schlüssel zu EVI Schlüssel erforderlich, erfolgt dies mittels der Methode SC12SCHLEUPENUTILS.getKey.
Liegt ein Schlüssel in EVI bereits vor, wird dieser verwendet.
Liegt ein Schlüssel in EVI im Rahmen der Verarbeitung noch nicht vor, so wird dieser automatisch aus Kürzel und Beschreibung angelegt.

Die in der EVI Auslieferungsversion verwendeten Standard-Schlüssel, welche für ein Schlüsselmapping herangezogen werden könnten, sind in der Entität Prüfschlüssel (C12KEYCHECK) zu finden und vor der Erstinbetriebnahme der Schnittstelle mit den jeweiligen Schleupen-Schlüsseln abzugleichen.

Auszug Schlüsselmapping

Auszug des Schlüsselmappings der Methode SC12SCHLEUPENUTILS.getKey

Auszug Schlüsselmappings der Methode SC12SCHLEUPENUTILS.getKey

CODE

case "S_ADDRTYPE":
      if (!ScriptUtils.isEmpty(map.get("Postfach")))
      {
        return LookupUtils.lookup("pobox", "AddressType.Address", true, false); // Postfach
      }
  
      if (!ScriptUtils.isEmpty(map.get("Strasse")))
      {
        return LookupUtils.lookup("street", "AddressType.Address", true, false); // Straße (Default)
      }
      
      return LookupUtils.lookup("majorcustomer", "AddressType.Address", true, false); // Großkunden
  
    case "S_PRDART":
      if(ScriptUtils.equal(map.get("Kuerzel"), "S"))
      {
       return LookupUtils.lookup("c51v611baip25hgS_Keytab", fieldName, true, false); //01 BITTE ÄNDERN Strom
      }
      if(ScriptUtils.equal(map.get("Kuerzel"), "G"))
      {
       return LookupUtils.lookup("v9ia5v1baip2c3eS_Keytab", fieldName, true, false); //02 BITTE ÄNDERN Gas
      }
      
      //Overload for more supported keys.
      
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    case "ANLART":
      //Currently no existing keys. Overload for more supported keys.
      
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
      
    case "C12MEASURINGUNIT":
      if(ScriptUtils.equal(map.get("Kuerzel"), "kWh"))
      {
       return LookupUtils.lookup("11r8o8l1f4qvm241S_Keytab", fieldName, true, false); //KWH
      }
          
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    case "C12COUNTERTYPE":
  
      if(ScriptUtils.equal(map.get("Kuerzel"), "HT"))
      {
       return LookupUtils.lookup("n43kgb1f4qv83t3S_Keytab", fieldName, true, false); //HT Bitte pflegen
      }
  
      if(ScriptUtils.equal(map.get("Kuerzel"), "NT"))
      {
       return LookupUtils.lookup("o60mbg1f4qv8j4bS_Keytab", fieldName, true, false); //NT Bitte pflegen
      }
  
      //Overload for more supported keys.
  
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    case "S_SPEBEN":
      if(ScriptUtils.equal(map.get("Kuerzel"), "HSP"))
      {
       return LookupUtils.lookup("fvvvvvvcs503t1eeate08gS_Keytab", fieldName, true, false); //HS  Hochspannung
      }
      if(ScriptUtils.equal(map.get("Kuerzel"), "MSP"))
      {
       return LookupUtils.lookup("njta611e4nej3fbS_Keytab", fieldName, true, false); //MS  Mittelspannung
      }
      if(ScriptUtils.equal(map.get("Kuerzel"), "NSP"))
      {
       return LookupUtils.lookup("fvvvvvuuic9g11e4nejfcsS_Keytab", fieldName, true, false); //NS  Niederspannung
      }
     
      return LookupUtils.EMPTY_KEY;
  
    case "SERVICEART":
      ILookup medium = (ILookup)parameter;
      if(ScriptUtils.equal(map.get("Kuerzel"), "VNB"))
      {
        if(ScriptUtils.equal(LookupUtils.getPk(medium), "c51v611baip25hgS_Keytab")) //01 BITTE ÄNDERN Strom
        {
          return LookupUtils.lookup("fvvvvvu0fovo81beiiufg6S_Keytab", fieldName, true, false); //SNET BITTE ÄNDERN Strom Netznutzung
        }
        if(ScriptUtils.equal(LookupUtils.getPk(medium), "v9ia5v1baip2c3eS_Keytab")) //02 BITTE ÄNDERN Gas
        {
          return LookupUtils.lookup("fvvvvvvuaoeuj1beiis4ouS_Keytab", fieldName, true, false); //GNET BITTE ÄNDERN Gas Netznutzung
        }
      }
      else if(ScriptUtils.equal(map.get("Kuerzel"), "MSB"))
      {
        if(ScriptUtils.equal(LookupUtils.getPk(medium), "c51v611baip25hgS_Keytab")) //01 BITTE ÄNDERN Strom
        {
          return LookupUtils.lookup("fvvvvvvsnsluu1enate269S_Keytab", fieldName, true, false); //MSB STROM BITTE AEND  Messstellenbetreiber Strom
        }
        if(ScriptUtils.equal(LookupUtils.getPk(medium), "v9ia5v1baip2c3eS_Keytab")) //02 BITTE ÄNDERN Gas
        {
          return LookupUtils.lookup("fvvvvvu650srm1enathbs9S_Keytab", fieldName, true, false); //MSB GAS BITTE AENDER  Messstellenbetreiber Gas
        }
      }
      else if(ScriptUtils.equal(map.get("Kuerzel"), "ENH"))
      {
        if(ScriptUtils.equal(LookupUtils.getPk(medium), "c51v611baip25hgS_Keytab")) //01 BITTE ÄNDERN Strom
        {
          return LookupUtils.lookup("fvvvvvurrdbsv1ejrun1q7S_Keytab", fieldName, true, false); //LF STROM BITTE AENDE  Lieferant Strom
        }
        if(ScriptUtils.equal(LookupUtils.getPk(medium), "v9ia5v1baip2c3eS_Keytab")) //02 BITTE ÄNDERN Gas
        {
          return LookupUtils.lookup("8iqbav1ejrulrpjS_Keytab", fieldName, true, false); //LF GAS BITTE AENDERN  Lieferant Gas
        }
      }
      //Overload for more supported keys.
      
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    case "C12UNIT":
      String unit = "";
      switch(fieldName)
      {
        case "MinDurationUnit.C12RTIMESL":
          unit = map.get("Bindungstyp");
          break;
        case "Termunit.C12RTIMESL":
          unit = map.get("Kuendigungsfristtyp");
          break;
        case "Extunit.C12RTIMESL":
          unit = map.get("Verlaengerungsfristtyp");
          break;
        case "C12ExtUnit.BillingContract":
          unit = map.get("VerlaengernUmTyp") != null ? map.get("VerlaengernUmTyp").get("Kuerzel") : null;
          break;
        case "C12TermUnit.BillingContract":
          unit = map.get("KuendigungsfristTyp") != null ? map.get("KuendigungsfristTyp").get("Kuerzel") : null;
          break;
        default:
          break;
      }
      
      if(ScriptUtils.equal(unit, "T", "TAGE"))
      {
       return LookupUtils.lookup("q8tnth1c8utahv7S_Keytab", fieldName, true, false); //TAGE
      }
      if(ScriptUtils.equal(unit, "W", "WOCHEN"))
      {
       return LookupUtils.lookup("900m3j1c8utbhbuS_Keytab", fieldName, true, false); //WOCHEN
      }
      if(ScriptUtils.equal(unit, "M", "MONATE"))
      {
       return LookupUtils.lookup("fvvvvvvj13lpt1b75uhn60S_Keytab", fieldName, true, false); //MONATE
      }
      if(ScriptUtils.equal(unit, "J", "JAHRE"))
      {
       return LookupUtils.lookup("5mmc61b75ui71qS_Keytab", fieldName, true, false); //JAHRE
      }
      
      //Overload for more supported keys.
      
      return LookupUtils.EMPTY_KEY;
  
    case "C12METERCLASS":
      String shortCut = map.get("Kuerzel");
      String code = map.get("EDIFACT");
      String identifier = ScriptUtils.isEmpty(code) ? shortCut : code;
      if(ScriptUtils.equal(identifier, "AHZ"))
      {
        return LookupUtils.lookup("fvvvvvvscs7qu1g7mbnamvS_Keytab", fieldName, true, false); //AHZ BITTE AENDERN	analoger Haushaltszähler (Drehstrom)
      }
      if(ScriptUtils.equal(identifier, "BGZ"))
      {
        return LookupUtils.lookup("dibm3a1g7mbqo44S_Keytab", fieldName, true, false); //BGZ BITTE AENDERN	Balgengaszähler
      }
      if(ScriptUtils.equal(identifier, "DKZ"))
      {
        return LookupUtils.lookup("tbhrp01g7mbq5meS_Keytab", fieldName, true, false); //DKZ BITTE AENDERN	Drehkolbengaszähler
      }
      if(ScriptUtils.equal(identifier, "EHZ"))
      {
        return LookupUtils.lookup("ica92t1g7mjmjgnS_Keytab", fieldName, true, false); //EHZ BITTE AENDERN	elektronischer Haushaltszähler
      }
      if(ScriptUtils.equal(identifier, "IVA"))
      {
        return LookupUtils.lookup("fvvvvvv5es7gl1g7mbu9adS_Keytab", fieldName, true, false); //IVA BITTE AENDERN	Individuelle Abstimmung (Sonderausstattung)
      }
      if(ScriptUtils.equal(identifier, "LAZ"))
      {
        return LookupUtils.lookup("ileu371g7mbomntS_Keytab", fieldName, true, false); //LAZ BITTE AENDERN	Lastgangzähler
      }
      if(ScriptUtils.equal(identifier, "MAZ"))
      {
        return LookupUtils.lookup("aojb981g7mbp326S_Keytab", fieldName, true, false); //MAZ BITTE AENDERN	Maximumzähler
      }
      if(ScriptUtils.equal(identifier, "MME"))
      {
        return LookupUtils.lookup("1nmhoda1g7mbpk9uS_Keytab", fieldName, true, false); //MME BITTE AENDERN	moderne Messeinrichtung nach MsbG
      }
      if(ScriptUtils.equal(identifier, "MRG"))
      {
        return LookupUtils.lookup("19d2o101g7mbsjp3S_Keytab", fieldName, true, false); //MRG BITTE AENDERN	Messdatenregistriergerät
      }
      if(ScriptUtils.equal(identifier, "TRZ"))
      {
        return LookupUtils.lookup("fvvvvvusn8rl61g7mbr95fS_Keytab", fieldName, true, false); //TRZ BITTE AENDERN	Turbinenradgaszähler
      }
      if(ScriptUtils.equal(identifier, "UGZ"))
      {
        return LookupUtils.lookup("fvvvvvv7rg0ej1g7mbrnrbS_Keytab", fieldName, true, false); //UGZ BITTE AENDERN	Ultraschallgaszähler
      }
      if(ScriptUtils.equal(identifier, "WGZ"))
      {
        return LookupUtils.lookup("fvvvvvule6d6t1g7mbs43sS_Keytab", fieldName, true, false); //WGZ BITTE AENDERN	Wirbelgaszähler
      }
      if(ScriptUtils.equal(identifier, "WSZ"))
      {
        return LookupUtils.lookup("fvvvvvvfni9fp1g7mbo3trS_Keytab", fieldName, true, false); //WSZ BITTE AENDERN	analoger Wechselstromzähler
      }
  
      //Overload for more supported keys.
  
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    case "S_MESSW":
      String shortCut = map.get("Kuerzel");
      String code = map.get("EDIFACT");
      String identifier = ScriptUtils.isEmpty(code) ? shortCut : code;
  /*
      if(ScriptUtils.equal(identifier, "ELEKTRONISCH"))
      {
        return LookupUtils.lookup("1p1msdc1eeas7ubsS_Keytab", fieldName, true, false); //ELEKTRONISCH BITTE AENDERN	Elektronisch
      }
      if(ScriptUtils.equal(identifier, "IMS"))
      {
        return LookupUtils.lookup("ok4k7l1eeas8fa7S_Keytab", fieldName, true, false); //IMS BITTE AENDERN	IMS
      }
      if(ScriptUtils.equal(identifier, "MECHANISCH"))
      {
        return LookupUtils.lookup("fvvvvvuf5ofko1eeas70frS_Keytab", fieldName, true, false); //MECHANISCH BITTE AENDERN	MechanischS
      }
      if(ScriptUtils.equal(identifier, "MS_MME_NS"))
      {
        return LookupUtils.lookup("mim3id1eeas93j0S_Keytab", fieldName, true, false); //MS_MME_NS BITTE AENDERN	MS_MME_NS
      }*/
      if(ScriptUtils.equal(identifier, "Z01"))
      {
        return LookupUtils.lookup("1jcv0jn1g7mkeb6uS_Keytab", fieldName, true, false); //Z01 BITTE AENDERN	EDL40
      }
      if(ScriptUtils.equal(identifier, "Z02"))
      {
        return LookupUtils.lookup("fvvvvvvnu8rja1g7mkerjsS_Keytab", fieldName, true, false); //Z02 BITTE AENDERN	EDL21
      }
      if(ScriptUtils.equal(identifier, "Z03"))
      {
        return LookupUtils.lookup("fvvvvvv2ud9q51g7mkf9b5S_Keytab", fieldName, true, false); //Z03 BITTE AENDERN	sonstiger EHZ
      }
      if(ScriptUtils.equal(identifier, "Z04"))
      {
        return LookupUtils.lookup("fvvvvvu8lj34f1g7mkfk8eS_Keytab", fieldName, true, false); //Z04 BITTE AENDERN	Standard
      }
      if(ScriptUtils.equal(identifier, "Z05"))
      {
        return LookupUtils.lookup("fvvvvvuga85vg1g7mkg685S_Keytab", fieldName, true, false); //Z05 BITTE AENDERN	MeDa-Zähler
      }
  
      //Overload for more supported keys.
  
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    case "C12STATUS TARIFZEITSCH.":
      Date fromDate = SC12SCHLEUPENUtils.getValueFromJSON("FromDate.C12RTIMESL", parameter.get("GueltigAb"));
      Date untilDate = SC12SCHLEUPENUtils.getValueFromJSON("UntilDate.C12RTIMESL", parameter.get("GueltigBis"));
  
      if(DateUtils.compareDate(DateUtils.NOW, fromDate) > 0 //now > fromDate
         && untilDate != null && DateUtils.compareDate(DateUtils.NOW, untilDate) > 0) //now > untilDate
      {
        return LookupUtils.lookup("1rghqmk1bb6gcq91S_Keytab", fieldName, true); //BEENDET Beendet (Tarifzeitscheibe nicht mehr verwenden)
      }
      
      if(DateUtils.compareDate(DateUtils.NOW, fromDate) > 0 //now > fromDate
         && (untilDate == null || DateUtils.compareDate(DateUtils.NOW, untilDate) <= 0)) //now < untilDate
      {
        return LookupUtils.lookup("fvvvvvuglad4k1bb6gbu7iS_Keytab", fieldName, true); //AKTIV Im Vertrieb befindliche Tarifzeitscheibe
      }
  
      return LookupUtils.lookup("fvvvvvvaqejqq1bb6gb8klS_Keytab", fieldName, true); //IN VORBEREITUNG In Vorbereitung
  
    case "C12READINGBYTYPE":
      if(ScriptUtils.equal(map.get("Kuerzel"), "001"))
      {
       return LookupUtils.lookup("fvvvvvv2nfqls1f502vpakS_Keytab", fieldName, true, false); //  01 Ablesung durch Kunde
      }
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    
    case "C12READINGREASON":
      if(ScriptUtils.equal(map.get("Kuerzel"), "04"))
      {
       return LookupUtils.lookup("fvvvvvvgaig881f502utanS_Keytab", fieldName, true, false); //  01 Jahresverbrauch / Turnusablesung
      }
      return SC12SCHLEUPENUtils.createOrUpdateKey(map, fieldName);
  
    default:
      return MetaDataUtils.isNumericLookupField(fieldName) ? LookupUtils.EMPTY_KEY_NUM : LookupUtils.EMPTY_KEY;
  }
}

Fehlerhandling

Tritt im Rahmen der Entgegenenahme oder Verarbeitung der Daten ein Fehler auf, liefert die REST-Api entsprechende http-Fehlercodes an das aufrufende System, hier Schleupen CS.VA, zurück.

200: OK - Die Anfrage wurde erfolgreich bearbeitet und das Ergebnis der Anfrage wird in der Antwort übertragen.
- Im Payload der Returnmessage wird dann der eigentliche Verarbeitungsstatus übermittelt.
- Diese kann auch fachliche Fehler enthalten.

CODE

returnCode returnMessage
0 : "Success.",
1 : "Missing mandatory fields.",
2 : "Error while writing data.",
3 : "An unknown error occured.",
4 : "Mandatory values do not exist or are not unique"
Beispiel: 
 
{
  "id": "fvvvvvunkksnm1fevgapiqEvAr",
  "status": "DONE",
  "payload": {
    "returnCode": 0,
    "returnMessage": "Success."
    "missingFields": "Field1, Field2"
    //gemäß den in JSon übertragenen Feldnamen
  }
}

401: Unauthorized - Die Anfrage kann nicht ohne gültige Authentifizierung durchgeführt werden
500: Internal Server Error - Sammler für unerwartete Serverfehler
Sonderbehandlung Zeitscheibenkonflikt
Innerhalb von EVI sind auf den Tabellen Anlagenzeitdaten, Tarifzeitscheiben und Abschlagsplänen Zeitscheibenprüfungen aktiviert. Bei der Verarbeitung der Tabellen kann es somit zu Zeitscheibenkonflikten kommen.
Hierbei wird der Status 2 : "Error while writing data.", mit einer Detailierung in der returnmessage übermittelt.

Beispiel Zeitscheibenkonflikt, hier Verarbeitung von Abrechnungsverträgen - Zeitscheibenprüfung auf Anlagenzeitdaten

CODE

{
    "id": "94mlvd1h0i7ucseEvAr",
    "status": "ERROR",
    "payload": {
        "duration": 996,
        "returnCode": 2,
        "returnMessage": "Error while writing data., createOrUpdateBillingContract: error while writing data.\n\ntimeSlicingIs [\ntableName [TimeSlicingIs],\npk [[PrimaryKeyAC: simplePrimaryKey: null, relationPk:null]],\ncopyable [false], mailable [false], wordable [false]\nattributeValues contained: 5,\nattributeValues [\n\t[C12RateTypePk.TimeSlicingIs] [key = [?], pk = [#EMPTY-KEY#], validDBKey = [true]], readable [true], writable [true], managingAllowed [false], confidential [false]\n\t[FromDate.TimeSlicingIs] [2023-04-30 00:00:00.0], readable [true], writable [true], managingAllowed [false], confidential [false]\n\t[InstallationPk.TimeSlicingIs] [key = [?], pk = [#EMPTY-KEY#], validDBKey = [true]], readable [true], writable [true], managingAllowed [false], confidential [false]\n\t[TimeSlicingIsDesc.TimeSlicingIs] [20230419], readable [true], writable [true], managingAllowed [false], confidential [false]\n\t[UntilDate.TimeSlicingIs] [2023-05-16 00:00:00.0], readable [true], writable [true], managingAllowed [false], confidential [false]\n], [Exception while writing data: de.cursor.exception.LoggableRuntimeException: [Process: C12TIMESLICE_UTIL(58|C1) 'TIMESLICE_UTIL'] [Instance: bc6deda4-f3e3-11ed-8d85-005056880f47] [Task: cid_fvvvvvvm9gsh81b968hvf8ScriptTaskProperty 'Check timeslices consistency'][User: 3C-SCHLEUPEN as 3C-SCHLEUPEN] -  de.cursor.exception.ScriptingException: <html>Zeitscheibenkonflikt:<br>02.07.2022-02.08.2023<br>18.04.2023-30.04.2023<br></html>\n Script1683865130353_1152.run:44]]\n"
    }
}

Sonderfall ausgebaute Zähler:
Ein in der Initialbeladung ausgebaut und übermittelter Zähler wird in der Verarbeitung mit "status": "DONE" quittiert und erhält in der returnmessage eine Zusatzinfo "returnMessage": "measuringDevice [202212231] not created because all counters are already removed".
Dies hat den Hintergrund, dass durch den Ausbau abgelehnte Zähler nicht nochmals übertragen werden. Details siehe de.schleupen.createOrUpdateMeasuringDevice

Fehlerhandling Schleupen

Der der returncode/returnmessage wird durch Schleupen interpretiert und entsprechend reagiert.

Fehlercode 1, Fehlercode 4: führt in Schleupen zur Information an einen VA-Sachbearbeiter. Die Objekte werden im nächsten Lauf nochmal übermittelt.
Fehlercode 2, Fehlercode 3: Die Objekte werden im nächsten Lauf nochmal übermittelt.

Fehlerhandling EVI:

Bei auftretenden internen Fehler wird eine zentrale SkriptMethode in SC12SchleupenUtils aufgerufen und o.g. Fehlercodes und Messages erzeugt. Diese werden in der Antwort im Verarbeitungsstatus und Message mit übermittelt.

Im Fehlerfall werden aus der SC12SchleupenUtils die C0-Klassen SC0InterfaceUtils aufgrufen, welche wiederum die Interface-Tabellen schreiben.
InterfaceOver:
- Einträge beginnen mit DE.SCHLEUPEN.
- Je EventType wird ein InterfaceOver-Datensatz erzeugt, bspw. DE.SCHLEUPEN.CREATEORUPDATECONTRACTACCOUNT
- InterfaceDetail:
  - Protokollieren das Ergebnis des jeweiligen Laufes
  - Die Struktur wird in TechInfo.InterfaceDetail übernommen (Payload des Aufrufs in [Logging] und Fehlermeldung in [Error]
    - weitere Werte zum Befüllen der Tabelle werden durch die C0-Methoden vorgegeben
  - Der InterfaceDetail-Datensatz wird mit dem jeweiligen Zeitereignis (EventArchive-Datensatz) verknüpft, so dass man direkt einen Einblick in den Request- und Responsestruktur nehmen kann.

Monitoring

Die über das Schnittstellenmonitoring in der Schnittstellenübersicht geschriebenen Datensätze können über das Infoboard Systemmonitor überwacht werden.

Sofern die C0-Kachel Systemmonitor verwendet wird, kann das Skript wie folgt verwendet werden

Skript Schnittstellenmonitoring

CODE

{
				"name": "Schleupen",
				"leafs": [
					{
						"name": "Schleupen2EVI",
						"leafs": [
							{
								"name": "createOrUpdateBillingContract",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEBILLINGCONTRACT"
							},
							{
								"name": "Event createOrUpdateBillingData ",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEBILLINGDATA"
							},
							{
								"name": "Event deleteBillingData",
								"id": "DE.SCHLEUPEN.DELETEBILLINGDATA"
							},
							{
								"name": "Event createOrUpdateContractAccount",
								"id": "DE.SCHLEUPEN.CREATEORUPDATECONTRACTACCOUNT"
							},
							{
								"name": "Event deleteContractAccount",
								"id": "DE.SCHLEUPEN.DELETECONTRACTACCOUNT"
							},
							{
								"name": "Event createOrUpdateInstallationMalo",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEINSTALLATIONMALO"
							},
							{
							"name": "Event createOrUpdateInstallationMelo",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEINSTALLATIONMELO"
							},
							{
							"name": "Event createOrUpdateLocation",
								"id": "DE.SCHLEUPEN.CREATEORUPDATELOCATION"
							},
							{
								"name": "Event createOrUpdateMeasuringDevice",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEMEASURINGDEVICE"
							},
							{
								"name": "Event createOrUpdateMeterread",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEMETERREAD"
							},
							{
								"name": "Event deleteMeterread",
								"id": "DE.SCHLEUPEN.DELETEMETERREAD"
							},
							{
								"name": "Event createOrUpdatePerson",
								"id": "DE.SCHLEUPEN.CREATEORUPDATEPERSON"
							},
							{
								"name": "Event deletePerson",
								"id": "DE.SCHLEUPEN.DELETEPERSON"
							},
							{
								"name": "Event createOrUpdateRateType",
								"id": "DE.SCHLEUPEN.CREATEORUPDATERATETYPE"
							},
							{
								"name": "Event createOrUpdateServiceProvider",
								"id": "DE.SCHLEUPEN.CREATEORUPDATESERVICEPROVIDER"
							},
							{
								"name": "Event deleteServiceprovider",
								"id": "DE.SCHLEUPEN.DELETESERVICEPROVIDER"
							}							
						]
					},
					{
						"name": "EVI2Schleupen",
						"leafs": [
							{
								"name": "MASTERDATA_CHANGE_CUSTOMER",
								"id": "EVI2SCHLEUPEN-MASTERDATA_CHANGE_CUSTOMER"
							},
							{
								"name": "CHANGE_BILLINGPLAN",
								"id": "EVI2SCHLEUPEN-CHANGE_BILLINGPLAN"
							},
							{
								"name": "PC_CANCEL_BILLINGCONTRACT",
								"id": "EVI2SCHLEUPEN-PC_CANCEL_BILLINGCONTRACT"
							},
							{
								"name": "PC_CHANGE_PRODUCT",
								"id": "EVI2SCHLEUPEN-PC_CHANGE_PRODUCT"
							},
							{
								"name": "SLP_CREATE_METERREADING",
								"id": "EVI2SCHLEUPEN-SLP_CREATE_METERREADING"
							}							
						]
					}
				]
			}

Installation

Die Installation der Integration EVI-Schleupen Datenaktualisierung bei Änderung Schleupen2EVI beschränkt sich seitens EVI auf

das Einspielen des Modulpakete EVI-Schleupen und die jeweilige Konfiguration
die Herstellung des Verbindungsaufbaus zwischen den jeweiligen Serversystemen. Diese ist im wesentlichen abhängig von der IT-Infrastruktur des Kunden
Für den Prozess deletePerson sind zuvor entsprechende DSGVO Verarbeitungstätitgkeiten und Kategorien anzulegen. Diese sind unter de.schleupen.deletePerson als Download verfügbar und das Vorgehen beschrieben.

Installationsaufwand (PT)

0,5 PT für Modulimport und Import der Verarbeitungstätigkeiten

0,5 ~ 1 PT für Abstimmungen mit den jeweiligen IT Abteilungen und Herstellung der Verbindung der Systemumgebungen.

Updateaufwand (PT)

Technische Dokumentation

Komponentenübersicht

Prozesse

Anlagenkonto erzeugen oder aktualisieren (C12CreateOrUpdateInstallationAccount)

Dieser Prozess reagiert auf Änderungen von Anlagen, Anlagen-Zeitdaten, Anschlussobjekte und Vertragskonten, sowie auf Neuanlage von Anlagen-Zeitdaten und markiert das jeweils zugehörige Anlagenkonto für eine spätere Aktualisierung.

Bei Änderungen von Abrechnungsverträgen wird ein zugehöriges Anlagenkonto ebenfalls für eine spätere Aktualisierung markiert. Existiert hingegen noch keines, wird ein Anlagenkontorumpf angelegt. In diesem werden lediglich Anlage und Geschäftspartner, sowie der Abrechnungsvertrag und ggf. ein zugehöriges Vertragskonto hinterlegt. Das neue Anlagenkonto wird auch für eine spätere Aktualisierung markiert um die restlichen Informationen zu ziehen. Sollte kein Geschäftspartner oder keine Anlage ermittelt werden können, wird ein entsprechender Aktualisierungsfehler im Anlagenkonto gesetzt.

Skriptbibliothek

SC12SCHLEUPENUtils

Diese Skriptmethode wird automatisiert durch den Zeitereignis-Service angesteuert, wenn oben stehende Events eingehen. Die Einstiegnsmethoden sind dementsprechend jeweils createOrUpdate<Entity> bzw. delete<Entity>. Für jede Entität (ein Event kann mehrere enthalten) gibt es eine read<Entity> Methode, die das Mapping der Felder enthält.

Je nach Event werden eine oder mehrere Entitäten angelegt und/oder aktualisiert. Dabei wird erwartet, dass die Events in einer vorgegebenen Reihenfolge eintreffen.

Zum Schreiben von Daten werden die EnergyMarketUtils verwendet.

Ü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.

Methodenname	Methodensignatur	Funktionalität
SC12SCHLEUPENUtils.checkMandatoryFields<Entity>	zum Beispiel private void checkMandatoryFieldsAddress(String eventType, Map<String,Object> payloadRequest, List<String> missingFields)	Weitere Pflichtfelder definieren.
SC12SCHLEUPENUtils.getCommunicationType	private String getCommunicationType(String jsonField, String defaultCommunicationType)	Die von Schleupen gelieferten Kommunikationsarten übersteuern, falls sie von den Standardwerten "Mobil", "Fax", "Tel" und "e-mail" abweichen.
SC12SCHLEUPENUtils.getKey	private ILookup getKey(Map<String,Object> map, String fieldName, String keyRange, Object parameter)	Hier ist das Schlüsselmapping hinterlegt. Die Methode kann übersteuert werden um weitere Schlüssel oder Schlüsselbereiche zu mappen.
SC12SCHLEUPENUtils.lookup	private ILookup lookup(Map<String,Object> map, String fieldName, String lookupEntityName)	Hier sind Nachschlagevorgänge hinterlegt. Die Methode kann übersteuert werden um das Nachschlagen zu erweitern oder zu ändern.