Administrationshandbuch (EVI-WILKEN)

Voraussetzungen

• EVI-Basismodul muss installiert und lizenziert sein

• Wilken-Modul muss installiert und lizenziert sein

Technische Dokumentation

Komponentenübersicht

Prozesse

• OSSTEVI2WilkenEventQuote

Beim Einspielen des Moduls werden die Prozesse automatisch veröffentlicht, dennoch ist eine Prüfung des Veröffentlichungsstatus empfehlenswert. Entsprechende Hinweise werden auch beim Import des Moduls ausgegeben.

Skriptbibliothek

• SC12OSSTEVI2WilkenMain

• SC12OSSTEVI2WilkenUtils

• SC12OSSTEVI2WilkenCSVTools

• SC12OSSTEVI2WilkenTestUtils

Globale Variablen

• C12WILKEN_CSVDIR

Administrationsmöglichkeiten

Administrationsmöglichkeit über globale Variablen:

Übersteuerungsmöglichkeiten

Bei Anpassungen ist zu beachten, dass auch die automatischen Tests entsprechend angepasst werden müssen

Ändern der CSV-Parameter

Hierzu ist die Methode transferQuoteCSVConfig() zu übersteuern. Als Vorlage kann der Code aus C1 kopiert werden. Die in den auskommentierten Zeilen definierten Werte enthalten die Defaultwerte des Moduls. Um einen Wert zu ändern kann eine Zeile auskommentiert werden und dann der Wert angepasst werden.

