Spezifikationsexport basierend auf einer Microsoft-Word-Vorlage (November-Update)

Durch die Nutzung der Python- & Rest-API des Requirements & Systems Portal, die vollständigen Zugriff auf alle Daten ermöglicht, und in Kombination mit der Seriendruckfeld-Funktionalität von Microsoft Word gibt es eine Ein-Klick-Funktion zum Exportieren Ihrer Anforderungsspezifikationen in ein Word-Dokument. Diese Funktionalität gibt Ihnen die Möglichkeit auszuwählen, welche Anforderungsfelder Sie in Ihr Dokument aufnehmen möchten und wie diese platziert werden sollen.

Seriendruckfelder und Vorlagen

Seriendruckfelder werden als Verweis auf ein Datenfeld anhand seines Namens verwendet. Wenn ein Vorlagendokument per Seriendruck mit den Werten aus einer Datenquelle zusammengeführt wird, ersetzt die Datenfeldinformation das Seriendruckfeld.

Durch das Erstellen eines Vorlagendokuments mit verschiedenen Seriendruckfeldern ist es möglich, schnell denselben Typ von Ausgabedokument (Spezifikationen oder andere) auf dieser Basis zu erzeugen.

Ein neues Seriendruckfeld erstellen

1. Öffnen Sie das Dokument, das Sie bearbeiten möchten, und wechseln Sie zur Registerkarte Insert.

2. Öffnen Sie das Menü Quick Partd und wählen Sie Field. Das Dialogfenster Field wird geöffnet.

3. Wählen Sie im Menü des Felddialogs Merge Field aus der Liste auf der linken Seite. Geben Sie den Namen des Seriendruckfelds in das Textfeld Field name auf der rechten Seite ein und klicken Sie auf OK.
   Hinweis: Benennen Sie das Feld anhand der Daten, durch die es ersetzt werden soll, damit es leichter nachverfolgt werden kann

4. Das Seriendruckfeld wird in die Word-Datei eingefügt. Das Objekt sollte grau hervorgehoben sein, wenn Sie darauf klicken.

Die Seriendruckfelder, für die bereits entsprechende Python-Funktionen definiert sind, sind:

«req_id» - Anforderungskennung
«req_title» - Anforderungstitel
«req_text» - Anforderungstext
«req_state» - Anforderungsstatus 
«req_type» - Anforderungstyp
«req_rationale» – Die einer Anforderung zugeordnete Begründung 
«images» – Die an eine Anforderung angehängten Bilder
«specification_name» - Spezifikation, die die Anforderung enthält
«section_name» - Abschnitt, der die Anforderung enthält
«req_compliance» - Compliance-Aussage(n) der Anforderung
«req_comp_comment» - Compliance-Kommentare der Anforderung
«req_owner» - Eigentümer der Anforderung 
«req_applicability» - Anwendbarkeit der Anforderung
«req_ver_methods» - Verifikationsmethoden der Anforderung
«req_ver_m_text» - Kommentare zu den Verifikationsmethoden der Anforderung
«req_ver_closeout_ref» - Abschlussreferenzen der Verifikationsmethoden der Anforderung
«req_ver_status» - Status der Verifikationsmethoden der Anforderung

Vorlagen erstellen (für Vorlagenreplikation)

Eine Kombination von Seriendruckfeldern kann verwendet werden, um die Vorlagendateien zu erstellen, die zur Generierung der Spezifikationsdokumente verwendet werden.

Ein Beispiel für eine Vorlage ist unten dargestellt, bei der einige Felder als „Klartext“ und andere als Teil einer Tabelle geschrieben sind. Dieses Beispiel ist die Basisvorlage für die Python-Skripte, die im folgenden Abschnitt beschrieben werden.

Die resultierende Ausgabe dieser Vorlage würde dem untenstehenden Bild ähneln.

Python-Skript zum Befüllen der Vorlage

Das Python-Skript, das verwendet wird, um Dokumente auf Basis einer mit Seriendruckfeldern befüllten Vorlage zu erzeugen, basiert auf der Verwendung der folgenden Hauptpakete:

• valispace - Die Python-API des Requirements & Systems Portal ermöglicht Ihnen den Zugriff auf und die Aktualisierung von Objekten im Requirements & Systems Portal.

• docx-mailmerge2 - Führt einen Seriendruck aus (ersetzt die Seriendruckfelder durch die gewünschten Daten) in Office Open XML (Docx)-Dateien und kann auf jedem System verwendet werden, ohne dass Microsoft Office Word installiert sein muss.

