Pola własne w enova365 — zmiana schematu, o której nikt Wam nie powie

Administrator enova365 dodaje pole do kartoteki kontrahenta w jakieś pięć minut. Bez zgłoszenia, bez wdrożenia, bez niczyjej zgody i bez najmniejszego sprzeciwu ze strony systemu. Od środka enova365 to ledwie zdarzenie.

Dla każdej integracji, która te dane czyta, te same pięć minut to zmiana schematu.

Na tej asymetrii stoi cała historia pól własnych w projektach z enova365. Prawie każda awaria, do której mnie wołano, sprowadza się do niej — i nigdy nie jest to awaria głośna. Zawsze cicha. Taka, w której dane są błędne od marca, a wychodzi to w czerwcu.

„Pola własne" to nazwa na trzy różne rzeczy

Pierwszy praktyczny problem to słownictwo. Zapytajcie klienta, czy ma pola własne — usłyszycie „tak". I to jedno „tak" obejmuje co najmniej trzy niepowiązane ze sobą mechanizmy.

Cechy. Droga bez kodu. Administrator definiuje je z poziomu interfejsu, podpina pod typ obiektu — kontrahenta, towar, typ dokumentu — i wybiera typ danych: tekst, liczba, data, wartość logiczna, lista słownikowa, powiązanie z innym obiektem. Wartości siedzą w strukturze ogólnej, a nie w kolumnie na tabeli samego obiektu. Z tego mechanizmu biura korzystają najczęściej, bo nie potrzebuje nikogo technicznego.

Pola dodane przez Konfigurator. Nadal bez kodu, ale narzędzie jest cięższe, a zakres tego, co wolno w nim zmieniać, zależy od poziomu licencji. Nie bierzcie mapy poziomów ode mnie ani z żadnego innego wpisu na blogu — otwórzcie własną licencję i sprawdźcie, co Wam przysługuje. Widziałem zakres napisany wokół mechanizmu, którego klient po prostu nie miał, i to nie jest rozmowa, którą chcecie odbywać w trzecim tygodniu projektu.

Pola wkompilowane przez dodatek. Branżowe dodatki budowane na SDK dokładają obiektom biznesowym prawdziwe, otypowane właściwości. Pod każdym względem zachowują się jak pola natywne. Wygodnie — dokładnie do momentu aktualizacji dodatku, po której właściwość zmienia kształt.

Po stronie API cała trójka zachowuje się inaczej, więc „mamy pola własne" nie jest odpowiedzią, na której da się oprzeć wycenę. Musicie wiedzieć, które z trzech, na jakim obiekcie, z jakiego dodatku i w jakiej wersji. Cztery pytania — klient zwykle odpowiada na wszystkie w jednym mailu.

Co przychodzi przez WebAPI, a co po cichu nie

Pola, które dodatek wkompilował w obiekt biznesowy, przychodzą przez kontrolery dynamiczne jak wszystko inne. Nic specjalnego do zrobienia.

Zaskakują cechy. To nie są właściwości obiektu, tylko kolekcja par definicja-wartość podpięta pod obiekt. Klient, który czyta płaską listę właściwości, dostaje odpowiedź całkowicie poprawną: bez błędu, bez ostrzeżenia i bez cech w środku. Ogólna mechanika kontrolerów dynamicznych, licencji i obsługi JWT jest w przewodniku po WebAPI; akurat tę jej część odkrywa się na końcu, zwykle już na produkcji.

Jest jeszcze efekt drugiego rzędu i bywa gorszy od samego problemu. Cecha typu tekst pomieści wszystko, co ktokolwiek w nią wpisał. Widziałem jedno pole „data podpisania umowy" z wartościami 15.03.2026, 2026-03-15, marzec 2026 i podpisana — cztery różne rzeczy w jednym polu i cztery poprawne teksty. Definicja mówiła „tekst", więc żadna walidacja nigdy się nie uruchomiła. Nikomu w biurze przez lata to nie przeszkadzało. Wasz parser jest pierwszym elementem łańcucha, któremu na tym zależy — czyli pierwszym, który się wywróci.

Inwentaryzacja i jedyna kolumna, która ma znaczenie

Zanim cokolwiek wycenicie, weźcie od administratora trzy rzeczy. Przygotowanie zajmie mu niecałą godzinę:

1. Definicje pól własnych w podziale na typy obiektów, z typem każdego pola.
2. Zainstalowane dodatki z numerami wersji.
3. Liczbę wypełnień każdego pola z ostatnich dwunastu miesięcy i liczbę wartości unikalnych.

Tej trzeciej nikt nie proponuje z siebie, a to właśnie ona rozstrzyga o zakresie. W instalacjach, które otwierałem, kartoteka kontrahenta i towaru niosą razem mniej więcej trzydzieści do pięćdziesięciu zdefiniowanych cech, a sensowne wypełnienie ma z tego niecały tuzin. Reszta to archeologia: czyjś pomysł z 2019 roku, pozostałość po migracji, pole założone pod akcję, która odbyła się raz.

Posortujcie każde pole do trzech kubełków i każdy potraktujcie inaczej:

Martwe. Wypełnienie bliskie zeru. Nie mapujcie, nie testujcie, nie wpuszczajcie do wyceny. I napiszcie to klientowi na piśmie, bo długość listy pól czyta się po jego stronie jako wielkość roboty — a tę rozmowę chcecie mieć udokumentowaną, zanim ktokolwiek zacznie porównywać Waszą liczbę z cudzą.

