Positions-Matching (RMB)

Das Positions-Matching-Gadget vergleicht die Rechnungspositionen mit den Bestellpositionen aus der Datenbank. Welche Felder dabei geladen und verglichen werden sowie welche Spalten das Gadget anzeigt, ist konfigurierbar.

Felder konfigurieren

Die zu vergleichenden Felder und die Felder für fehlende Bestellpositionen werden über die Eigenschaft positionMatching im Skript ou.cust.ptpINV.settings gesteuert.

Bekannte Felder

Standard-Felder, die in der Liste orderItemSelectFields im Skript ou.sp.ptpINV.lib.rmb.orderItems bereits definiert sind, werden einfach als String angegeben:

const settings = {
    // ...
    positionMatching: {
        compareFields: [
            "itemOrderNumber",       // Pflichtfeld
            "itemOrderItemNumber",   // Pflichtfeld
            "itemArticleNumber",
            "itemArticleName",
            "itemOrderQuantity",
            "itemOrderQuantityUnit",
            "itemOrderSingleAmount",
            "itemPriceUnit",
            "itemVatRate",
            "itemCostCenter",        // zusätzliches Feld
        ],
    },
    // ...
};

itemOrderNumber und itemOrderItemNumber sind Pflichtfelder – fehlen sie, wird beim Matching ein Fehler geworfen.

Eigene Datenbankfelder

Felder, die nicht standardmäßig definiert sind, werden als Objekt mit name (DB-Spaltenname), type und optionalem alias übergeben:

positionMatching: {
    compareFields: [
        "itemOrderNumber",
        "itemOrderItemNumber",
        // ...
        { name: "customColumn", type: "string", alias: "itemCustomColumn" },
    ],
},

Felder für fehlende Bestellpositionen

Analog steuert orderItemFields, welche Felder beim Laden fehlender Bestellpositionen aus der Datenbank abgerufen und als neue Rechnungspositionen übernommen werden:

positionMatching: {
    orderItemFields: [
        "itemOrderNumber",       // Pflichtfeld
        "itemOrderItemNumber",   // Pflichtfeld
        "itemArticleNumber",
        "itemArticleName",
        "itemOrderQuantity",
        "itemOrderQuantityUnit",
        "itemOrderSingleAmount",
        "itemVatRate",
        "itemVatCode",
        "itemPriceUnit",
        "itemCostCenter",
        "itemCostUnit",
        "itemImpersonalAccount",
        { name: "customColumn", type: "string", alias: "itemCustomColumn" },
    ],
},

Spalten im Gadget anzeigen

Das Konfigurieren eines Feldes in compareFields macht es vergleichbar, zeigt es aber noch nicht im Gadget an. Die Spalten des Gadgets werden über den Callback renderPositionMatcher before im Skript ou.cust.ptpINV.callbacks.dataExtraction gesteuert:

const renderPositionMatcherBefore = (data: {
    docFile: ptpInvoice;
    columns: Record<string, MultiTableColumn>;
    selection: Record<number, boolean>;
}): otris.gadget.gui.HTML | void => {
    data.columns["itemCostCenter"] = {
        label: "de:Kostenstelle;en:Cost center",
        tooltip: "de:Kostenstelle;en:Cost center",
        width: "150px",
    };
};

Bestelldaten auffüllen konfigurieren

Wenn Rechnungspositionen mit Bestelldaten aus der Datenbank angereichert werden – sowohl nach dem Positions-Matching als auch beim Import aus Dexpro –, sind die dabei kopierten Felder über fillOrderDataFields im Skript ou.cust.ptpINV.settings konfigurierbar. Wird die Eigenschaft gesetzt, ersetzt sie die Standard-Felder vollständig:

Standard-Feld (Quelle)	Zielfeld
`deliveryNoteNumber`	`itemDeliveryNoteNumber`
`quantityDelivered`	`itemQuantityDelivered`
`quantityUnitDelivered`	`itemQuantityUnitDelivered`
`receiptNumber`	`itemReceiptNumber`
`receiptRequired`	`itemReceiptRequired`

Jeder Eintrag kann zusätzlich shouldOverwriteExistingValues: true erhalten, um den Zielwert auch dann zu überschreiben, wenn er bereits gesetzt ist (Standard: false).

const settings = {
    // ...
    fillOrderDataFields: [
        { sourceField: "deliveryNoteNumber", targetField: "itemDeliveryNoteNumber" },
        { sourceField: "quantityDelivered", targetField: "itemQuantityDelivered" },
        { sourceField: "quantityUnitDelivered", targetField: "itemQuantityUnitDelivered" },
        { sourceField: "receiptNumber", targetField: "itemReceiptNumber" },
        { sourceField: "receiptRequired", targetField: "itemReceiptRequired" },
        // Artikelnummer immer überschreiben
        { sourceField: "articleNumber", targetField: "itemArticleNumber", shouldOverwriteExistingValues: true },
    ],
    // ...
};

Logik nach dem Speichern erweitern

Über die Callbacks saveMatchedPositions before und saveMatchedPositions after im Skript ou.cust.ptpINV.callbacks.dataExtraction kann die Logik nach dem Schließen des Gadgets erweitert werden. Der before-Callback erhält die ausgewählten Positionen vor dem Speichern — gibt er einen String zurück, wird die Aktion abgebrochen und der String als Fehlermeldung angezeigt. Der after-Callback wird nach erfolgreichem Speichern aufgerufen und eignet sich für Folgeaktionen.