Exportación de especificaciones basada en la plantilla de Microsoft Word (actualización de noviembre)

Aprovechando la API de Python y Rest de Requirements & Systems Portal, que permite acceso completo a todos los datos, y combinándola con la funcionalidad de Campos de combinación de Microsoft Word, existe una funcionalidad de un solo clic para exportar sus especificaciones de requisitos a un documento de Word. Esta funcionalidad le brinda la oportunidad de elegir qué campos de requisitos desea incluir en su documento y cómo colocarlos.

Campos de combinación y plantillas

Los campos de combinación se utilizan como referencia a un campo de datos por su nombre. Cuando un documento de plantilla se combina con los valores de una fuente de datos, la información del campo de datos reemplaza al campo de combinación.

Al crear un documento de plantilla con diferentes campos de combinación, es posible generar rápidamente el mismo tipo de documento de salida (especificaciones u otros) basándose en ellos.

Crear un nuevo campo de combinación

1. Abra el documento que desea editar y vaya a la pestaña Insert.

2. Abra el menú Quick Partd y seleccione Field. Se abrirá la ventana de diálogo Field.

3. En el menú de diálogo de campos, elija Merge Field de la lista del lado izquierdo. Introduzca el nombre del campo de combinación en el cuadro de texto Field name del lado derecho y haga clic en OK.
   Consejo: asigne al campo un nombre basado en los datos por los que desea que sea reemplazado para que sea más fácil de rastrear

4. El campo de combinación se inserta en el archivo de Word. El objeto debería resaltarse en gris si hace clic sobre él.

Los campos de combinación que ya tienen funciones de Python correspondientes definidas son:

«req_id» - Identificador del requisito
«req_title» - Título del requisito
«req_text» - Texto del requisito
«req_state» - Estado del requisito 
«req_type» - Tipo de requisito
«req_rationale» – La justificación asociada a un requisito 
«images» – Las imágenes adjuntas a un requisito
«specification_name» - Especificación que contiene el requisito
«section_name» - Sección que contiene el requisito
«req_compliance» - Declaración(es) de cumplimiento de los requisitos
«req_comp_comment» - Comentarios de cumplimiento de los requisitos
«req_owner» - Propietario de los requisitos 
«req_applicability» - Aplicabilidad de los requisitos
«req_ver_methods» - Métodos de verificación de los requisitos
«req_ver_m_text» - Comentarios de los métodos de verificación de los requisitos
«req_ver_closeout_ref» - Referencias de cierre de los métodos de verificación de los requisitos
«req_ver_status» - Estado de los métodos de verificación de los requisitos

Creación de plantillas (para replicación de plantillas)

Se puede utilizar una combinación de campos de combinación para crear los archivos de plantilla que se usarán para generar los documentos de especificación.

A continuación se muestra un ejemplo de una plantilla en la que algunos campos están escritos como “texto sin formato” y otros como parte de una tabla. Este ejemplo es el ejemplo base para los scripts de Python que se describirán en la siguiente sección.

El resultado de salida de esta plantilla se vería similar a la imagen de abajo

Script de Python para completar la plantilla

El script de Python que se utiliza para generar documentos basados en una plantilla completada con campos de combinación se basa en el uso de los siguientes paquetes principales:

• valispace - La API de Python de Requirements & Systems Portal le permite acceder y actualizar objetos en Requirements & Systems Portal.

• docx-mailmerge2 - Realiza una combinación de correspondencia (reemplaza los campos de combinación con los datos deseados) en archivos Office Open XML (Docx) y puede utilizarse en cualquier sistema sin necesidad de instalar Microsoft Office Word.

• python-docx - Biblioteca de Python para crear y actualizar archivos de Microsoft Word (.docx).

• htmldocx - Biblioteca de Python para convertir HTML a Docx. Se utiliza para mantener el formato de Requirements & Systems Portal en Word (negrita, cursiva, viñetas…)

El código se divide en 3 tipos de funciones:

• Master functions - Compuesto por las funciones main y create_specification_document, que contienen la lógica para exportar los requisitos al documento final completando la plantilla dada

• Requirement data extract functions- Son todas las funciones para extraer los datos del requisito, como el tipo de requisito, el estado, las imágenes…

• Document "Format" functions- Funciones que realizan formato, como la eliminación de espacios en blanco y asegurar que las tablas no se dividan en el documento final generado

En el siguiente subcapítulo, explicamos brevemente estas funciones.

Funciones maestras - Main

Esta función permite al usuario insertar el nombre del dominio, su nombre de usuario y contraseña, el identificador del proyecto del que generar las especificaciones y la ruta al archivo de plantilla

Luego utilizará esta información para:

1. Iniciar sesión en Requirements & Systems Portal usando la API de Python;

2. Descargar datos genéricos del proyecto, como especificaciones, imágenes, tipos de requisitos y otros;

3. Llamar a la función create_specification_document para cada especificación en el proyecto seleccionado.

Funciones maestras - Create_specification_document

Las funciones crearán el archivo de especificaciones completando los campos de combinación de la plantilla con los datos correspondientes del requisito.

Inicialmente, es necesario recopilar todos los requisitos de la especificación seleccionada:

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