Prawdziwe. Wysokie wypełnienie, mało wartości unikalnych. To kategoria, na której firma faktycznie działa: segment, poziom obsługi, przypisany opiekun. Mapujcie i przypinajcie do identyfikatorów, nie do tekstu.

Bagno tekstowe. Wysokie wypełnienie, wartości unikalnych prawie tyle co rekordów. To pole na notatki, które po cichu urosło do procesu biznesowego. Na wsad dla integracji się nie nadaje. Co najwyżej na wsad dla modelu, który coś z niego wyciągnie — czyli osobny projekt z osobną rozmową o skuteczności, a nie pozycja w tabelce mapowania.

To sortowanie zajmuje popołudnie i rutynowo zbija o połowę liczbę pól, o które ktokolwiek się spiera.

Mapujcie po ID. Zawsze.

Przemianowanie pola albo pozycji słownika w enova365 to zabieg kosmetyczny. Nic się nie psuje. Raporty dalej działają, użytkownicy widzą czytelniejszą etykietę, wszyscy wracają do swoich spraw.

Jedyne, czemu na tej nazwie zależało, to Wasza integracja — i nikt nie wiedział, że ma Was uprzedzić.

Czyli: dopasowujcie po identyfikatorze definicji, nazwę trzymajcie wyłącznie do wyświetlania, a jej zmianę traktujcie jako wpis w logu, nie jako błąd. Ta sama zasada piętro niżej: dla cechy słownikowej zapisujcie ID pozycji, nigdy jej treść. To dokładnie ta dyscyplina decyduje, czy definicja formatu bankowego wystawia podpola widoczne dla mechanizmu dopasowania, czy oddaje Wam jeden nierozróżnialny blok tekstu opisu. Struktura, która istnieje, ale nikt jej nie adresuje, to struktura, której nie macie.

„Nie ma" i „puste" to nie to samo

Tu zaczyna się awaria, która kosztuje najwięcej i która na żadnym etapie nie zapala żadnej lampki.

Pole znika z komunikatu: przemianowane, przetypowane, przesunięte przez aktualizację dodatku albo po prostu przestało być wystawiane przez kontroler. Dalej w łańcuchu kod czyta nieobecny klucz i zapisuje null. Czyli dokładnie to samo, co zapisuje, kiedy pole jest obecne i faktycznie puste. Oba stany zlewają się w jeden, nie do odróżnienia, i od tej chwili system raportuje „niewypełnione" dla pola, którego w ogóle nie da się już odczytać.

A nikt nie drąży niskiego wypełnienia. Na tym polega pułapka.

Poprawka jest drobna, tylko trzeba się na nią zdecydować wcześnie: na granicy systemu odróżniajcie brak w schemacie od obecne i puste, a to pierwsze zgłaszajcie głośno. Pole niezmapowane albo zniknięte idzie do logu razem ze swoją nazwą. Nigdy do null i nigdy po cichu do kosza — to ta sama zasada, na której stoją nocne kontrole tylko do odczytu z wpisu o KSeF i JPK: sensem zadania jest zauważyć, nie naprawić.

Skoro już tam jesteście, dołóżcie alarm dryfu. Odczytajcie listę definicji pól własnych na obiektach, których dotykacie, policzcie z niej skrót, porównajcie z wczorajszym. Jedno zapytanie, w zadaniu, które i tak pewnie już chodzi w nocy z innych powodów. Kiedy skrót się ruszy, ktoś dostaje wiadomość z nazwą pola. To różnica między dowiedzeniem się o nowym polu w dniu jego powstania a dowiedzeniem się kwartał później, od klienta, na spotkaniu o liczbach, które się nie zgadzają. Jak takie rzeczy układają się w całość po stronie usług, pokazuję tutaj: integracja enova365 z AI.

O co zapytać dostawcę, jeśli jesteście po stronie kupującej

Test mieści się w jednym pytaniu, w tym samym duchu, co pytanie dostawcę, kiedy potrzebuje dostępów: zapytajcie, co robi z polem własnym dodanym po uruchomieniu.

„Dopiszemy je do mapowania" oznacza fakturę przy każdej zmianie w Waszej firmie. Oznacza też, że pola nie będzie w danych tak długo, aż ktoś przypadkiem zauważy.

„Lista definicji jest czytana co noc, pola niezmapowane trafiają do logu zamiast wypadać, a przy zmianie schematu dostajecie wiadomość" oznacza, że ktoś już przez to przechodził.

Druga odpowiedź kosztuje w budowie prawie nic. To znacznik doświadczenia, nie budżetu — i właśnie dlatego pytanie działa. Takiej odpowiedzi nie da się dokupić w trakcie rozmowy.

Wersja w jednym zdaniu

Pole własne to zmiana schematu wykonana przez kogoś, kto nie ma obowiązku Was o niej uprzedzać, a Wasza integracja jest jedyną stroną, która ją kiedykolwiek zauważy. Zaprojektujcie system pod to założenie, a takie projekty stają się zwyczajne. Załóżcie, że lista pól jest stabilna, a spędzicie kwartał na tłumaczeniu liczby, której nikt nie umie uzgodnić.

Nie wiecie, co właściwie siedzi na Waszych kartotekach kontrahenta i towaru? Napiszcie do mnie — przyślijcie listę definicji z liczbą wypełnień, a powiem Wam, które pola to prawdziwa robota, a które archeologia. Zanim ktokolwiek napisze wycenę. Pół godziny, bez opłat.