Jak opisać integrację systemów, żeby nie utopić projektu

Tak na poważnie wszedłem w tematy integracyjne na początku 2020 roku. To był szok podobny do rozpoczynającej się wtedy pandemii. Doświadczenia zdobyte przy budowaniu aplikacji IT nie pasowały do tego typu projektów. Zastanawiałem się jak sensownie opisać integrację systemów. W głowie rodziły się pytania:

• od czego zacząć prace integracyjne?
• jakie dokumenty będą pomocne?
• co jeszcze powinienem uwzględnić?

Jaki był efekt?

Dałem radę. Nie obyło się jednak bez potknięć. O tym, czego się nauczyłem przeczytasz w tym artykule.

Jak opisywać integracje – spis treści

Z kolejnych rozdziałów dowiesz się:

1. Od czego zacząć opisywanie integracji.
2. Jak wyszukiwać braki i błędy w projekcie integracji.
3. Jakie wymagania formalne muszą spełniać integracje.
4. Jaki wpływ mają wymagania niefunkcjonalne na projekt integracyjny.
5. Jak opisać wymagania integracyjne.
6. Co jest kluczowe z perspektywy testowania integracji.
7. Jak zaplanować komunikację pomiędzy zespołami.

Projekty integracyjne – 7 krytycznych etapów

Teraz wiem to na pewno. Integrowanie systemów IT stanowi odrębną kategorię projektów. Doświadczenia, które zdobyłeś w innego typu projektach, będą jednak pomocne. Zwłaszcza, jeżeli połączysz je z krokami opisanymi poniżej.

1. Pierwszy krok – ustal procesy biznesowe w projektach integracyjnych

Integrowanie systemów może brzmieć jak proces wyłącznie techniczny. Nic bardziej mylnego!

Zanim systemy zaczną ze sobą rozmawiać, to najpierw ludzie powinni ustalić ważną rzecz. Chodzi o cel, czyli powód, dla którego integrujemy rozwiązania IT.

Technicznie można bowiem połączyć prawie wszystko. Tylko czy biznesowo to się będzie spinać?

Jako pierwszy krok przygotuj więc analizę od strony biznesowej. Zamodeluj procesy z uwzględnieniem możliwych integracji. Użyj formy i notacji, która Ci najbardziej odpowiada. Na przykład:

• zamodeluj docelowy proces korzystając z BPMN,
• opracuj diagram przypadków użycia,
• przygotuj model przepływu danych (Data Flow Diagram),
• lub przygotuj po prostu listę procesów w pliku Word czy Excel.

Przykład procesów dla integracji

Przykładowo, w sklepie na blogu Project Makers realizowane są procesy jak na diagramie poniżej (wykorzystałem notację z modelu przepływu danych).

Czyli:

• Utworzenie i przechowywanie Zamówień (prostokąt = obiekt w systemie),
• Dokonywanie płatności i pobieranie statusu płatności (okrąg = proces),
• Zarządzanie wysyłką – przekazywanie informacji o danych dostawcy (prostokąt niedomknięty = źródło danych),
• Fakturowanie – przekazywanie danych, generowanie faktur i zapisywanie faktur w systemie.

Jak widzisz, nie trzeba wiele, żeby opisać integrację systemów IT. Już na podstawie takiego diagramu „biznes” może stwierdzić na przykład, że brakuje przekazania adresu email do narzędzia zarządzającego wysyłką Newsletterów. Dzięki temu można uzupełnić zakres integracji jeszcze przed rozpoczęciem prac.

W kroku 1 przedstawiłem proces od strony biznesowej.
Teraz pora zaplanować współpracę pomiędzy systemami.

2. Wybierz systemy (wstępna weryfikacja)

W kolejnym kroku dobierz systemy, które są w stanie zrealizować zamodelowany proces. Dla każdego systemu sprawdź:

• Czy system posiada wymagana funkcjonalności (wynikające z procesów biznesowych),
• Czy te funkcjonalności są udostępnione przez API lub inną formę połączenia.

Tak wybrane systemy umieść na przygotowanym wcześniej diagramie lub przygotuj nowy model.

Kontynuując przykład sklepu Project Makers:

• Sklep działa w oparciu o WooCommerce, czyli popularny dodatek do WordPressa.
• Płatności realizuje Autopay.
• Faktury generuje dodatek FlexibleInvoices, który jest wbudowany w WordPress.
• Wysyłkami zajmuje się serwis Furgonetka, który generuje i przechowuje dokumenty wysyłkowe.

3. Ustal wymagania formalne

To, że system ma określone funkcjonalności to dopiero połowa sukcesu. W kolejnym kroku sprawdź wszelkie kwestie formalne oraz wymagania pozafunkcjonalne ze strony dostawców rozwiązań.

Kluczowe kwestie, to:

