Virtual Reports

W programie Enterprise Architect w zakresie generowania dokumentacji w formacie RTF jest możliwość generowania tzw. raportów prostych - opartych o jeden szablon oraz raportów złożonych - opartych o więcej niż jeden szablon. Zaproponowany przeze mnie podział na typy raportów został opisany w artykule Rodzaje raportów.
Metoda wykorzystania raportów złożonych, czyli Virtual Reports może nie być czytelna dla każdego, w związku z tym postanowiłem poświęcić jej nieco miejsca.

Konstrukcja Virtual Report

Do wykorzystania Virtual Reports konieczne jest przygotowanie odpowiedniej struktury pakietowej opisującej dokument, np. o nazwie Dokumentacja. W tym celu warto zastanowić się nad miejscem wpasowania takiego pakietu wraz z zawartością w taki sposób, aby korespondowała ona z pozostałymi treściami modelu. Jednak zagadnienie wzorcowej struktury modelu to temat na inny artykuł.

Owa struktura pakietowa dla każdego dokumentu z osobna definiuje jego elementy składowe, z których jest zbudowany. Dzięki temu możemy definiować osobno poszczególne fragmenty dokumentacji, a potem składać z nich całe dokumenty jak z klocków. Podstawowe zalety takiego rozwiązania to:

• łatwa manipulacja kolejnością treści dokumentu,
• możliwość umieszczania tej samej sekcji w wielu dokumentach,
• możliwość opracowania części wspólnych dla wielu dokumentów, takich jak wstęp.

Poniższy rysunek prezentuje przykładową strukturę pakietową dokumentu generowanego przy użyciu mechanizmu Virtual Reports.

Struktura ta została opracowana na bazie własnych doświadczeń. Nie została opisana ani w EA User Guide ani w White Papers autorstwa firmy Sparx Systems.

Pakiet o nazwie Dokumentacja zawiera specjalny typ pakietu opatrzony stereotypem <<master document>>. Zawartość tego pakietu stanowią elementy typu <<model document>>. Dodatkowo dokument może zawierać tzw. treści statyczne (w pakiecie Treść statyczna), które stanowią integralną część dokumentacji, a nie są związane z merytoryczną zawartością modelu. Tego typu treści statyczne można wydzielić również na wyższy poziom (bezpośrednio pod pakietem Dokumentacja), gdy dotyczyć będą więcej niż jednego dokumentu, czyli na przykład wspólny wstęp.

W artykule opisującym metody generowania raportów opisałem sposób tworzenia definicji raportu (Resource document), za pomocą których możliwe jest generowanie pojedynczego dokumentu lub całego zestawu z okna Resources. Struktura pakietowa opisująca zawartość dokumentu definiuje tylko jego elementy składowe. Stworzenie i wykorzystanie definicji całego raportu (Resource document) jest jak najbardziej możliwe i wskazane w odniesieniu do raportów złożonych.

Diagram dokumentacji

W celu ułatwienia opracowywania Virtual Reports przygotowano specjalny typ diagramu o nazwie Documentation oraz odpowiadającą mu paletę typów elementów (Toolbox). Paleta ta umożliwia tworzenie:

• pakietów Master Document,
• elementów Model Document,
• elementów Document Artifact.

Poniższy rysunek prezentuje zawartość diagramu w Dokumentacja pakiecie Dokumentacja.

Diagram ten służy do umieszczania pakietów typu <<master document>>. Jeśli z jednego modelu jest generowanych kilka raportów złożonych, wówczas wszystkie one mogą znaleźć się na tym jednym diagramie.
Dla ułatwienia korzystania z mechanizmu Virtual Reports przez dowolnych użytkowników warto umieścić na tym diagramie dodatkowe informacje w postaci notek oraz łączy do odpowiednich sekcji w Pliku Pomocy programu, tak jak to pokazano na powyższym rysunku.

Master document

Pakiet typu <<master document>> tworzony jest poprzez umieszczenie na diagramie z Toolboxa Documentation elementu (pakietu) typu Master Document. Służy on do zdefiniowania ram oraz formy dla całego dokumentu.