Luego organizará los datos de los requisitos por sección, comenzando por los requisitos sin ninguna sección.

Para obtener estos requisitos sin sección, se utiliza la función de soporte get_requirements_without_section para filtrar todos los requisitos de la especificación que no tienen un grupo (cómo se almacenan las secciones en el backend de Requirements & Systems Portal) y ordenarlos alfabéticamente.

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

Ahora que se han recopilado todos los requisitos sin sección, es momento de preparar los datos que completarán los campos de combinación. Estos datos se obtienen con la ayuda de Requirement data extract functions y se almacenarán en la lista de Python como se muestra en el siguiente código.

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

Para la mayoría de los campos de combinación, los datos se asignan directamente, pero para images y req_text los datos se combinarán en una etapa posterior:

• Para images, se almacena como dato una marca que indica si el requisito tiene imágenes o no

• Para req_text, se almacena como dato un marcador de posición. Este marcador de posición también se utilizará como clave en una lista que contiene el resultado de analizar el texto del requisito desde HTML a Word, como se muestra en el siguiente código

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

El mismo proceso se repetirá para los requisitos que tienen secciones y, una vez hecho esto, los datos se combinarán en los campos de la plantilla y se almacenarán como un nuevo archivo:

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

Finalmente, utilizaremos Document "Format" functions para finalizar el documento eliminando secciones vacías y encabezados vacíos, manteniendo las tablas en una sola página e insertando en el documento el texto con formato de los requisitos y sus imágenes

    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'])

Funciones de extracción de datos de requisitos

Las funciones disponibles para extraer datos de los requisitos son las siguientes:

• get_requirements_without_section - Devuelve una lista ordenada de todos los requisitos sin sección

• get_specification_sections - Devuelve una lista de todas las secciones de la especificación dada

• get_section_requirements - Devuelve una lista ordenada de todos los requisitos de la sección dada

• get_requirement_images - Devuelve un arreglo de todas las imágenes del requisito

• get_requirement_type - Devuelve el nombre del tipo de requisito

• get_requirement_state - Devuelve el nombre del estado del requisito

• get_requirement_owner - Devuelve los grupos de usuarios y el nombre y apellido del propietario del requisito

• get_requirement_applicability - Devuelve una lista de todos los tipos de bloque aplicables al requisito, separados por “;”

• get_requirement_verification_methods - Devuelve el nombre de todos los métodos de verificación del requisito, separados por “;”

• get_requirement_verification_methods_newline - Devuelve el nombre de todos los métodos de verificación del requisito, separados por un salto de línea

• get_requirement_verification_methods_comments - Devuelve todos los comentarios de los métodos de verificación del requisito, separados por doble salto de línea

• get_requirement_verification_status - Devuelve el estado de todos los métodos de verificación de requisitos, separados por “;”

• get_requirement_verification_closeout_refs - Devuelve los nombres de las referencias de cierre para cada método de verificación de requisitos, separados por “;”

• get_requirement_attachments_references - Devuelve el nombre de todos los archivos adjuntos del requisito, separados por “;”

• get_requirement_custom_field - Devuelve el valor de un campo personalizado específico del requisito que se pasa como argumento a la función

Funciones de "Formato" del documento

Las funciones utilizadas para dar formato al documento final son las siguientes:

• keep_tables_on_one_page - Da formato al documento final para evitar que el contenido de las celdas de las tablas se distribuya entre diferentes páginas.

• remove_all_empty_headings - Da formato al documento final para eliminar todos los encabezados vacíos

• remove_all_but_last_section - Da formato al documento final para que tenga una sola sección en lugar de varias

• put_images - Reemplaza el marcador de posición de las imágenes con las imágenes de cada requisito

• clone_run_props - función auxiliar para copiar las propiedades de una ejecución a otra (se utiliza para copiar las propiedades de texto con formato HTML)

• put_html_text - Reemplaza el marcador de posición del texto del requisito con el texto con el formato correspondiente, como negrita, cursiva, subrayado, tachado y viñetas

Descargue la última plantilla genérica, script de Python o ejecutable

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

Cosas que se deben editar antes de ejecutar el script:

El procedimiento completo sobre cómo ejecutar este código, desde la creación de los scripts hasta la generación del documento, se ha ilustrado en el siguiente video (sin audio).
 

Line 27 - Line 30 El usuario debe definir el nombre de usuario y la contraseña para que el script se ejecute. El usuario puede usar la gestión de secretos y ejecutar el script, o introducir directamente el nombre de usuario y la contraseña en el script. Sin embargo, la contraseña será visible para todos los usuarios dentro de la implementación. Por lo tanto, le recomendamos utilizar “Secrets Management”.

Line 31 Copie el nombre de la especificación e introdúzcalo en esta línea.

Line 32 Cargue la plantilla de especificación genérica en la gestión de archivos, copie su “ID” y agréguelo en esta línea.

Line 33 Agregue el “ID” del proyecto donde se encuentra la especificación.

Line 34 Puede proporcionar un nombre al documento exportado.

Si necesita orientación sobre cómo cambiar la plantilla, extraer otra información para completar sus plantillas o tiene cualquier pregunta relacionada con esta función, no dude en enviarnos sus preguntas/solicitudes a través de nuestra página de soporte de Altium.