EDE

Electronic Document Exchange, czyli w skrócie EDE jest modułem serwera aplikacji Neos pozwalającym na wymianę dokumentów elektronicznych. Wymiana ta może dotyczyć dowolnego formatu plików i jest możliwa poprzez fizyczne pliki odczytywane i zapisywane na dysku jak i z wykorzystaniem WebService.

Konfiguracja

Moduł EDE może być obsługiwany poprzez specjalnie przygotowane interfejsy dla klienta, jak również w swojej najprostszej postaci przez domyślny i standardowy interfejs. Definicje reguł wymiany dostępne są jedynie dla administratora lub developera w zakładce:

Note

Konfiguracja->System->Reguły wymiany dokumentów elektronicznych

Na poniższym rysunku jest zaprezentowane okno edycji reguły wymiany dokumentów. Pola wymagane do minimalnej konfiguracji, które musimy wypełnić aby reguła mogła prawidłowo działać to:

• Symbol reguły wybierany ze słownika
• Import/export
• Driver, gdzie podajemy nazwę wpisaną przy rejestracji drivera w serwerze aplikacji
• Procedura generująca zawartość komunikatu - w przypadku eksportu
• Procedura interpretacji otrzymanego komunikatu - w przypadku importu

Jeżeli chcemy dokument wymieniać poprzez standardowe okna, a nagłówki zakładać z przycisku Dołącz, należy zaznaczyć Inicjalizacja manualna z poziom GUI. Automatyczną wymianę dokumentu zaznaczamy, jeżeli chcemy aby po przetworzeniu dokument został od razu wymieniony.\ Automatyczne przetwarzanie zaznaczamy, jeżeli chcemy aby podczas eksportu automatycznie została przetworzona odpowiedź(np. z WebService) lub podczas importu aby automatycznie przetworzyć dokument po zaimportowaniu pozycji.

Przeglądanie nagłówków dokumentów dostępne jest w zakładce:

Note

Workplace->Wychodzące/Przychodzące

Okno przeglądania różni się głównie przyciskami akcji dla dokumentów eksportowych i importowych. Poniżej jest zaprezentowane okno dla dokumentów eksportowych. Dostępne są takie akcje jak Dodaj, Wyświetl, Popraw manipulujące definicją nagłówka(EDEDOCSH) oraz przyciski odpowiedzialne za wykonywanie akcji na nagłówkach:

• Przetwarzaj - następuje przetwarzanie dokumentu w wyniku którego uruchamiana jest odpowiednia procedura i zakładane są pozycje(EDEDOCSP)
• Wyślij - Uruchamia funkcję wymiany dokumentu, która obsługiwana jest przez odpowiedni sterownik
• Podpisz - pozwala na podpisanie dokumentów, które tego wymagają
• Pozycje - wyświetla pozycje danego dokumentu

Akcje dla dokumentów importowych pozwalają na Poprawianie, Wyświetlanie i Usuwanie nagłówków dokumentów(a wraz z nimi wszystkich powiązanych pozycji) oraz:

• Sprawdź nowe dokumenty - wysyła komunikat do serwera by dla określonych reguł i w określonych ścieżkach sprawdził, czy pojawiły się nowe dokumenty, które trzeba zaimportować. Zakładane są nagłówki tych dokumentów.
• Importuj - przeprowadzany jest import pozycji do tabeli EDEDOCSP wykonywany przez serwer aplikacji
• Przetwarzaj - uruchamiana jest procedura interpretująca zaimportowane dane
• Pozycje - pozwala wyświetlić zaimportowane pozycje.

Poniższe okno przedstawia edycję/tworzenie nagłówka dokumentu. Do poprawnego działania konieczne jest wskazanie którą regułą dokument będzie wymieniany, jakiego obiektu w systemie dotyczy, REF tego obiektu, ścieżka pliku i nazwa pliku(razem z rozszerzeniem) w przypadku eksportu.

Opis struktur

Moduł EDE wykorzystuje tabele w bazie esystem.fdb:

• EDERULES, która przechowuje definicje reguł wymiany dokumentów
• EDEDOCSH, która przechowuje nagłówki dokumentów
• EDEDOCSP, która przechowuje pozycje dokumentów
• EDERULEPARAMS, która przechowuje parametry reguł wymiany dokumentów

Tabele EDEDOCSH i EDEDOCSP mają odwzorowywać drzewiastą strukturę pliku XML. Podczas każdej wymiany dane są do nich zapisywane i pobierane. Tabela EDERULES pozwala na rozdzielenie poszczególnych rodzajów wymiany.

