Sfera w Subiekcie nexo: przewodnik programisty i co się zmienia po GT

Pytanie, od którego zaczyna się każdy projekt na nexo

Przewodnik po Sferze dla Subiekta GT napisałem kilka tygodni temu i nie pada w nim ani razu słowo nexo. Błąd, który spłacam od tamtej pory w rozmowach telefonicznych. Każdy, kto siedzi na nowszej linii InsERT-u, zaczyna od jakiejś wersji tego samego zdania: u nas też jest Sfera, czyli integracja wygląda tak samo, prawda?

Nie wygląda. Nazwa się przenosi, prawie nic pod nią — nie. Sfera w Subiekcie GT i Sfera w Subiekcie nexo to dwie różne technologie, sprzedawane na dwa różne sposoby, które pierwszego dnia psują się z dwóch zupełnie innych powodów.

To jest nexowa połowa tamtego przewodnika. Stoi obok przewodnika po API Optimy, przewodnika po WebAPI enova365 i porównania trzech systemów dla integratorów. Jak we wszystkich tamtych: każde twierdzenie techniczne poniżej pochodzi z materiałów samego InsERT-u albo z kodu, który możecie przeczytać sami. W tym kawałku rynku wymyślona nazwa biblioteki kosztuje kogoś dzień pracy.

„Sfera" to trzy produkty, nie jeden

Zacznijmy tutaj, bo pomyłka w tym miejscu nie jest błędem technicznym, tylko handlowym.

Sfera dla Subiekta GT to dodatek. Macie Subiekta GT, dokupujecie Sferę osobno, dostajecie dostęp COM do działającej aplikacji. Około tysiąca złotych netto za pierwsze stanowisko według opublikowanego cennika InsERT-u, więcej za każde kolejne.

Sfera dla Subiekta nexo w ogóle nie jest tak sprzedawana. Jest funkcją Subiekta nexo PRO — InsERT wymienia ją wśród możliwości wersji PRO obok zaawansowanych pól własnych i własnych raportów. Nie istnieje wersja standardowego Subiekta nexo ze Sferą ani dodatek, który by ją tam dołożył.

Sfera PRO+ to trzecia rzecz i to ją najczęściej myli się z drugą. Warstwa zdarzeniowa — Sfera zdarzeniowa, dzięki której Wasz kod uruchamia się w reakcji na to, co użytkownik robi w programie: zablokowanie pola, odrzucenie zapisu, reakcja na zmianę wartości, zablokowanie usunięcia towaru. Do tego menu sferyczne, które wstawia Wasze własne operacje w menu samego programu. InsERT opisuje jedenaście głównych zdarzeń i trzynaście kolejnych, specyficznych dla Subiekta. Mieszka to wyłącznie w nexo PRO+, czyli w najwyższej wersji.

I teraz konsekwencja, dla której ta sekcja stoi na początku.

W GT zdobycie API to zakup: jedna pozycja, decyzja działu IT, podpisana przez tego, kto podpisuje oprogramowanie. W nexo zdobycie API to podniesienie wersji całej instalacji, wyceniane per stanowisko. Firma z dziesięcioma stanowiskami nie kupuje jednej licencji, żeby odblokować integrację — przenosi dziesięć stanowisk wyżej. A jeśli okaże się, że wymaganie potrzebuje haczyków zdarzeniowych, a nie zewnętrznego procesu, przenosi je o dwa poziomy.

Inna rozmowa, inna osoba przy stole. Ustalcie wersję klienta w pierwszej rozmowie, nie w czwartej. Widziałem, jak całkiem rozsądna dwutygodniowa integracja umarła dlatego, że odpowiedź licencyjna przyszła po wycenie — a wycena nagle okazała się mniejszą liczbą na kartce.

Model połączenia jest odwrócony

W GT architektura brzmi: steruj aplikacją. Tworzycie obiekt COM o ProgID InsERT.GT, podajecie mu dwa komplety danych logowania, wołacie Uruchom z trybem uruchomienia i od tej chwili integracja jest przywiązana do żywego procesu subiekt.exe. Tryb 4 chowa okno. Nic nie chowa zależności: jeśli ten proces się skończy, uchwyt do obiektu jest martwy i sam się nie odbuduje.