• python-docx - Python-Bibliothek zum Erstellen und Aktualisieren von Microsoft Word-Dateien (.docx).

• htmldocx - Python-Bibliothek zur Konvertierung von HTML in Docx. Wird verwendet, um die Formatierung vom Requirements & Systems Portal in Word beizubehalten (Fett, Kursiv, Aufzählungspunkte …)

Der Code ist in 3 Funktionstypen unterteilt:

• Master functions - Besteht aus den Funktionen main und create_specification_document, die die Logik enthalten, um die Anforderungen durch Befüllen der angegebenen Vorlage in das endgültige Dokument zu exportieren

• Requirement data extract functions- Dies sind alle Funktionen zum Extrahieren von Anforderungsdaten wie Anforderungstyp, Status, Bilder …

• Document "Format" functions- Funktionen, die Formatierungen durchführen, wie das Entfernen von Leerraum oder das Sicherstellen, dass Tabellen im endgültig erzeugten Dokument nicht über Seiten umbrechen

Im folgenden Unterkapitel erläutern wir diese Funktionen kurz.

Master-Funktionen - Main

Diese Funktion ermöglicht es dem Benutzer, den Domainnamen, den Benutzernamen und das Passwort, die Projektkennung, aus der die Spezifikationen erzeugt werden sollen, sowie den Pfad zur Vorlagendatei einzugeben.

Dann werden diese Informationen verwendet, um:

1. sich über die Python-API beim Requirements & Systems Portal anzumelden;

2. allgemeine Projektdaten wie Spezifikationen, Bilder, Anforderungstypen und andere herunterzuladen;

3. die Funktion create_specification_document für jede Spezifikation im ausgewählten Projekt aufzurufen.

Master-Funktionen - Create_specification_document

Die Funktionen erzeugen die Spezifikationsdatei, indem sie die Seriendruckfelder in der Vorlage mit den entsprechenden Anforderungsdaten befüllen.

Zunächst müssen alle Anforderungen für die ausgewählte Spezifikation gesammelt werden:

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("Keine Anforderungen für Spezifikation -> "+ specification_data['name'])
        return

Dann werden die Anforderungsdaten nach Abschnitt organisiert, beginnend mit den Anforderungen ohne Abschnitt.

Um diese Anforderungen ohne Abschnitt zu erhalten, wird die Hilfsfunktion get_requirements_without_section verwendet, um alle Spezifikationsanforderungen zu filtern, die keine Gruppe haben (so werden Abschnitte im Backend des Requirements & Systems Portal gespeichert), und sie alphabetisch zu sortieren.

    #Zuerst fügen wir Anforderungen ohne Abschnitt zum Dokument hinzu
    no_section_requirements = get_requirements_without_section(all_specification_requirements)

Nachdem nun alle Anforderungen ohne Abschnitt gesammelt wurden, ist es an der Zeit, die Daten vorzubereiten, die die Seriendruckfelder befüllen werden. Diese Daten werden mit Hilfe von Requirement data extract functions abgerufen und wie im folgenden Code gezeigt in der Python-Liste gespeichert.

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"
            })

Für die Mehrheit der Seriendruckfelder werden die Daten direkt zugeordnet, aber für imagesundreq_text werden die Daten in einem späteren Schritt zusammengeführt:

• Für images wird ein Kennzeichen gespeichert, das angibt, ob die Anforderung Bilder enthält oder nicht.

• Für req_text wird ein Platzhalter als Daten gespeichert. Dieser Platzhalter wird auch als Schlüssel in einer Liste verwendet, die das Ergebnis des Parsens des Anforderungstexts von HTML nach Word enthält, wie im folgenden Code gezeigt.

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

Der gleiche Prozess wird für die Anforderungen mit Abschnitten wiederholt, und sobald dies abgeschlossen ist, werden die Daten in die Vorlagenfelder eingefügt und als neue Datei gespeichert:

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

Abschließend verwenden wir Document "Format" functions, um das Dokument fertigzustellen, indem leere Abschnitte und leere Überschriften entfernt, Tabellen auf einer Seite gehalten sowie der formatierte Text der Anforderungen und deren Bilder in das Dokument eingefügt werden.

    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 ("Spezifikationsdokument erstellt -> "+ specification_data['name'])

Funktionen zum Extrahieren von Anforderungsdaten

Die verfügbaren Funktionen zum Extrahieren von Daten aus Anforderungen sind die folgenden:

• get_requirements_without_section - Gibt eine sortierte Liste aller Anforderungen ohne Abschnitt zurück

