Esportazione delle specifiche basata su un modello Microsoft Word (aggiornamento di novembre)

Sfruttando l’API Python & Rest di Requirements & Systems Portal, che consente l’accesso completo a tutti i dati, e combinandola con la funzionalità Merge Fields di Microsoft Word, è disponibile una funzione con un solo clic per esportare le tue specifiche dei requisiti in un documento Word. Questa funzionalità ti offre la possibilità di scegliere quali campi dei requisiti includere nel documento e come posizionarli.

Campi unione e modelli

I campi unione vengono utilizzati come riferimento a un campo dati tramite il relativo nome. Quando un documento modello viene unito ai valori provenienti da una sorgente dati, le informazioni del campo dati sostituiscono il campo unione.

Creando un documento modello con diversi campi unione, è possibile generare rapidamente lo stesso tipo di documento di output (specifiche o altro) basandosi su di essi.

Creare un nuovo campo unione

1. Apri il documento che desideri modificare e vai alla scheda Insert.

2. Apri il menu Quick Partd e seleziona Field. Si aprirà la finestra di dialogo Field.

3. Nel menu della finestra di dialogo dei campi, scegli Merge Field dall’elenco sul lato sinistro. Inserisci il nome del campo unione nella casella di testo Field name sul lato destro e fai clic su OK.
   Suggerimento: assegna al campo un nome basato sui dati che dovrà sostituire, così sarà più facile da tracciare

4. Il campo unione viene inserito nel file Word. L’oggetto dovrebbe essere evidenziato in grigio se fai clic su di esso.

I campi unione per i quali sono già definite le corrispondenti funzioni Python sono:

«req_id» - Identificatore del requisito
«req_title» - Titolo del requisito
«req_text» - Testo del requisito
«req_state» - Stato del requisito 
«req_type» - Tipo di requisito
«req_rationale» – Motivazione associata a un requisito 
«images» – Immagini allegate a un requisito
«specification_name» - Specifica che contiene il requisito
«section_name» - Sezione che contiene il requisito
«req_compliance» - Dichiarazione/i di conformità dei requisiti
«req_comp_comment» - Commenti di conformità dei requisiti
«req_owner» - Proprietario del requisito 
«req_applicability» - Applicabilità del requisito
«req_ver_methods» - Metodi di verifica del requisito
«req_ver_m_text» - Commenti ai metodi di verifica del requisito
«req_ver_closeout_ref» - Riferimenti di chiusura dei metodi di verifica del requisito
«req_ver_status» - Stato dei metodi di verifica del requisito

Creazione di modelli (per la replica del modello)

Una combinazione di campi unione può essere utilizzata per creare i file modello che verranno usati per generare i documenti di specifica.

Di seguito è mostrato un esempio di modello in cui alcuni campi sono scritti come “testo semplice” e altri come parte di una tabella. Questo esempio è il modello di base per gli script Python che verranno descritti nella sezione seguente.

L’output risultante di questo modello apparirà simile all’immagine seguente

Script Python per popolare il modello

Lo script Python utilizzato per generare documenti basati su un modello popolato con campi unione si basa sull’uso dei seguenti pacchetti principali:

• valispace - L’API Python di Requirements & Systems Portal consente di accedere e aggiornare gli oggetti in Requirements & Systems Portal.

• docx-mailmerge2 - Esegue una stampa unione (sostituisce i campi unione con i dati desiderati) su file Office Open XML (Docx) e può essere utilizzato su qualsiasi sistema senza dover installare Microsoft Office Word.

• python-docx - Libreria Python per creare e aggiornare file Microsoft Word (.docx).

• htmldocx - Libreria Python per convertire HTML in Docx. Utilizzata per mantenere la formattazione da Requirements & Systems Portal a Word (grassetto, corsivo, elenchi puntati…)

Il codice è suddiviso in 3 tipi di funzioni:

• Master functions - Composte dalle funzioni main e create_specification_document che contengono la logica per esportare i requisiti nel documento finale popolando il modello fornito

• Requirement data extract functions- Sono tutte le funzioni per estrarre i dati dei requisiti, come tipo di requisito, stato, immagini…

• Document "Format" functions- Funzioni che eseguono la formattazione, come la rimozione degli spazi bianchi e l’assicurarsi che le tabelle non si spezzino nel documento finale generato

Nel sottocapitolo seguente spieghiamo brevemente queste funzioni.

Funzioni principali - Main

Questa funzione consente all’utente di inserire il nome del dominio, il nome utente e la password, l’identificatore del progetto da cui generare le specifiche e il percorso del file modello

Successivamente utilizzerà queste informazioni per:

1. Accedere a Requirements & Systems Portal utilizzando l’API Python;

2. Scaricare i dati generici del progetto, come specifiche, immagini, tipi di requisito e altri;

3. Chiamare la funzione create_specification_document per ogni specifica nel progetto selezionato.

Funzioni principali - Create_specification_document

Le funzioni genereranno il file delle specifiche popolando i campi unione del modello con i corrispondenti dati dei requisiti.

Inizialmente, è necessario raccogliere tutti i requisiti della specifica selezionata:

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("No requirements for Specification -> "+ specification_data['name'])
        return

Successivamente organizzerà i dati dei requisiti per sezione, iniziando dai requisiti senza alcuna sezione.

