Interfejs Programistyczny w Comarch ERP XL | Artykuł ERP XL

Jednym z najważniejszych aspektów przy wyborze systemu klasy ERP jest możliwość jego dostosowania do indywidualnych potrzeb danego przedsiębiorstwa. Fakt ten niewątpliwie został zauważony przez producentów rozwiązań ERP, którzy udostępniają w swoich produktach różne możliwości integracji oraz rozbudowy systemu. W poniższym artykule przedstawię jedną z możliwości rozbudowy systemu Comarch ERP XL, którą jest Interfejs Programistyczny. Opowiem o jego zastosowaniach oraz przedstawię proces tworzenia i rejestracji w systemie dodatku napisanego w oparciu o tenże interfejs.

Czym jest Interfejs Programistyczny

Zastosowanie Dużej Hydry

Korzystając z DH w tworzeniu dodatków dla systemu ERP XL, mamy szeroki wachlarz możliwości modyfikacji i dostosowywania systemu do naszych potrzeb i oczekiwań.

Możemy między innymi:

• Wprowadzać usprawnienia procesów w firmie (np. blokować operacje, których nie chcemy, by miały miejsce w określonych okolicznościach, automatycznie tworzyć dokumenty i/lub kartoteki, tworzyć schematy wypełnień dokumentu).
• Dodawać własne, spersonalizowane, okna w systemie z dodatkowymi funkcjonalnościami.
• Dokonywać integracji z innymi systemami i przygotowywać dane do wymiany pomiędzy systemami lub też bezpośrednio wykonywać ich synchronizację.

Korzystając z DH, mamy możliwość wprowadzenia zmiany w środowisku produkcyjnym, która będzie od razu widoczna i dostępna dla wszystkich użytkowników systemu. Jednorazowe zarejestrowanie dodatku lub podmiana jego wersji powoduje, iż będzie on dostępny na każdym urządzeniu końcowym – bez potrzeby ręcznej podmiany plików w środowisku klienta i instalowania dodatkowych rozwiązań.
Pod warunkiem, że nie zdecydujemy się na wykorzystywanie bibliotek zewnętrznych w naszych implementacjach.

Cykl życia dodatku

Wszystkie dodatki DH (jak również Małej Hydry, która nie jest tematem niniejszego artykułu) są rejestrowane w bazie danych ERP XL jako dane binarne. Każdy z modułów systemu podczas uruchamiania ładuje te dane i tworzy instancje obiektów każdego z dodatku. Przy podnoszeniu formatek systemu odnajdywana jest informacja o zarejestrowanej dla niej instancji klasy dodatku, na której wykonywane są przeciążone metody Init, Cleanup oraz Exit, a także wykonywane są tzw. subskrypcje na zdarzenia w stosunku do wybranych kontrolek systemu w obrębie wspomnianych przeciążonych metod. Obiekty dodatków są zwalniane wraz z zamknięciem aplikacji.

Raz jeszcze chciałbym zwrócić uwagę na fakt, który jest bardzo istotny w całym cyklu rozwiązania. Mianowicie przez cały czas działania systemu operujemy na tych samych instancjach klas dodatków. W przypadku ustawiania wszelkiego rodzaju flag w kodzie aplikacji należy mieć całkowitą pewność co do miejsca ich inicjowania i czasu odczytu. W skrajnych przypadkach mógłby pojawić się problem związany z podejmowaniem akcji na widoku z informacjami, które nie wynikałyby z bieżącego użycia naszej klasy w stosunku do przetwarzanych danych na widoku, a z jej poprzedniego wywołania. Także niepoprawnie korzystając z możliwości DH, moglibyśmy dopuścić do sytuacji, w której wykonywalibyśmy logikę aplikacyjną niezgodnie z danymi z formatek systemu.

Przykładowa implementacja

Napisanie dodatku typu „Hello World” wydaje się zbyt proste, wykonamy zatem znacznie ciekawszą implementację, która zwiększy domyślne możliwości systemu ERP XL o możliwość edycji opisu na nagłówku dokumentu Przyjęcia Zewnętrznego, które zostało już zdjęte z bufora (zatwierdzone). Domyślnie system uniemożliwia zmianę opisu takiego dokumentu, jednakże może zdarzyć się, iż chcemy dać możliwość wybranym operatorom korygowania tej informacji.