W nexo architektura brzmi: załaduj logikę biznesową. Dodajecie referencje do własnych bibliotek .NET InsERT-u — InsERT.Moria.API.dll, InsERT.Moria.ModelDanych.dll, InsERT.Moria.Sfera.dll, InsERT.Moria.BibliotekaDokumentow.dll, InsERT.Mox.Core.dll i kilku sąsiadów — wskazujecie serwer i podmiot, logujecie się i pracujecie na modelu obiektowym we własnym procesie. Bez okna. Bez aplikacji, do której trzeba się podłączyć. Bez serwera RPC, który może zniknąć w nocy.

Jeśli przychodzicie z GT, to usuwa Wam najlepiej znaną awarię. Usługa, która chodziła spokojnie przez sześć tygodni i ucichła, bo ktoś zamknął okno, nie jest problemem nexo.

Zastępuje ją subtelniejszy.

Referencje wskazują na instalację klienta, nie na paczkę

Nie ma tu kanału NuGet. Biblioteki, do których się odwołujecie, to te leżące w katalogu instalacyjnym Subiekta nexo na tamtej maszynie — bezwzględna ścieżka do binariów podmiotu. Wynik Waszej kompilacji jest związany z tą wersją nexo, która była zainstalowana w chwili budowania.

InsERT daje na to szablony. Od wersji 40.0.0 SDK istnieje rozszerzenie do Visual Studio (nexoSDKSzablony_VS2019.vsix) z szablonami projektu konsolowego i WPF, które same przygotowują inicjalizację Sfery. Wskazówka co do platformy docelowej jest jednoznaczna: .NET Framework 4.6.1, wybrany dla zgodności z wersją Entity Framework, której używa samo nexo.

Oba fakty bierzcie dosłownie. Swobody wyboru środowiska uruchomieniowego tu nie ma — ładujecie cudzy graf obiektów do własnego procesu.

Dlatego pierwszą awarią na nexo jest błąd ładowania zestawu. Klasyk to płaska odmowa załadowania InsERT.Moria.Sfera — komunikat, który nie mówi nic o wersjach, nic o aktualizacji i kieruje prosto do konfiguracji Waszego projektu, gdzie problemu zwykle nie ma.

Porównajcie z odpowiednikiem w GT: projekt .NET zbudowany jako AnyCPU na maszynie 64-bitowej rzuca Klasa niezarejestrowana na obiekcie COM zarejestrowanym całkiem poprawnie, tylko nie dla procesu 64-bitowego. Inna platforma, inny komunikat, identyczna lekcja. Na obu liniach InsERT-u pierwszy komunikat błędu wskazuje gdzie indziej niż przyczyna i na obu kosztuje pół dnia tych, którzy jeszcze go nie widzieli.

Wynikają z tego trzy zasady i wszystkie są tanie do wprowadzenia:

Przypnijcie wersję, względem której budujecie — na piśmie, we wdrożeniu. Nie w czyjejś pamięci.

Traktujcie aktualizację nexo u klienta jak ponowne wdrożenie własnego komponentu. Nie jak zdarzenie, które dzieje się ERP-owi i może Was dotyczyć. Aktualizacja to wdrożenie; okno planujcie wspólnie. To ta sama dyscyplina, o którą upominałem się przy nocnych zadaniach, których nikt nie pilnuje, i z tego samego powodu: po cichu psuje się to, czego nikomu nie przypisano.

Zapisujcie wersje załadowanych zestawów i wersję podmiotu przy każdym starcie. Jedna linia w logu i rozjazd wersji zgłasza się z nazwiskiem, zamiast przychodzić jako stos wywołań, którego nikt nie potrafi datować.

Znowu pytanie o konto serwisowe

Połączenie przez Sferę w nexo uwierzytelnia się jako użytkownik nexo, skonfigurowany do tego celu — po to jest ekran konfiguracji Sfery. Uprawnienia tego użytkownika to uprawnienia Waszej integracji.

Pisałem już o tym, co naprawdę znaczy „tylko do odczytu" dla konta serwisowego, i przypadek nexo jest czystszy niż GT, gdzie dwa osobne komplety poświadczeń — login SQL i operator Subiekta — bywają nazywane „kontem integracyjnym" w jednym zdaniu. Tamtej dwuznaczności tu nie ma.