1. Całkowity koszt integracji – połączenia, oraz późniejszego korzystania.
2. Ograniczenia techniczne pod względem liczby zapytań, rodzaju komunikatów itp.
3. Bezpieczeństwo komunikacji i samego systemu przetwarzającego dane.
4. Zgodność z przepisami i oczekiwania pod tym względem.
5. Wymagania formalne stawiane przez dostawcę. Na przykład niektóre firmy wymagają przejścia przez proces certyfikacji zanim możliwa będzie integracja (np. dla booking.com).

Przykładowe wymagania dla serwisu Autopay:

• Liczba transakcji uruchomionych w ciągu jednej minuty może wynieść maksymalnie 100, chyba że Partner i Autopay ustalą wyższy limit w ramach zawartej umowy.
• Żeby otrzymywać powiadomienia o statusie realizacji płatności, domena musi być zabezpieczona ważnym certyfikatem wystawionym przez publiczny urząd certyfikacji (Certificate authority), serwer musi się przedstawiać pełnym łańcucha certyfikatów (Chain of Trust), komunikacja musi się odbywać w oparciu o prokół TLS w wersji 1.2 lub 1.3.

Co zrobić z ograniczeniami?

Pominięcie analizy wymagań formalnych odbije się rykoszetem na późniejszych etapach. Nie przeskakuj tego kroku!

Zanotuj wszystkie formalne wymagania jako ograniczenia projektowe. Może to być część opisu wymagań lub osobny dokument.

Jeżeli planujesz proces integracji, to koniecznie uwzględnij w harmonogramie działania formalne. Przykładowo, certyfikacja konieczna do korzystania z API może zająć nawet kilka miesięcy.

4. Zamodeluj przepływ danych pod względem ilościowym

Planując integrację systemów miej jeden cel – nie zabij systemów dużą ilością danych. Każda aplikacja ma inne możliwości wydajnościowe. Niektóre można przeskalować, w innych nie jest to takie proste.

Zanim powstanie pierwsza linijka kodu przygotuj model przepływu informacji pod względem ilościowym. Zaniechanie tego prowadzi do przykrych niespodzianek.

Widziałem kilka takich przypadków. Nie polecam.

Na przykładzie mojego sklepu ciężko mówić o ilościach danych, które mogą zabić system.

Wyobraź sobie jednak sklep, który sprzedaje bilety na jedyny w tym roku koncert popularnego artysty. Sprzedaż zaczyna się punktualnie o 12:00. Co się wtedy może stać…

1. Załóżmy, że 1000 osób / minutę chce kupić bilet.
2. System sprzedaży biletów jest w stanie udźwignąć takie obłożenie.
3. Po odrzuceniu części zamówień (walidacje), system biletowy rozpoczyna proces płatności.
4. System do płatności obsługuje jednak tylko 100 transakcji na minutę.
5. Pozostałe transakcje są odrzucane, lub czekają w kolejce.
6. Ludzie są niezadowoleni 🙁

Co może zabić system?

Inne sytuacje, które zabijają procesy integracji systemów:

1. Zbyt duży rozmiar danych (np. duże pliki graficzne).
2. Zbyt duża liczba danych do przechowywania (np. konieczność przechowywania logów otrzymywanych co 100 ms).
3. Długotrwały proces przetwarzania danych (np. dane są otrzymywane co 1 sek., ale ich przetworzenie zajmuje 2 sek. ze względu na niewydajne procesy).
4. Niezsynchronizowane oczekiwane czasy reakcji (np. system X oczekuje odpowiedzi od systemu Y po 500 ms., ale system Y potrzebuje 750 ms., żeby otrzymać informacje od systemu Z, które są potrzebne do zbudowania odpowiedzi dla systemu X).

Jak uchronić system przed śmiercią?

Co może pomóc?

Na pewno wczesne wykrycie problemów. Jeszcze na etapie projektowania. Czyli właśnie przygotowanie diagramów pokazujących zależności czasowe i ilościowe.

Jeszcze większą pewność da przetestowanie integracji w realnych warunkach. O tym więcej w kolejnych rozdziałach.

5. Pora w pełni opisać integrację systemów

Masz już wysokopoziomowy plan integracji. Znasz ograniczenia poszczególnych systemów. Wiesz, że wydajnościowo całość się zgadza.

Teraz czas opisać szczegółowo komunikację pomiędzy systemami.

W praktyce najlepiej zrobić to za pomocą diagramu. Na przykład:

• Diagramu sekwencji (jeżeli znasz ten sposób zapisu),
• Lub dowolnego, prostego diagramu, który pokaże połączenia pomiędzy systemami, jak poniżej.

Oczywiście każda z tych wiadomości wymaga szczegółowego rozpisania na konkretne parametry. Zobacz to na przykładzie requestu dla Autopay.

Nie zapomnij o wyjątkach

W idealnym świecie opisanie pozytywnych ścieżek integracyjnych by wystarczyło. W realiach IT to za mało. Koniecznie opisz scenariusze alternatywne i błędne.