W pakiecie umieszczany jest kolejny diagram (w przykładzie o nazwie Specyfikacja wymagań) oraz elementy typu <<model document>>.

Menu kontekstowe, które jest dostępne po kliknięciu prawym przyciskiem myszy na takim pakiecie widocznym na diagramie jest wzbogacone o dodatkową pozycję umożliwiającą alternatywne wywołanie okna dialogowego służącego do generowania dokumentacji (tego samego, które jest dostępne z poziomu okna Project Browser).

Wywołanie okna generowania dokumentacji w kontekście <<master document>> posiada jedną różnicę w stosunku do generowania raportów prostych. A mianowicie nie jest możliwa zmiana przypisanego do dokumentu szablonu RTF (pole Use Template).

Pakiet typu <<master document>> posiada predefiniowany atrybut Tagged Value o nazwie RTFTemplate. Atrybut ten służy przypisaniu odpowiedniego szablonu RTF do całego dokumentu.

Zdefiniowana w tym szablonie pagina (nagłówek i stopka) znajdzie zastosowanie we wszystkich sekcjach generowanego dokumentu. Dzięki temu nie ma potrzeby definiowania paginy osobno dla każdej sekcji dokumentu.
Szablon ten może zawierać również stronę tytułową, metrykę dokumentu oraz spis treści.

Model document

Element typu <<model document>> służy do zamodelowania sekcji dokumentu. Kolejność sekcji w dokumencie jest determinowana przez kolejność elementów w pakiecie. Domyślnie elementy są ułożone w kolejności alfabetycznej, stąd też wskazane jest umieszczenie numerów sekcji na początku nazwy elementu. Jeśli zachodzi konieczność zmiany kolejności, należy skorzystać z przycisków oznaczonych strzałkami w oknie Project Browser.

Dla każdego elementu <<model document>> należy określić:

• treść - wskazanie na pakiet(y), których zawartość ma się znaleźć w raporcie,
• forma - wybór szablonu RTF sekcji raportu.

Określenie treści realizowane jest poprzez przeciągnięcie wybranego pakietu (pakietów) z okna Project Browser na wybrany element typu <<model document>> umieszczony na diagramie. W wyniku tej operacji tworzone są automatycznie atrybuty tego elementu. Nazwy tych atrybutów można zmieniać, aby w bardziej czytelny sposób informowały użytkownika o pochodzeniu treści. Może to być szczególnie istotne, gdy w modelu istnieje wiele pakietów o tej samej nazwie.
W przypadku, gdy wybrano więcej niż jeden pakiet kolejność treści w ramach sekcji determinowana jest kolejnością atrybutów. Kolejność atrybutów można zmieniać podobnie jak w przypadku kolejności elementów.

Dla określania treści jako zawartość pakietów przeciągniętych w formie atrybutów istnieje dodatkowa alternatywa. Treść może stanowić wynik wyszukiwania poprzez wybór zdefiniowanego zapytania Model Search. W tym celu zamiast tworzenia atrybutów wskazujących na pakiet(y) należy wybrać definicję zapytania z listy rozwijalnej atrybutu Tagged Value o nazwie SearchName. Zapytania w EA umożliwiają przekazywanie jednego parametru wyszukiwania w formie #searchvalue. Parametr ten jest określany poprzez wpisanie wartości atrybutu Tagged Value o nazwie SearchValue. W przypadku, gdy dla danego elementu typu <<model document>> określono zarówno atrybut(pakiet) oraz SearchName, wówczas podczas generowania dokumentu zapytanie określone jako SearchName zostanie zignorowane.
Stosowanie zapytań do wyboru treści raportu posiada jednak pewne ograniczenia. Wynik zapytania musi zwracać:

• ea_guid - unikalny identyfikator elementu,
• object type - typ elementu.

Pozostałe cechy elementów, które powinny się pojawić w raporcie nie muszą być zwracane przez zapytanie, gdyż EA odczytuje je nie z wyników zapytania, a wprost z odpowiedniej tabeli repozytorium EA po odnalezieniu elementu poprzez GUID.

Powyższy rysunek prezentuje przykład zastosowania zdefiniowanego zapytania o nazwie Zmiany wraz z parametrem 30. Zapytanie takie zwraca elementy typu Requirement, które zostały zmienione w ciągu ostatnich 30 dni. Dzięki temu realizowane jest monitorowanie zmian wymagań.

