bertaplus Ablauf- / Prozessbeschreibungen

Ein flexibler CSV-Import mit kundenspezifischem Spalten-Mapping ist in Vorbereitung, aber noch nicht erreichbar (Reader und Mapping existieren, sind aber nicht an eine Maske oder einen Job angeschlossen).

Für beide Wege gilt:

• Der Artikel muss im Artikelmandanten existieren.

• Der Preis ist Pflicht und darf nicht negativ sein.

• Liegt der Preis unter dem Mindestpreis des Artikels (Feld Mindestpreis im Artikelstamm, ersatzweise der Preis in der Mindestpreis-Stufe des Mandanten), wird er auf den Mindestpreis angehoben, nicht abgewiesen. Die Anhebung steht im Änderungsprotokoll der Preisstufe als Feld „Auf Mindestpreis angehoben“. Importierte Preise gelten nicht als von Hand gesetzt – beides beschreibt die Anwenderdokumentation in Abschnitt 4.6.

• Pro Artikel gibt es in einer Version genau einen Eintrag: Ein zweiter Satz zum selben Artikel ersetzt den ersten – samt Konditionsfeldern und Mengenstaffel.

• Ein fehlerhafter Satz bricht den Lauf nicht ab; er wird protokolliert, der nächste Satz wird verarbeitet.