W tym celu możemy utworzyć dodatek DH, który umożliwi nam odblokowanie edycji wskazanego pola na zatwierdzonym dokumencie po kliknięciu przycisku przy polu z opisem.

Listing 1. Implementacja dodatku DH – pełny kod dodatku

Metoda Cleanup uruchamia się przed zamknięciem okna. W zależności od potrzeb programisty często nie jest implementowana. Używa się jej m.in., implementując zakończenie połączenia z bazą danych.

DH napisana jest w .NET Framework, dodatek do ERP XL jest więc biblioteką DLL, która również jest utworzona w .NET Framework. W celu wykonania własnej implementacji dodatku należy zbudować rozwiązanie w oparciu o szablon Class Library (.Net Framework). Następnym krokiem jest dodanie referencji do DLL DH CdnHydra.dll, która przy domyślnej instalacji znajduje się w katalogu z plikami systemu np. w ścieżce: C:\Program Files (x86)\Comarch ERP XL 2022.1.

W przypadku, gdy tworzymy dodatek dla niezdefiniowanej wersji systemu lub mamy podejrzenie, iż można wykorzystać go nie tylko w środowisku, dla którego pierwotnie wprowadzamy zmianę, warto dodać referencję do CdnHydra.dll z poprzedniej wersji systemu. Dzięki takiemu rozwiązaniu nasza modyfikacja będzie działała również dla wcześniejszych wersji systemu, co zwiększy nasz rynek odbiorców. Osobiście tworząc dodatki, staram się wybierać wersje aktualnie wspierane przez Comarch.

Aby system Comarch ERP XL mógł poprawnie zarejestrować dodatek, należy go oznaczyć, posiłkując się atrybutem CallbackAssemblyDescription. Informacje z atrybutu są odczytywane przez system ERP XL i prezentowane w informacji o dodatku w Liście dodatków (dostępnych z menu System > Dodatki dowolnego modułu programu – Rysunek 2).

Rysunek 2. Podgląd dodatku na liście dodatków w systemie

Nad klasą dodatku należy przypisać atrybut SubscribeProcedure. Wskazuje on na nazwę procedury w systemie, określającą formatkę, na której ma się wykonać kod pisanego rozwiązania. Aby określić wartość enum Procedures, można posiłkować się celownikiem, który wspomaga tworzenie dodatków Małej Hydry. W tym celu w Liście dodatków tworzymy Nowy dodatek, klikamy na nim Dodaj, tworzymy grupę procedur i ponownie klikamy Dodaj. Przy edycji subskrypcji procedury przeciągamy celownik na okno systemu, co powoduje zwrócenie nam nazwy procedury. Zapisanie zmian i ponowne wybranie Dodaj umożliwia wskazanie kontrolki na oknie, które analizujemy, i pobranie nazwy tej kontrolki, która będzie nam potrzebna w dalszej części implementacji.

W klasie EnableDescriptionWidget, która dziedziczy po klasie abstrakcyjnej Callback dokonujemy nadpisania metod abstrakcyjnych Init oraz Cleanup.

W metodzie Init dodajemy główną subskrypcję na oknie na zdarzenie OpenWindow, w obrębie której uzupełniamy logikę działania aplikacji.

Sama metoda AddSubscription umożliwia podpięcie się pod określone zdarzenie na wybranej kontrolce formatki, podając poszczególne parametry:

• BeforeHandling – flaga ustalająca, czy nasza implementacja ma się wykonać przed wykonaniem się zdarzenia, czy też po nim.
• ControlId – id kontrolki na oknie (wartość 0 determinuje zawsze całe okno).
• EventId – typ zdarzenia, na które chcemy zareagować w systemie (np. wciśnięcie przycisku).
• EventDelegate – delegat, który określa zachowanie, jakie chcemy zaimplementować po lub przed wykonaniu się danego zdarzenia.
   

Każda subskrypcja oraz delegat w systemie kończy się zwracaniem wartości typu bool true, rzadziej false. False zwracane jest w przypadku, gdy informujemy system o potrzebie wycofania operacji. Najczęstszym zastosowaniem takiego mechanizmu jest dodanie subskrypcji na zdarzenie kontrolki Events.Accepted w powiązaniu z kontrolką zapisu dokumentu/kartoteki i podjęcie akcji wycofania zapisu. Przykład takiej implementacji można znaleźć w artykule: liszewski.me/comarch/duza-hydra/duza-hydra-pierwszy-projekt.

