Systemy są wymienione, ale brakuje opisu ich API i nie wskazano, kto je udostępni
Czym to grozi. Wykonawca wycenia koszt i termin w ciemno, opierając się na przypuszczeniach dotyczących metod, formatów i sposobu uwierzytelniania. Po zawarciu umowy okazuje się, że dokumentacji nie ma, a właściciel drugiego systemu nie ma obowiązku jej wydać. Praca staje, termin się przesuwa, a umowa nie wskazuje winnego.
Jak napisać to dobrze. Dodajcie sekcję „Dane wejściowe do integracji”: dla każdego systemu wersja, typ interfejsu, odnośnik do aktualnej dokumentacji lub załącznik do specyfikacji. Osobnym wierszem wskażcie, kto i w jakim terminie po podpisaniu umowy przekazuje dostęp do dokumentacji oraz co uznaje się za opóźnienie z winy zamawiającego.
Nie opisano zachowania w razie awarii wymiany
Czym to grozi. Płatność przeszła, ale w księgowości jej nie widać. Zapytanie wyszło, odpowiedź nie nadeszła. Jeśli specyfikacja nie mówi, co system robi w takich sytuacjach, wykonawca wybiera sam, a przy odbiorze zamawiający stwierdza, że duplikaty, utracone rekordy czy ciche odrzucenia mu nie odpowiadają. Nie ma o co się spierać: wymagania nie było.
Jak napisać to dobrze. Opiszcie scenariusze awarii wprost: niedostępność drugiej strony, przekroczenie czasu odpowiedzi, odpowiedź z błędem, ponowne wysłanie tej samej wiadomości. Dla każdego określcie, co robi system: ponawia zapytanie, kieruje je do kolejki, oznacza rekord, powiadamia osobę odpowiedzialną i kogo dokładnie. Osobno wymagajcie ochrony przed duplikatami przy ponowieniach.
Druga strona nie ma środowiska testowego i nigdzie tego nie uregulowano
Czym to grozi. Integrację trzeba sprawdzać na systemie produkcyjnym albo nie sprawdzać jej wcale. W pierwszym przypadku ryzykuje się prawdziwe dane i płatności, w drugim błędy wychodzą po uruchomieniu. Testy odbiorcze formalnie przechodzą na atrapach, a prawdziwa wymiana odbywa się po raz pierwszy w dniu uruchomienia.
Jak napisać to dobrze. W specyfikacji wskażcie, dla których systemów potrzebne jest środowisko testowe, kto je zapewnia i w jakim terminie. Jeśli strona takiego środowiska nie ma, zapiszcie alternatywę: emulator, uzgodniony zestaw danych testowych, okno sprawdzenia na systemie produkcyjnym z opisem ograniczeń. Testy odbiorcze powiążcie z tym środowiskiem.
Nie rozdzielono odpowiedzialności za dane na styku systemów
Czym to grozi. Gdy w jednym systemie kwota lub status są inne niż w drugim, każda strona uważa za błędny system przeciwnej. Wykonawca mówi, że przekazał to, co dostał. Właściciel systemu źródłowego, że ten działa prawidłowo. Zamawiający zostaje bez odpowiedzi, kto poprawia dane i kto za nie odpowiada.
Jak napisać to dobrze. Włączcie sekcję o własności danych: dla każdego obiektu wymiany wskażcie, który system jest źródłem prawdy, kto odpowiada za jakość danych źródłowych, a kto za ich przekształcenie przy przekazywaniu. Opiszcie tryb wyjaśniania rozbieżności: kto je rejestruje, kto poprawia, w jakim terminie.
Brak wymagania dotyczącego dziennika wymiany
Czym to grozi. Sporu o to, czy wiadomość została wysłana, co zawierała i jaka przyszła odpowiedź, nie da się rozstrzygnąć bez zapisów. Bez dziennika analiza incydentu sprowadza się do porównywania wspomnień uczestników, a roszczenia wobec wykonawcy lub właściciela sąsiedniego systemu pozostają niepotwierdzone.
Jak napisać to dobrze. Wymagajcie dziennika wymiany w osobnym punkcie: co jest rejestrowane (czas, kierunek, identyfikator operacji, status, kod błędu), jak długo jest przechowywane, kto ma dostęp do podglądu, jak chronione są dane osobowe i płatnicze w zapisach. Zaznaczcie, że dziennik stanowi podstawę przy rozstrzyganiu sporów.
Odbiór opisany ogólnikami: „integracja działa”
Czym to grozi. Bez weryfikowalnych kryteriów protokół można nie podpisywać w nieskończoność albo podpisać, nie sprawdziwszy niczego istotnego. Obie strony znajdują się w sytuacji, w której każda ocena wyniku jest subiektywna.
Jak napisać to dobrze. Dla każdego scenariusza wymiany przygotujcie listę sprawdzeń: dane wejściowe, oczekiwany wynik, środowisko weryfikacji. Włączcie do odbioru scenariusze negatywne z sekcji o awariach oraz kontrolę dziennika. Warunek podpisania protokołu sformułujcie jako pozytywne przejście tych sprawdzeń.