• get_specification_sections - Gibt eine Liste aller Abschnitte der angegebenen Spezifikation zurück

• get_section_requirements - Gibt eine sortierte Liste aller Anforderungen des angegebenen Abschnitts zurück

• get_requirement_images - Gibt ein Array aller Anforderungsbilder zurück

• get_requirement_type - Gibt den Namen des Anforderungstyps zurück

• get_requirement_state - Gibt den Namen des Anforderungsstatus zurück

• get_requirement_owner - Gibt die Benutzergruppen sowie Vor- und Nachnamen des Eigentümers der Anforderung zurück

• get_requirement_applicability - Gibt eine Liste aller anwendbaren Blocktypen der Anforderung zurück, getrennt durch ein „;“

• get_requirement_verification_methods - Gibt die Namen aller Verifikationsmethoden der Anforderung zurück, getrennt durch ein „;“

• get_requirement_verification_methods_newline - Gibt die Namen aller Verifikationsmethoden der Anforderung zurück, getrennt durch einen Zeilenumbruch

• get_requirement_verification_methods_comments - Gibt alle Kommentare zu den Verifikationsmethoden der Anforderung zurück, getrennt durch einen doppelten Zeilenumbruch

• get_requirement_verification_status - Gibt den Status aller Verifikationsmethoden der Anforderungen zurück, getrennt durch ein „;“

• get_requirement_verification_closeout_refs - Gibt die Namen der Abschlussreferenzen für jede Verifikationsmethode der Anforderungen zurück, getrennt durch ein „;“

• get_requirement_attachments_references - Gibt die Namen aller Anforderungsanhänge zurück, getrennt durch ein „;“

• get_requirement_custom_field - Gibt den Wert eines bestimmten benutzerdefinierten Feldes der Anforderung zurück, das als Argument an die Funktion übergeben wird

Dokument-„Format“-Funktionen

Die Funktionen, die zum Formatieren des endgültigen Dokuments verwendet werden, sind die folgenden:

• keep_tables_on_one_page - Formatiert das endgültige Dokument so, dass Tabellen keinen Zellinhalt über verschiedene Seiten hinweg haben.

• remove_all_empty_headings - Formatiert das endgültige Dokument so, dass alle leeren Überschriften entfernt werden

• remove_all_but_last_section - Formatiert das endgültige Dokument so, dass es nur einen Abschnitt statt mehrerer enthält

• put_images - Ersetzt den Bildplatzhalter durch die Bilder jeder Anforderung

• clone_run_props - Hilfsfunktion zum Kopieren der Eigenschaften eines Runs auf einen anderen (wird verwendet, um Eigenschaften von HTML-formatiertem Text zu kopieren)

• put_html_text - Ersetzt den Platzhalter für den Anforderungstext durch den entsprechend formatierten Text, z. B. Fett, Kursiv, Unterstrichen, Durchgestrichen und Aufzählungspunkte

Laden Sie die neueste generische Vorlage, das Python-Skript oder die ausführbare Datei herunter

Generic Specification Creation Nov2023.py Generic Specification Template.docx requirements.txt

Dinge, die vor dem Ausführen des Skripts bearbeitet werden müssen:

Das vollständige Verfahren zum Ausführen dieses Codes – vom Erstellen der Skripte bis zur Generierung des Dokuments – wird im folgenden Video veranschaulicht (ohne Audio).
 

Line 27 - Line 30 Der Benutzer muss Benutzername und Passwort definieren, damit das Skript ausgeführt werden kann. Der Benutzer kann die Geheimnisverwaltung verwenden und das Skript ausführen oder Benutzername und Passwort direkt im Skript eingeben. Das Passwort ist dann jedoch für alle Benutzer innerhalb der Bereitstellung sichtbar. Daher empfehlen wir Ihnen, „Secrets Management“ zu verwenden.

Line 31 Kopieren Sie den Namen der Spezifikation und geben Sie ihn in diese Zeile ein.

Line 32 Laden Sie die generische Spezifikationsvorlage in die Dateiverwaltung hoch, kopieren Sie deren „ID“ und fügen Sie sie in diese Zeile ein.

Line 33 Fügen Sie die „ID“ des Projekts hinzu, in dem sich die Spezifikation befindet.

Line 34 Sie können dem exportierten Dokument einen Namen geben.

Falls Sie Unterstützung beim Ändern der Vorlage, beim Extrahieren weiterer Informationen zum Befüllen Ihrer Vorlagen oder bei Fragen zu dieser Funktion benötigen, senden Sie uns Ihre Fragen/Anfragen bitte über unsere Altium Support Page.