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.

    • AB 26.3 Für ein EVI mit mehreren Mandanten, dass an mehrere Schleupen-Mandanten angebunden ist, müssen die Benutzer der einzelnen Mandanten als kommaseparierte Liste hinterlegt werden

  • 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

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

AB 26.4 Schlüssel werden aus Schleupen mit Schlüssel und Beschreibung übernommen. Es ist kein spezielles Mapping mehr notwendig, da EVI alle Schlüssel übernimmt und die vorhandenen EVI-Schlüssel vor einer Initialbeladung an die Schleupen-Schlüssel angepasst werden müssen. Falls es mehrere mögliche Schlüssel geben kann, beinhaltet die Methode SC12SCHLEUPENUtils.getKey ein Mapping für die Schlüsselbereiche S_ADDRTYPE, SERVICEART, C12UNIT, C12METERCLASS, S_MESSW, C12STATUS TARIFZEITSCH., C12READINGBYTYPE, C12READINGREASON, C12METERSIZE, C12COUNTERTYPE, C12MEASURINGUNIT, S_SPEBEN, S_PRDART. Für alle anderen Schlüsselbereiche werden die Schlüssel angelegt. Ist ein Schlüssel bereits vorhanden, prüft EVI, ob die gelieferte Beschreibung des Schlüssel in der EVI-Schlüsselbeschreibung vorhanden ist. Falls nicht, wird sie mit | getrennt an die vorhandene Beschreibung angehangen. So wird sichergestellt, dass auch Schlüssel, die mehrfach in Schleupen vorhanden sind, mit ihrer Beschreibung nach EVI übernommen werden.

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 Status 2 : "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.

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

{
				"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.

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.