Sekcja Dokumentacja w module administratora pokazuje strukturę bazy danych konkretnej instalacji: tabele wraz z opisem przeznaczenia, widoki, procedury składowane, funkcje, assembly oraz triggery. Pozwala poznać logikę danych bez logowania się do serwera SQL.
Po co dokumentować strukturę
Praca wdrożeniowa na platformie StudioSystem bardzo szybko schodzi na poziom bazy danych. Nowy widok zestawienia, definicja eksportu dla przewoźnika, raport dla zarządu, warunek filtrujący dokumenty jednego oddziału - każde z tych zadań wymaga odpowiedzi na to samo pytanie: w której tabeli i w której kolumnie znajduje się potrzebna informacja.
Można na nie odpowiadać, logując się bezpośrednio do serwera SQL. W praktyce jednak nie każdy wdrożeniowiec ma taki dostęp, a nawet mając go, trafia na surową listę obiektów bez informacji o tym, do czego dana tabela służy w kontekście platformy. Sekcja Dokumentacja rozwiązuje oba problemy naraz: udostępnia strukturę z poziomu aplikacji i uzupełnia ją o opisy przeznaczenia.
Narzędzie adresowane jest do trzech grup odbiorców:
- Wdrożeniowców - budujących widoki danych, raporty i definicje importu dla konkretnego klienta.
- Serwisantów - diagnozujących zgłoszenia i sprawdzających, gdzie zapisywane są sporne dane.
- Administratorów - poznających logikę systemu, którym zarządzają.
Zwykły użytkownik operacyjny nie ma powodu, by tu zaglądać - jego praca odbywa się na poziomie dokumentów, a nie tabel.
Gdzie znaleźć sekcję
Dokumentacja stanowi jedną z grup menu w module administratora, obok pozycji konfiguracyjnych takich jak Użytkownicy, Skorowidze, Numeracja i Parametry oraz grup HelpDesk, Integracja i Pomoc.
Dostęp bez opuszczania aplikacji
Umieszczenie dokumentacji w tym samym menu co ustawienia oznacza, że osoba konfigurująca system sięga po strukturę bazy w tym samym miejscu, w którym pracuje.
Sekcja podzielona jest na sześć pozycji odpowiadających rodzajom obiektów bazy danych. Każda działa na tej samej zasadzie: wyświetla listę, którą można filtrować i sortować.
| Pozycja | Co zawiera | Typowe zastosowanie |
|---|---|---|
| Tabele | Nazwa, rola w platformie i opis przeznaczenia | Ustalenie, gdzie zapisywane są dane dokumentu |
| Widoki | Zdefiniowane zapytania do tabel i innych widoków | Sprawdzenie gotowych zestawień przed budową nowego |
| Procedury składowane | Lista procedur wraz z opisem zastosowania | Zrozumienie operacji wykonywanych po stronie bazy |
| Funkcje | Lista funkcji dostępnych w bazie | Wykorzystanie gotowych przeliczeń we własnym zapytaniu |
| Assembly | Skompilowany kod zainstalowany w bazie | Weryfikacja rozszerzeń dodanych dla danego klienta |
| Triggery | Wyzwalacze działające przy zmianie danych | Kontrola, czy w bazie nie ma niepożądanych automatów |
Tabele
Lista tabel jest najczęściej wykorzystywaną pozycją całej sekcji. Dla każdej pozycji podawana jest nazwa tabeli, opis domyślnej roli, jaką pełni w ramach platformy, oraz opis jej przeznaczenia. Pozycje można filtrować i sortować, co przy bazie liczącej setki obiektów bywa jedynym sensownym sposobem odnalezienia właściwego.
Dostępne są dwa polecenia. Pierwsze to eksport danych do arkusza Excel, przydatny przy przygotowywaniu dokumentacji wdrożenia lub uzgodnień z klientem. Drugie to wyświetlenie szczegółów wskazanej tabeli - kolejna lista, tym razem z kolumnami wybranej tabeli.
Warto zestawić tę listę z opisami publikowanymi w serwisie. Materiały takie jak opis rejestru dokumentów magazynowych DPMAG czy kartoteki kontrahentów KNKON tłumaczą przeznaczenie standardowych tabel platformy, natomiast sekcja w aplikacji pokazuje rzeczywisty stan konkretnej instalacji - łącznie z obiektami dodanymi na potrzeby danego klienta.
Pomocna bywa też sama konwencja nazewnicza obowiązująca w bazie. Nazwy tabel platformy zbudowane są z przedrostków wskazujących obszar systemu, dzięki czemu już po samej nazwie można zawęzić poszukiwania:
dp*- dokumenty operacyjne, na przykładDPMAGdla dokumentów magazynowych czyDPINWdla inwentaryzacji.kn*- kartoteki, czyli dane słownikowe o dłuższym cyklu życia, jakKNKONdla kontrahentów.x_*oraz_*- obiekty systemowe platformy, w tym tabele konfiguracyjne i historyczne.
W praktyce najszybsza droga do właściwej tabeli prowadzi przez trzy kroki. Najpierw ustal, jakiego rodzaju danych szukasz - dokumentu, kartoteki czy ustawienia. Następnie odfiltruj listę po przedrostku odpowiadającym temu obszarowi. Na końcu otwórz szczegóły kandydata i sprawdź listę kolumn: obecność pola, którego szukasz, jest ostatecznym potwierdzeniem, że trafiłeś we właściwy obiekt. Metoda ta jest zwykle szybsza niż przeglądanie całej listy alfabetycznie, zwłaszcza w instalacjach rozbudowanych o tabele niestandardowe.
Widoki
Pozycja Widoki wyświetla listę zdefiniowanych zapytań do tabel lub innych widoków. To obszar o szczególnym znaczeniu przy pracy z platformą, ponieważ konfigurowalne widoki SQL są jednym z podstawowych mechanizmów dopasowania systemu - opisuje je szerzej materiał o bazie danych platformy.
Przed zbudowaniem nowego widoku warto przejrzeć istniejące. Bardzo często okazuje się, że potrzebne zestawienie już istnieje albo wymaga jedynie drobnej modyfikacji, co jest rozwiązaniem znacznie tańszym w utrzymaniu niż tworzenie kolejnego, równoległego zapytania o zbliżonym zakresie danych.
Procedury i funkcje
Procedury składowane to zapisane w bazie zestawy poleceń SQL wykonywane na żądanie. Lista podaje ich nazwy wraz z opisem zastosowania, dzięki czemu można ustalić, które operacje realizowane są po stronie serwera bazy, a które w warstwie transakcji aspx. Rozróżnienie bywa istotne przy diagnozowaniu wydajności.
Osobna pozycja prezentuje listę funkcji dostępnych w bazie. Funkcje przydają się przy budowaniu własnych zapytań - zamiast powielać logikę przeliczeń w kilku miejscach, można sięgnąć po gotowy element już obecny w systemie.
Assembly i triggery
W niektórych wdrożeniach pojawia się potrzeba zainstalowania bezpośrednio w bazie danych skompilowanego kodu, czyli assembly. Jeżeli taka sytuacja miała miejsce, obiekty te pojawią się na odpowiedniej liście. Dla osoby przejmującej opiekę nad instalacją jest to ważna informacja - sygnał, że system zawiera rozszerzenie wykraczające poza standard platformy.
Ostatnia pozycja wymaga osobnego komentarza. Lista triggerów prezentuje wyzwalacze obecne w bazie, przy czym platforma odradza ich stosowanie. Powód jest praktyczny: wyzwalacz uruchamia się automatycznie przy zmianie danych, poza kontrolą warstwy transakcji, przez co zachowanie systemu przestaje wynikać wprost z kodu transakcji i konfiguracji. Diagnostyka takiego przypadku bywa czasochłonna, bo objaw pojawia się w zupełnie innym miejscu niż przyczyna.
Dlatego celem tej pozycji jest przede wszystkim uświadomienie wdrożeniowcowi, że w bazie mogą istnieć takie automaty. W dobrze utrzymanej instalacji lista triggerów pozostaje pusta.
Zastosowanie przy wdrożeniu
W codziennej pracy sekcja Dokumentacja najczęściej służy jako punkt startowy trzech zadań. Pierwszym jest budowa raportu - zanim powstanie zapytanie zasilające zestawienie w Reporting Services, trzeba ustalić źródło danych. Drugim jest przygotowanie definicji eksportu lub importu, gdzie nazwy kolumn muszą być zgodne z oczekiwaniami systemu zewnętrznego. Trzecim - diagnostyka zgłoszenia serwisowego, gdy trzeba sprawdzić, gdzie faktycznie zapisała się sporna wartość.
We wszystkich trzech przypadkach dochodzi jeszcze jeden element: wartości słownikowe podpowiadane użytkownikom pochodzą ze skorowidzy, więc pełny obraz danych wymaga zajrzenia zarówno do struktury tabel, jak i do konfiguracji słowników.
Sekcja bywa też przydatna w sytuacji odwrotnej - przy przejmowaniu opieki nad instalacją, której nikt z zespołu wcześniej nie konfigurował. Przegląd list pozwala wtedy w kilkanaście minut ustalić skalę odstępstw od standardu: czy w bazie pojawiły się tabele spoza konwencji nazewniczej platformy, czy zainstalowano assembly oraz czy ktoś dodał wyzwalacze. Odpowiedzi na te trzy pytania zwykle wystarczają, by ocenić, jak bardzo dana instalacja różni się od typowej i ile pracy będzie wymagać jej utrzymanie.
Warto przy tej okazji zapisać wynik przeglądu. Eksport listy tabel do arkusza wykonany na starcie współpracy staje się punktem odniesienia przy kolejnych zmianach - porównanie go z aktualnym stanem po kilku miesiącach od razu pokazuje, co w bazie przybyło.
Podsumowanie
Sekcja Dokumentacja zamienia bazę danych z czarnej skrzynki w czytelny katalog obiektów. Udostępnia tabele z opisem przeznaczenia i listą kolumn, widoki, procedury składowane, funkcje, assembly oraz triggery - wszystko z poziomu aplikacji, bez logowania do serwera SQL, z możliwością filtrowania, sortowania i eksportu do arkusza.
Dla wdrożeniowca to najkrótsza droga od pytania „gdzie są te dane" do gotowego widoku lub raportu. Pełny wykaz opisanych obiektów i transakcji platformy znajduje się natomiast w spisie treści serwisu.