Codeunit 6401 E-Document PEPPOL Utility

E-Document Core, Microsoft.eServices.EDocument.Processing.Import

src/Apps/W1/EDocument/App/src/Processing/Import/StructureReceivedEDocument/EDocumentPEPPOLUtility.Codeunit.al420 lines, Copyright (c) Microsoft Corporation. MIT

// ------------------------------------------------------------------------------------------------// Copyright (c) Microsoft Corporation. All rights reserved.// Licensed under the MIT License. See License.txt in the project root for license information.// ------------------------------------------------------------------------------------------------namespace Microsoft.eServices.EDocument.Processing.Import;using Microsoft.eServices.EDocument;using Microsoft.eServices.EDocument.Processing.Import.Purchase;using Microsoft.Finance.GeneralLedger.Setup;using System.Text;using System.Utilities;/// <summary>/// Reusable PEPPOL BIS 3.0 extraction helpers for reading UBL XML into staging tables./// Contains generic UBL party, amounts, line, attachment, and currency logic/// shared across Invoice and CreditNote document types./// </summary>codeunit 6401 "E-Document PEPPOL Utility"{    Access = Public;    InherentEntitlements = X;    InherentPermissions = X;    #region Namespace Initialization    /// <summary>    /// Registers the standard PEPPOL BIS 3.0 UBL namespace prefixes on the namespace manager    /// so that subsequent XPath lookups can resolve cac, cbc, and document-type namespaces.    /// </summary>    /// <param name="XmlNamespaces">The namespace manager that receives the PEPPOL namespace prefixes.</param>    procedure InitializePEPPOL3Namespaces(var XmlNamespaces: XmlNamespaceManager)    var        CommonAggregateComponentsLbl: Label 'urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2';        CommonBasicComponentsLbl: Label 'urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2';        DocumentationLbl: Label 'urn:un:unece:uncefact:documentation:2';        QualifiedDatatypesLbl: Label 'urn:oasis:names:specification:ubl:schema:xsd:QualifiedDatatypes-2';        UnqualifiedDataTypesSchemaModuleLbl: Label 'urn:un:unece:uncefact:data:specification:UnqualifiedDataTypesSchemaModule:2';        DefaultInvoiceLbl: Label 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2';        DefaultCreditNoteLbl: Label 'urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2';    begin        XmlNamespaces.AddNamespace('cac', CommonAggregateComponentsLbl);        XmlNamespaces.AddNamespace('cbc', CommonBasicComponentsLbl);        XmlNamespaces.AddNamespace('ccts', DocumentationLbl);        XmlNamespaces.AddNamespace('qdt', QualifiedDatatypesLbl);        XmlNamespaces.AddNamespace('udt', UnqualifiedDataTypesSchemaModuleLbl);        XmlNamespaces.AddNamespace('inv', DefaultInvoiceLbl);        XmlNamespaces.AddNamespace('cre', DefaultCreditNoteLbl);    end;    #endregion Namespace Initialization    #region XML Value Extraction    /// <summary>    /// Reads the value at the specified XPath, resolving either an element's inner text or an attribute value.    /// </summary>    /// <param name="XMLDocument">The XML document to read from.</param>    /// <param name="XMLNamespaces">The namespace manager used to resolve the XPath expression.</param>    /// <param name="Path">The XPath to the node or attribute whose value should be read.</param>    /// <param name="Value">The extracted value when the node is found.</param>    /// <returns>True when the node was found and a value was extracted; otherwise false.</returns>    procedure TryGetStringValue(XMLDocument: XmlDocument; XMLNamespaces: XmlNamespaceManager; Path: Text; var Value: Text): Boolean    var        XMLNode: XmlNode;    begin        if not XMLDocument.SelectSingleNode(Path, XMLNamespaces, XMLNode) then            exit(false);        if XMLNode.IsXmlElement() then begin            Value := XMLNode.AsXmlElement().InnerText();            exit(true);        end;        if XMLNode.IsXmlAttribute() then begin            Value := XMLNode.AsXmlAttribute().Value();            exit(true);        end;        exit(false);    end;    /// <summary>    /// Reads the value at the specified XPath and copies it into the destination field, truncated to the target length.    /// </summary>    /// <param name="XMLDocument">The XML document to read from.</param>    /// <param name="XMLNamespaces">The namespace manager used to resolve the XPath expression.</param>    /// <param name="Path">The XPath to the node or attribute whose value should be copied.</param>    /// <param name="MaxLength">The maximum number of characters to copy into the destination field.</param>    /// <param name="Field">The destination field that receives the extracted text value.</param>    procedure SetStringValueInField(XMLDocument: XmlDocument; XMLNamespaces: XmlNamespaceManager; Path: Text; MaxLength: Integer; var Field: Text)    var        Value: Text;    begin        if not TryGetStringValue(XMLDocument, XMLNamespaces, Path, Value) then            exit;        Field := CopyStr(Value, 1, MaxLength);    end;    /// <summary>    /// Reads the value at the specified XPath and evaluates it into the destination decimal field when present.    /// </summary>    /// <param name="XMLDocument">The XML document to read from.</param>    /// <param name="XMLNamespaces">The namespace manager used to resolve the XPath expression.</param>    /// <param name="Path">The XPath to the element whose value should be evaluated.</param>    /// <param name="DecimalValue">The destination decimal field that receives the evaluated value.</param>    procedure SetNumberValueInField(XMLDocument: XmlDocument; XMLNamespaces: XmlNamespaceManager; Path: Text; var DecimalValue: Decimal)    var        XMLNode: XmlNode;    begin        if not XMLDocument.SelectSingleNode(Path, XMLNamespaces, XMLNode) then            exit;        if not XMLNode.IsXmlElement() then            exit;        if XMLNode.AsXmlElement().InnerText() <> '' then            Evaluate(DecimalValue, XMLNode.AsXmlElement().InnerText(), 9);    end;    /// <summary>    /// Reads the value at the specified XPath and evaluates it into the destination date field when present.    /// </summary>    /// <param name="XMLDocument">The XML document to read from.</param>    /// <param name="XMLNamespaces">The namespace manager used to resolve the XPath expression.</param>    /// <param name="Path">The XPath to the element whose value should be evaluated.</param>    /// <param name="DateValue">The destination date field that receives the evaluated value.</param>    procedure SetDateValueInField(XMLDocument: XmlDocument; XMLNamespaces: XmlNamespaceManager; Path: Text; var DateValue: Date)    var        XMLNode: XmlNode;    begin        if not XMLDocument.SelectSingleNode(Path, XMLNamespaces, XMLNode) then            exit;        if not XMLNode.IsXmlElement() then            exit;        if XMLNode.AsXmlElement().InnerText() <> '' then            Evaluate(DateValue, XMLNode.AsXmlElement().InnerText(), 9);    end;    /// <summary>    /// Reads the currency code at the specified XPath and copies it into the destination field when it differs from the local currency.    /// </summary>    /// <param name="XMLDocument">The XML document to read from.</param>    /// <param name="XMLNamespaces">The namespace manager used to resolve the XPath expression.</param>    /// <param name="Path">The XPath to the node or attribute whose value should be copied.</param>    /// <param name="MaxLength">The maximum number of characters to copy into the destination field.</param>    /// <param name="CurrencyCode">The destination currency code field that receives the extracted value when appropriate.</param>    procedure SetCurrencyValueInField(XMLDocument: XmlDocument; XMLNamespaces: XmlNamespaceManager; Path: Text; MaxLength: Integer; var CurrencyCode: Code[10])    var        Value: Text;    begin        if not TryGetStringValue(XMLDocument, XMLNamespaces, Path, Value) then            exit;        SetCurrencyIfForeign(CopyStr(Value, 1, MaxLength), CurrencyCode);    end;    /// <summary>    /// Returns the value of the node or attribute at the specified XPath, or an empty string when the node is missing.    /// </summary>    /// <param name="XMLDocument">The XML document to read from.</param>    /// <param name="XMLNamespaces">The namespace manager used to resolve the XPath expression.</param>    /// <param name="Path">The XPath to the node or attribute whose value should be returned.</param>    /// <returns>The node or attribute value, or an empty string if the XPath does not resolve to a value.</returns>    procedure GetNodeValue(XMLDocument: XmlDocument; XMLNamespaces: XmlNamespaceManager; Path: Text): Text    var        Value: Text;    begin        if TryGetStringValue(XMLDocument, XMLNamespaces, Path, Value) then            exit(Value);        exit('');    end;    #endregion XML Value Extraction    #region Header Field Extraction    /// <summary>    /// Extracts AccountingSupplierParty and PayeeParty fields from a UBL document.    /// Per PEPPOL BIS 3.0: PartyName is optional; RegistrationName is mandatory fallback.    /// PayeeParty, when present, overrides vendor name and VAT ID.    /// SchemeID 0088 on EndpointID = GLN.    /// </summary>    internal procedure PopulateSupplierInfo(PeppolXML: XmlDocument; XmlNamespaces: XmlNamespaceManager; RootPath: Text; var Header: Record "E-Document Purchase Header")    var        XmlNode: XmlNode;        Value: Text;    begin        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name', Value) then            Header."Vendor Company Name" := CopyStr(Value, 1, MaxStrLen(Header."Vendor Company Name"));        if Header."Vendor Company Name" = '' then            if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName', Value) then                Header."Vendor Company Name" := CopyStr(Value, 1, MaxStrLen(Header."Vendor Company Name"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:PayeeParty/cac:PartyName/cbc:Name', Value) then            Header."Vendor Company Name" := CopyStr(Value, 1, MaxStrLen(Header."Vendor Company Name"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:Name', Value) then            Header."Vendor Contact Name" := CopyStr(Value, 1, MaxStrLen(Header."Vendor Contact Name"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingSupplierParty/cac:Party/cac:PostalAddress/cbc:StreetName', Value) then            Header."Vendor Address" := CopyStr(Value, 1, MaxStrLen(Header."Vendor Address"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID', Value) then            Header."Vendor VAT Id" := CopyStr(Value, 1, MaxStrLen(Header."Vendor VAT Id"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:PayeeParty/cac:PartyLegalEntity/cbc:CompanyID', Value) then            Header."Vendor VAT Id" := CopyStr(Value, 1, MaxStrLen(Header."Vendor VAT Id"));        if PeppolXML.SelectSingleNode(RootPath + '/cac:AccountingSupplierParty/cac:Party/cbc:EndpointID/@schemeID', XmlNamespaces, XmlNode) then            if XmlNode.AsXmlAttribute().Value() = '0088' then                if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingSupplierParty/cac:Party/cbc:EndpointID', Value) then                    Header."Vendor GLN" := CopyStr(Value, 1, MaxStrLen(Header."Vendor GLN"));    end;    /// <summary>    /// Extracts AccountingCustomerParty fields from a UBL document.    /// Per PEPPOL BIS 3.0: PartyName is optional; RegistrationName is mandatory fallback.    /// SchemeID 0088 on EndpointID = GLN. Customer Company Id stores schemeID:value.    /// </summary>    internal procedure PopulateCustomerInfo(PeppolXML: XmlDocument; XmlNamespaces: XmlNamespaceManager; RootPath: Text; var Header: Record "E-Document Purchase Header")    var        XmlNode: XmlNode;        SchemeID: Text;        EndpointValue: Text;        Value: Text;    begin        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingCustomerParty/cac:Party/cac:PartyName/cbc:Name', Value) then            Header."Customer Company Name" := CopyStr(Value, 1, MaxStrLen(Header."Customer Company Name"));        if Header."Customer Company Name" = '' then            if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName', Value) then                Header."Customer Company Name" := CopyStr(Value, 1, MaxStrLen(Header."Customer Company Name"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID', Value) then            Header."Customer VAT Id" := CopyStr(Value, 1, MaxStrLen(Header."Customer VAT Id"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID', Value) then            Header."Customer VAT Id" := CopyStr(Value, 1, MaxStrLen(Header."Customer VAT Id"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingCustomerParty/cac:Party/cac:PostalAddress/cbc:StreetName', Value) then            Header."Customer Address" := CopyStr(Value, 1, MaxStrLen(Header."Customer Address"));        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cac:AccountingCustomerParty/cac:Party/cbc:EndpointID', EndpointValue) then begin            if PeppolXML.SelectSingleNode(RootPath + '/cac:AccountingCustomerParty/cac:Party/cbc:EndpointID/@schemeID', XmlNamespaces, XmlNode) then                SchemeID := XmlNode.AsXmlAttribute().Value();            if SchemeID = '0088' then                Header."Customer GLN" := CopyStr(EndpointValue, 1, MaxStrLen(Header."Customer GLN"));            Header."Customer Company Id" := CopyStr(SchemeID + ':' + EndpointValue, 1, MaxStrLen(Header."Customer Company Id"));        end;    end;    /// <summary>    /// Extracts LegalMonetaryTotal amounts, IssueDate, and DueDate from a UBL document.    /// DueDatePath is parameterized because Invoice uses /cbc:DueDate while    /// CreditNote uses /cac:PaymentMeans/cbc:PaymentDueDate.    /// </summary>    internal procedure PopulateAmountsAndDates(PeppolXML: XmlDocument; XmlNamespaces: XmlNamespaceManager; RootPath: Text; DueDatePath: Text; var Header: Record "E-Document Purchase Header")    begin        SetNumberValueInField(PeppolXML, XmlNamespaces, RootPath + '/cac:LegalMonetaryTotal/cbc:PayableAmount', Header.Total);        SetNumberValueInField(PeppolXML, XmlNamespaces, RootPath + '/cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount', Header."Sub Total");        SetNumberValueInField(PeppolXML, XmlNamespaces, RootPath + '/cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount', Header."Total Discount");        Header."Total VAT" := Header."Total" - Header."Sub Total" - Header."Total Discount";        SetDateValueInField(PeppolXML, XmlNamespaces, DueDatePath, Header."Due Date");        SetDateValueInField(PeppolXML, XmlNamespaces, RootPath + '/cbc:IssueDate', Header."Document Date");    end;    /// <summary>    /// Extracts DocumentCurrencyCode and applies the BC LCY-blank convention.    /// </summary>    internal procedure PopulateCurrency(PeppolXML: XmlDocument; XmlNamespaces: XmlNamespaceManager; RootPath: Text; var Header: Record "E-Document Purchase Header")    var        DocumentCurrencyCode: Text;    begin        if TryGetStringValue(PeppolXML, XmlNamespaces, RootPath + '/cbc:DocumentCurrencyCode', DocumentCurrencyCode) then            SetCurrencyIfForeign(DocumentCurrencyCode, Header."Currency Code");    end;    #endregion Header Field Extraction    #region Line Field Extraction    /// <summary>    /// Populates a staging line record from a UBL InvoiceLine or CreditNoteLine element.    /// LineElementName and QuantityElementName are parameterized to handle both document types.    /// </summary>    internal procedure PopulatePurchaseLine(LineXML: XmlDocument; XmlNamespaces: XmlNamespaceManager; var Line: Record "E-Document Purchase Line"; LineElementName: Text; QuantityElementName: Text)    var        Value: Text;    begin        SetNumberValueInField(LineXML, XmlNamespaces, LineElementName + '/' + QuantityElementName, Line.Quantity);        if TryGetStringValue(LineXML, XmlNamespaces, LineElementName + '/' + QuantityElementName + '/@unitCode', Value) then            Line."Unit of Measure" := CopyStr(Value, 1, MaxStrLen(Line."Unit of Measure"));        SetNumberValueInField(LineXML, XmlNamespaces, LineElementName + '/cbc:LineExtensionAmount', Line."Sub Total");        SetNumberValueInField(LineXML, XmlNamespaces, LineElementName + '/cac:AllowanceCharge/cbc:Amount', Line."Total Discount");        // Per PEPPOL BIS 3.0: Item Name (1..1, mandatory) is the primary short product description.        // Item Description (0..1) is an optional longer description that may exceed field capacity.        // Priority: Name (always present per spec), fallback to Description if Name is absent.        if TryGetStringValue(LineXML, XmlNamespaces, LineElementName + '/cac:Item/cbc:Name', Value) then            Line.Description := CopyStr(Value, 1, MaxStrLen(Line.Description));        if Line.Description = '' then            if TryGetStringValue(LineXML, XmlNamespaces, LineElementName + '/cac:Item/cbc:Description', Value) then                Line.Description := CopyStr(Value, 1, MaxStrLen(Line.Description));        // Per PEPPOL BIS 3.0: SellersItemIdentification is the seller's internal product code.        // StandardItemIdentification is a registered standard (e.g., GTIN via schemeID 0160).        // StandardItemIdentification takes priority as the more universally recognized identifier.        if TryGetStringValue(LineXML, XmlNamespaces, LineElementName + '/cac:Item/cac:SellersItemIdentification/cbc:ID', Value) then            if Value <> '' then                Line."Product Code" := CopyStr(Value, 1, MaxStrLen(Line."Product Code"));        if TryGetStringValue(LineXML, XmlNamespaces, LineElementName + '/cac:Item/cac:StandardItemIdentification/cbc:ID', Value) then            if Value <> '' then                Line."Product Code" := CopyStr(Value, 1, MaxStrLen(Line."Product Code"));        SetNumberValueInField(LineXML, XmlNamespaces, LineElementName + '/cac:Item/cac:ClassifiedTaxCategory/cbc:Percent', Line."VAT Rate");        SetNumberValueInField(LineXML, XmlNamespaces, LineElementName + '/cac:Price/cbc:PriceAmount', Line."Unit Price");        PopulateLineCurrency(LineXML, XmlNamespaces, Line, LineElementName);    end;    local procedure PopulateLineCurrency(LineXML: XmlDocument; XmlNamespaces: XmlNamespaceManager; var Line: Record "E-Document Purchase Line"; LineElementName: Text)    var        LineCurrencyCode: Text;    begin        if TryGetStringValue(LineXML, XmlNamespaces, LineElementName + '/cbc:LineExtensionAmount/@currencyID', LineCurrencyCode) then            SetCurrencyIfForeign(LineCurrencyCode, Line."Currency Code");    end;    #endregion Line Field Extraction    #region Attachment Extraction    /// <summary>    /// Extracts a single embedded base64 attachment from an AdditionalDocumentReference element.    /// Skips external URI references and bare references without embedded content.    /// Per PEPPOL BIS 3.0: @filename and @mimeCode are mandatory on EmbeddedDocumentBinaryObject.    /// </summary>    internal procedure ExtractAttachment(EDocument: Record "E-Document"; AttachmentXML: XmlDocument; XmlNamespaces: XmlNamespaceManager)    var        EDocAttachmentProcessor: Codeunit "E-Doc. Attachment Processor";        Base64Convert: Codeunit "Base64 Convert";        AttachmentBlob: Codeunit "Temp Blob";        InStream: InStream;        OutStream: OutStream;        Base64Content: Text;        FileName: Text;        MimeCode: Text;        FileExtension: Text;        ElementName: Text;    begin        ElementName := 'cac:AdditionalDocumentReference';        if not TryGetStringValue(AttachmentXML, XmlNamespaces, ElementName + '/cac:Attachment/cbc:EmbeddedDocumentBinaryObject', Base64Content) then            exit;        if Base64Content = '' then            exit;        if not TryGetStringValue(AttachmentXML, XmlNamespaces, ElementName + '/cac:Attachment/cbc:EmbeddedDocumentBinaryObject/@filename', FileName) then            TryGetStringValue(AttachmentXML, XmlNamespaces, ElementName + '/cbc:ID', FileName);        if FileName = '' then            exit;        if not FileName.Contains('.') then            if TryGetStringValue(AttachmentXML, XmlNamespaces, ElementName + '/cac:Attachment/cbc:EmbeddedDocumentBinaryObject/@mimeCode', MimeCode) then begin                FileExtension := MimeToFileExtension(MimeCode);                if FileExtension <> '' then                    FileName := FileName + '.' + FileExtension;            end;        AttachmentBlob.CreateOutStream(OutStream);        Base64Convert.FromBase64(Base64Content, OutStream);        AttachmentBlob.CreateInStream(InStream);        EDocAttachmentProcessor.Insert(EDocument, InStream, FileName);    end;    local procedure MimeToFileExtension(MimeCode: Text): Text    begin        case MimeCode of            'image/jpeg':                exit('jpeg');            'image/png':                exit('png');            'application/pdf':                exit('pdf');            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':                exit('xlsx');            'application/vnd.oasis.opendocument.spreadsheet':                exit('ods');            'text/csv':                exit('csv');            else                exit('');        end;    end;    #endregion Attachment Extraction    #region Currency    /// <summary>    /// BC convention: blank Currency Code means LCY. Sets the field to the currency code    /// only if it differs from LCY. Explicitly blanks the field when it matches LCY.    /// </summary>    procedure SetCurrencyIfForeign(CurrencyFromXml: Text; var CurrencyCode: Code[10])    var        GLSetup: Record "General Ledger Setup";    begin        if CurrencyFromXml = '' then            exit;        GLSetup.GetRecordOnce();        if GLSetup."LCY Code" = CopyStr(CurrencyFromXml, 1, MaxStrLen(CurrencyCode)) then            CurrencyCode := ''        else            CurrencyCode := CopyStr(CurrencyFromXml, 1, MaxStrLen(CurrencyCode));    end;    #endregion Currency}