Instrukcja wytwarzania adapterów dla systemów dziedzinowych

Załącznik do działania pozaprocesowego komórki: Departament Informatyki Wdrażanie nowych interfejsów komunikacyjnych na Korporacyjnej Szynie Danych Wersja: 01 Data wydania: 16 styczeń 2014 Akceptacja/Odpowiedzialność aktualizację zapisów: Kierownik Biura Usług IT za Zatwierdzenie: Dyrektor Departamentu Informatyki Zakres podmiotowy: Departament Informatyki Rejestr zmian Lp. Punk Opis zmiany Modyfikujący Data 1 4.1 Zmiana wersji WSDL do wersji 1.1 Arkadiusz Szatkowski 11 marzec 2013 2 8.1 Wykreślono zdanie: Na poziomie Usługi należy zdefiniować grupy AD, których członkowie mają prawo jej wywoływania. 3 8.4 Wykreślono zdanie: Dostęp ten powinien być ewidencjonowany w specyfikacji interfejsów celem weryfikacji uprawnień. 4 8.6 Wykreślono zdanie: Dostęp ten powinien być ewidencjonowany w specyfikacji interfejsów celem weryfikacji uprawnień. Łukasz Szot 18 marzec 2013 Łukasz Szot 18 marzec 2013 Łukasz Szot 18 marzec 2013 Instrukcja wytwarzania adapterów dla systemów dziedzinowych Spis treści Spis treści... 1 1. Cel dokumentu... 3 2. Definicje... 3 3. Adaptery... 4 3.1. Rodzaje adapterów... 5 3.2. Synchronizacja danych pomiędzy adapterami / systemami... 5 4. Komunikacja adaptera z KSD... 5 4.1. Format komunikatu... 5 4.2. Namespaces i obiekty złożone... 8 4.3. Definiowanie usług... 8 Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 1

4.4. WebSphere MQ... 8 4.4.1. Podłączenie adaptera z menadżerem kolejek... 9 4.4.2. Zestaw kolejek MQ... 9 4.5. Generowanie WebService HTTP... 9 4.6. Połączenie adaptera z systemem dziedzinowym... 10 5. Działanie adaptera... 10 5.1. Ogólne informacje... 10 5.2. Transakcje... 10 5.3. Timeout komunikacji... 11 5.4. Monitoring... 11 5.4.1. Obsługa błędów i sytuacji wyjątkowych... 11 5.4.2. Kody błędów / odpowiedzi... 11 5.5. Logowanie... 13 5.6. Startowanie i zatrzymywanie adaptera... 14 5.7. Strona kodowa adapterów... 14 5.8. Operacje długotrwałe... 14 5.9. Wydajność Adaptera... 15 6. Implementacja... 15 6.1. Języki programowania oraz biblioteki... 15 7. Parametry konfiguracyjne... 15 8. Bezpieczeństwo... 16 8.1. Bezpieczeństwo usług... 16 8.2. Bezpieczeństwo konfiguracji... 16 8.3. Bezpieczeństwo logów... 17 8.4. Bezpieczeństwo haseł... 17 8.5. Bezpieczeństwo danych osobowych... 17 8.6. Bezpieczeństwo dostępu do serwera i zasobów... 17 8.7. Bezpieczeństwo komunikacji (SSL / HTTPS )... 17 8.8. Wystawienie usług na zewnątrz... 18 9. Dokumentacja usługi... 18 9.1. Szablon opisu Usługi... 18 9.2. Opis danych... 18 Załącznik 1 Struktura komunikatów... 19 1. Headers.xsd... 19 2. OperationName.xsd... 20 Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 2

Załącznik nr 2 Szablony operaji... 22 1. AsyncService.wsdl... 22 2. SyncService.wsdl... 22 Załącznik 3 Szablon opisu Usługi... 24 1. Opis biznesowy usługi... 24 1.1. Cel wprowadzenia usługi SI... 24 1.2. Zakres funkcjonalny usługi SI... 24 1.3. Zależności względem zakresów innych usług SI... 24 2. Opis techniczny usługi... 24 2.1. Podstawowe informacje o usłudze... 24 2.2. Operacje usługi... 26 2.3. Parametry jakościowe usługi... 29 1. Cel dokumentu Niniejszy dokument stanowi element wytycznych szczegółowych dla procesów tworzenia adapterów integracyjnych Systemów Informatycznych Energa-Operator SA. Definiuje on sposób tworzenia adapterów SI i podłączania ich do szyny integracyjnej Energa-Operator SA. Dokument przeznaczony jest dla dostawców poszczególnych Systemów Informatycznych wykorzystywanych w Energa- Operator SA i ma na celu dostarczenie im jednoznacznych, spójnych i kompletnych wytycznych tworzenia adapterów integracyjnych. Celem dokumentu jest zapewnienie, że wszystkie nowobudowane oraz modyfikowane adaptery będą spełniały dokładnie te same wymagania architektoniczne i będą budowane w taki sam sposób, a co za tym idzie, administrowanie nimi będzie bardziej intuicyjne i mniej pracochłonne. 2. Definicje Poniżej przedstawiono słownik najważniejszych pojęć używanych w niniejszym dokumencie Termin Definicja terminu Adapter GUI KMD GK Energa KSD Adapter to część aplikacji realizująca bezpośrednią komunikację aplikacji z infrastrukturą KSD. Komunikacja jest realizowana poprzez wymianę danych zgodnie ze specyfikacją interfejsów i szczegółowym opisem usług WSDL. Adapter musi realizować wyspecyfikowane operacje zgodnie z niniejszym standardem. Graficzny Interfejs Użytkownika Korporacyjny Model Danych Grupy Kapitałowej Energa Korporacyjna Szyna Danych. Implementacja architektury usługowej w Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 3

Grupie Energa oparta o komponenty IBM. SI Timeout Usługa UTF-8 System Informatyczny oznacza w tym dokumencie aplikację dla której jest tworzony adapter i na rzecz którego adapter realizuje swoje funkcjonalności. Przekroczenie dopuszczalnego czasu realizacji zadania. Usługa internetowa jest składnikiem oprogramowania, niezależnym od platformy sprzętowej oraz implementacji, dostarczającym określonej funkcjonalności z możliwością wywoływania tych funkcjonalności zdalnie. Usługa synchroniczna, jest rodzajem usługi której wywołanie wstrzymuje przetwarzanie po stronie klienta w oczekiwaniu na odpowiedź. W przypadku usługi asynchronicznej wywołanie nie wstrzymuje dalszego przetwarzania po stronie wątku klienta. Format kodowania znaków przy komunikacji. WebService Składnik oprogramowania, niezależny od platformy sprzętowej i implementacji, udostępniający określoną funkcjonalność. Do przekazywania danych używany jest zwykle protokół HTTP z wykorzystaniem XML WSDL XSD Web Services Description Language oparty o XML język opisu usług sieciowych XML Schema Definition standard służący do opisu struktury dokumentów XML XML extensible Markup Language uniwersalny język formalny do reprezentowania hierarchicznych struktur danych. Log4J patern Synchroniczny WebService Asynchroniczny WebService Szablon wpisu do logów, pod który podczas działania podstawiane są konkretne wartości. W trybie wywołania synchronicznego aplikacja klienta wysyła żądanie uruchomienia zdalnej funkcji biznesowej i wstrzymuje pracę aż do chwili otrzymania wyników jej realizacji W trybie wywołania asynchronicznego aplikacja klienta wysyła żądanie uruchomienia zdalnej funkcji biznesowej lecz nie oczekuje na jej wynik, kontynuując działanie. 3. Adaptery Adapter jest komponentem wewnętrznym SI. Komponent ten nie dostarcza żadnych funkcjonalności wykorzystywanych bezpośrednio przez użytkownika. Pracuje w tle i realizuje funkcjonalności na rzecz SI, z którym jest powiązany. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 4