Na przykład, dla integracji z bramką Autopay będzie to powtórzenie parametru OrderID w ramach tego samego ServiceID, co jest niedopuszczalne. Opis takiego scenariusza powinien zawierać:

• Wyzwalacz, czyli opis sytuacji, która powoduje błąd (OrderID już istnieje dla podanego ServiceID).
• Reakcja odbiorcy (np. Autopay zwraca 400 Bad Request).
• Reakcja nadawcy (np. system po stronie sklepu generuje nowy OrderID).

Mapuj dane

Systemy tak jak i ludzie, nie zawsze używają tego samego języka.

Popularny przykład to kody krajów:

• System X używa kodu alfa-2, czyli np.: PL,
• System Y używa kodu alfa-3, czyli np. POL.

Oba systemy mają rację, ale bez Twojej pomocy się nie dogadają.

Rozwiązaniem jest zaprojektowanie mapowania danych. Może to być zwykła tabela, np.:

SYSTEM X	SYSTEM Y
PL	POL
FR	FRA

Mapowanie nie zawsze jest symetryczne. Na przykład dla statusów wysyłki zamówienia:

SKLEP	SYSTEM LOGISTYCZNY
W_transporcie	Odebrana_przez_kuriera
W_transporcie	Na_magazynie
W_transporcie	W_drodze_do_odbiorcy

W takiej sytuacji, jeżeli system Sklepu otrzyma od systemu Logistycznego status „Na_magazynie”, to zamieni go na „W_transporcie”. Taka konwersja nie działa jednak w drugą stronę. Gdyby z jakichś przyczyn system Sklepu miał odesłać status do systemu Logistycznego, to z informacji „W_transporcie” nie będzie w stanie ustalić dokładnego statusu Logistycznego.

Taką sytuację rozwiązuje się np. oznaczaniem domyślnej wartości w przypadku wieloznacznego mapowania.

Potwierdź opis z dostawcą

Opis, który przygotujesz na tym etapie koniecznie potwierdź z dostawcą systemu, z którym się integrujesz.

Najlepiej jakby takie potwierdzenie stanowiło część umowy, a każda większa zmiana w działaniu będzie rozpatrywana jako Change Request.

6. Testuj (ograniczone zaufanie do dokumentacji)

Zasada nr 6 – nie wierz dokumentacji. A przynajmniej nie na 100%.

Ja kiedyś miałem pełne zaufanie do dokumentów integracyjnych. Potem się okazywało, że „tak, tak system działa, ale…” i tutaj zaczynała się seria wyjątków, które przecież są oczywiste.

Dokumentacja jest często nieaktualna i zawiera błędy. Trzeba się z tym pogodzić.

Jakie jest rozwiązanie?

Testy, testy i jeszcze raz testy!

Od samego początku projektu poproś dostawcę o udostępnienie środowiska testowego.

Przykładowo, serwis Furgonetka udostępnia takie środowisko właśnie do testów developerskich (sandbox, zobacz pod tym adresem).

I teraz, kiedy masz dostęp do środowiska testowego, to będzie trochę pracy do wykonania po Twojej stronie. Przejdź przez każdy proces i sprawdź, czy zachowanie teoretyczne = zachowanie w praktyce.

Jeżeli tak, to super. Jeżeli nie, to potrzebne będzie wyjaśnienie szczegółów.

7. Zadbaj o integrację białkową

I tu dochodzimy do ostatniego, ale bardzo ważnego punktu.

Komunikacja techniczna to jedno, ale integracja pomiędzy dostawcami na poziomie ludzkim to drugie.

Od samego początku współpracy zdobądź namiary na osoby po drugiej stronie. Zarówno techniczne, jak i biznesowe.

Ustal kanały komunikacji. Mail jest ok, ale komunikator do rozwiązywania nagłych przypadków będzie jeszcze lepszy.

Bądź wyrozumiały jeżeli coś nie działa. Sukces na końcu zależy od zaangażowania obu stron. Nie ma co się złościć i obwiniać nawzajem. Im lepsza będzie komunikacja międzyludzka, tym lepiej będą działały potem systemy.

Podsumowanie

Jak więc opisać integrację systemów IT?

1. Zacznij od biznesowych przypadków użycia.
2. Zamodeluj przepływ danych, który pozwoli zrealizować te przypadki. Użyj do tego konkretnych systemów!
3. Zbierz ograniczenia i wymagania formalne.
4. Sprawdź, czy gdzieś nie pojawiają się wąskie gardła.
5. Potwierdź Twoje zrozumienie integracji z drugą stroną. Oczywiście w formie specyfikacji.
6. Nie ufaj w pełni dokumentacji, dopóki nie zobaczysz tego w akcji.
7. Pamiętaj o komunikacji międzyludzkiej.

+ BONUS: obojętne jak dobrze się nie przygotujesz, to w integracjach zawsze coś Cię zaskoczy.

Powodzenia!

---