Jak działają profile mapowania

Profile mapowania to serce BizFlow NH. Definiują jak dane z SAP Business One przekształcane są na XML faktury KSeF (format FA wersja 3). Dzięki nim nie trzeba pisać kodu — cała logika transformacji jest konfigurowalna.

Anatomia profilu

Każdy profil mapowania składa się z trzech głównych elementów:

Profil mapowania
├── Źródła danych (Data Sources)
│   ├── invoice — dane główne faktury
│   ├── buyer — dane nabywcy
│   ├── lines — pozycje faktury (tablica)
│   └── ... (kolejne źródła)
├── Mapowania pól (Field Mappings)
│   ├── Faktura.Naglowek.KodFormularza → CONST("FA")
│   ├── Faktura.Fa.P_1 → TaxDate
│   ├── Faktura.Podmiot2.DaneIdentyfikacyjne.NIP → FederalTaxID
│   └── ... (wszystkie pola XML)
└── Mapowanie VAT (VAT Mappings)
    ├── "Dzw" → "23"
    ├── "E8" → "8"
    └── ... (kody VAT SAP → kategorie KSeF)

Jak działa przetwarzanie

1. Wykonanie źródeł danych

   System wykonuje źródła danych w kolejności sort_order. Każde źródło to zapytanie do SAP (OData przez Service Layer lub SQL bezpośrednio do bazy) z aliasem (np. invoice, buyer, lines).

   Późniejsze źródła mogą odwoływać się do wyników wcześniejszych przez placeholdery: {invoice.DocEntry}, {buyer.CardCode}.

2. Mapowanie pól

   Dla każdego pola XML w schemacie FA(3) system:

   • Znajduje odpowiednie mapowanie w profilu
   • Pobiera wartość ze źródła danych (np. invoice.TaxDate)
   • Stosuje łańcuch transformacji (np. TaxDate|TRIM|FORMAT_DATE)

3. Obsługa tablic

   Źródła danych oznaczone jako tablice (np. lines, vat_summary) generują powtarzające się elementy XML. Każdy wiersz wyniku tworzy osobny element FaWiersz lub P_13x.

4. Generowanie XML

   Przetworzone dane składane są w dokument XML zgodny ze schematem FA(3).

Edytor profilu

Edytor transformacji

Każde mapowanie pola można edytować w modalnym edytorze transformacji — wizualnym builderze z podglądem na żywo. Pozwala budować łańcuchy transformacji krok po kroku, widząc wynik na przykładowych danych.

Picker endpointów Service Layer

Przy definiowaniu źródeł danych typu ServiceLayer dostępny jest picker endpointów — przeglądarka/wyszukiwarka dostępnych endpointów OData w SAP Service Layer. Pozwala wybrać endpoint i pola bez konieczności pamiętania ścieżek API.

Walidacja XSD

Profil musi przejść walidację XSD przed aktywacją. System automatycznie sprawdza wygenerowany XML pod kątem zgodności ze schematem FA(3). Profil, który nie przechodzi walidacji, nie może być użyty do wysyłki faktur — można go używać tylko w trybie podglądu.

Ograniczenie typu dokumentu

Profil można ograniczyć do konkretnego typu dokumentu SAP (np. tylko OINV, tylko ODPI). Ograniczenie to jest walidowane przy próbie użycia profilu — system nie pozwoli zastosować profilu OINV do dokumentu ODPI.

Źródła danych — szczegóły

Każde źródło danych ma:

Pole	Opis	Przykład
alias	Identyfikator do odwoływania się w mapowaniach	invoice
type	Typ źródła	ServiceLayer, SqlMssql, SqlHana
query	Zapytanie OData lub SQL	Invoices({DocEntry})?$select=DocNum,DocDate
sort_order	Kolejność wykonania	1, 2, 3…
is_array	Czy wynik to tablica (wiele wierszy)	true / false

Placeholdery

W zapytaniach można używać placeholderów odwołujących się do wyników wcześniejszych źródeł:

// Źródło "invoice" (sort_order: 1) zwraca: CardCode = "C00001"
// Źródło "buyer" (sort_order: 2) może użyć:
BusinessPartners('{invoice.CardCode}')

Źródła tablicowe

Źródła z is_array: true zwracają wiele wierszy. Każdy wiersz generuje osobny element w XML:

• lines — wiele elementów Faktura.Fa.FaWiersz
• vat_summary — wiele elementów Faktura.Fa.P_13x

Mapowania pól — szczegóły

Każde mapowanie pola definiuje:

Pole	Opis	Przykład
xml_path	Ścieżka w XML FA(3)	Faktura.Fa.P_1
source_alias	Alias źródła danych	invoice
source_field	Pole ze źródła + transformacje	TaxDate|TRIM

Łańcuch transformacji

Transformacje łączy się znakiem | (pipe):

CardName|TRIM|UPPER

Oznacza: weź pole CardName, przytnij białe znaki (TRIM), zamień na wielkie litery (UPPER).

Pełna lista transformacji: Transformacje pól.

Podgląd na żywo

Dashboard oferuje podgląd na żywo generowanego XML:

1. Otwórz profil mapowania
2. Wpisz DocEntry istniejącej faktury z SAP
3. Kliknij Podgląd
4. System wykona wszystkie źródła danych i wygeneruje XML

To pozwala iteracyjnie dostrajać profil bez wysyłania faktur do KSeF.

Eksport i import

Profile można eksportować jako JSON i importować w innych instalacjach:

• Eksport: Profil — menu — Eksportuj JSON
• Import: Profile — Importuj — wybierz plik JSON

Ułatwia to standaryzację konfiguracji między klientami o podobnej strukturze SAP.

Profile per firma

Każdy profil jest przypisany do konkretnej firmy (SapConfig). Różne firmy mogą mieć różne profile, ponieważ:

• Struktury danych SAP mogą się różnić między firmami
• Kody VAT mogą być inne
• Wymagania dotyczące faktur mogą się różnić (np. faktury walutowe)