^{//csvData.put(";CHARSET;", "UTF-8");              // Zeichensatz
//csvData.put(";SEP;", ";");                      // Trenner
//csvData.put(";QUOTE;", "\"");                   // Quote
//csvData.put(";QUOTED;", "\"\"");                // Ersatzdarstellung
//csvData.put(";NEWLINE;", "\r\n");               // Zeilentrenner
//csvData.put(";DOUBLEFMT;", "#########.###");    // Zahlenformat
//csvData.put(";DATEFMT;", "ISO");                // Datumsformat}

Die für den Zeichensatz zulässigen Werte können in der Java-Dokumentation nachgeschlagen werden (https://docs.oracle.com/javase/7/docs/api/java/nio/charset/Charset.html). Als Zahlenformat kann ein Format angegeben werden, das auch für NumberUtils.format() gültig ist. Wenn als Datumsformat ISO angegeben wird, dann wird DateUtils.convertISO() zur Formatierung der Datumswerte verwendet. Ansonsten ist ein Format für die Methode DateUtils.convertDateTimePattern() anzugeben.

Hinzufügen und Entfernen von Feldern

Um die übertragenen Felder zu manipulieren kann die Methode SC12OSSTEVI2WilkenMain.transferQuoteCSVCompleteLine() übersteuert werden. Sie wird für jeden Satz aufgerufen. Sie bekommt folgende Parameter:

• eviData - eine Map mit Container des aktuellen Angebotssatzes

• csvData - die Datenstruktur mit den CSV-Daten

• logMap - eine Logmap, um Fehler zu protokollieren

Auch hier ist es sinnvoll, den Code aus C1 zu kopieren, der ein Gerüst für die Methode enthält.

IContainer Quote_AC = eviData.get("Quote_AC");
IContainer C12INSTACC_AC = eviData.get("C12INSTACC_AC");
IContainer PriceCalc_AC = eviData.get("PriceCalc_AC");
IContainer Customer_AC = eviData.get("Customer_AC");
IContainer RECustomer_AC = eviData.get("RECustomer_AC");

/*
* Hier können weitere Aufrufe von
 *
 * SC12OSSTEVI2WilkenCSVTools.setFieldFromAC(csvData, "<csvname>", <IContainer>, "<Containerfeld>");
 * SC12OSSTEVI2WilkenCSVTools.setField(csvData, "<csvname>", <Wert>);
 * SC12OSSTEVI2WilkenCSVTools.deleteColumn(csvData, "fieldName");
 *
 * stehen.
 */

Im ersten Teil werden die vorhanden EVI-Datenelemente (Attributcontainer) aus der Map gelesen. Die Container enthalten alle Felder der Entität und nicht nur die, die für die Suche verwendet wurden.

Um Werte in die CSV-Datenstruktur zu transportieren, kann die Methode

• SC12OSSTEVI2WilkenCSVTools.setFieldFromAC(csvData, csvname, AC, Field);

verwendet werden. Sie kopiert den Wert aus dem Container AC im Feld Field in die Spalte csvname in die aktuelle Zeile der Datenstruktur csvData.

Beispiel

^{SC12OSSTEVI2WilkenCSVTools.setFieldFromAC(csvData, "KalcTemplate", Quote_AC, "C12CalcTemplate.Quote");}

schreibt den Wert aus dem Angebot (Quote_AC) in dem Feld C12CalcTemplate.Quote in die Spalte KalcTemplate der aktuellen Zeile.

Wurde für diese Spalte schon ein Wert festgelegt, dann wird dieser überschrieben. Gibt es die Spalte noch nicht, dann wird sie neu angefügt. Damit bestimmt die Reihenfolge der setFieldFromAC() Aufrufe die Reihenfolge der Felder in der CSV-Datei. Da neue Spalten immer hinten angefügt werden, ist es nicht möglich Spalten dazwischen einzufügen.

Da transferQuoteCSVCompleteLine()  für jede Zeile aufgerufen wird, wird eine Spalte in jeder Zeile gefüllt. Es sei denn, hier wird mit Bedingungen gearbeitet, die setFieldFromAC() nur für bestimmte Zeilen aufrufen. Wird beim Hinzufügen einer Spalte entdeckt, dass diese nicht in den vorherigen Zeilen vorhanden ist, dann wird sie dort ergänzt und mit dem Leerwert gefüllt.

Die Werte können in verschiedenen Datentypen angegeben werden und werden für die CSV-Daten in einen String konvertiert. Hier gelten folgende Regeln:

• Date - wird durch Aufruf von formatDate() in einen String verwandet. Wenn formatDate() nicht überschrieben wurde, wird das in ";DATEFMT;" definierte Format verwendet.

• Double - wird durch Aufruf von formatDouble() in einen String verwandet. Wenn formatDouble() nicht überschrieben wurde, wird das in ";DOUBLEFMT;" definierte Format verwendet.

• ILookup - der String wird aus dem Schlüssel gebildet

• alle anderen Datentypen - der String wird mittels toString() erzeugt

Soll für ein bestimmtes Feld eine andere Konvertierung verwendet werden, dann kann der Wert auch manuelle aus dem Container gelesen werden, konvertiert werden und mit Hilfe der Methdoe setField() übergeben werden. Die Methode setField() macht im Prinzip das Gleiche wie setFieldFromAC() mit dem Unterschied, dass der Wert direkt angegeben wird und nicht aus einem Attributcontainer gelesen wird. Die Methode kan auch für Konstanten oder berechnete Werte verwendet werden.

Mit deleteColumn() kann eine Spalte in der Datenstruktur gelöscht werden. Als Parameter ist die Datenstruktur und der Name der Spalte in der CSV.

Ändern der Feldreihenfolge

Felder, die innerhalb von transferQuoteCSVCompleteLine() hinzugefügt werden, werden immer hinten angefügt. Um die Feldreihenfolge zu ändern, kann eine neue Überschrift definiert werden. Dazu kann die Funktion transferQuoteCSVBeforeWrite() übersteuert werden. Sie wird unmittelbar vor dem Erzeugen der CSV aufgerufen. Hier kann dann durch Aufruf von SC12OSSTEVI2WilkenCSVTools.changeHeadline() die Überschrift geändert werden. Bei Erzeugen der CSV-Datei wird die Reihenfolge der Felder anhand der Überschrift gebildet. Bei der Definition einer neuen Überschrift muss darauf geachtet werden, dass alle Felder darin vorkommen, die auch in der vorherigen Überschrift vorkommen. Es darf also nur die Reihenfolge geändert werden.

Beispiel

SC12OSSTEVI2WilkenCSVTools.changeHeadline(csvData,"Vorname;Nachname;...;BisherigeKundenNr");

Anpassen der Datenmenge

An der Ermittlung der Datenmenge ist die Suche C12BPM_WILKEN_QUOTE_WITH_SUBENTITY beteiligt, die in der Entität Angebot/Quote zu finden ist. Sie bekommt den PK des Angebotes als Platzhalter und sucht dazu alle Anlagenkonten mit dazugehörigen Preiskalkulationen im Status ZUG. Die Felder, die die Suche liefert ist dabei nicht von zentraler Bedeutung, da zu jedem Container die Felder im Nachgang komplett gelesen werden. Sollen weitere Felder übertragen werden, ist es also nicht notwendig die Suche anzupassen. Bei folgenden Fällen, kann die C2-Erweitrung jedoch über ein Anpassen der Suche erreicht werden:

• Andere Bedingungen zur Ermittlung der Datenmenge. Sollen beispielsweise alle Preiskalkulationen übertragen werden, statt nur der im Status ZUG, kann das über eine Anpassung der Suche erreicht werden.

• Weitere Entitäten als Datenquelle. Sollen Beispielsweise Kalkulationsdetails (CalcTemplate) übertragen werden, kann die Suche entsprechend angepasst werden.

Beim Anpassen ist jedoch darauf zu achten, dass die bestehenden Elemente, aus denen die Standardfelder gelesen werden, nicht entfernt werden. Deshalb müssen folgende Felder auf jeden Fall in der Suche vorhanden sein:

• Pk.Quote

• CustNoInvoice.C12INSTACC

• CustomerPk.C12INSTACC

• Pk.PriceCalc

• Pk.C12INSTACC

Wenn weitere Entitäten hinzugefügt werden, dann sollten diese auch als Attributcontainer zur Verfügung gestellt werden, damit in SC12OSSTEVI2WilkenMain.transferQuoteCSVCompleteLine()  darauf zugegriffen werden kann. Dazu ist die Methode createEviDataQuote() zu übersteuern. Sie erzeugt zu einem Satz aus dem Suchergebnis (search_AC) die Attributcontainer und schreibt sie mit einem definierten Namen in eine Map. In dem C1-Code kann man sehen, wie das gemacht wird und den Code für eine eigene Vorlage verwenden. Wurde beispielsweise die Suche um die Entität CalcTemplate erweitert - die Suche sollte dann das Feld Pk.CalcTemplate enthalten - sieht der Code zum Erzeugen des Attributcontainers dafür so aus:

/* Alle Standardentitäten hinzufügen */
HashMap eviData = super(search_AC, logMap); 

/* Kalkulationsdetails hinzufügen */
String CalcTemplate_PK = WorkSpaceScriptUtils.getValue(search_AC, "Pk.CalcTemplate");
IContainer CalcTemplate_AC = WorkSpaceScriptUtils.searchEntryForRead(CalcTemplate_PK, "CalcTemplate");
eviData.put("CalcTemplate_AC",CalcTemplate_AC);
return eviData;

In SC12OSSTEVI2WilkenMain.transferQuoteCSVCompleteLine()  kann dann so auf den Container zugegriffen werden:

IContainer RECustomer_AC = eviData.get("CalcTemplate_AC");

Ändern des Namens der CSV-Datei

Der Name der CSV-Datei wird von der Methode getCSVQuoteFilename() erzeugt. Standardmässig wird das Format:

QUOTE_V<version>_<Angebotsnummer>_<Zeitstempel>.csv

Wenn ein anderer Name verwendet werden soll, dann kann die Methode in C2 übersteuert werden. Die Methode unterscheidet zwischen zwei Dateinamen, die über den Parameter testflags gesteuert werden. Einmal wird ein Dateiname für den Export erzeugt und einmal ein Dateiname für einen automatischen Test (testflags > 0). Grund für die unterschiedlichen Dateinamen ist zum einen, dass eine zum Test erzeugte Datei sich von der Exportdatei unterscheiden muss, damit diese nicht vom Importprozess in das produktive System eingelesen wird. Andererseits darf der Dateiname für den automatischen Test keine generierten Zeitangaben enthalten, da der Name der erwarteten Datei ebenfalls (möglicherweise einige Sekunden später) generiert wird und sich dann unterscheiden würde.

Ablaufbeschreibung

Ablauf der Erzeugung einer CSV-Datei

Der Prozess OSSTEVI2WilkenEventQuote reagiert auf die Neuanlage eines Events mit dem Namen RLM_QUOTE_ACCEPTED. Als Reaktion wird der PK des Eventsatzes ermittelt und an die Methode SC12OSSTEVI2WilkenMain.transferQuote() übergeben.

transferQuote() ließt den PK des Angebotes aus dem Event, erzeugt eine leere Logmap und ruft zum Übertragen transferQuoteByPk() mit diesen Werten auf. Nach der Übertragung wird durch Aufruf von SC12OSSTEVI2WilkenUtils.createEventRes() ein neuer Satz der Entität C12EVENTRES als Ergebnis aus der Logmap erzeugt und dem Event zugeordnet.

transferQuoteByPK() startet über searchQuote() eine Suche (C12BPM_WILKEN_QUOTE_WITH_SUBENTITY), die zu jeder angenommenen Preiskalkulation des Angebotes einen Satz liefert. Diese Menge wird an SC12OSSTEVI2WilkenMain.transferQuoteCSV() zur Übertragung übergeben.

Grund für die Aufteilung auf drei Methoden ist zum einen die Option statt CSV später auch andere Übertragungsmethoden verwenden zu können und zum anderen die Funktionalität auch unabhängig von einem Event zur Verfügung zu stellen. So kann transferQuoteByPK()  auch von anderen Prozessen aufgerufen werden, ohne dass ein C12EVENT vorliegt.

transferQuoteCSV() nutzt die Klasse SC12OSSTEVI2WilkenCSVTools zur Erzeugung der CSV-Datei. Diese Klasse sammelt die Daten erst in einer internen Datenstruktur und erzeugt erst zum Schluss eine Datei. Damit wird das Problem umgangen, dass die Menge der Spalten erst bekannt ist, wenn alle Zeilen geschrieben wurden. Allerdings sollten damit keine großen Datenmengen erzeugt werden, da sonst der Arbeitsspeicher nicht ausreicht.

Erster Schritt ist die Erzeugung der Datenstruktur für die Daten durch Aufruf von SC12OSSTEVI2WilkenCSVTools.createCsvData(). Neben einer leeren Datenstruktur sind in diesem Objekt auch Parameter zur Erzeugung der CSV-Datei enthalten, wie z.B. der Zeichensatz. Dieses Objekt wird dann in Schritt 2 an die Methode SC12OSSTEVI2WilkenMain.transferQuoteCSVConfig() übergeben, die im Auslieferungsstand des Moduls leer ist. In einer C2-Ausprägung kann die Methode übersteuert werden, um die Parameter zur Erzeugung der CSV-Datei zu ändern.

Die Methode SC12OSSTEVI2WilkenCSVTools.createCsvData() verarbeitet dann in einer Schleife zeilenweise die übergebenen Suchergebnisse aus transferQuoteByPK()  und erzeugt zu jedem Satz eine Zeile in der internen Datenstruktur mit den CSV Daten. Dazu benutzt sie die Methoden

• SC12OSSTEVI2WilkenCSVTools.addRow() - neue Zeile hinzufügen

• SC12OSSTEVI2WilkenCSVTools.setFieldFromAC() - Feldwert aus einem IContainer hinzufügen

• SC12OSSTEVI2WilkenCSVTools.setField() - Feldwert hinzufügen

Da das Suchergebnis nur einzelne Feldwerte enthält, werden die notwendigen Container zu einem Satz über SC12OSSTEVI2WilkenMain.createEviDataQuote() ermittelt.

Nach dem Erzeugen der Daten für eine Zeile wird die Methode SC12OSSTEVI2WilkenMain.transferQuoteCSVCompleteLine() aufgerufen. Diese führt im Auslieferungszustand keinen relevanten Code aus und kann in C2 übersteuert werden, um weitere Felder zu übertragen oder Feldwerte zu entfernen.

Wenn alle Zeilen abgearbeitet wurden, wird die CSV-Datei durch Aufruf von SC12OSSTEVI2WilkenCSVTools.write() geschrieben.