Biblioteka dokumentów w EA

W artykule Import wymagań z Linked Document opisałem mechanizm tworzenia elementów modelu wprost z dokumentów składowanych w modelu w formie Linked Documents. Wykorzystanie tego mechanizmu wymaga zaimportowania dokumentów do modelu i przypisanie ich do określonych elementów typu <<document>>. Proces taki wymaga pewnego nakładu sił, co w przypadku dużych projektów może być kłopotliwe, a poza tym użytkownicy modelu i tak mają świadomość, że dokumenty te są tylko kopią dokumentów składowanych poza modelem. Aby mieć pewność, że sięgają do właściwej treści użytkownicy i tak będą korzystać z referencyjnego repozytorium dokumentów, jakim może być np. Sharepoint lub SVN.

Zatem po co tworzyć bibliotekę dokumentów w modelu Enterprise Architect?

Mogą istnieć różne przesłanki wynikające ze specyfiki projektów. Z analitycznego punktu widzenia  wartość dodaną stanowi możliwość tworzenia relacji dokumentów do innych elementów modelu (np. Dependency, Trace) oraz możliwość łączenia poprzez hiperłącza określonych słów czy fraz z dokumentu.
Ponadto model dokumentacji może służyć do wspomagania procesów tworzenia dokumentacji projektowej poprzez zastosowanie diagramów i relacji pomiędzy dokumentami. Na przykład można zamodelować zależności prezentujące informacje o tym, który dokument (lub rozdział) wynika z jakiegoś innego dokumentu. Dzięki temu łatwiej zorientować się, czy aktualizacja jednego dokumentu pociąga za sobą konieczność aktualizacji innego dokumentu.

Mechanizm automatycznego importu dokumentacji

Sparx Systems, producent programu Enterprise Architect proponuje wykorzystanie przygotowanego przez nich skryptu, który w sposób automatyczny jest w stanie przeprowadzić import nawet dużych zbiorów dokumentacji.
Jest on dostępny do pobrania na stronie Enterprise Architect Community w formie przykładowego modelu EAP.
Skrypt ten na podstawie wskazanego drzewa katalogów na dysku lokalnym tworzy odpowiednią strukturę pakietów odzwierciedlającą strukturę katalogów, a w pakietach tych tworzy elementy odpowiadające znalezionym plikom. Jeśli plik może zostać skonwertowany do formatu RTF, wówczas tworzony jest również Linked Document zawierający treść dokumentu.
Dodatkowo, zapewne z myślą o dokumentach w innych formatach, przygotowano jeszcze jeden skrypt ułatwiający otwarcie z poziomu EA pliku źródłowego. Funkcja ta jest szczególnie przydatna, gdy mamy do czynienia z repozytorium dokumentów zawierającym kilkadziesiąt lub kilkaset dokumentów, gdyż na podstawie powiązań (np. wymagania czy przypadku użycia) jesteśmy w stanie szybko zlokalizować w modelu właściwy powiązany dokument, a następnie bezpośrednio otworzyć jego zawartość z zewnętrznego repozytorium. Zewnętrznym repozytorium może być, jak już wspomniałem, Sharepoint, system kontroli wersji lub dysk sieciowy.

Przygotowanie modelu

Aby skutecznie wykorzystać mechanizm importu biblioteki dokumentów należy przekopiować do swojego modelu skrypty z pliku EAP pobranego ze strony Enterprise Architect Community. W tym celu należy otworzyć pobrany plik EAP, wybrać w menu programu View -> Scripting. Otworzy się wówczas okno z zestawem skryptów.

W oknie tym widoczna jest grupa skryptów o nazwie Import Documents. W swoim modelu należy utworzyć taką samą grupę wybierając typ New Project Browser Group. Skrypty, które są w grupie tego typu można uruchamiać kontekstowo dla wybranego pakietu lub elementu w oknie Project Browser.
Po utworzeniu takiej samej grupie należy utworzyć nowe skrypty, takie same, jakie są widoczne w grupie Import Documents, tj.:

• Import Documents - typ VB Script,
• Open - typ JS Script.

Nowo utworzone skrypty mają już określoną treść wynikającą z szablonu. Treść tę należy usunąć i wkleić zawartość skryptów z pobranego pliku EAP.

Następnie należy przygotować w modelu miejsce, czyli w oknie Project Browser stworzyć odpowiedni pakiet (lub widok), który będzie zawierał bibliotekę dokumentów.

Wywołanie skryptu Import Documents

Skrypt importujący bibliotekę dokumentów wywołujemy z okna Project Browser klikając prawym przyciskiem myszy na wybranym pakiecie (lub widoku). Następnie z menu kontekstowego wybieramy Scripts -> Import Documents.

W kolejnym kroku należy wskazać folder na dysku, w którym znajdują się dokumenty posegregowane w podfolderach.
Po wskazaniu folderu skrypt dla każdego z podfolderów tworzy odpowiadający mu pakiet. W takim pakiecie umieszcza dla każdego ze znalezionych plików element typu <<document>>. Jeśli jest to dokument o rozszerzeniu .doc lub .rtf, wówczas jest otwierany w tle w programie MS Word lub OpenOffice, skąd pobierana jest jego zawartość (ewentualnie konwertowana do formatu RTF), a następnie umieszczana jako Linked Document dla tworzonego elementu.
Po zakończeniu procesu wyświetlany jest komunikat 'Import Completed'.
Poniższy rysunek prezentuje przykładowy efekt importu.

Otwieranie dokumentów z referencyjnego repozytorium

Dokumenty w formacie MS Word, których zawartość została przeniesiona do repozytorium można przeglądać jako Linked Document. W tym celu należy w oknie Project Browser nacisnąć prawy przycisk na wybranym elemencie typu <<document>>, a potem z menu kontekstowego wybrać Linked Document.
Niezależnie od typu dokumentu dokument można otworzyć z referencyjnego repozytorium wybierając z menu kontekstowego Scripts ->Open tak, jak pokazano poniżej.

Ścieżka wskazująca na położenie pliku na dysku jest zapisana jako atrybut elementu o nazwie Filename. Jeśli ktoś będzie próbował otworzyć taki plik na innej stacji roboczej, gdzie dokument znajduje się w innej lokalizacji, wówczas otwarcie pliku nie powiedzie się. Istnieje na szczęście prosty sposób na parametryzację ścieżek lokalnych.
Wystarczy z menu wybrać  Settings -> Local Directories and Paths... W oknie, które zostanie wyświetlone należy dodać nową definicję określając:

• Type - Delphi (taki typ został określony w skrypcie),
• ID - nazwa zmiennej,
• Path - wartość zmiennej.

Naciśnięcie przycisku Apply Path spowoduje zamianę ścieżki we wszystkich polach Filename na zmienną %TEST%, która przy próbie otwarcia pliku jest zamieniana przez Enterprise Architect na wartość zmiennej podaną w powyższym oknie.

Podsumowanie

Mechanizm importu dokumentów może być wzbogacany o dodatkowe funkcje. Warto pokusić się na przykład o takie modyfikacje:

• Aktualizacja istniejących dokumentów - obecnie przy ponownym przebiegu skrypty tworzone są kopie oraz nie są usuwane dokumenty, których już brak w referencyjnym repozytorium.
• Wyciąganie z plików MS Word dodatkowych informacji - na przykład autor dokumentu, data modyfikacji, słowa kluczowe itp.

Dodatkowo prześledzenie działania skryptu do importu może być cenną wskazówką co do tego, w jaki sposób przy użyciu Visual Basic z poziomu EA można "dobrać się" do zawartości plików MS Word na przykład w celu automatycznego importu wymagań z plików MS Word.