Eksport specyfikacji w oparciu o szablon Microsoft Word (aktualizacja z listopada)

Wykorzystując interfejs API Python i Rest portalu Requirements & Systems Portal, który umożliwia pełny dostęp do wszystkich danych i łącząc go z funkcją scalania pól programu Microsoft Word, można jednym kliknięciem wyeksportować specyfikację wymagań do dokumentu Word. Funkcjonalność ta daje możliwość wyboru pól wymagań, które mają być zawarte w dokumencie i sposobu ich umieszczenia.

Pola scalania i szablony

Pola scalania są używane jako odniesienie do pola danych według ich nazwy. Gdy szablon dokumentu jest scalany pocztą z wartościami ze źródła danych, informacje o polu danych zastępują pole scalania.

Tworząc szablon dokumentu z różnymi polami scalania, można szybko wygenerować na ich podstawie ten sam typ dokumentu wyjściowego (specyfikacje lub inne).

Tworzenie nowego pola scalania

1. Otwórz dokument, który chcesz edytować i przejdź do zakładki Insert.

2. Otwórz menu Quick Partd i wybierz Field. Otworzy się okno dialogowe Field.

3. W menu dialogowym pola wybierz Merge Field z listy po lewej stronie. Wprowadź nazwę pola scalania w polu tekstowym Field name po prawej stronie i kliknij OK.
   Wskazówka: Nazwij pole na podstawie danych, które mają zostać zastąpione, aby ułatwić śledzenie

4. Pole scalania zostanie wstawione do pliku Word. Po kliknięciu obiekt powinien zostać podświetlony na szaro.

Połączone pola, które mają już zdefiniowane odpowiednie funkcje Pythona to:

"req_id" - Identyfikator wymagania
"req_title" - Tytuł wymagania
"req_text" - tekst wymagania
"req_state" - stan wymagania 
"req_type" - typ wymagania
"req_rationale" - Uzasadnienie powiązane z wymaganiem 
"images" - obrazy dołączone do wymagania
"specification_name" - specyfikacja zawierająca wymaganie
"section_name" - Sekcja zawierająca wymaganie
"req_compliance" - Oświadczenie(a) o zgodności z wymaganiami
"req_comp_comment" - komentarze dotyczące zgodności wymagań
"req_owner" - Właściciel wymagań 
"req_applicability" - Zastosowanie wymagań
"req_ver_methods" - Metody weryfikacji wymagań
"req_ver_m_text" - Komentarze do metod weryfikacji wymagań
"req_ver_closeout_ref" - Referencje zamknięcia metod weryfikacji wymagań
"req_ver_status" - Status metod weryfikacji wymagań

Tworzenie szablonów (dla replikacji szablonów)

Kombinacja pól scalania może być użyta do utworzenia plików szablonów, które będą używane do generowania dokumentów specyfikacji.

Poniżej przedstawiono przykład szablonu, w którym niektóre pola są zapisane "zwykłym tekstem", a inne jako część tabeli. Ten przykład jest przykładem bazowym dla skryptów Python, które zostaną opisane w następnej sekcji.

Wynikowy wynik tego szablonu będzie wyglądał podobnie do poniższego obrazka

Skrypt Python do wypełniania szablonu

Skrypt Pythona, który jest używany do generowania dokumentów na podstawie szablonu wypełnionego polami scalania, wykorzystuje następujące główne pakiety:

• valispace - Python API portalu wymagań i systemów umożliwia dostęp i aktualizację obiektów w portalu wymagań i systemów.

• docx-mailmerge2 - Wykonuje scalanie poczty (zastępuje pola scalania żądanymi danymi) na plikach Office Open XML (Docx) i może być używany w dowolnym systemie bez konieczności instalowania programu Microsoft Office Word.

• python-docx - Biblioteka Python do tworzenia i aktualizowania plików Microsoft Word (.docx).

• htmldocx - Biblioteka Python do konwersji HTML na Docx. Służy do zachowania formatu z portalu wymagań i systemów do Worda (pogrubienie, kursywa, punktory...)

Kod jest podzielony na 3 typy funkcji:

• Master functions - Złożony z funkcji main i create_specification_document, które mają logikę eksportowania wymagań do dokumentu końcowego poprzez wypełnienie danego szablonu

• Requirement data extract functions- Wszystkie funkcje wyodrębniające dane wymagań, takie jak typ wymagania, stan, obrazy..

