Stammdaten-Import

Ein Stammdaten-Import ist ein wiederkehrender Hangfire-Job. Er liest die Stammdaten aus einer Quelle (CSV-Datei, ODBC- oder SQL-Abfrage, Schnittstelle eines ERP), wandelt jede Zeile mit einem Mapping-Skript in einen Datensatz um und gleicht das Ergebnis mit den bestehenden Stammdaten ab.

Welche Quellen es gibt, hängt vom ERP-Plugin ab. Die generischen Plugins lesen CSV-Dateien, ODBC-Datenquellen und SQL-Server-Datenbanken. Diese Seite beschreibt vor allem den Import aus CSV-Dateien.

Der Import-Job

Jeder Import ist ein Eintrag in der Tabelle conf.IrRecurringJobs. Eingerichtet wird er bei der Inbetriebnahme durch die enio AG oder einen Partner.

Feld	Bedeutung
`HangfireId`	Eindeutige Kennung des Jobs, zum Beispiel `ch.invoicer.mstr.suppliers`
`Description`	Beschreibung, die unter Administration > Job-Ausführung erscheint
`Enabled`	Ob der Job aktiv ist
`CronExpression`	Wann der Job läuft, zum Beispiel `0 6 * * *` für täglich um 6 Uhr
`TimeZoneId`	Zeitzone für die Cron-Expression
`ClassIdentifier`	Klasse, die den Import ausführt, zum Beispiel `enio.erp.Plugin.FromCsv.Import.Import_Supplier_From_File`
`MethodName`	Methode der Klasse, für Importe in der Regel `DoImport`
`MethodArgumentIdentifier`	Typ der Konfiguration, zum Beispiel `enio.erp.Plugin.FromCsv.Import.ImportFromFileBaseArgument`
`Configuration`	Konfiguration des Imports als JSON (siehe unten)
`ObjectMappingCode`	Das Mapping-Skript (siehe unten)

Konfiguration eines CSV-Imports

{
  "SourceFilePath": "\\\\<server>\\export\\lieferanten.csv",
  "SourceFileEncoding": "utf-8",
  "Separator": ";",
  "HasHeaderRow": true,
  "OuColumnIndex": 0,
  "Source": "ERP",
  "MappingKeys": ["IrOrganizationUnitId", "Number"],
  "DeleteNotDeliveredRecords": true,
  "TraceLevel": "Default"
}

Einstellung	Standard	Bedeutung
`SourceFilePath`		Pfad zur Datei. Möglich sind ein Dateipfad, eine Freigabe im Netzwerk oder eine Adresse mit `http`.
`Host`, `Port`, `Username`, `Password`		Für Dateien auf einem SFTP-Server: `Host` beginnt mit `sftp://`.
`SourceFileEncoding`	Standard des Servers	Zeichensatz, zum Beispiel `utf-8`, `utf-8bom` oder `windows-1252`
`Separator`	`;`	Trennzeichen zwischen den Spalten
`HasHeaderRow`	`false`	Ob die erste Zeile Spaltenüberschriften enthält. Sie wird dann übersprungen.
`CsvHelperMode`	`RFC4180`	Umgang mit Anführungszeichen: `RFC4180`, `Escape` oder `NoEscape`
`IgnoreEmptyFile`	`false`	Leere Datei ohne Fehler überspringen
`IgnoreBadData`	`false`	Fehlerhaft formatierte Zeilen tolerieren
`OnlyTakeNewestFileOfFolder`	`false`	`SourceFilePath` ist ein Ordner. Der Import nimmt die neueste Datei darin.
`FileNameIncludesTimeStamp`	`false`	Der Dateiname enthält ein Datum (Format in `FileNameIncludesTimeStampFormat`, Standard `yyyyMMdd`).
`OuColumnIndex`	`0`	Spalte (ab 0 gezählt) mit der externen Kennung des Geschäftsbereichs
`UseOUId`		Feste externe Kennung des Geschäftsbereichs für alle Zeilen. Ersetzt `OuColumnIndex`.
`Source`	`External`	Quelle der Datensätze, siehe Stammdaten
`MappingKeys`		Felder, an denen der Import bestehende Datensätze erkennt, siehe Stammdaten
`IgnoreProperties`		Felder, die der Import bei bestehenden Datensätzen nie überschreibt, zum Beispiel weil sie im invoiceR gepflegt werden
`DeleteNotDeliveredRecords`	`true`	Nicht mehr gelieferte Datensätze als gelöscht markieren
`ReactivateDeletedRecords`	`false`	Gelöschte Datensätze wieder aktivieren, wenn sie erneut geliefert werden
`MappingFilePath`, `MappingFileEncoding`		Mapping-Skript aus einer Datei oder Adresse laden statt aus `ObjectMappingCode`
`BatchSize`	`999999`	Nach wie vielen Zeilen zwischengespeichert wird
`TraceLevel`	`Default`	Mit `Verbose` schreibt der Job jede Zeile ins Protokoll.

Das Mapping-Skript

Das Mapping-Skript ist C#-Code. Es wird für jede Zeile ausgeführt und füllt den neuen Datensatz. Im Skript stehen zur Verfügung:

Variable	Inhalt
`words`	Die Spalten der aktuellen Zeile als Text-Array, ab 0 gezählt
`entityFromImport`	Der neue Datensatz, den das Skript füllt. Geschäftsbereich und Mandant sind bereits gesetzt.
`cultureInfo`	Schweizer Ländereinstellung, zum Beispiel zum Umwandeln von Zahlen und Daten
`importDynamic`	Bei Importen aus Datenbanken die Zeile als Objekt mit den Spaltennamen

Das Skript muss den Datensatz mit return zurückgeben. Gibt es null zurück, überspringt der Import die Zeile.