EDERULES

• SYMBOL - unikalny symbol reguły, np EDE_EXP_XML, EDE_PIT11_V20_EXP
• IMPEXP - 0/1 reguła importu/eksportu
• DRIVER - nazwa drivera zarejestrowanego w serwerze aplikacji(więcej<-link)
• GENPROCEDURE - nazwa procedury, generującej wpisy w tabeli EDEDOCSP
• VERIFYPROCEDURE - nie używane
• IMPORTPROCEDURE - nazwa procedury, przetwarzającej wygenerowaną przez serwer odpowiedź
• AUTOPROCESS - czy przetwarzać automatycznie?:
• 0 - brak
• 1 - uruchomienie automatycznego przetwarzania
  • eksport - zaraz po zalozeniu naglowka
  • import - zaraz po wymianie
• 2 - uruchomienie przetwarzania asynchronicznie
• AUTOEXCHANGE - czy wymieniać automatycznie?:
• 0 - brak
• 1 - uruchomienie automatycznej wymiany
  • eksport - zaraz po przetworzeniu dokumentu
  • import - zaraz po założeniu nagłówka
• 2 - uruchomienie przetwarzania asynchronicznie
• MANUALINIT - 0/1 czy jest możliwe uruchamianie ręczne procedury?
• CONFIRMPATH - 0/1 czy wyświetlać potwierdzenie ścieżki zapisu?
• NEEDSIGN - 0/1 czy dokument wymieniany daną regułą wymaga podpisu kwalifikowanego?

EDERULEPARAMS

• EDERULE - wskazanie na regułę, której parametr dotyczy
• NAME - nazwa
• VAL - wartość

EDEDOCSH

• EDERULE - wskazanie na regułę, którą będzie wymieniany dokument
• DIRECTION - kierunek dokumentu(import/eksport)
• REGDATE - data
• REGOPER
• CREATEDATE
• CREATEOPER
• FINISHDATE
• FINISHOPER
• OTABLE - nazwa tabeli, której dotyczy import/eksport
• OREF - REF rekordu w tabeli z pola OTABLE
• STATUS - status dokumentu:
• Eksport:
  • 0 - nowy
  • 1 - wygenerowane pozycje
  • 2 - do wysłania
  • 3 - utworzony plik, przygotowany do wysłania
  • 4 - wysłany
  • 5 - anulowany
  • Import
  • 0 - nowy
  • 1 - zaznaczony do importu
  • 2 - gotowy do importu(praktycznie nieuzywany)
  • 3 - zaimportowane pozycje
  • 4 - przetworzony
  • 5 - anulowany
• PATH - ścieżka wynikowa zapisu/odczytu pliku
• Jeżeli driver fizyczny oznacza ścieżkę do katalogu po stronie serwera
• Jeżeli driver transmisyjny oznacza parametry do nawiązania połączenia np. z WebServicem
• FILENAME - nazwa pliku z rozszerzeniem
• SYMBOLDOK -
• CONFIRMPATH - nie używane narazie
• MANUALINIT - wskazanie czy dokument został założony ręcznie
• REPLYEDEDOC - wskazanie na dokument odpowiedzi
• SIGNSTATUS
• 0 - nie wymaga podpisu
• 1 - oczekuje na podpis
• 2 - dokument podpisany

EDEDOCSP

• EDEDOCH - wskazanie na nagłówek dokumentu
• ID - identyfikator pozycji
• PARENT - identyfikator rodzica
• NAME - nazwa węzła XML
• PARAMS - atrybuty węzła XML
• VAL - wartość węzła XML

EDEManager - C++

Klasa po stronie klienta C++ odpowiedzialna za komunikację z jej odpowiednikiem po stronie serwera aplikacji. Jest częścią modułu common3. Przechowuje listę zarejestrowanych sterowników w serwerze aplikacji i wysyła komunikaty mające na celu uruchomić odpowiednie metody po stronie C#. Z poziomu kodu funkcji i akcji należy używać następujących funkcji:

ExchangeDoc(int ededoc)

Odpowiada za wymianę dokumentu. Możliwe błędy:

• Błąd wskazania nagłówka dokumentu - nie znaleziono przekazanego REFa w tabeli EDEDOCSH
• Brak procedury eksportu - nie znaleziono reguły wymiany przypisanej do nagłówka dokumentu w tabeli EDERULES
• Brak zarejestrowanego drivera:... - nie znaleziono drivera po stronie serwera aplikacji(może wynikać z błędu połączenia z serwerem)
• Nieudana próba wymiany dokumentu ... - wystąpił błąd na serwerze
• Arithmetic exception, numeric overflow, or string truncation. - zbyt długa wartość w EDEDOCSP.VAL, należy zwiększyć rozmiar w tabeli EDEDOCSP i w procedurze EDEDOC_INSERT_EDEDOCP

PrepareDoc(int ededoc)

Odpowiada za przygotowanie dokumentu. Możliwe błędy podobne jak w funkcji ExchangeDoc.

CheckNewDocsToImport(int ederule, AnsiString &errorMsg)

Odpowiada za sprawdzenie czy istnieją nowe dokumentu do zaimportowania. Możliwe błędy:

• Brak reguły importu - nie znaleziono przekazanego REFa w tabeli EDERULES
• Brak zarejestrowanego drivera:... - nie znaleziono drivera po stronie serwera aplikacji(może wynikać z błędu połączenia z serwerem)

Funkcje

Funkcje wykorzystujące EDEManagera zdefiniowane są w pliku edefuncs.cpp w module common3.

EDEDoProcess(int ededoc,int direction, TDataSet *dataset, bool showmessages)

Funkcja ma za zadanie przetworzyć dokument wymiany. W przypadku eksportu oznacza to, że dokument musi być w statusie 0, czyli nowy a w przypadku importu w statusie 3, czyli zaimportowane pozycje. Do funkcji przekazujemy REF dokumentu, kierunek wymiany(import/eksport), dataset z rekordami EDEDOCSH. Na podstawie tych trzech parametrów ustalana jest dziedzina na jakiej funkcja będzie operować.

Parametr ededoc

Jeżeli podamy parametr ededoc > 0, oznacza to, że chcemy wymienić jeden konkretny dokument. Otwierany jest więc tymczasowy dataset z dziedziną zawężoną do tego jednego rekordu i na nim jest przeprowadzana operacja.

Parametr direction

Żeby skorzystać z parametry direction, który pozwoli nam na wymianę wszystkich dokumentów eksportowych lub wszystkich dokumentów importowych musimy pamiętać aby parametr ededoc był <= 0. Wtedy jeżeli wybraliśmy direction = 1 oznacza to eksport a każda inna wartość większa od -1 import.

Parametr dataset

Możemy chcieć również wymienić konkretną dziedzinę z tabeli EDEDOCSH. Do tego będzie służył parametr dataset. Aby z niego skorzystać jego wartość nie może być NULLem i powinnien posiadać multiselekcję.

Parametr showmessages

Parametr typu bool pozwalający sterować widocznością komunikatów podczas przetwarzania. Jeżeli wiemy, że dokumenty będą wymieniane w dużej liczbie, jednak każdy będzie wymieniany oddzielnie(np. z powodu wymogu WebService) należy wyłączyć powiadomienia, by użytkownik nie musiał co wymieniony dokument kliknąć OK.

Celem funkcji EDEDoProcess jest przetworzenie informacji otrzymanej podczas importu, lub przygotowanie danych do eksportu. Uruchamiana jest za jej pomocą procedura zdefiniowana w regule wymiany. Jeżeli zdefiniowaliśmy w regule, że dokument ma być automatycznie wymieniony(dotyczy tylko eksportu) zostanie uruchomiona funkcja EDEDoExchange.

Wynikiem działania funkcji EDEDoProcess są dane w tabeli EDEDOCSP lub na ich podstawie uzupełnione dane w innych tabelach.

EDEDoExchange

Funkcja ma bardzo podobne działanie jeśli chodzi o przekazywanie parametrów jak EDEDoProcess, natomiast zamiast uruchamiać procedurę z bazy danych wywołuje funkcje EDEMenagera - ExchangeDoc. Dodatkowo sprawdza czy dokument wymaga podpisu kwalifikowanego do wymiany.

EDEDoImportRule

Funkcja sprawdza czy dla podanej reguły importowej są nowe dokumenty do zaimportowania. Obsługuje ona również multiselekcję dokumentów. Jeżeli reguła ma ustawioną automatyczną wymianę dokumentów po sprawdzeniu i znalezieniu dokumentów do importu następuje ich wymiana.

EDEDoSign