• Document "Format" functions- Funkcje, które wykonują formatowanie, takie jak usuwanie białych spacji, upewniając się, że tabele nie są łamane w końcowym wygenerowanym dokumencie

W poniższym podrozdziale krótko wyjaśnimy te funkcje.

Funkcje główne - Główna

Ta funkcja pozwala użytkownikowi wprowadzić nazwę domeny, nazwę użytkownika i hasło, identyfikator projektu do wygenerowania specyfikacji oraz ścieżkę do pliku szablonu

Następnie użyje tych informacji do:

1. Zalogowania się do portalu wymagań i systemów za pomocą interfejsu API Python;

2. Pobrania ogólnych danych projektu, takich jak specyfikacje, obrazy, typy wymagań i inne;

3. Wywołanie funkcji create_specification_documentdla każdej specyfikacji w wybranym projekcie.

Funkcje główne - Create_specification_document

Funkcje utworzą plik specyfikacji, wypełniając pola scalania w szablonie odpowiednimi danymi wymagań.

Początkowo należy zebrać wszystkie wymagania dla wybranej specyfikacji:

all_specification_requirements = get_map(api, f "requirements/complete/?project="+str(DEFAULT_VALUES["project"])+"&clean_html=text&clean_text=comment", "id", None, filter_specification)
    if len(all_specification_requirements) 1:
        print("Brak wymagań dla Specification -> "+ specification_data['name'])
        return

Następnie uporządkuje dane wymagań według sekcji, zaczynając od wymagań bez żadnej sekcji.

Aby uzyskać te wymagania bez sekcji, funkcja pomocnicza get_requirements_without_sectionjest używana do filtrowania wszystkich wymagań specyfikacji, które nie mają grupy (w jaki sposób sekcje są przechowywane w zapleczu portalu wymagań i systemów) i sortowania alfabetycznego.

    #1st dodamy wymagania bez sekcji do dokumentu
    no_section_requirements = get_requirements_without_section(all_specification_requirements)

Teraz, gdy wszystkie wymagania bez sekcji zostały zebrane, nadszedł czas na przygotowanie danych, które wypełnią pola scalania. Dane te są pobierane za pomocą Requirement data extract functions i będą przechowywane na liście Pythona, jak pokazano w poniższym kodzie.

template_data.append({
                "specification_name" : CURRENT_SPECIFICATION["name"] if counter == 1 else "",
                "section_name" : "", 
                "req_id" : reqdata['identifier'],
                "req_title" : reqdata['title'],
                "req_text" : reqdata['identifier']+"_docx",
                "req_type" : req_type,
                "req_rationale" : reqdata['comment'],
                "req_ver_methods" : req_vms,
                "req_applicability" : req_applicability, 
                "images" : "Images_Placeholder_"+str(requirement) if requirement_with_images == True else "No_Images" }
            })

W przypadku większości pól Merged dane są mapowane bezpośrednio, ale w przypadku imagesireq_textdane zostaną scalone na późniejszym etapie:

• W przypadku images flaga wskazująca, czy wymaganie ma obrazy, czy nie, jest przechowywana jako dane

• Dla req_textsymbol zastępczy jest przechowywany jako dane. Ten symbol zastępczy będzie również używany jako klucz na liście zawierającej wynik parsowania tekstu wymagania z HTML do Worda, jak pokazano w poniższym kodzie

  docx_list[reqdata['identifier']+"_docx"] = new_parser.parse_html_string(reqdata['text'])

Ten sam proces zostanie powtórzony dla wymagań, które mają sekcje, a po zakończeniu dane zostaną scalone z polami szablonu i zapisane jako nowy plik:

document.merge_templates(template_data, separator='continuous_section')
document.write(OUTPUT_FILE)

Na koniec użyjemy Document "Format" functions do sfinalizowania dokumentu, usuwając puste sekcje i puste nagłówki, utrzymując tabele na jednej stronie, wstawiając sformatowany tekst wymagań i ich obrazy do dokumentu

    document2 = Document(OUTPUT_FILE)
    remove_all_but_last_section(document2)
    remove_all_empty_headings(document2)
    put_html_text(document2, docx_list)
    put_images(document2, all_project_images)   
    keep_tables_on_one_page(document2)

    document2.save(OUTPUT_FILE)
    print ("Utworzono dokument specyfikacji -> "+ specification_data['name'])