Beispiel für Lieferanten aus einer CSV-Datei im Format unten:

entityFromImport.Number = words[1];
entityFromImport.Name = words[2];
entityFromImport.Address1 = words[3];
entityFromImport.Zip = words[6];
entityFromImport.City = words[7];
entityFromImport.UID = words[8];
entityFromImport.Country = words[11];
entityFromImport.DefaultTermOfPayment = words[12];
entityFromImport.DefaultVatCode = words[13];

if (string.IsNullOrWhiteSpace(entityFromImport.Number))
    return null;

return entityFromImport;

Beispiel für Zahlungsmethoden aus einer Datenbank-Abfrage, bei dem das Skript den Typ aus der IBAN ableitet:

using System;
using System.Linq;
using web_manager.Enio;

entityFromImport.Number = importDynamic.LaufNummer.ToString();
entityFromImport.SupplierNumber = importDynamic.KreditorNummer.ToString();
entityFromImport.IBAN = importDynamic.IBAN.ToString().Replace(" ", "");
entityFromImport.Account = entityFromImport.IBAN;
entityFromImport.Country = importDynamic.LandCode.ToString();
entityFromImport.Type = string.IsNullOrWhiteSpace(entityFromImport.IBAN)
    ? PaymentMethodType.BankAccount
    : PaymentMethodType.BankIBAN;

return entityFromImport;

CSV-Formate

Liefert euer ERP die Stammdaten als CSV-Dateien, empfehlen wir die folgenden Formate. Die Reihenfolge der Spalten ist frei, sie wird im Mapping-Skript zugeordnet. Die erste Spalte enthält jeweils die externe Kennung des Geschäftsbereichs (Mandant im ERP).

Lieferanten

Spalte	Typ	Bemerkung	Pflicht
Mandant	Text	Externe Kennung des Geschäftsbereichs	ja
Number	Text	Eindeutige Lieferantennummer	ja
Name	Text		ja
Address1	Text	Adresszeile 1	nein
Address2	Text	Adresszeile 2	nein
Address3	Text	Adresszeile 3	nein
Zip	Text	Postleitzahl	nein
City	Text	Ort	nein
UID	Text	Unternehmens-Identifikationsnummer	nein
Email	Text		nein
Phone	Text	Telefonnummer	nein
Country	Text	ISO-Länderkennung (CH, DE, LI, …)	nein
DefaultTermOfPayment	Text	Standard-Zahlungsbedingung (Nummer aus den Zahlungsbedingungen)	nein
DefaultVatCode	Text	Standard-MwSt-Code (Code aus den MwSt-Codes)	nein

Zahlungsmethoden

Spalte	Typ	Bemerkung	Pflicht
Mandant	Text	Externe Kennung des Geschäftsbereichs	ja
Number	Text	Eindeutige Nummer der Zahlungsmethode	ja
SupplierNumber	Text	Lieferantennummer aus den Lieferanten	ja
Name	Text	Name der Zahlungsmethode, zum Beispiel der Bank	ja
Address	Text	Adresse	nein
Zip	Text	Postleitzahl	nein
City	Text	Ort	nein
Country	Text	ISO-Länderkennung	nein
Account	Text	Kontonummer bei Postverbindung	bei Postverbindung
IBAN	Text	IBAN	bei Bankverbindung mit IBAN
BICCode	Text	BIC nach ISO 9362	nein
SwiftNumber	Text	SWIFT	nein

Konten

Spalte	Typ	Bemerkung	Pflicht
Mandant	Text	Externe Kennung des Geschäftsbereichs	ja
Number	Text	Eindeutige Kontonummer	ja
Description	Text	Beschreibung	nein
VATCode	Text	Standard-MwSt-Code für das Konto	nein
IsBalanceSheetAccount	Ja/Nein	`1` = Bilanzkonto	nein

Kostenstellen

Spalte	Typ	Bemerkung	Pflicht
Mandant	Text	Externe Kennung des Geschäftsbereichs	ja
Number	Text	Eindeutige Kostenstellennummer	ja
Description	Text	Beschreibung	nein

Konto/Kostenstelle

Spalte	Typ	Bemerkung	Pflicht
Mandant	Text	Externe Kennung des Geschäftsbereichs	ja
AccountNumber	Text	Kontonummer aus den Konten	ja
CostCenterNumber	Text	Kostenstellennummer aus den Kostenstellen	ja

Zahlungsbedingungen

Spalte	Typ	Format	Bemerkung	Pflicht
Mandant	Text		Externe Kennung des Geschäftsbereichs	ja
Number	Text		Eindeutige Nummer der Zahlungsbedingung	ja
Description	Text		Beschreibung	nein
NetPeriod	Zahl	`0`	Zahlungsfrist netto in Tagen	ja
DiscountPeriod1	Zahl	`0`	Frist für Skonto 1 in Tagen	nein
DiscountPercent1	Zahl	`0.00`	Skonto 1 in Prozent	nein
DiscountPeriod2	Zahl	`0`	Frist für Skonto 2 in Tagen	nein
DiscountPercent2	Zahl	`0.00`	Skonto 2 in Prozent	nein

MwSt-Codes

Spalte	Typ	Format	Bemerkung	Pflicht
Mandant	Text		Externe Kennung des Geschäftsbereichs	ja
Code	Text		MwSt-Code	ja
Rate	Zahl	`0.00`	MwSt-Satz	ja
Description	Text		Beschreibung	nein
CountryCode	Text		ISO-Länderkennung	nein

Projekte

Spalte	Typ	Bemerkung	Pflicht
Mandant	Text	Externe Kennung des Geschäftsbereichs	ja
Number	Text	Eindeutige Projektnummer	ja
Name	Text	Bezeichnung	ja