Adapter stanowi dla SI jedyny komponent komunikacji z KSD, poprzez który SI wymienia komunikaty z innymi SI. Adapter musi mieć własne logi niezależne od reszty logów SI. Każdy SI może mieć więcej niż jeden Adapter KSD. Adaptery te mogą być rozdzielone ze względu na logikę działania czy też ze względu na inne aspekty pracy. 3.1. Rodzaje adapterów Adaptery możemy podzielić ze względu na technologie wykorzystywane do komunikacji oraz ze względu na rolę w komunikacji. Ze względów technologicznych możemy je podzielić na Adaptery realizujące komunikacje HTTP oraz Adaptery realizujące komunikacje MQ / JMS. Różnica tu polega tylko na wykorzystywanej technologii komunikacji. Ze względu na rolę możemy Adaptery podzielić na Adaptery pełniące rolę serwerową, czyli te realizujące Usługi oraz klienckie, czyli te, których zadaniem jest wywoływanie Usług. Specyficznym rodzajem Adaptera serwerowego jest Adapter przyjmujący informacje o zmianie statusu komunikacji. Nie realizuje on logiki na rzecz innych SI poprzez udostępnianie im danych lub tez pozwalając na ich modyfikacje, ale jako, że Usługa jest wystawiona na zewnątrz należy go traktować jako Adapter serwerowy. Podstawowym rodzajem Adaptera wykorzystywanym w Energa-Operator SA jest asynchroniczny WebService. W uzasadnionych biznesowo przypadkach, np. gdy operator systemu w czasie rzeczywistym oczekuje na komunikat odpowiedzi, dopuszcza się stosowanie WebService synchronicznych. 3.2. Synchronizacja danych pomiędzy adapterami / systemami Adapter komunikuje się z pozostałą częścią systemu w zakresie pobierania i aktualizacji danych potrzebnych do realizacji operacji realizowanych przez siebie. Adapter powinien pozwalać na włączanie i wyłączanie modułu aplikacji niezależnie od reszty systemu. Jest to szczególnie ważne w przypadku konieczności użytkowania systemu bez adaptera. W normalnych warunkach adapter powinien być częścią SI uruchamianą i zatrzymywaną razem z nią. Nie zaleca się oddzielania adaptera od SI ze względu na konieczność administrowania dodatkowym komponentem. 4. Komunikacja adaptera z KSD 4.1. Format komunikatu W komunikacji muszą być wykorzystywane następujące standardy: WSDL 1.1 (http://www.w3.org/tr/wsdl) SOAP 1.1 (http://www.w3.org/tr/2000/note-soap-20000508/) Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 5

XML Schema 1.0 (http://www.w3.org/xml/schema/) Wymagane jest stosowanie jednego standardu nagłówka komunikatów wysyłanych pomiędzy SI zgodnie z poniższą specyfikacją. Schemat komunikatu operacji w usłudze udostępniającej funkcjonalności SI niezależnie, czy mówimy o operacji synchronicznej, czy asynchronicznej powinien mieć postać: Pole w komunikacie operacji Opis ApplicationArea ApplicationArea/Sender ApplicationArea/Sender/LogicalId ApplicationArea/Sender/Component ApplicationArea/Sender/Task ApplicationArea/Sender/ReferenceId ApplicationArea/Sender/Confirmation ApplicationArea/CreationDateTime/ ApplicationArea/BODId/ Identyfikator systemu źródłowego - wartość wg słownika Id modułu sys. źródłowego wg słownika Pole służące do sterowania przetwarzaniem. Pole musi wystąpić, ale może być puste. Pole musi wystąpić, ale może być puste. Pole określające zapotrzebowanie na potwierdzenie [0-brak potwierdzenia, 1-potwierdzenie niezależnie od wyniku, 2-potwierdzenie tylko w przypadku błędów] Data publikacji / przygotowania dokumentu xml, publikowana z systemu dziedzinowego Unikalny Identyfikator dokumentu xml publikowany z systemu dziedzinowego DataArea Sekcja danych biznesowych zależna od operacji Tabela 1 Schemat komunikatu operacji wywoływanej w systemie dziedzinowym Zakłada się możliwość wywołania Usługi bez otrzymania odpowiedzi XML poprzez wykorzystanie komunikacji w jednym kierunku. W takiej sytuacji serwis odpowiada tylko kodem HTTP 202 informując, że przyjął zlecenie do realizacji. Schemat komunikatu potwierdzenia / zmiany statusu w systemie dziedzinowym niezależnie, czy mówimy o operacji synchronicznej, czy asynchronicznej powinien mieć postać: Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 6

Pole w komunikacie Opis ApplicationArea ApplicationArea/Sender ApplicationArea/Sender/LogicalId ApplicationArea/Sender/Component ApplicationArea/Sender/Task ApplicationArea/Sender/ReferenceId ApplicationArea/Sender/Confirmation ApplicationArea/CreationDateTime/ ApplicationArea/BODId/ Reply Reply /ReplyCode/ Reply /ReplyDescription/ Identyfikator systemu źródłowego - wartość wg słownika Id modułu sys. źródłowego wg słownika Pole służące do sterowania przetwarzaniem. Pole musi wystąpić, ale może być puste. Pole referencyjne wypełniane przy potwierdzeniach. Zawierające BODid komunikatu referencyjnego Pole określające zapotrzebowanie na potwierdzenie [0-brak potwierdzenia, 1-potwierdzenie niezależnie od wyniku, 2-potwierdzenie tylko w przypadku błędów Data publikacji / przygotowania dokumentu xml, publikowana z systemu dziedzinowego Unikalny Identyfikator dokumentu xml publikowany z systemu dziedzinowego Sekcja zawierająca informacje o wyniku przetwarzania Zwracany kod odpowiedzi / błędu Opis odpowiedzi / błędu DataArea Sekcja danych biznesowych zależna od operacji Tabela 2 Schemat komunikatu potwierdzenia / zmiany statusu w systemie dziedzinowym Dokładny schemat XSD nagłówka jest zdefiniowany w Załączniku nr 1 do dokumentu Struktura komunikatów. Headers.xsd OperationName.xsd Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 7

4.2. Namespaces i obiekty złożone Przestrzenie nazw w obiektach złożonych powinny być ustandaryzowane w postaci url_glowny/nazwa_systemu_dziedzinowego/nazwa_modułu_systemu_dziedzinowego. Jak tylko jest to możliwe należy reużywać obiekty złożone podczas tworzenia definicji obiektów biznesowych celem uproszczenia definicji. Uchroni to przed sytuacja kiedy to będzie konieczność utrzymywania kilka definicji opisujących tak naprawdę ten sam obiekt. Dla schematu XML powinny zostać ustawione atrybuty: elementformdefault="qualified" oraz attributeformdefault="unqualified" Przy definiowaniu obiektów biznesowych wskazane jest odzwierciedlenie w definicji XSD relacji pól obiektu biznesowego. Przy definiowaniu obiektów biznesowych w pierwszej kolejności należy używać obiektów zdefiniowanych w KMD GK Energa zgodnie z profilem modelu CIM dla EOP. Przy definiowaniu obiektów biznesowych należy zawsze określać restrykcje dla pól obiektu, aby nie określać każdego pola jako opcjonalne lub jako wymagane. Wymagalność pól powinna być określana na etapie analizy i powinna być uwzględniona w definicji XSD obiektu. W przypadku korzystania w obiektach z pól przechowujących czas, zapisywany w nich powinien być lokalny czas polski ze wskazaniem strefy czasowej. 4.3. Definiowanie usług W przypadku tworzenia nowej Usługi udostępnianej przez dany Adapter należy w pierwszej kolejności sprawdzić czy podobna już nie istnieje aby niepotrzebnie nie tworzyć dodatkowych bytów, co w konsekwencji może utrudnić zarządzanie Usługami. Dla każdej Usługi musi występować dokładnie jeden SI występujący w roli serwera i udostepniający dana Usługę. Każda Usługa może być wywoływana przez więcej niż jeden kliencki SI. 4.4. WebSphere MQ Adapter WebSphere MQ realizuje komunikacje za pomocą technologii kolejkowej z wykorzystaniem kolejek komunikacyjnych. Zalecane jest łączenie Adapterów do managera kolejek jako klient TCP/IP. Adapter musi minimalizować ilość jednoczesnych połączeń do managera kolejek WebSphere MQ, ze względu na ograniczone zasoby tego komponentu. Najlepiej aby istniało tylko jedno połączenie współdzielone przez Adapter. Jeśli zakładana jest większa ilość połączeń powinna być wykorzystywana pula połączeń, w której to należy określić inicjalną oraz maksymalną wykorzystywaną ilość połączeń. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 8

4.4.1. Podłączenie adaptera z menadżerem kolejek Adapter musi łączyć się do managera kolejek poprzez jedną z wymienionych bibliotek programistycznych: API C API C++ Biblioteki Java Implementacje bibliotek JMS na bazie WebSphere MQ Inne o ile jest ona dostarczona do obowiązującej wersji WebSphere MQ 4.4.2. Zestaw kolejek MQ Komunikaty wysyłane przez Adapter muszą być wkładane do jego kolejki wyjściowej. Komunikaty odbierane przez Adapter muszą być pobierane z jego kolejki wejściowej. Komunikaty błędów przetwarzania wysyłane przez Adapter muszą być wkładane do jego kolejki błędów. Nazwy kolejek powinny być zawsze definiowane z wielkiej litery. Kolejki takie musza mieć wspólny prefix celem łatwego określenia przynależności kolejki do danego Adaptera. Przykładowe nazwy kolejek: BILLING.ADP1.IN BILLING.ADP1.OUT BILLING.ADP1.ERR 4.5. Generowanie WebService HTTP Usługa może być wygenerowana z góry lub z dołu, tj. na podstawie gotowego pliku WSDL/XSD zostaje wygenerowany kod lub odwrotnie, w oparciu o istniejący kod zostaje wygenerowany plik definicji usługi WSDL/XSD. W przypadku przesyłania w komunikacie załączników binarnych należy stosować standard MTOM. Szablony dla operacji synchronicznych i asynchronicznych zamieszczone są w Załączniku nr 2 Szablony operacji. AsyncService.wsdl SyncService.wsdl Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 9

Prawidłowość konstrukcji definicji WSDL, schematów XML i komunikatów będzie rozstrzygana przez walidację przy użyciu narzędzia SOAP UI v4.5.2. 4.6. Połączenie adaptera z systemem dziedzinowym Adapter jako komponent wewnętrzny SI ma dostęp do danych przechowywanych przez SI, z którym jest związany. Realizuje Usługi na rzecz klientów zewnętrznych (innych SI) lub też będąc klientem realizuje komunikacje z innymi SI na rzecz własnego SI. Dla przykładu adapter udostepniający Usługi np. zwraca informacje o danych przechowywanych w bazie danych własnego SI. Adapter wywołujący Usługi z kolei przykładowo realizuje zlecenie odpytania zewnętrznego SI o dane, które to dane potrzebne są do funkcjonalności aktualnie realizowanej przez SI Adaptera. 5. Działanie adaptera 5.1. Ogólne informacje Adapter powinien działać jako oddzielny wątek, proces SI. Powinien realizować tylko i wyłącznie zadanie związane z wykonaniem danej Usługi. W pierwszej kolejności powinno następować przyjęcie komunikatu wejściowego sparsowanie go, zmapowanie na dane SI i zrealizowanie operacji, np. pobranie danych z bazy i zwrócenie tych danych po zmapowaniu na komunikat odpowiedzi. W przypadku Adaptera klienckiego Adapter oczekuje na zlecenia komunikacji na zewnątrz z własnego SI. Po nadejściu takiego zlecenia zostaje ono zamienione na wywołanie Usługi zewnętrznego SI. Po otrzymaniu odpowiedzi następuje jej obsługa, która musi być opisana w dokumencie Projektu Technicznego i dla każdego wywołania może wyglądać inaczej. Najczęściej będzie to aktualizacja własnej bazy danych, choć możliwe są dowolne działania zależnie od danej funkcjonalności, dla której Adapter kliencki jest wykorzystywany. 5.2. Transakcje W przypadku wystąpienia awarii lub błędu Adapter musi zapewnić spójność danych w danych własnego SI. W przypadku zmian w SI po wywołaniu Usługi powinno następować otwarcie transakcji do bazy czy też innego zasobu przechowującego dane SI. Następnie powinny następować wszelkie operacje zmieniające te dane. Dalej zależnie od wyników operacji, w przypadku poprawnej aktualizacji danych następuje zatwierdzenie transakcji, a w przypadku wystąpienia błędu, czy też problemów z aktualizacją, musi nastąpić cofnięcie transakcji i w odpowiedzi musi zostać wygenerowany stosowny komunikat z błędem. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 10

W przypadku tylko odczytywania danych i zwracania tych danych w odpowiedzi, transakcje nie są wykorzystywane. 5.3. Timeouty komunikacji Za każdym razem podczas ustalania komunikacji pomiędzy Adapterem klienckim, a wystawioną Usługą należy ustalić timeout Usługi. Po stronie Adaptera klienckiego należy ustawić timeout większy od timeoutu Usługi klienckiej na szynie KSD (120s). Po stronie adaptera serwerowego należy ustawić timeout mniejszy od timeoutu Usługi serwerowej na szynie KSD (90s). 5.4. Monitoring 5.4.1. Obsługa błędów i sytuacji wyjątkowych Obsługę błędów i sytuacji wyjątkowych można realizować na kilka sposobów. Sposób obsługi jest zależny od założeń poczynionych na etapie przygotowania architektury i Projektu Technicznego rozwiązania. Ważne jest to, że w przypadku wystąpienia awarii, czy też błędu Adapter musi zapewnić spójność danych poprzez cofnięcie wszystkich zmian poczynionych w ramach transakcji, w której nastąpił problem / błąd / awaria. Przykładowa obsługa sytuacji wyjątkowych: zatrzymanie działania, wpis do logów i przekazanie informacji do SI celem wyświetlenie informacji w interfejsie użytkownika. zatrzymanie działania, wpis do logów i odłożenie informacji z kontekstem celem późniejszej analizy 5.4.2. Kody błędów / odpowiedzi Kody błędów / odpowiedzi możemy podzielić na techniczne kody błędów związane z komunikacją HTTP i MQ / JMS oraz kody odpowiedzi i błędów biznesowych. Kody odpowiedzi błędów biznesowych i aplikacyjnych znajdują się w odpowiedzi i muszą zostać wyszczególnione podczas definiowania Usługi i umieszczone w specyfikacji opisującej daną Usługę. W przypadku komunikacji synchronicznej przy poprawnej komunikacji Usługa Adaptera powinna zwrócić kod odpowiedzi HTTP 200. W przypadku komunikacji asynchronicznej przy poprawnej komunikacji Usługa Adaptera powinna zwrócić kod odpowiedzi HTTP 202. Dla komunikacji HTTP najczęściej wykorzystywane kody odpowiedzi / błędów obejmują: Kod Znaczenie Opis 200 OK Zawartość żądanego dokumentu 201 Created Utworzono wysłany dokument został zapisany na serwerze Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 11

Kod Znaczenie Opis 202 Accepted Przyjęto zapytanie zostało przyjęte do obsłużenia, lecz jego zrealizowanie jeszcze się nie skończyło 301 Moved Permanently Trwale przeniesiony żądany zasób zmienił swój URI i w przyszłości zasób powinien być szukany pod wskazanym nowym adresem 304 Not Modified Nie zmieniono zawartość zasobu nie podległa zmianie według warunku przekazanego przez klienta (np. data ostatniej wersji zasobu pobranej przez klienta 307 Temporary Redirect Tymczasowe przekierowanie żądany zasób znajduje się chwilowo pod innym adresem URI, odpowiedź powinna zawierać zmieniony adres zasobu, na który klient zobowiązany jest się przenieść 400 Bad Request Nieprawidłowe zapytanie żądanie nie może być obsłużone przez serwer z powodu błędnej składni zapytania 401 Unauthorized Nieautoryzowany dostęp żądanie zasobu, który wymaga uwierzytelnienia 403 Forbidden Zabroniony serwer zrozumiał zapytanie lecz konfiguracja bezpieczeństwa zabrania mu zwrócić żądany zasób 404 Not Found Nie znaleziono serwer nie odnalazł zasobu według podanego URL ani niczego co by wskazywało na istnienie takiego zasobu w przeszłości 405 Method Not Allowed 500 Internal Server Error 503 Service Unavailable Niedozwolona metoda metoda zawarta w żądaniu nie jest dozwolona dla wskazanego zasobu, odpowiedź zawiera też listę dozwolonych metod Wewnętrzny błąd serwera serwer napotkał niespodziewane trudności, które uniemożliwiły zrealizowanie żądania Usługa niedostępna serwer nie jest w stanie w danej chwili zrealizować zapytania klienta ze względu na przeciążenie Tabela 3 Kody błędów / odpowiedzi HTTP W przypadku komunikacji MQ / JMS kody są na tyle zróżnicowane, że ich możliwych wartości oraz interpretacji należy szukać na stronach producenta narzędzia serwera kolejkowego. Dla komunikacji MQ najczęściej wykorzystywane kody odpowiedzi / błędów obejmują: Kod Znaczenie Opis 2030 MQRC_MSG_TOO_BIG_FOR_Q Komunikat za duży dla kolejki 2033 MQRC_NO_MSG_AVAILABLE Brak komunikatu w kolejce 2035 MQRC_NOT_AUTHORIZED Brak uprawnień do operacji na kolejce lub Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 12

innym obiekcie MQ 2080 MQRC_TRUNCATED_MSG_FAILED Problem z odczytaniem podzielonego komunikatu 2085 MQRC_UNKNOWN_OBJECT_NAME Nieznana nazwa kolejki lub innego obiektu MQ 2086 MQRC_UNKNOWN_OBJECT_Q_MGR Nieznana nazwa menadżera kolejek 2092 MQRC_XMIT_Q_USAGE_ERROR Nieprawidłowe użycie kolejki transmisyjnej 2110 MQRC_FORMAT_ERROR Niepoprawny format komunikatu MQ 2031 MQRC_MSG_TOO_BIG_FOR_Q_MGR Komunikat za duży dla menadżera kolejek Tabela 4 Kody błędów / odpowiedzi MQ 5.5. Logowanie Adapter powinien mieć zaimplementowany moduł logowania, w którym zapisywanie są informacje o jego działaniu. Logi Adaptera powinny znajdować się w katalogu logs wewnątrz katalogu aplikacji. W katalogu tym powinny znajdować się zarówno logi samej aplikacji jaki i logi Adaptera przy czym logi te powinny być rozdzielone i umieszczone w odrębnych plikach. Dla logów Adaptera plik logów powinien mieć prefix adapter. Moduł logów powinien zapewnić dzienne rotowanie plików logów oraz możliwość ustawienia odpowiedniego poziomu logów (TRACE, DEBUG, WARNING, INFO, ERROR). Poziom logowania jak i położenie pliku logów powinien znajdować się w pliku konfiguracji. Sposób logowania dla każdego Adaptera powinien być szczegółowo opisany w dokumencie Projektu Technicznego. Bardzo ważną kwestią jest to aby sposób logowania umożliwiał analizę sytuacji wyjątkowych i błędów powstałych podczas działania Adaptera, tak aby w przypadku wystąpienia takiej sytuacji można było łatwo ustalić jej przyczynę. W kluczowych funkcjonalnościach powinno się do logów wpisywać informacje o działaniu tych funkcjonalności. Każdy wpis w logach powinien być poprzedzony unikalnym kluczem pobranym z komunikatu wejściowego tak aby zawsze była możliwość identyfikacji jakiego komunikatu zewnętrznego wpis dotyczy. Przykładowy zalecany patern logów dla narzędzia log4j może mieć postać: %d{dd.mm.yyyy HH\:mm\:ss,SSS} [%t] %-5p %c %x - %m%n Przykładowy wpis w logach: Id: xyz123 Zaktualizowano dane w bazie Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 13

W przypadku Adapterów już działających i nie sprawiających problemów powinno być możliwe ustawienie logowania w taki sposób aby zminimalizować ilość generowanych logów. Generalną zasadą powinno być to aby na podstawie wygenerowanych logów istniała możliwość ustalenia co się wydarzyło podczas pracy Adaptera. W szczególności w przypadku wystąpienia błędu, należy na poziomie ERROR zalogować szczegółową informacje o błędzie oraz kontekst działania Adaptera. Wpisy na innych poziomach logowania następują podczas normalnej pracy Adaptera. 5.6. Startowanie i zatrzymywanie adaptera Adapter powinien być częścią SI i być uruchamiany i zatrzymywany razem z SI. Proces zatrzymywania i startowania musi być powiązany z zatrzymywaniem i startowaniem serwera, tak aby nie było sytuacji w której nastąpił restart serwera, a aplikacja z Adapterem nie jest uruchomiona i należy je uruchomić ręcznie. Zalecane jest stosowanie mechanizmów uruchomienia procesów Adaptera specyficznych dla systemu operacyjnego na którym jest zainstalowany. Dla platformy MS Windows będzie to serwis. Na platformie Linux / Unix będą to serwisy init.d. 5.7. Strona kodowa adapterów Cała komunikacja pomiędzy Adapterem klienckim, a serwerowym musi odbywać się z wykorzystaniem kodowania UTF-8. 5.8. Operacje długotrwałe W przypadku operacji długotrwałych zdecydowanie zaleca się stosowanie komunikacji asynchronicznej w celu minimalizacji wykorzystania zasobów oraz poprawy wydajności. W pierwszej fazie wywołujemy Usługę i od razu w odpowiedzi dostajemy informację, że Usługa została uruchomiona. Rekomendowane jest udostępnienie dodatkowej operacji pozwalającej na odczytanie aktualnego statusu albo procentowej wartości określającej stopień realizacji wskazanej operacji długotrwałej. Po zakończeniu przetwarzania SI realizujący funkcjonalność wywołuje Usługę przekazującą status do systemu będącego źródłem pierwotnego wywołania. Dodatkowo należy przewidzieć po stronie usługodawcy, mechanizm zabezpieczający przed wywoływaniem więcej niż jeden raz tej samej Usługi z tymi samymi danymi (z tym samy kluczem). Takie samo zabezpieczenie powinno być zaimplementowane po stronie klienckiej aby uniemożliwić przypadkowe ponowne wysłanie tego samego wywołania. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 14

5.9. Wydajność Adaptera Jednym z istotnych elementów prac projektowych jest analiza obciążenia Adaptera. Jej celem jest przygotowanie takiego rozwiązania, w którym wydajność będzie akceptowalna. Analiza powinna być realizowana przy założeniu odpowiedniego zapasu ze względu na zmiany charakterystyki działania Adaptera udostepniającego Usługę, klientów wywołujących ta Usługę oraz danych przechowywanych przez SI na rzecz którego działa Adapter. W przypadku dużego obciążenia należy szczególnie zwrócić uwagę na optymalizacje wydajności działania Adaptera. Jeśli tylko w fazie przygotowania analizy / architektury / projektu technicznego pojawi się wiedza, że Usługa będzie intensywnie wykorzystywana i / lub czas wykonywania Usługi będzie odpowiednio długi zdecydowanie wskazane jest wykorzystanie komunikacji asynchronicznej.. Dodatkowo Adapter musi być implementowany w taki sposób, aby była możliwość uruchomienia go w wielu instancjach / wątkach. Jeśli wąskim gardłem okaże się komunikacja po sieci zdecydowanie wskazane jest takie skonfigurowanie Adaptera klienckiego / serwerowego aby na poziomie transportu dane były skompresowane. Tu należy jednak przeanalizować czy oszczędność czasu poprzez zastosowanie kompresji danych nie będzie zniwelowana poprzez obciążenie procesora, który będzie musiał po jednej i drugiej stronie te dane najpierw skompresować, a później rozkompresować. 6. Implementacja 6.1. Języki programowania oraz biblioteki Nie ma szczególnych wytycznych jeśli chodzi o wybór języków programowania oraz bibliotek. Wybór ten następuje na podstawie wielu aspektów i powinien być dokonywany indywidualnie dla każdego projektu. Ważne jest, aby wykorzystywano stabilne i powszechnie znane języki programowania oraz biblioteki w celu uniknięcia problemów podczas trwania projektu. Gdzie jest to możliwe należy wykorzystywać gotowe biblioteki w celu usprawnienia procesu wytwórczego. 7. Parametry konfiguracyjne Dopuszczalnymi opcjami przechowywania parametrów konfiguracyjnych Adaptera są: Plik konfiguracyjny Baza danych Wartości te nie mogą być umieszczanie w kodzie aplikacji aby w przypadku zmian tych wartości nie było konieczności aktualizowania aplikacji i wgrywania jej nowej wersji. Adapter powinien udostępniać funkcjonalność restartu bez konieczności restartu całego SI, z którym jest powiązany. Dla pliku konfiguracyjnego dopuszczalnymi opcjami edycji parametrów są bezpośrednia edycja tekstowego pliku konfiguracyjnego lub edycja za pośrednictwem GUI. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 15

Dla parametrów przechowywanych w bazie danych wymagana jest możliwość ich edycji za pośrednictwem GUI. Parametry te powinny być w postaci klucz=wartość, gdzie każdy parametr powinien być umieszczony w oddzielnej linii pliku. Parametry jakie na pewno muszą znaleźć się w pliku konfiguracyjnym to: Parametry zmienne pomiędzy środowiskami (url Usługi jaką Adapter wywołuje, połączenia do bazy i innych zasobów, itp) Parametry związane z timeout em zapytania, czy też timeout em połączenia do baz i innych zasobów Dla pliku konfiguracyjnego zaleca się aby był on umieszczony w jednym dedykowanym katalogu, o nazwie conf, w ramach aplikacji. 8. Bezpieczeństwo 8.1. Bezpieczeństwo usług Wszystkie Usługi powinny być zabezpieczone poprzez autentykację Basic-Auth. Dostęp do Usługi powinien być ewidencjonowany z możliwością weryfikacji uprawnień. Dodatkowo wskazane jest aby komunikat w części zawierającej dane wrażliwe był szyfrowany za pomocą certyfikatu X.509 wystawionego przez centrum autoryzacji CA Energa. W zakresie szyfrowania wskazane jest aby szyfrować tylko te elementy komunikatu, które są wrażliwe z punktu widzenia interesów Energa-Operator SA (dane poufne i wrażliwe), pozostała część komunikatu nie musi być szyfrowana. Szyfrowaniu podlegają zawsze dane stanowiące dane osobowe w rozumieniu ustawy z dnia 29 sierpnia 1997 r. o ochronie danych osobowych. W przypadku wskazania potrzeby ochrony integralności zestawu danych w komunikacie, odpowiedni fragment komunikatu powinien być podpisany. 8.2. Bezpieczeństwo konfiguracji Dostęp do pliku konfiguracyjnego Adaptera powinien być ograniczony tylko i wyłącznie do określonego konta lub grupy kont. Dostęp ten powinien być ewidencjonowany w specyfikacji interfejsów celem weryfikacji uprawnień. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 16

8.3. Bezpieczeństwo logów Dostęp do logów Adaptera powinien być ograniczony tylko i wyłącznie do określonego konta lub grupy kont AD lub systemu operacyjnego. Dostęp ten powinien być ewidencjonowany w specyfikacji interfejsów celem weryfikacji uprawnień. 8.4. Bezpieczeństwo haseł Wszelkie hasła oraz inne parametry działania Adaptera powinny być umieszczane w pliku konfiguracyjnym lub bazie danych. Hasła te powinny być zakodowane zgodnie ze standardem Base64. Dostęp do pliku konfiguracyjnego powinien być ograniczony tylko dla określonego konta lub grupy kont AD lub systemu operacyjnego. 8.5. Bezpieczeństwo danych osobowych Wszystkie usługi przetwarzające dane osobowe powinny być zarejestrowane, zabezpieczone oraz utrzymywane zgodnie z aktualnymi wytycznymi Generalnego Inspektora Ochrony Danych Osobowych. 8.6. Bezpieczeństwo dostępu do serwera i zasobów Dostęp do serwerów i zasobów, na jakich działają Usługai SI powinien być ograniczony tylko i wyłącznie do określonego konta lub grupy kont AD lub systemu operacyjnego. 8.7. Bezpieczeństwo komunikacji (SSL / HTTPS ) Wszelka komunikacja pomiędzy Adapterem, a Usługą zewnętrzną musi być zabezpieczona za pomocą protokołu SSL. Każdy Adapter powinien mieć własną bazę kluczy lub powinien wykorzystywać istniejącą wspólną bazę dla systemów danego serwera aplikacji, czy też hosta, na którym Adapter działa, zawierającą zaufane certyfikaty oraz certyfikat prywatny dedykowany dla Adaptera służący do komunikacji szyfrowanej. W bazie certyfikatów powinien znajdować się zaufany certyfikat centrum autoryzacji CA ENERGA, którym podpisywane są wszelkie certyfikaty używane w Energa-Operator SA (a nie certyfikat, którym przedstawia się druga strona komunikacji Adaptera). Certyfikaty używane do komunikacji powinny mieć ważność 2 lata i powinny być odnawiane przynajmniej na miesiąc przed końcem ważności certyfikatu. Certyfikaty muszą posiadać następujące pola informacyjne: nazwę posiadacza certyfikatu organizację jednostkę organizacyjną rejon lub miasto województwo lub powiat kraj lub region Wystawcą wszystkich certyfikatów jest CA Energa. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 17

8.8. Wystawienie usług na zewnątrz W przypadku komunikacji na zewnątrz GK Energa wymagane jest używanie połączenia szyfrowanego z dodatkową weryfikacją pełnej nazwy certyfikatu oraz weryfikacją IP serwera z którego następuje wywołanie usług. Dodatkowo komunikacja powinna przechodzić przez komponent Gateway na którym następuje przekierowanie komunikacji na docelowe Usługi znajdujące się wewnątrz środowiska IT Energa-Operator SA. Wskazane jest aby komunikat w części wrażliwej był szyfrowany za pomocą certyfikatu X.509. Zaleca się szyfrowanie tylko tych elementów komunikatu, które są wrażliwe z punktu widzenia interesu Energa-Operator SA (dane wrażliwe i poufne). Szyfrowaniu podlegają zawsze dane stanowiące dane osobowe w rozumieniu ustawy z dnia 29 sierpnia 1997 r. o ochronie danych osobowych. W przypadku wskazania potrzeby ochrony integralności zestawu danych w komunikacie, odpowiedni fragment komunikatu powinien być podpisany. 9. Dokumentacja usługi 9.1. Szablon opisu Usługi Każda Usługa SI musi być udokumentowana zgodnie z Szablonem opisu Usługi który stanowi Załącznik nr 3 do Instrukcji. Przed przystąpieniem do implementacji usługi w SI lub na KSD, Opis usługi musi być zatwierdzony przez Energa Operator. 9.2. Opis danych W przypadku gdy zakres danych wymienianych przez Usługę zgodny jest z KMD GK Energa w Opisie usługi w sekcji Komunikat wejściowy oraz Opis zakresu informacji zwracanych przez usługę należy wskazać typy elementów z których korzysta. W przypadku gdy zakres danych wymienianych przez Usługę jest szerszy niż KMD GK Energa w Opisie usługi w sekcji Komunikat wejściowy oraz Opis zakresu informacji zwracanych przez usługę należy udokumentować zastosowany w Usłudze model danych. W takim przypadku dokumentacja powinien zawierać minimum: nazwę pola lub atrybutu, typ, wymagalność, zasady walidacji (maskę wprowadzania/wartości słownikowe), opis biznesowy. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 18

Załącznik 1 Struktura komunikatów 1. Headers.xsd <?xml version="1.0" encoding="utf-8"?> <!-- edited with XMLSpy v2013 sp1 (x64) (http://www.altova.com) by Arkadiusz Szatkowski (ENERGA-OPERATOR SA) --> <xsd:schema xmlns="http://ksd.energa.pl/xsd" xmlns:xsd="http://www.w3.org/2001/xmlschema" targetnamespace="http://ksd.energa.pl/xsd" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:complextype name="applicationarea_type"> <xsd:sequence> <xsd:element name="sender" type="sender_type"> <xsd:annotation> <xsd:documentation>rekord identyfikujący źródło danych </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="creationdatetime" type="xsd:datetime" nillable="false"> <xsd:annotation> <xsd:documentation>data publikacji / przygotowania dokumentu xml w systemie dziedzinowym [lokalny czas polski ze wskazaniem strefy czasowej]</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="bodid"> <xsd:annotation> <xsd:documentation>unikalny Identyfikator dokumentu xml publikowany z systemu dziedzinowego</xsd:documentation> </xsd:annotation> <xsd:simpletype> <xsd:restriction base="xsd:string"> <xsd:maxlength value="20"/> </xsd:restriction> </xsd:simpletype> </xsd:element> </xsd:sequence> </xsd:complextype> <xsd:complextype name="sender_type"> <xsd:sequence> <xsd:element name="logicalid"> <xsd:annotation> <xsd:documentation>identyfikator systemu źródłowgo </xsd:documentation> </xsd:annotation> <xsd:simpletype> <xsd:restriction base="xsd:string"> <xsd:length value="2"/> </xsd:restriction> </xsd:simpletype> </xsd:element> <xsd:element name="component"> <xsd:annotation> <xsd:documentation>id modułu sys. źródłowego wg słownika</xsd:documentation> </xsd:annotation> <xsd:simpletype> <xsd:restriction base="xsd:string"> <xsd:length value="2"/> </xsd:restriction> </xsd:simpletype> </xsd:element> <xsd:element name="task"> <xsd:annotation> <xsd:documentation>pole służące do sterowania przetwarzaniem. Pole musi wystąpić, ale może być puste.</xsd:documentation> </xsd:annotation> <xsd:simpletype> <xsd:restriction base="xsd:string"> <xsd:maxlength value="28"/> </xsd:restriction> </xsd:simpletype> </xsd:element> <xsd:element name="referenceid"> <xsd:annotation> Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 19

<xsd:documentation>pole referencyjne wypełniane przy potwierdzeniach. Zawierające BODid komunikatu referencyjnego</xsd:documentation> </xsd:annotation> <xsd:simpletype> <xsd:restriction base="xsd:string"> <xsd:maxlength value="28"/> </xsd:restriction> </xsd:simpletype> </xsd:element> <xsd:element name="confirmation"> <xsd:annotation> <xsd:documentation>pole określające zapotrzebowanie na potwierdzenie [0- brak potwierdzenia, 1-potwierdzenie niezależnie od wyniku, 2-potwierdzenie tylko w przypadku błędów]</xsd:documentation> </xsd:annotation> <xsd:simpletype> <xsd:restriction base="xsd:integer"> <xsd:mininclusive value="0"/> <xsd:maxinclusive value="2"/> </xsd:restriction> </xsd:simpletype> </xsd:element> </xsd:sequence> </xsd:complextype> <xsd:complextype name="reply_type"> <xsd:sequence> <xsd:element name="replycode" type="xsd:string"> <xsd:annotation> <xsd:documentation>zwracany kod odpowiedzi / błędu</xsd:documentation> </xsd:annotation> </xsd:element> <xsd:element name="replydescription" type="xsd:string"> <xsd:annotation> <xsd:documentation>opis odpowiedzi / błędu</xsd:documentation> </xsd:annotation> </xsd:element> </xsd:sequence> </xsd:complextype> <xsd:complextype name="messagerequest_type"> <xsd:sequence> <xsd:element name="applicationarea" type="applicationarea_type"/> </xsd:sequence> </xsd:complextype> <xsd:complextype name="messageresponse_type"> <xsd:sequence> <xsd:element name="applicationarea" type="applicationarea_type"/> <xsd:element name="reply" type="reply_type"/> </xsd:sequence> </xsd:complextype> </xsd:schema> 2. OperationName.xsd <?xml version="1.0" encoding="utf-8"?> <xsd:schema xmlns:tns="http://ksd.energa.pl/system/module/xsd" xmlns:ksd="http://ksd.energa.pl/xsd" xmlns:xsd="http://www.w3.org/2001/xmlschema" targetnamespace="http://ksd.energa.pl/system/module/xsd" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:import namespace="http://ksd.energa.pl/xsd" schemalocation="headers.xsd"/> <xsd:complextype name="dataarea_type"> <xsd:annotation> <xsd:documentation>sekcja przeznaczona na dane biznesowe</xsd:documentation> </xsd:annotation> </xsd:complextype> <xsd:complextype name="operationname_type"> <xsd:complexcontent> <xsd:extension base="ksd:messagerequest_type"> <xsd:sequence> <xsd:element name="dataarea" type="tns:dataarea_type"/> </xsd:sequence> </xsd:extension> </xsd:complexcontent> </xsd:complextype> <xsd:complextype name="operationnameresponse_type"> <xsd:complexcontent> <xsd:extension base="ksd:messageresponse_type"> Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 20

<xsd:sequence> <xsd:element name="dataarea" type="tns:dataarea_type"/> </xsd:sequence> </xsd:extension> </xsd:complexcontent> </xsd:complextype> <xsd:element name="operationname" type="tns:operationname_type"/> <xsd:element name="operationnameresponse" type="tns:operationnameresponse_type"/> </xsd:schema> Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 21

Załącznik nr 2 Szablony operaji 1. AsyncService.wsdl <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions name="operationname_service" targetnamespace="http://ksd.energa.pl/system/module" xmlns:tns="http://ksd.energa.pl/system/module" xmlns:xsd="http://ksd.energa.pl/system/module/xsd" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/xmlschema" > <wsdl:types> <xs:schema targetnamespace="http://ksd.energa.pl/system/module" elementformdefault="qualified"> <xs:import namespace="http://ksd.energa.pl/system/module/xsd" schemalocation="operationname.xsd"/> </xs:schema> </wsdl:types> </wsdl:definitions> <wsdl:message name="operationname_request"> <wsdl:part name="parameters" element="xsd:operationname" /> </wsdl:message> <wsdl:porttype name="operationname_porttype"> <wsdl:operation name="operationname"> <wsdl:input message="tns:operationname_request" /> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="operationname_binding" type="tns:operationname_porttype"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="operationname"> <soap:operation soapaction="..." /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> </wsdl:operation> </wsdl:binding> <wsdl:service name="async_operationname_service"> <wsdl:port name="operationname_httpsport" binding="tns:operationname_binding"> <soap:address location="https://..." /> </wsdl:port> </wsdl:service> 2. SyncService.wsdl <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions name="service" targetnamespace="http://ksd.energa.pl/system/module" xmlns:tns="http://ksd.energa.pl/system/module" xmlns:xsd="http://ksd.energa.pl/system/module/xsd" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/xmlschema" > <wsdl:types> <xs:schema targetnamespace="http://ksd.energa.pl/system/module" elementformdefault="qualified"> <xs:import namespace="http://ksd.energa.pl/system/module/xsd" schemalocation="operationname.xsd"/> </xs:schema> </wsdl:types> Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 22

<wsdl:message name="operationname_request"> <wsdl:part name="parameters" element="xsd:operationname" /> </wsdl:message> <wsdl:message name="operationname_response"> <wsdl:part name="parameters" element="xsd:operationnameresponse" /> </wsdl:message> <wsdl:porttype name="operationname_porttype"> <wsdl:operation name="operationname"> <wsdl:input message="tns:operationname_request" /> <wsdl:output message="tns:operationname_response" /> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="operationname_binding" type="tns:operationname_porttype"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" /> <wsdl:operation name="operationname"> <soap:operation soapaction="..." /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> <wsdl:output> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> </wsdl:definitions> <wsdl:service name="sync_operationname_service"> <wsdl:port name="operationname_httpsport" binding="tns:operationname_binding"> <soap:address location="https://..." xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" /> </wsdl:port> </wsdl:service> Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 23

Załącznik 3 Szablon opisu Usługi 1. Opis biznesowy usługi 1.1. Cel wprowadzenia usługi SI W ramach niniejszego podrozdziału należy przedstawić cel wprowadzenia usługi SI. Należy opisać przeznaczenie usługi oraz przewidywanych konsumentów usługi (np. poprzez nazwanie obszarów wykorzystania i/lub systemów informatycznych). Przykład: Usługa Client udostępnia informacje o klientach indywidualnych wraz z możliwością ich aktualizacji, w tym dodawania i usuwania klientów. Usługa będzie ona wykorzystywana przez systemy i usługi, które korzystają z obiektu biznesowego klient, stanowiąc pojedynczy punkt dostępu do tego obiektu. W szczególności, zakładane jest jej wykorzystanie w systemach wspierających obszar biznesowy obsługi sprzedaży. 1.2. Zakres funkcjonalny usługi SI W ramach niniejszego podrozdziału należy podać ogólne informacje na temat funkcjonalności udostępnianych przez usługę. Opis powinien zostać przedstawiony z perspektywy biznesowej oraz powinien możliwie precyzyjnie określać granice zakresu funkcjonalnego usługi. Przykład 1: Zakres funkcjonalny usługi Client obejmuje wszystkie operacje dotyczące bezpośrednio klientów indywidualnych i ich atrybutów, takich jak dane identyfikacyjne i kontaktowe. W szczególności, usługa udostępnia funkcjonalności: Pobrania listy klientów indywidualnych o określonej charakterystyce, Pobrania informacji o kliencie indywidualnym, Dodania nowego klienta indywidualnego, Aktualizacji danych klienta indywidualnego, Usunięcia danych klienta indywidualnego. 1.3. Zależności względem zakresów innych usług SI W ramach niniejszego podrozdziału należy podać ogólne informacje na temat funkcjonalności udostępnianych przez usługę, które pokrywają się z zakresem funkcjonalności innych usług. Przykład 1: Usługa Client obejmuje wszystkie operacje związane z bezpośrednimi działaniami na obiekcie biznesowym klienta indywidualnego. Operacje dotyczące klientów korporacyjnych są realizowane przez usługę EnterpriseClient. 2. Opis techniczny usługi Opis techniczny usługi zawiera wszystkie niezbędne informacje pozwalające na wykorzystanie usługi. Został on podzielony na trzy części: Podstawowe informacje o usłudze, Operacje usługi opis operacji udostępnianych przez usługę, Parametry jakościowe usługi. 2.1. Podstawowe informacje o usłudze Tabela poniżej zawiera podstawowe informacje o usłudze. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 24

Tabela 1. Podstawowe informacje o usłudze. Nazwa usługi SI Wersja usługi Warstwa usługi Typ usługi System źródłowy Komponent Operacje usługi Okres ważności usługi URI usługi Timeout usługi Główny Namespace usługi Certyfikat Podstawowe informacje o usłudze W niniejsze pole należy wpisać nazwę usługi SI. Nazwa usługi powinna być zgodna z zaleceniami wytycznych W-1.7 i W-1.8 przedstawionymi w ramach reguł projektowania usług SI [3]. Przykładowe nazwy usług SI zostały podane w ww. dokumencie. W niniejsze pole należy wpisać oznaczenie wersji usługi. W niniejsze pole należy wpisać nazwę warstwy usług, do której należy usługa SI. Warstwa usługi powinna być określona zgodnie z modelem kategoryzacji usług według warstw [2]. W niniejsze pole należy wpisać typ usług, do którego należy usługa SI. Typ usługi powinien być określony zgodnie z modelem kategoryzacji usług według typów [2]. W niniejsze pole należy wpisać identyfikator systemu źródłowego usługi W niniejsze pole należy wpisać Id modułu sys. Źródłowego jeśli istnieje Ze względu na przyjęty model usług udostępniających pojedyncze operacje, nazwa operacji powinna być zgodna z nazwą usługi. W niniejsze pole należy wpisać przedział czasu, w którym usługa była/jest/będzie udostępniana. Należy podać datę udostępnienia oraz zakończenia udostępniania usługi. W przypadku usługi planowanej, wystarczy wpisać: USŁUGA PLANOWANA, ewentualnie z podaniem planowanej daty udostępnienia, jeśli jest ona znana. Przykład: Data udostępnienia usługi 12.04.2012 r. Data zakończenia udostępniania usługi nieznana W niniejsze pole należy wpisać adresy, pod którym usługa jest udostępniana. W przypadku usługi planowanej, wystarczy wpisać: USŁUGA PLANOWANA. Wartości te powinny być podane dla wszystkich środowisk na których usługa jest wdrożona. Przykład: PRD https://domena/nazwa_usługi. TST https://tstdomena/nazwa_usługi. DEV https://devdomena/nazwa_usługi. W niniejsze pole należy wpisać wartość timeout ustawionego dla danej usługi W niniejsze pole należy wpisać wartość dla namespace związanej z usługą W niniejsze pole należy wpisać dane certyfikatu używanego przez usługę, tj czas Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 25

wygaśnięcia, nazwa Podstawowe informacje o usłudze Certyfikaty przychodzące Właściciel usługi W niniejsze pole należy wpisać dane certyfikatów klientów zewnętrznych, które to certyfikaty są akceptowane przez usługę jeśli taka weryfikacja następuje W niniejsze pole należy wpisać imię, nazwisko, nazwę Spółki, adres e-mail oraz numer telefonu właściciela usługi. 2.2. Operacje usługi W przypadku, gdy usługa udostępnia więcej niż jedną operację, każda operacja usługi powinna zostać opisana zgodnie z szablonem poniżej w ramach osobnego podrozdziału. 1. Operacja [nazwa_operacji] Tabela 2. Opis operacji usługi. Opis operacji Poziom granulacji operacji Opis zakresu informacji wymaganych przez usługę Operacja [nazwa_operacji] W niniejsze pole należy wpisać opis funkcjonalności operacji usługi SI. Powinien on zawierać możliwie precyzyjne zdefiniowanie funkcjonalności operacji. Należy wskazać przewidywanych konsumentów operacji. Przykład: Operacja NAZWA_OPERACJI umożliwia pobranie informacji o wybranym kliencie indywidualnym po podaniu numeru identyfikacyjnego tego klienta. Operacja będzie wykorzystywana przez systemy wspierające realizację tych procesów biznesowych, w których istotne są informacje na temat klientów, w szczególności w obszarze obsługi sprzedaży. W niniejsze pole należy wpisać poziom granulacji operacji w ramach usługi SI. Poziom granulacji powinien być zgodny z modelem przedstawionym w ramach opisu reguły reużywalności usług [3]. Wytyczna W-4.9 reguł projektowania usług SI określa zalecenie w zakresie poziomu granulacji operacji. Przykład 1: Wąski zakres danych, Przykład 2: Szeroki zakres danych. W niniejszym polu należy opisać ogólny zakres informacji wymaganych do przekazania do operacji, aby została ona wykonana. Należy przedstawić opis na poziomie biznesowym (encje / obiekty biznesowe), a szczegółowy opis parametrów powinien zostać przedstawiony w kolejnym polu. Jeśli zakres informacji odpowiada udokumentowanemu logicznemu lub koncepcyjnemu modelowi danych, należy umieścić odpowiednią referencję. Przykład: Identyfikator klienta, o którym informacje zostaną zwrócone przez operację. Instrukcja wytwarzania adapterów dla systemów dziedzinowych Strona 26