• Jede Änderung landet im Änderungsprotokoll der Preisstufe.

  2. Weg A – Datenimport 9.6, Zielbereich PRICETIER

  2.1 Voraussetzungen

  1. Feld-Dictionary registriert. Die Struktur PRICETIER muss in ^HVAR stehen. Das macht einmalig pro Namespace ##class(BERTA.PriceCondition.PriceManagement.Infrastructure.Config.PriceTierFieldDictionary).Register() im Terminal. Das läuft nicht automatisch mit dem Setup des Moduls. Wird in der Satzdefinition die Struktur PRICETIER nicht angeboten, fehlt dieser Schritt. Nach einer Modulaktualisierung erneut ausführen – erst dann stehen neue Felder (z. B. die Staffelspalten aus 2.5) in der Satzdefinition zur Verfügung, und erst dann zeigt das Änderungsprotokoll neue Protokollfelder wie „Auf Mindestpreis angehoben“ mit Bezeichnung statt Feldcode. Der Aufruf ist idempotent.

  2. Entwurfs-Version angelegt. In 8.44.9 muss zu Stufenschlüssel und Version ein Entwurf existieren. Der Import legt keine Versionen an.

  3. Importdefinition (9.6.10) mit Zielbereich PRICETIER, Kopfsatz wie üblich.

  4. Satzdefinition: je Dateispalte Struktur PRICETIER, Feld = Feldcode aus den Tabellen unten, Feldtyp nach Abschnitt 2.6.

  Die Werte kommen im Modul als IMPZSSATZ("PRICETIER", <Feldcode>) an. Artikel- und Kundenmandant kommen aus der Sitzung, die Konditionsbasis ist fest „Preisstufe“ (PriceLevel). Ein Satz ist eine komplette Artikelzeile: Basispreis, Konditionsfelder und Mengenstaffel stehen in einem Satz.

  2.2 Adressfelder – Pflicht in jedem Satz

  Feldcode	Bezeichnung	Dictionary-Typ	Format / Regel	Beispiel
  Tier	Stufe	STRING	Stufenschlüssel, exakt wie in 8.44.9 angelegt (frei, Groß-/Kleinschreibung beachten)	USD
  Version	Version	STRING	XXX.YYY, dreistellig. Ungepolstert wird toleriert (1.0 = 001.000). Eine dritte Stelle .Z wird ignoriert.	001.000

  Zu Stufe + Version muss ein Entwurf existieren. Sonst: „Keine Entwurfs-Version 001.000 zum Stufenschlüssel USD gefunden.“ – der Satz wird abgewiesen.

  2.3 Basisfelder der Artikelzeile

  Feldcode	Bezeichnung	Dictionary-Typ	Pflicht	Format / Regel	Beispiel
  ArticleNumber	Artikel-Nr	STRING	ja	Artikelnummer (ATNR) des Artikelmandanten. Textfeld, führende Nullen bleiben.	4711
  Price	Preis	NUMMER, 2 NKS	ja	Betrag ≥ 0, Komma oder Punkt als Dezimaltrennzeichen, keine Tausenderpunkte. Feldtyp NK (oder leer). Das Modul ergänzt auf mindestens zwei Nachkommastellen (12 → 12.00, 12,5 → 12.50); mehr Nachkommastellen bleiben erhalten (12,345 → 12.345). Kein N2 – siehe 2.6.	12,50
  Currency	Währung	STRING	nein	ISO-4217-Code. Leer → Währung des Stufenschlüssels aus dem Stufenkatalog.	EUR

  2.4 Konditionsfelder der Artikelzeile – alle optional

  Jedes Konditionsfeld der Struktur wird verarbeitet. Leere Spalten lassen den Wert unbesetzt (ein Ja/Nein-Feld bleibt dann „nein“). Die Umsetzung richtet sich nach dem Dictionary-Typ:

  • NUMMER: Komma oder Punkt, keine Tausenderpunkte; das Modul ergänzt auf mindestens die angegebenen Nachkommastellen, mehr bleiben erhalten (wie beim Price). Feldtyp NK oder leer. Die Umsetzung ist unabhängig von der Spracheinstellung des Servers.

  • DATUM: Entweder internes Datum (Feldtyp D10 bei TT.MM.JJJJ, D9 bei JJJJ-MM-TT, D8R bei JJJJMMTT – HUSBIMP setzt um) oder ohne Feldtyp als Text JJJJ-MM-TT bzw. JJJJMMTT (das Modul setzt um). Anderes wird abgewiesen.

  • %JN (Ja/Nein): 1, J, Y oder X = ja; 0 oder N = nein; Groß-/Kleinschreibung egal. Ohne Feldtyp importieren (kein JNP-N). Anderes wird abgewiesen.

  • STRING: unverändert.

  Feldcode	Bezeichnung	Dictionary-Typ	Zielformat
  CustomerArticleNo	Kd-Artikelnr.	STRING	Text
  AltCustArticleNo	Alt. Kd-Artikelnr.	STRING	Text
  CustomerVariant	Kunden-Variante	STRING	Text
  Information	Information	STRING	Freitext
  DiscountPercent	Rabatt %	NUMMER, 2 NKS	Prozentwert 0–100
  Provision	Provision	NUMMER, 2 NKS	Zahl
  PricePer	Preis per	NUMMER, 0 NKS	Ganzzahl
  AdditionalCosts	Nebenkosten	NUMMER, 2 NKS	Betrag
  PriceUnit	Preiseinheit	STRING	Schlüssel aus ^PV("GB")
  CostCenter	Kostenstelle	STRING	Text
  RecommSalesPrice	Empf. VK-Preis	NUMMER, 2 NKS	Betrag
  Label	Etikett	STRING	Text
  ConditionVersion	Konditions-Version	STRING	Text (Version der Kondition, nicht die Stufen-Version)
  DiscountType	Rabattart	STRING	Schlüssel aus ^PV("RAB")
  DiscountAmount	Rabatt-Betrag	NUMMER, 2 NKS	Betrag
  NoPriceIncrease	Keine Preiserhöhung	%JN	1/J/Y/X oder 0/N
  FollowUpDate	Wiedervorlage	DATUM	internes Datum, JJJJ-MM-TT oder JJJJMMTT
  RevenueExclusion	Umsatzausschluss	%JN	1/J/Y/X oder 0/N
  FirstVpe	VPE	STRING	Schlüssel aus ^PV("VP")
  FirstVpeQuantity	VPE-Menge	NUMMER, 0 NKS	Ganzzahl
  GrossWeight	Gewicht brutto	NUMMER, 3 NKS	Zahl, mindestens 3 Nachkommastellen
  LoadAid	Ladehilfe	STRING	Schlüssel aus ^PV("ADV")
  LoadAidQuantity	Ladehilfe-Menge	NUMMER, 0 NKS	Ganzzahl
  OrderBlock	Ordersperre	%JN	1/J/Y/X oder 0/N
  OrderBlockQuantity	Ordersperre-Menge	NUMMER, 0 NKS	Ganzzahl
  OrderEntryMessage	Meldung Auftragserfassung	STRING	Text
  InShowroom	In Ausstellung	%JN	1/J/Y/X oder 0/N
  OneTimeDiscRecvd	Einmalrabatt erhalten	%JN	1/J/Y/X oder 0/N
  Gtin	GTIN	STRING	Text (führende Nullen, keine Exponentialschreibweise)
  DropShipment	Streckengeschäft	%JN	1/J/Y/X oder 0/N
  CustomerOeNumber	Kunden-OE-Nr.	STRING	Text
  CustWhseVpe	Kd-Lager VPE	STRING	Text
  CustWhseQuantity	Kd-Lager Menge	NUMMER, 0 NKS	Ganzzahl
  CustWhseWeight	Kd-Lager Gewicht	NUMMER, 3 NKS	Zahl, mindestens 3 Nachkommastellen

  Kopffelder kommen aus der Maske und werden nie importiert: Name (Bezeichnung), ConditionBasis (Konditionsbasis), ValidFrom (Gültig ab), State (Status), ScheduledFor (Geplante Aktivierung). Das Feld Staffel (STRING) dient nur dem Änderungsprotokoll; die Mengenstaffel wird über die Spaltengruppen in 2.5 importiert.

  2.5 Mengenstaffel – bis zu fünf Staffeln je Satz

  Die Datei ist flach (eine Zeile je Artikel), deshalb steht die Mengenstaffel als Spaltengruppen im Satz: je Staffel n (1 bis 5) vier Felder.

  Feldcode	Bezeichnung	Dictionary-Typ	Pflicht	Format / Regel
  Staffel<n>From	Staffel n ab Menge	NUMMER, 0 NKS	ja, sobald die Gruppe genutzt wird	Menge > 0, ab der die Staffel gilt. Je Artikel nur einmal dieselbe Menge.
  Staffel<n>Price	Staffel n Preis	NUMMER, 2 NKS	nein	Staffelpreis; Regeln wie Price (Komma/Punkt, mindestens 2 NKS, mehr bleiben). Übernimmt die Währung des Eintrags.
  Staffel<n>Discount	Staffel n Rabatt %	NUMMER, 2 NKS	nein	Prozentwert 0–100
  Staffel<n>Provision	Staffel n Provision	NUMMER, 2 NKS	nein	Zahl

  Beispiel: Staffel1From = 10, Staffel1Price = 11,90, Staffel1Discount = 5, Staffel2From = 50, Staffel2Price = 10,50.

  Regeln:

  • Eine Gruppe gilt als genutzt, sobald Staffel<n>From gefüllt ist. Leere Gruppen werden übersprungen – die Gruppen müssen nicht lückenlos belegt sein.

  • Preis, Rabatt und Provision einer Gruppe sind einzeln optional; eine Staffel darf z. B. nur einen Rabatt tragen.

  • Steht in einer Gruppe ein Preis, Rabatt oder eine Provision ohne ab Menge, wird der ganze Satz abgewiesen („Staffel 2: Preis, Rabatt oder Provision ohne ‚ab Menge‘.“). Es wird nichts stillschweigend verworfen.

  • Mehr als fünf Staffeln je Artikel sind über Weg A derzeit nicht möglich (Weg B kennt keine Grenze).

  2.6 Feldtyp in der Satzdefinition – was HUSBIMP mit dem Wert macht

  Der Dictionary-Typ (NUMMER / DATUM / %JN) steuert die Umsetzung des Moduls (2.4); der Feldtyp in der Satzdefinition steuert, was HUSBIMP vorher mit dem Rohwert macht:

  Feldtyp	Wirkung	Empfehlung für PRICETIER
  NK	numerisch mit Komma: Fremdzeichen entfernt, Komma → Punkt, Tausenderpunkte vor einem Komma entfernt, Vorzeichen erhalten, alle Nachkommastellen bleiben. Eine 0 wird zu leer.	Für alle Zahlenfelder (Preis, Staffelpreise, Rabatt, Provision, Mengen, Gewichte).
  (leer)	Wert unverändert übergeben. Für ein Dictionary-Feld vom Typ NUMMER setzt HUSBIMP in der Regel automatisch NK.	Für Text-, Adress-, Datums- (als JJJJ-MM-TT) und Ja/Nein-Felder. Für Zahlenfelder gleichwertig zu NK, das Modul setzt das Komma ebenfalls um.
  N2 (N0, N3 …)	numerisch mit impliziten Nachkommastellen	Nicht verwenden: Ein Wert ohne Dezimaltrennzeichen wird verschoben (12 → 0,12, 1250 → 12,50), und Nachkommastellen werden auf n begrenzt.
  D10, D9, D8R …	Datum (TT.MM.JJJJ, JJJJ-MM-TT, JJJJMMTT) → internes Datum	Für FollowUpDate, wenn die Datei TT.MM.JJJJ liefert (D10). Bei JJJJ-MM-TT oder JJJJMMTT geht es auch ohne Feldtyp.
  JNP-N	Ja/Nein: „N“ → 1, sonst leer	Nicht verwenden: Das Modul liest J/N bzw. 1/0 selbst.

  Fallstrick „Null wird leer“: Ein numerischer Wert 0 / 0,00 wird von HUSBIMP bei jedem N-Typ – auch NK – zu „“. Beim Price heißt das „Preis fehlt“, der Satz wird abgewiesen. Ein Preis von 0 ist über ein numerisch typisiertes Feld nicht importierbar.

  2.7 Fehlerverhalten

  Ein abgewiesener Satz landet mit Meldung im Importprotokoll (ERR-KFV), der Lauf geht weiter. Meldungen des Moduls:

  Meldung	Ursache
  „Stufenschlüssel und Version müssen im Importsatz gefüllt sein.“	Tier oder Version leer
  „Artikel-Nr und Preis müssen im Importsatz gefüllt sein.“	ArticleNumber oder Price leer (auch nach Umsetzung von 0 zu leer)
  „Keine Entwurfs-Version … zum Stufenschlüssel … gefunden.“	kein Entwurf zu Stufe + Version (Version aktiv, geplant oder nicht vorhanden)
  „Staffel n: Preis, Rabatt oder Provision ohne ‚ab Menge‘.“	Staffelgruppe mit Wert, aber ohne Staffel<n>From
  „<Feld>: Datum ‚…‘ nicht lesbar (erwartet JJJJ-MM-TT, JJJJMMTT oder internes Datum).“	Datumsfeld in anderem Format, z. B. 31.12.2026 ohne Feldtyp D10
  „<Feld>: Ja/Nein-Wert ‚…‘ nicht lesbar (erwartet 1/J/Y/X oder 0/N).“	Ja/Nein-Feld mit anderem Inhalt, z. B. WAHR
  „Feldkatalog: Feld … nennt die Eigenschaft …, die das Command nicht hat.“	Programmfehler im Feldkatalog des Moduls – bitte an die Entwicklung
  Money: amount is not numeric	Preis oder Staffelpreis nicht als Zahl lesbar (z. B. Tausenderpunkte ohne NK)
  Money: amount must not be negative	negativer Preis
  QuantityTier: fromQuantity must be positive	Staffel<n>From ≤ 0
  QuantityTier: discount out of range (0-100)	Staffelrabatt außerhalb 0–100
  PriceTierEntry: a quantity tier for this from-quantity already exists	zwei Staffelgruppen mit derselben Menge
  AddPriceTierEntry: article number not found	Artikel im Artikelmandanten unbekannt

  3. Weg B – Excel-Upload in der Maske (.xlsx)

  Auf einer Entwurfs-Version in 8.44.9 eine .xlsx-Datei hochladen. Der Entwurf ist der Zielsatz, Stufe und Version stehen nicht in der Datei.

  3.1 Aufbau der Datei

  • Gelesen wird das aktive Tabellenblatt.

  • Die Kopfzeile ist die erste Zeile, die eine Spalte Artikel-Nr, Artikel-Nr. oder Artikelnummer enthält. Zeilen davor werden ignoriert; Groß-/Kleinschreibung und Leerzeichen um die Überschrift spielen keine Rolle.

  • Zeilen mit leerer Artikel-Nr werden übersprungen.

  • Die Spaltenreihenfolge ist frei; unbekannte Spalten (z. B. Bezeichnung, Bild aus dem Export) werden ignoriert.

  • Eine exportierte Datei (Excel-Export der Preisstufe) kann unverändert wieder importiert werden.

  3.2 Spalten

  Spaltenüberschrift	Pflicht	Format / Regel
  Artikel-Nr (auch Artikel-Nr., Artikelnummer)	ja	Artikelnummer, Textzelle
  Preis	ja	Betrag ≥ 0; Komma oder Punkt
  Währung (auch Waehrung)	nein	ISO-Code; leer → EUR (anders als Weg A)
  Mengenstaffel	nein	mehrzeilige Zelle, siehe 3.3
  Kd-Artikelnr., Alt. Kd-Artikelnr., Kunden-Variante, Information, Preiseinheit, Kostenstelle, Etikett, Kond.-Version, Rabattart, 1. VPE, Ladehilfe, Meldung Auftragserf., GTIN, Kunden-OE-Nr., Kd-Lager VPE	nein	Text. Identifikatoren als Textzelle formatieren (führende Nullen; eine GTIN als Zahlzelle kommt sonst als 4.01234e+12 an).
  Rabatt %, Provision, Preis per, Nebenkosten, Empf. VK-Preis, Rabatt-Betrag, VPE-Menge, Gewicht brutto, Ladehilfe-Menge, Ordersperre-Menge, Kd-Lager Menge, Kd-Lager Gewicht	nein	Zahl. Excel-Zahlzellen kommen als Zahl an; Textzellen brauchen den Dezimalpunkt (nur beim Preis wird ein Komma umgesetzt).
  Keine Preiserhöhung, Umsatzausschluss, Ordersperre, In Ausstellung, Einmalrabatt erh., Streckengeschäft	nein	1 / 0 (leer = nicht gesetzt). Keine WAHR/FALSCH-Zellen: Sie kommen als True/False an, und der Fehler fällt erst beim Speichern der ganzen Version auf. Dann bricht der gesamte Upload ab, nicht nur die Zeile.
  Wiedervorlage	nein	Datum als Text JJJJ-MM-TT (so schreibt es der Export, und so wird es sicher gelesen). Eine echte Excel-Datumszelle kommt als JJJJ-MM-TT 00:00:00 an; laut InterSystems-Doku ignoriert die Umsetzung ($zdateh, Format 3) den Zeitanteil, am System ist das aber nicht nachgestellt. Schlägt sie fehl, landet nur diese Zeile in failed.

  Die Spaltenüberschriften entsprechen exakt den Überschriften des Excel-Exports; drei davon sind Kurzformen (Kond.-Version, Meldung Auftragserf., Einmalrabatt erh.).

  3.3 Mengenstaffel

  Eine Zeile pro Staffel innerhalb der Zelle (Zeilenumbruch mit Alt+Enter):

  ab 10 => 11,90 / 5 % / 1,5


  ab 50 => 10,50 / % /

  Format je Zeile: ab <Menge> => <Preis> / <Rabatt> % / <Provision>. Menge > 0 ist Pflicht; Preis, Rabatt (0–100) und Provision dürfen leer bleiben. Zeilen ohne => werden übersprungen. Der Staffelpreis übernimmt die Währung des Eintrags.

  3.4 Ergebnis

  Rückmeldung imported (Anzahl) und failed (Zeile, Artikel, Grund). Gründe sind z. B. „Artikelnummer unbekannt“, „Preis fehlt“ oder der technische Ausnahmename.

  4. Die beiden Wege im Vergleich

  	Weg A – Datenimport 9.6	Weg B – Excel-Upload
  Zielsatz	Tier + Version im Satz	geöffneter Entwurf
  Feldumfang	alle Konditionsfelder + Mengenstaffel (bis zu 5 Staffeln als Spaltengruppen)	alle Konditionsfelder + Mengenstaffel (mehrzeilige Zelle, unbegrenzt)
  Währung leer	Währung des Stufenschlüssels	EUR
  Dezimalkomma	bei allen Zahlenfeldern umgesetzt; mindestens die Nachkommastellen des Feldes, mehr bleiben	nur beim Preis umgesetzt; Zahlzellen unkritisch
  Ja/Nein	1/J/Y/X bzw. 0/N	1/0
  Datum	internes Datum, JJJJ-MM-TT oder JJJJMMTT	JJJJ-MM-TT
  Fehlerprotokoll	Importprotokoll 9.6	Rückmeldung in der Maske