czwartek, 13 grudnia 2012

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.
Generate Documentation
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.
zalecane opcje generowania raportów RTF
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.
tworzenie definicji raportu
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.
ustawianie opcji generowanego raportu

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.
filtr elementów przy generowaniu raportu

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. okno Resources lista definicji raportów RTF
  4. Kliknij prawym przyciskiem na definicji wybranego dokumentu i wybierz z menu kontekstowego opcję Generate Documents...
  5. generowanie raportu z okna Resources
  6. 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.

3 komentarze:

  1. Witam próbowałem wykluczyć elementy po:
    "With element status - wartość pola Status elementów"

    Lecz ciągle wprowadzał mi elementy ze wszystkimi statusami. Jak powinno się wprowadzać taką nazwę w te pole by prawidłowo zadziałał filtr? Próbowałem też przy filtrach zaawansowanych. To samo. W końcu uzupełniłem pole Where Package Phase. wtedy pomineło mi elementy. Proszę o poprawienie mnie jeśli się mylę.

    OdpowiedzUsuń
    Odpowiedzi
    1. Oprócz Twojego komentarza w tym samym czasie dostałem podobne pytania. Doszedłem do wniosku, że najlepiej będzie, jeśli opiszę to w osobnym poście: http://eablogpl.blogspot.com/2013/03/jak-wybrac-tylko-wasciwe-elementy.html
      Mam nadzieję, że ten opis będzie przydatny.

      Usuń
  2. Ja mam pytanie odnośnie "word substitution".
    Wiem, że nie da się dodać swoich wartości do listy, ale może jest jakieś obejście tego? Bo z tego co patrzyłem brakuje wpisu, np. exception (występujące w use case scenario). Zmiana ręczna z angielskiego na polski po wygenerowaniu dokumentacji mija sie z celem.
    Dzięki za info

    OdpowiedzUsuń