Zostaje zwyczajna. Zadajcie ją na głos na starcie: pod jakim nazwanym kontem to pojedzie, kto je założył, co mu wolno i co się z nim stanie, kiedy ta osoba odejdzie z firmy.

Druga połowa tego samego pytania to pola własne. Subiekt nexo PRO ma zaawansowane pola własne na obiektach systemu, a wszystko, czego nauczyłem się boleśnie o polach własnych jako nieudokumentowanej zmianie schematu, stosuje się tutaj bez poprawek. Pole dodane przez administratora po starcie produkcyjnym to zmiana łamiąca zgodność, wykonana przez kogoś, kto nie ma obowiązku Was o tym poinformować. A Wasza integracja jest jedyną stroną, która kiedykolwiek to zauważy.

Gdzie jest dokumentacja

W GT dokumentacja to plik CHM w katalogu instalacyjnym i nie ma publicznej kopii. Ludzie tracą godziny na szukanie czegoś, co nie istnieje.

W nexo dokumentacja to świadome pobranie: nexoSDK.exe, publikowany przez InsERT na ich publicznym FTP, obejmujący Subiekta, Rachmistrza, Rewizora, Gratyfikanta i Gestora nexo PRO oraz Sello NX i Biuro nexo. Zawiera strukturę bazy, opis obiektów i metod oraz kilkadziesiąt kategorii gotowych przykładów — wtyczki importu i eksportu e-faktur i wyciągów bankowych, operacje menu sferycznego na dokumentach i asortymencie, pola własne razem ze słownikami opartymi na SQL, zadania automatyczne, własne raporty.

Przeczytajcie przykłady, zanim cokolwiek zaprojektujecie. Nie dla kodu — dla kształtu punktów rozszerzeń. To on rozstrzyga, czy rzecz, o którą Was poproszono, jest zewnętrznym procesem, operacją w menu czy obsługą zdarzenia. A ta decyzja, jak ustaliliśmy wyżej, ustawia wersję licencji.

Co zbudowałbym najpierw

Ten sam kształt, który polecam na GT, i z tych samych powodów.

Postawcie cienką usługę HTTP na tym hoście Windows, który ma instalację nexo, i niech to będzie jedyny komponent w Waszym systemie, który wie o istnieniu Sfery. Aplikacja rozmawia z nią po JSON. Ta przekładka pochłania powiązanie z bibliotekami, ograniczenie .NET Framework, poświadczenia i dyscyplinę wersji — więc wszystko to zostaje jednym małym, wymienialnym komponentem, zamiast stać się właściwością całej architektury.

Potem zacznijcie od odczytów. Stany, kontrahenci, ceny, wystawione tylko do odczytu, z pulsem i tym logiem wersji przy starcie. Tydzień pracy, który daje Wam prawo rozmawiać o wystawianiu dokumentów.

Jedna rada specyficzna dla nexo na koniec. Jeśli klient jest gdziekolwiek blisko migracji z GT na nexo, zbudujcie najpierw interfejs przekładki, a dopiero potem jej sferową połowę. Interfejs przeżyje migrację. Sferowa połowa nie — nie przenosi się z niej nic. Zespół, który zaczął od interfejsu, wymienia jeden komponent. Zespół, który tego nie zrobił, pisze integrację od nowa. Praca nad przyjmowaniem zamówień w Subiekcie GT, którą opisywałem, jest dokładnie tym: część, która czyta maile i decyduje, co ma znaleźć się w dokumencie, jest warta więcej niż część, która go zapisuje, i jest jej obojętne, która linia InsERT-u leży pod spodem.

Po czym w ogóle poznać, że proces nadaje się do oddania maszynie? Opisałem to przy okazji agentów AI dla firm. Wariant, w którym pod spodem stoi enova365 zamiast Subiekta, rozbiera integracja enova365 z AI.

Zastanawiacie się, czy integracja z Subiektem nexo ma sens — albo czy wersja licencji jej nie zabija? Napiszcie do mnie. Godzina z Waszą instalacją, Waszą wersją i realnym obiegiem dokumentów rozstrzyga więcej niż jakakolwiek wycena napisana z listy funkcji.