Generowanie raportów RTF w EA

Gdy zakończymy pracę nad opracowaniem modelu w Enterprise Architect nadchodzi moment, gdy należy podzielić się wynikami pracy z innymi członkami zespołu projektowego lub z klientem. Możemy przesłać lub udostępnić repozytorium EA, ale o wiele lepszym rozwiązaniem jest opracowanie dokumentacji, która w bardziej przejrzysty i czytelny sposób prezentuje zawartość modelu. W tym celu należy skorzystać z funkcjonalności generowania raportów w EA.

Generowanie dokumentu z poziomu okna Package Browser

Podstawową metodą generowania dowolnego raportu w formacie RTF jest wywołanie okna Generate Documentation przy użyciu menu kontekstowego na zaznaczonym pakiecie w oknie Project Browser poprzez wybranie Documentation -> Rich Text Format (RTF) Report... lub naciśnięcie przycisku F8.

Wyświetlane jest wówczas okno zaprezentowane poniżej.

Generowany raport będzie zawierał treść pochodzącą z wybranego pakietu (pole Root Package) wraz ze wszystkimi pakietami podrzędnymi (o ile zostało to wskazane w szablonie raportu) przy użyciu szablonu wybranego z listy rozwijalnej (pole Use Template). Plik wynikowy zostanie zapisany na dysku w lokalizacji wskazanej w polu Output to File.

Dodatkowo możliwe jest ustawienie szeregu opcji generowanego raportu. Opcje dostępne w pierwszej zakładce - Generate to:

• Output to PDF - bezpośrednio po wygenerowaniu, raport zostanie przekonwertowany do formatu PDF. Zastosowanie tej opcji uniemożliwia wprowadzenie jakichkolwiek zmian w wygenerowanym dokumencie, ale jest alternatywą dla stosowania zewnętrznego programu do konwersji.
• Use Language Substitutions - wybranie tej opcji powoduje zastąpienie wybranych fraz zdefiniowanych w zakładce Word Substition frazami określonymi przez użytkownika. Opcja ta umożliwia na przykład zastąpienie wszystkich wystąpień "Basic Path" frazą "Przebieg główny". Nie jest możliwe dodawanie własnych fraz do listy zastąpień w zakładce Word Substitution.
• View Document on Completion - umożliwia automatyczne wyświetlenie zawartości wygenerowanego dokumentu.
• Use Internal Viewer - wybranie tej opcji powoduje wyświetlenie dokumentu przy użyciu wewnętrznej przeglądarki. Jednak w przypadku, gdy na stacji roboczej mamy zainstalowany program MS Word lub Open Office, wówczas lepiej odznaczyć tę opcję.
• Include all Diagram Elements in Report - zaznaczenie tej opcji umożliwia umieszczenie w raporcie (o ile szablon zawiera odpowiednią sekcję) opisu elementów umieszczonych na diagramach w wybranym pakiecie, ale pochodzących z innych pakietów, czyli obcych elementów. Niezależnie możliwe jest określenie analogicznej opcji w odniesieniu do poszczególnych diagramów. Zatem w przypadku, gdy chcemy umieścić w raporcie informacje o elementach spoza pakietu tylko w odniesieniu do wybranego diagramu należy pozostawić tę opcję odznaczoną, a zaznaczyć ją we właściwościach wybranego diagramu.
• Optimize for Open Office - nazwa tej opcji jest nieco myląca. Odznaczenie jej powoduje umieszczenie w wygenerowanym dokumencie specjalnego pola dla każdej nazwy pakietu, elementu, które zawiera unikalny identyfikator (GUID) w modelu. Pole takie jest ukryte i nie widzę dla niego zastosowania poza osadzaniem raportów RTF w MS Word.

Zalecane ustawienie opcji stosowane przeze mnie w większości przypadków prezentuje poniższy rysunek.

Wybrane w tym miejscu opcje są zapamiętywane w momencie generowania dokumentu w rejestrze systemowym i przywoływane w momencie kolejnego wywołania okna.

Tworzenie definicji raportu

Użycie przycisku Resource Document zlokalizowanego w oknie generowania dokumentów umożliwia stworzenie definicji dokumentu, która może być wykorzystana do generowania dokumentów z poziomu okna Resources.

Definicja ta obejmuje:

• Nazwa dokumentu - opisowa nazwa definicji raportu wpisywana w polu Enter Value. Zalecam wpisywanie nazwy pliku wynikowego, czasem nawet łącznie z rozszerzeniem .rtf. Dzięki temu łatwiej jest powiązać wygenerowane pliku na dysku po ich nazwie z definicją.
• Pakiet źródłowy - czyli identyfikator pakietu wybranego w polu Root Package.
• Szablon RTF -  szablon wybrany w polu Use Template.
• Output to File - ścieżka i nazwa pliku wynikowego.
• Advanced - określone w zakładce Advanced.
• Element Filters - określone w zakładce Element Filters.
• Other Filters - określone w zakładce Other Filters.

Wartości określane w zakładkach Project Constants, Word Substitution oraz Codepage mają charakter ogólny i są niezależne od kontekstu konkretnego raportu.