W pierwszej linii zdarzenia obsługującego delegat widzimy if, który sprawdza, czy stan dokumentu jest >= 3, czyli czy dokument został zdjęty z bufora (zatwierdzony). Odwołanie do obiektu TraNag w tym przypadku jest odwołaniem do tzw. bufora tabeli, co pozwala na odczytanie wartości z bazy danych w kontekście pracy na danej procedurze (widoku) systemu. W tym konkretnym przypadku dzięki zastosowaniu bufora tabeli jesteśmy w stanie odczytać stan dokumentu, na którym się obecnie znajdujemy, i zdecydować, czy logika, którą implementujemy, ma rację bytu. Bufor tabeli jest zatem odzwierciedleniem stanu bazy danych w kontekście do aktualnie procesowanej formatki systemu.

Jeżeli stwierdziliśmy, że nasza realizacja powinna działać na wybranej formatce systemu, implementujemy logikę tworzenia buttona, który umożliwi edycję opisu. Tworzony jest więc nowy obiekt ClaWindow, który stanowi definicję przycisku umieszczonego na zakładce TabItem o nazwie ?TabNaglowek dokumentu (chcemy, aby nasz dodatek był widoczny tylko na tej zakładce). Następnie przypisywane są informacje o jego stanie. Ciekawym zagadnieniem jest ustanowienie na nim grafiki. W kodzie widnieje zapis przypisujący pod IconRaw wartość PIOR16.ICO – jest to nazwa ikony, która znajduje się w module systemu. Dokumentacja DH wspomina, iż „pełna lista istniejących ikon nie jest dostępna na zewnątrz”. Jednakże jest możliwość ich wydobycia z działającej aplikacji za pomocą np. narzędzia IconsExtract, które umożliwia odczytanie ikon uruchomionego procesu (Rysunek 4). Alternatywnym rozwiązaniem jest podanie pełnej ścieżki na dysku do danej ikony, jest to jednak proces uciążliwy z powodu potrzeby zapewnienia dostępności ikony w podanej ścieżce przez każdą maszynę z zainstalowaną instancją systemu.

Każda kontrolka systemu ma zdefiniowane miejsce na formatce systemu (położenie), rozmiar oraz zdefiniowane zachowanie, jak ma się przemieszczać i skalować wraz ze zmianą rozmiaru okna. Pierwotne przypisanie lokalizacji wykonuje button.Bounds, w którym, w tym przypadku, położenie kontrolki zależne jest od obecnego rozmiaru okna. Identyczny kod jest dodany do zdarzenia OnAfterSized na oknie, aby kontrolka była dostępna dla użytkownika w przewidzianym miejscu po zmianie rozmiaru okna.

Ostatnim etapem implementacji jest przypisanie zdarzenia OnAfterAccepted, które wykonuje akcję po przyciśnięciu danego buttona na oknie. W naszym przypadku przestawia label z wartością „Opis:” na Enabled = true, by nie był on wyszarzony. Przypisywana jest również wartość na kontrolce opisu ReadOnlyRaw = "0", która przywraca możliwość modyfikowania wartości kontrolki, oraz FontColorRaw= "-2147483640", która w kontrolce tekstowej zmieni kolor tekstu na czarny, by nie był on wyszarzony. Aby odnaleźć wartość koloru FontColorRaw, można m.in. odczytać stan tej właściwości kontrolki na dokumencie będącym w buforze.

Podsumowanie

Interfejs Programistyczny jest modułem Comarch ERP XL, który umożliwia dokonywanie optymalizacji systemowych w wielu aspektach jego działania. Będąc posiadaczem tego systemu, warto rozważyć skorzystanie z możliwości DH. Za jej użyciem przemawiają korzyści wynikające z możliwości modelowania systemu do własnych potrzeb, preferencji i integracji.

Artykuł ten nie wyczerpuje tematu Dużej Hydry i jej funkcjonalności, warto więc zapoznać się z pozostałą dokumentacją w tym zakresie.

Autor: Szymon Liszewski