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 CRMDelete
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:
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 |
---|---|---|---|---|
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. | |
Person / Debitor | Geschäftspartner Ansprechpartner Adresse Kommunikation | de.schleupen.createOrUpdatePerson | Löschen eines zuvor angelegten Geschäftspartners | |
Marktpartner | Serviceprovider | de.schleupen.createOrUpdatePerson | Information zu Marktrollen eines Marktteilnehmers.
| |
Marktpartner | Serviceprovider | de.schleupen.createOrUpdateServiceprovider | Löschen eines zuvor angelegten Serviceprovider | |
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. | |
Messlokation | Anlage Strukturtyp = MELO | de.schleupen.createOrUpdateLocation | ||
Marktlokation | Anlage Strukturtyp = MALO | de.schleupen.createOrUpdateLocation de.schleupen.createOrUpdateInstallationMelo | ||
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. | |
Ablesung | Zählerstand | de.schleupen.createOrUpdateMeasuringDevice | Zählerstände je Zählwerk | |
Ablesung | Zählerstand | de.schleupen.createOrUpdateMeterread | Löschen von übermittelten Zählerständen | |
Rechnungseinheit Bankverbindung Massnahmenhistorie | Vertragskonto Konto Bank Mahnhistorie | de.schleupen.createOrUpdatePerson | Vertragskonto zum Geschäftspartner mit Informationen zur Bankverbindung, abw. Rechnungsempfänger / Rechnungsadresse und Mahnhistorie | |
Rechnungseinheit | Vertragskonto Mahnhistorie | de.schleupen.deleteContractAccount | Löschen eines zuvor übermittelten Vertragskontos inklusive Mahnhistorie | |
Tarifkopf Tarif | Tarif Tarifzeitscheibe | - | Tarifkopf und Liste der Tarifzeitscheiben-Informationen
| |
Vertrag | Abrechnungsvertrag | de.schleupen.createOrUpdateInstallationMalo de.schleupen.createOrUpdateContractAccount | Abrechnungsvertrag zum Vertragskonto mit Verknüpfung zur Anlage. | |
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. | |
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
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.
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 Status2
: "Error while writing data.",
mit einer Detailierung in der returnmessage übermittelt.
Beispiel Zeitscheibenkonflikt, hier Verarbeitung von Abrechnungsverträgen - Zeitscheibenprüfung auf Anlagenzeitdaten
{
"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.
![](../../../__attachments/165020139/image2022-3-10_14-27-22.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
Monitoring
Die über das Schnittstellenmonitoring in der Schnittstellenübersicht geschriebenen Datensätze können über das Infoboard Systemmonitor überwacht werden.
![](../../../__attachments/165020139/image2023-5-16_15-44-47.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
Sofern die C0-Kachel Systemmonitor verwendet wird, kann das Skript wie folgt verwendet werden
Skript Schnittstellenmonitoring
{
"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. |