Per ottenere questi requisiti senza sezione viene utilizzata la funzione di supporto get_requirements_without_section per filtrare tutti i requisiti della specifica che non hanno un gruppo (il modo in cui le sezioni sono memorizzate nel backend di Requirements & Systems Portal) e ordinarli alfabeticamente.

    #1st we will add requirements without section to the document
    no_section_requirements = get_requirements_without_section(all_specification_requirements)

Ora che tutti i requisiti senza sezione sono stati raccolti, è il momento di preparare i dati che popoleranno i campi unione. Questi dati vengono recuperati con l’aiuto di Requirement data extract functions e verranno memorizzati nella lista Python come mostrato nel codice seguente.

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

Per la maggior parte dei campi unione, i dati vengono mappati direttamente, ma per images e req_text i dati verranno uniti in una fase successiva:

• Per images viene memorizzato come dato un flag che indica se il requisito ha immagini oppure no

• Per req_text viene memorizzato come dato un segnaposto. Questo segnaposto verrà utilizzato anche come chiave in un elenco che contiene il risultato del parsing del testo del requisito da HTML a Word, come mostrato nel codice seguente

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

Lo stesso processo verrà ripetuto per i requisiti che hanno sezioni e, una volta completato, i dati verranno uniti ai campi del modello e salvati come nuovo file:

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

Infine, utilizzeremo Document "Format" functions per finalizzare il documento rimuovendo le sezioni vuote e le intestazioni vuote, mantenendo le tabelle su una sola pagina e inserendo nel documento il testo formattato dei requisiti e le relative immagini

    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 ("Specification document created -> "+ specification_data['name'])

Funzioni di estrazione dei dati dei requisiti

Le funzioni disponibili per estrarre i dati dai requisiti sono le seguenti:

• get_requirements_without_section - Restituisce un elenco ordinato di tutti i requisiti senza sezione

• get_specification_sections - Restituisce un elenco di tutte le sezioni della specifica fornita

• get_section_requirements - Restituisce un elenco ordinato di tutti i requisiti della sezione fornita

• get_requirement_images - Restituisce un array di tutte le immagini dei requisiti

• get_requirement_type - Restituisce il nome del tipo di requisito

• get_requirement_state - Restituisce il nome dello stato del requisito

• get_requirement_owner - Restituisce i gruppi di utenti e il nome e cognome del proprietario del requisito

• get_requirement_applicability - Restituisce un elenco di tutti i tipi di blocco applicabili al requisito, separati da un “;”

• get_requirement_verification_methods - Restituisce il nome di tutti i metodi di verifica del requisito, separati da un “;”

• get_requirement_verification_methods_newline - Restituisce il nome di tutti i metodi di verifica del requisito, separati da un ritorno a capo

• get_requirement_verification_methods_comments - Restituisce tutti i commenti dei metodi di verifica del requisito, separati da un doppio ritorno a capo

• get_requirement_verification_status - Restituisce lo stato di tutti i metodi di verifica dei requisiti, separati da un “;”

• get_requirement_verification_closeout_refs - Restituisce i nomi dei riferimenti di chiusura per ciascun metodo di verifica dei requisiti, separati da un “;”

• get_requirement_attachments_references - Restituisce il nome di tutti gli allegati dei requisiti, separati da un “;”

• get_requirement_custom_field - Restituisce il valore di uno specifico campo personalizzato del requisito passato come argomento alla funzione

Funzioni di "formattazione" del documento

Le funzioni utilizzate per formattare il documento finale sono le seguenti:

• keep_tables_on_one_page - Formatta il documento finale in modo da non consentire che il contenuto delle celle delle tabelle si estenda su pagine diverse.

• remove_all_empty_headings - Formatta il documento finale per rimuovere tutte le intestazioni vuote

• remove_all_but_last_section - Formatta il documento finale in modo che abbia una sola sezione invece di più sezioni

• put_images - Sostituisce il segnaposto delle immagini con le immagini di ciascun requisito

• clone_run_props - funzione ausiliaria per copiare le proprietà di un run in un altro (utilizzata per copiare le proprietà del testo formattato in HTML)

• put_html_text - Sostituisce il segnaposto del testo del requisito con il corrispondente testo formattato, ad esempio grassetto, corsivo, sottolineato, barrato ed elenchi puntati

Scarica l'ultimo Generic Template, script Python o eseguibile

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

Elementi da modificare prima di eseguire lo script:

La procedura completa su come eseguire questo codice, dalla creazione degli script alla generazione del documento, è illustrata nel video qui sotto (senza audio).
 

Line 27 - Line 30 L'utente deve definire Username e Password affinché lo script possa essere eseguito. L'utente può utilizzare la gestione dei segreti ed eseguire lo script oppure inserire direttamente Username e Password nello script. Tuttavia, la password sarà visibile a tutti gli utenti all'interno della distribuzione. Pertanto, consigliamo di utilizzare “Secrets Management”.

Line 31 Copiare il nome della specifica e inserirlo in questa riga.

Line 32 Caricare il template della specifica generica nella gestione file, copiarne l’“ID” e aggiungerlo in questa riga.

Line 33 Aggiungere l’“ID” del progetto in cui si trova la specifica.

Line 34 È possibile fornire un nome al documento esportato.

Nel caso in cui abbiate bisogno di indicazioni su come modificare il template, estrarre altre informazioni per popolare i vostri template o per qualsiasi domanda relativa a questa funzionalità, non esitate a inviarci le vostre domande/richieste tramite la nostra Altium Support Page.