Funkcja podpisuje dokumenty, które wymagają do wymiany podpisu kwalifikowanego. Jeżeli dokument nie jest jeszcze przygotowany(zapisany w ścieżce tymczasowej) zostanie wywołana funkcja z EDEManagera PrepareDoc, która dokument przygotuje do podpisu. Po przygotowaniu dokumentu nastąpi sprawdzenie czy czasem już nie jest podpisany. W chwili obecnej w podanej ścieżce sprawdzane jest czy istnieje dokument z rozszerzeniem .xades. Jeżeli nie, wywoływana jest funkcja Sign z pliku commonfunc.cpp, która uruchamia odpowiedni program do podpisywania plików. Po podpisaniu następuje ponowne sprawdzenie czy wygenerował się plik .xades. I zmieniany jest status dokumentu na podpisany.

Akcje

W źródła C++ wbudowane są również domyślne akcje wymiany i przetwarzania dokumentów, które wywołują odpowiednie funkcje. Każda akcja obsługuje parametry pozwalające na sterowanie działaniem uruchamianych funkcji.

EDEExchange

• EDOCUMENT - REF dokumentu
• DIRECTION - kierunek wymiany

EDEProcess

• EDOCUMENT - REF dokumentu
• DIRECTION - kierunek wymiany
• Table - nazwa tabeli

EDEImport

• EDERULE - REF reguły wymiany

EDESign

• EDOCUMENT - REF dokumentu

EDEManager - C

Klasa EDEManager po stronie serwera aplikacji Neos pełni funkcję zarządzająca sterownikami. Podczas inicjalizacji projektu w klasie Register(plik Register.cs) inicjalizowany jest obiekt EDEManagera i rejestrowane są drivery. Tworząc nowy driver wymiany należy pamiętać o jego zarejestrowaniu. EDEManager po otrzymaniu komunikatu od klienta przetwarza go funkcją DoDoc(), która jako jeden z parametrów dostaje REF dokumentu do wymiany(EDEDOCSH). Pobiera z niego przypisaną regułę, a na jej podstawie ustala jaki driver ma obsługiwać tą wymianę. Następnie uruchamia procedury PrepareDoc lub ExchangeDoc dla konkretnego drivera.

Sterowniki

EDE posiada zbiór standardowych sterowników obsługujących możliwe sposoby wymiany dokumentów. Klasą bazową dla wszystkich sterowników jest EDECustomDriver. Sposób dziedziczenia po klasach bazowych przedstawiony jest w sekcji Diagram Klas, gdzie zaprezentowane są obecnie zaimplementowane sterowniki. Po klasie EDECustomDriver dziedziczą EDECustomExportDriver i EDECustomImportDriver. W tym miejscu następuje rozdzielenie sterowników na eksportowe i importowe. Bezpośrednio po klasie EDECustomExportDriver dziedziczy EDEXmlExportDriver, który z kolei jest klasą bazową dla wszystkich sterowników obsługujących wymianę dokumentów XML. W sterownikach eksportowych należy przykryć metodę DoSendDoc, którą dokumenty są wysyłane(czy to do WebService, czy zapisywane na dysku).

W klasach odpowiedzialnych za import jest trochę inaczej, gdyż przed klasą EDEXmlImportDriver jest jeszcze klasa EDECustomFileImportDriver. Każdy sterownik powinnien dziedziczyć po tej klasie i implementować metodę ImportFileIntoXmlDoc, która będzie przetwarzać konkretny plik na obiekt XmlDocument.

Diagram klas

Instrukcje do poszczególnych sterowników

Instrukcja obsługi eDeklaracji

Instrukcja techniczna eDeklaracji

Sterowniki jako pluginy Neosa

Od wersji Neosa 4.0.8 możliwe jest wczytywanie własnych pluginów napisanych w Visual Studio(Tworzenie własnych pluginów w Visual Studio). W Neosie 4.0.12 została wydzielona obsługa sterowników do wymiany dokumentów elektronicznych z serwerami rządowymi w celu przesyłania eDeklaracji do osobnego pluginu(nowa solucja w nowym repozytorium). Tak wydzielone sterowniki do obsługi eDeklaracji możemy traktować jako wzorcowe do zakładania własnych opartych na WebService\'ach.

Quickstart

Aby zacząć pracę nad nowym sterownikiem lub rozwijać już istniejący(np przenosząc z Neos.Common) należy wykonać kilka prostych kroków:

• Pobieramy repozytorium pluginów Neos.Plugins
• Uruchamiamy solucję Neos.Plugins w Visual Studio
• Tworzymy nowy projekt jako Class Library(Add->New Project->Class Library)
• Na liście References projektu dodajemy potrzebne referencje(jeżeli tworzymy sterownik EDE to minimum to Neos.Common)
• Kopiujemy do katalogu projektu odpowiednie DLL Neosa(Neos.Common.dll)(w przyszłości będą to paczki Nuget)
• Zakładamy nowe klasy sterowników, gdzie tak jak robiliśmy to w Neosie tworzymy odpowiednie metody
• Zakładamy plik Register.cs na przykładzie sterownika eDeklaracji
• Zakładamy również nowy katalog w projekcie DriversTests, np. FedexDriverTest, gdzie umieszczamy testy jednostkowe naszych sterowników(oczywiście nie wszystko jesteśmy w chwili obecnej w stanie przetestować, jednak ten krok jest zalecany w celu wypracowania dobrych praktyk).
• Zalecanym rozwiązaniem jest utworzenie metody CreateDriver(int edeRule), która będzie odpowiedzialna za utworzenie konkretnego sterownika i wczytanie parametrów dla danej reguły. Dodatkowo metoda ta w przypadku sterowników działających na bramkach WebService powinna odpowiadać za stworzenie punktu dostępu do bramki, np. w sposób opisany poniżej.

Uwaga!

UWAGA!!! NOWOSC!!! Aby nie było konieczne kopiowanie ustawień do plików .exe.config w sterowniku GovXmlExportDriver została dodana obsługa wczytywania konfiguracji z odpowiedniego pliku .dll(czyli *.dll.config). Kod wraz z komentarzem jest również wstawiony poniżej.

//Pobieramy ścieżkę do aktualnej Assembly. Metoda wywołania jest statyczna,
//dlatego wykorzystujemy typeof naszego sterownika
string AssemblyPath = typeof(GovXmlExportDriver).Assembly.Location;
drv._GovGate = null;
Configuration config = null;
//Probujemy odczytac konfiguracje DLL *.dll.config
try
{
  config = ConfigurationManager.OpenExeConfiguration(AssemblyPath);
}
catch (ConfigurationErrorsException ex)
{
  //Jezeli dostalismy wyjatek to znaczy ze nie ma takiego pliku, tworzymy wtedy normalnie obiekt bramki
  drv._GovGate = new GateServicePortTypeClient(drv.ENDPOINT);
}
//Jezeli udalo sie ustawic config to tworzymy ChannelFactory by odczytac Binding i Endpoint.Address
if (config != null)
{
  var channelfactory = new ConfigurationChannelFactory<GateServicePortTypeChannel>(drv.ENDPOINT, config, null);
  drv._GovGate = new GateServicePortTypeClient(channelfactory.Endpoint.Binding, channelfactory.Endpoint.Address);
}
//Jezeli nie udalo sie w jakis sposob ustawic bramki to tworzymy ja tez po staremu
if (drv._GovGate == null)
{
  drv._GovGate = new GateServicePortTypeClient(drv.ENDPOINT);
}

Aktualizacja neosa

W przypadku aktualizacji neosa należy pamiętać aby zaktualizować do najnowszej wersji zależności do bibliotek neosa takich jak np: Neos.Common, Neos.Core, Neos.BussinesPlatform. Jeżeli to nie zostanie zrobione nie ma gwarancji, że sterownik będzie działał poprawnie.

How To: Podłączenie sterowników do Neosa

Od wersji 4.0.15 serwera Neos zostało usunięte wsparcie dla obsługi sterowników eDeklaracji z kodu serwera. Od tej wersji należy korzystać z oddzielnego pluginu: Neos.Plugins.

1. Należy pobrać źródła pluginu Neos.Plugins i skompilować go lub pobrać już skompilowany plugin FIXME (po opracowaniu emisji)
2. Umieścić wpis w pliku smd wg instrukcji.
3. Aby korzystać ze sterowników eDeklaracji nie trzeba robić nic więcej, gdyż dla systemu te zmiany bedą przezroczyste.

Wykorzystanie EDE w regułach schedulera

Metody

Sprawdzenie nowych dokumentów

Neos.Common.EDE.EDEManager.EDEImportAllNewDocs(bool onlyManualRules = true)

Parametry

• onlyManualRules - <domyślnie: true> - Oznacza czy mają być sprwadzane tylko reguły uruchamiane ręcznie