Filtrowanie zawartości raportu

Wygenerowane raporty w oparciu o ten sam pakiet oraz szablon RTF mogą znacząco różnić się między sobą dzięki zastosowaniu odpowiednich filtrów.

Najczęściej stosowane filtry są możliwe do ustawienia w zakładce Options oraz Element Filters.

Pierwsza z nich pozwala określić m.in.:

• Exclude details for - wybrane typy elementów zostaną pominięte w raporcie.
• Exclude connector type - wybrane typy powiązań zostaną pominięte w raporcie.
• Where Package Phase - wartość pola Phase pakietu (nie elementów i diagramów). Jeśli faza dla któregoś z pakietów jest różna od wskazanej, wówczas jego zawartość zostanie pominięta.
• With element status - wartość pola Status elementów.
• Connector Direction - wybranie wszystkich powiązań lub tylko wchodzących czy przychodzących. Dzięki temu mogą nie być wykazywane na przykład powiązania, w których element jest źródłem, bo chcemy takie powiązania przedstawić tylko w jednym miejscu w kontekście elementu docelowego powiązania lub odwrotnie.

Druga zakładka (Element Filters) umożliwia tworzenie bardziej zaawansowanych filtrów dotyczących cech elementów. 

Poniższy przykład prezentuje filtr, dzięki któremu w raporcie znajdą się tylko elementy, dla których określono fazę jako "1.0" oraz mają status "Zaimplementowane" lub "Zatwierdzone".

Ten sam mechanizm filtrowania wykorzystywany jest w funkcjonalności Model Search, dzięki czemu jesteśmy w stanie jeszcze przed generowaniem dokumentu sprawdzić, które elementy spełniają określone warunki.

Opisane tu opcje filtrowania mogą być z powodzeniem zastosowane również w odniesieniu do określonego szablonu RTF. W związku z tym, w przypadku, gdy oczekiwana zawartość raportu różni się zawartości pliku wynikowego należy zweryfikować zastosowane filtry również w szablonie RTF.

Generowanie dokumentu z poziomu Resources

Jeśli uprzednio została zapisana definicja dokumentu jako Resource Document, wówczas można skorzystać z opcji generowania dokumentów z okna Resources.

1. Otwórz okno Resources - wybierz w menu View -> More Project Tools... -> Project Resources.
2. Przejdź do sekcji Documents w tym oknie i rozwiń jej zawartość. Znajdziesz tam listę definicji dokumentów.

3. Kliknij prawym przyciskiem na definicji wybranego dokumentu i wybierz z menu kontekstowego opcję Generate Documents...

4. Otworzy się wówczas okno dialogowe służące do generowania raportów, które zostało opisane powyżej. Jednocześnie zostaną załadowane wszystkie ustawienia zapisane w definicji raportu.

Automatyczne generowanie kompletu dokumentacji

Z poziomu okna Resources możliwe jest automatyczne kompletu dokumentacji. W tym celu kliknij prawym przyciskiem na RTF Documents i wybierz z menu kontekstowego opcję Generate All Documents...

Po wybraniu tej opcji program Enterprise Architect wygeneruje kolejno wszystkie zdefiniowane dokumenty, które można odnaleźć na dysku w zdefiniowanej lokalizacji określonej w definicji w polu Output to file....

Ta opcja może być przydatna, gdy z jednego modelu powstaje szereg dokumentów powiązanych ze sobą. Oprócz przyspieszenia operacji generowania dokumentacji mamy pewność, że dokumenty będą spójne ze sobą. Jeśli na przykład zmienimy w modelu nazwę jakiejś klasy, a pojawia się ona w kilku różnych kontekstach w różnych dokumentach, wówczas nie musimy już pilnować, czy nazwa ta została poprawiona we wszystkich miejscach.

Dalsze czynności

Dokumenty po wygenerowaniu są w formacie RTF, zaś dokumentacja jest przekazywana zazwyczaj w formacie DOCX lub PDF. Zatem wygenerowane raporty powinny zostać przekonwertowane z formatu RTF. Warto o tym pamiętać tym bardziej, że rozmiar pliku RTF może być znacząco większy od pliku w formacie DOC lub DOCX.

Poza tym wygenerowany raport powinien zostać przejrzany, aby upewnić się, że niczego nie brakuje. Zdarza się, że jest konieczność w MS Word ponownego przeliczenia wartości niektórych pól, na przykład pola przechowującego ilość stron (jeśli w paginie numeracja stron ma format "Strona 15 z 47").

Dodatkowo wspomnę jeszcze o pewnym problemie, który występował w wersji Enterprise Architect 8.0 (została naprawiona w buildzie 863). Otóż przy domyślnych ustawieniach, gdy zawartość modelu była ładowana w trybie lazy loading wygenerowany dokument mógł nie zawierać treści ze wszystkich pakietów. Obejściem tego problemu, jeśli ktoś korzysta z wcześniejszej wersji, jest zmiana ustawień ładowania modelu na Entire Model.