Funkcje wyodrębniania danych wymagań

Funkcje dostępne do wyodrębniania danych z wymagań są następujące:

• get_requirements_without_section - Zwraca posortowaną listę wszystkich wymagań bez sekcji

• get_specification_sections - Zwraca listę wszystkich sekcji danej specyfikacji

• get_section_requirements - Zwraca posortowaną listę wszystkich wymagań danej sekcji

• get_requirement_images - Zwraca tablicę wszystkich obrazów wymagań

• get_requirement_type - Zwraca nazwę typu wymagania

• get_requirement_state - Zwraca nazwę wymagania State

• get_requirement_owner - Zwraca grupy użytkowników oraz imię i nazwisko właściciela wymagania

• get_requirement_applicability - Zwraca listę wszystkich typów bloków mających zastosowanie do wymagań, rozdzielonych znakiem ";"

• get_requirement_verification_methods - Zwraca nazwy wszystkich metod weryfikacji wymagań, rozdzielone znakiem ";"

• get_requirement_verification_methods_newline - Zwraca nazwy wszystkich metod weryfikacji wymagań, rozdzielone znakiem nowej linii

• get_requirement_verification_methods_comments - Zwraca wszystkie komentarze do metod weryfikacji wymagań, rozdzielone podwójną nową linią

• get_requirement_verification_status - Zwraca status wszystkich metod weryfikacji wymagań, rozdzielony znakiem ";"

• get_requirement_verification_closeout_refs - Zwraca nazwy referencji zamknięcia dla każdego wymagania Metody weryfikacji, podzielone przez ";"

• get_requirement_attachments_references - Zwraca nazwy wszystkich załączników wymagań, podzielone przez ";"

• get_requirement_custom_field - Zwraca wartość określonego pola niestandardowego w wymaganiu, które zostało przekazane jako argument do funkcji

Funkcje formatowania dokumentu

Funkcje używane do formatowania dokumentu końcowego są następujące:

• keep_tables_on_one_page - Formatuje dokument końcowy, aby nie zezwalać tabelom na zawartość komórek na różnych stronach.

• remove_all_empty_headings - Formatuje dokument końcowy, aby usunąć wszystkie puste nagłówki

• remove_all_but_last_section - Formatuje dokument końcowy tak, aby miał tylko jedną sekcję zamiast wielu

• put_images - Zastępuje obrazy zastępcze obrazami każdego wymagania

• clone_run_props - funkcja pomocnicza do kopiowania właściwości przebiegu do innego (używana do kopiowania właściwości tekstu sformatowanego HTML)

• put_html_text - Zastępuje symbol zastępczy tekstu wymagania odpowiednim sformatowanym tekstem, takim jak pogrubienie, kursywa, podkreślenie, przekreślenie i punktor

Pobierz najnowszy szablon ogólny, skrypt Python lub plik wykonywalny

Tworzenie specyfikacji ogólnej Nov2023.py Szablon specyfikacji ogólnej.docx requirements.txt

Rzeczy do edycji przed uruchomieniem skryptu:

Pełna procedura uruchamiania tego kodu, od tworzenia skryptów do generowania dokumentu, została zilustrowana na poniższym filmie (bez dźwięku).

Line 27 - Line 30 Użytkownik musi zdefiniować nazwę użytkownika i hasło do uruchomienia skryptu. Użytkownik może użyć tajnego zarządzania i uruchomić skrypt lub bezpośrednio wprowadzić nazwę użytkownika i hasło w skrypcie. Hasło będzie jednak widoczne dla wszystkich użytkowników w ramach wdrożenia. Dlatego zalecamy korzystanie z "Zarządzania sekretami".

Line 31 Skopiuj nazwę specyfikacji i wprowadź ją w tym wierszu.

Line 32 Prześlij szablon specyfikacji ogólnej do zarządzania plikami, skopiuj jego "ID" i dodaj go w tym wierszu.

Line 33 Dodaj "ID" projektu, w którym znajduje się specyfikacja.

Line 34 Możesz nadać nazwę eksportowanemu dokumentowi.

Jeśli potrzebujesz wskazówek dotyczących zmiany szablonu, wyodrębniania innych informacji w celu wypełnienia szablonów lub jakichkolwiek pytań związanych z tą funkcją, prześlij nam swoje pytania / prośby za pośrednictwem naszej strony pomocy technicznej Altium.