Określenie formy prezentacji treści realizowane jest poprzez wybór szablonu RTF jako wartość atrybutu Tagged Value o nazwie RTFTemplate dla każdego elementu <<model document>>. W powyższym przykładzie do zaraportowania specyfikacji wymagań zostanie użyty szablon RTF o nazwie Biblioteka_SE_Wymagania. 

Diagram dokumentu

Zawartość dokumentu prezentowana jest na diagramie. Poniższy rysunek przedstawia przykładową zawartość dokumentu, na którym umieszczone zostały wszystkie elementy typu <<model document>>, z których składa się dokument wraz z dodatkowymi informacjami.

Relacje typu <<flow>> mają charakter tylko informacyjny i nie są interpretowane przez mechanizm generowania raportów.

Document artifact

Struktura pakietów zawierająca elementy typu <<document artifact>> służy do zbudowania treści statycznych dokumentu, takich jak na przykład zawartość wstępu.

Powyżej zaprezentowany sposób umieszczania treści statycznych stanowi tylko moją propozycję, która wielokrotnie sprawdziła się w praktyce. Nie została ona jednak nigdzie opisana w dokumentacji firmy Sparx Systems.

Każdy element tego typu może posiadać treść sekcji dokumentu stworzoną przy użyciu Linked Document. Alternatywnie treść taką można umieszczać w polu Notes, jednakże wykorzystanie Linked Document daje większe możliwości w zakresie formatowania tekstu, umieszczania tabel oraz elementów graficznych. Z racji tego, że warto wybrać tylko jedną formę umieszczania treści, warto zdecydować się na Linked Document. Forma prezentacji treści statycznych zależna jest od zastosowanego szablonu RTF. Ja stosuję szablon, w którym nazwą sekcji dokumentu jest nazwa pakietu zawierające <<document artifact>> lub nazwa samego <<document artifact>>. Dzięki temu formatowanie nazwy sekcji oraz zastosowany styl numeracji zależy od szablonu RTF, a nie zawartości Linked Document. A zawartością sekcji w szablonie RTF jest zawartość Linked Document.

Inne uwagi

Mechanizm Virtual Reports można wykorzystać również do wygenerowania raportu w formacie HTML. W tym celu należy z menu kontekstowego elementu typu <<master document>> wybrać Documentation -> HTML Report...

Raport taki będzie posiadał formę prezentacji taką jak zwykły raport HTML, jednak struktura raportu będzie odzwierciedlać strukturę raportu RTF. 

Przykładowy raport wygląda może wyglądać jak na poniższym rysunku.

Z uwagi na to, że utworzenie dokumentu wirtualnego wymaga opracowania odpowiedniej struktury pakietów i elementów, a struktura taka jest zbliżona dla różnych dokumentów, wskazane jest przygotowanie szablonu, tzw. Package Template. Szablon taki może być dystrybuowany w postaci pliku w formacie XMI lub wchodzić w skład MDG Technology. Taki szablon po zaimportowaniu do modelu może zostać już tylko sparametryzowany poprzez wskazanie odpowiednich pakietów źródłowych (jako atrybuty elementów typu <<model document>>) oraz wybór odpowiednich szablonów sekcji (wartość tagged value RTFTemplate).

Wykorzystanie Virtual Reports wiąże się z koniecznością wytworzenia wielu szablonów RTF. Zaleca się wyróżnienie rodzajów tych szablonów poprzez zastosowanie przedrostków na przykład wg następującego schematu:

• Przedrostek MD - dla szablonów głównych, przeznaczonych dla pakietów typu <<master document>>. Np. MD_ProjektTechniczny.
• Przedrostek SE - dla opisu sekcji dokumentu, przeznaczonych dla elementów typu <<model document>>. Np. SE_ModelUzycia.
• Przedrostek DA - również dla opisu sekcji dokumentu, ale przeznaczonych do prezentacji treści statycznych, przypisanych do elementów typu <<document artifact>>. Np. DA_TrescStatycznaH1, gdzie H1 oznacza poziom nagłówka.