Exportação de especificações com base num modelo do Microsoft Word (atualização de novembro)

Tirando partido da API Python & Rest do Requirements & Systems Portal, que permite acesso completo a todos os dados, e combinando-a com a funcionalidade Merge Fields do Microsoft Word, existe uma funcionalidade de um clique para exportar as suas especificações de requisitos para um documento Word. Esta funcionalidade dá-lhe a possibilidade de escolher que campos de requisitos pretende incluir no seu documento e como os posicionar.

Merge Fields e Templates

Os Merge Fields são utilizados como referência a um campo de dados através do respetivo nome. Quando um documento template é sujeito a mail merge com os valores de uma fonte de dados, a informação do campo de dados substitui o merge field.

Ao criar um documento template com diferentes Merge Fields, é possível gerar rapidamente o mesmo tipo de documento de saída (especificações ou outros) com base neles.

Criar um novo merge field

1. Abra o documento que pretende editar e vá para o separador Insert.

2. Abra o menu Quick Partd e selecione Field. A janela de diálogo Field será aberta.

3. No menu de diálogo de campos, escolha Merge Field na lista do lado esquerdo. Introduza o nome do merge field na caixa de texto Field name do lado direito e clique em OK.
   Dica: dê ao campo um nome baseado nos dados pelos quais pretende que seja substituído, para ser mais fácil de identificar

4. O merge field é inserido no ficheiro Word. O objeto deverá ficar realçado a cinzento se clicar nele.

Os merge fields que já têm funções Python correspondentes definidas são:

«req_id» - Identificador do requisito
«req_title» - Título do requisito
«req_text» - Texto do requisito
«req_state» - Estado do requisito 
«req_type» - Tipo de requisito
«req_rationale» – Fundamentação associada a um requisito 
«images» – As imagens anexadas a um requisito
«specification_name» - Especificação que contém o requisito
«section_name» - Secção que contém o requisito
«req_compliance» - Declaração(ões) de conformidade dos requisitos
«req_comp_comment» - Comentários de conformidade dos requisitos
«req_owner» - Proprietário dos requisitos 
«req_applicability» - Aplicabilidade dos requisitos
«req_ver_methods» - Métodos de verificação dos requisitos
«req_ver_m_text» - Comentários dos métodos de verificação dos requisitos
«req_ver_closeout_ref» - Referências de fecho dos métodos de verificação dos requisitos
«req_ver_status» - Estado dos métodos de verificação dos requisitos

Criar templates (para replicação de templates)

Uma combinação de Merge Fields pode ser utilizada para criar os ficheiros template que serão usados para gerar os documentos de especificação.

É apresentado abaixo um exemplo de template em que alguns campos são escritos em “texto simples” e outros como parte de uma tabela. Este exemplo é o exemplo base para os scripts Python que serão descritos na secção seguinte.

O resultado final deste template terá um aspeto semelhante ao da imagem abaixo

Script Python para preencher o template

O script Python utilizado para gerar documentos com base num template preenchido com merge fields assenta na utilização dos seguintes pacotes principais:

• valispace - A API Python do Requirements & Systems Portal permite-lhe aceder e atualizar objetos no Requirements & Systems Portal.

• docx-mailmerge2 - Efetua um Mail Merge (substitui os merge fields pelos dados pretendidos) em ficheiros Office Open XML (Docx) e pode ser utilizado em qualquer sistema sem necessidade de instalar o Microsoft Office Word.

• python-docx - Biblioteca Python para criar e atualizar ficheiros Microsoft Word (.docx).

• htmldocx - Biblioteca Python para converter HTML em Docx. Utilizada para manter a formatação do Requirements & Systems Portal no Word (negrito, itálico, listas com marcas…)

O código está dividido em 3 tipos de funções:

• Master functions - Composto pelas funções main e create_specification_document, que contêm a lógica para exportar os requisitos para o documento final, preenchendo o template fornecido

• Requirement data extract functions- São todas as funções para extrair os dados dos requisitos, como tipo de requisito, estado, imagens…

• Document "Format" functions- Funções que executam formatação, como remoção de espaços em branco e garantia de que as tabelas não se dividem no documento final gerado

No subcapítulo seguinte, explicamos brevemente estas funções.

Funções principais - Main

Esta função permite ao utilizador inserir o nome do domínio, o respetivo nome de utilizador e palavra-passe, o identificador do projeto a partir do qual gerar as especificações e o caminho para o ficheiro Template

Em seguida, utilizará esta informação para:

1. Iniciar sessão no Requirements & Systems Portal utilizando a API Python;

2. Transferir dados genéricos do projeto, como especificações, imagens, tipos de requisito e outros;

3. Chamar a função create_specification_document para cada especificação no projeto selecionado.

Funções principais - Create_specification_document

As funções irão gerar o ficheiro de especificações preenchendo os Merge Fields no template com os dados correspondentes dos requisitos.

Inicialmente, é necessário recolher todos os requisitos da especificação selecionada:

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

Em seguida, os dados dos requisitos serão organizados por secção, começando pelos requisitos sem qualquer secção.

Para obter estes requisitos sem secção, é utilizada a função de suporte get_requirements_without_section para filtrar todos os requisitos da especificação que não têm grupo (forma como as secções são armazenadas no backend do Requirements & Systems Portal) e ordená-los alfabeticamente.

    #1.º vamos adicionar ao documento os requisitos sem secção
    no_section_requirements = get_requirements_without_section(all_specification_requirements)

Agora que todos os requisitos sem secção foram reunidos, é altura de preparar os dados que irão preencher os merge fields. Estes dados são obtidos com a ajuda de Requirement data extract functions e serão armazenados na lista Python, conforme mostrado no código abaixo.

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 a maioria dos merge fields, os dados são mapeados diretamente, mas para images e req_text os dados serão integrados numa fase posterior:

• Para images, é armazenado como dado um indicador que assinala se o requisito tem imagens ou não

• Para req_text, é armazenado como dado um marcador de posição. Este marcador de posição será também utilizado como chave numa lista que contém o resultado da análise do texto do requisito de HTML para Word, conforme mostrado no código abaixo

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

O mesmo processo será repetido para os requisitos que têm secções e, uma vez concluído, os dados serão integrados nos campos do template e guardados como um novo ficheiro:

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

Por fim, utilizaremos Document "Format" functions para finalizar o documento, removendo secções vazias e cabeçalhos vazios, mantendo as tabelas numa só página e inserindo no documento o texto formatado dos requisitos e respetivas imagens

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

Funções de extração de dados dos requisitos

As funções disponíveis para extrair dados dos requisitos são as seguintes:

• get_requirements_without_section - Devolve uma lista ordenada de todos os requisitos sem secção

• get_specification_sections - Devolve uma lista de todas as secções da especificação fornecida

• get_section_requirements - Devolve uma lista ordenada de todos os requisitos da secção fornecida

• get_requirement_images - Devolve um array com todas as imagens do requisito

• get_requirement_type - Devolve o nome do tipo de requisito

• get_requirement_state - Devolve o nome do estado do requisito

• get_requirement_owner - Devolve os grupos de utilizadores e o primeiro e último nome do proprietário do requisito

• get_requirement_applicability - Devolve uma lista de todos os tipos de bloco aplicáveis ao requisito, separados por “;”

• get_requirement_verification_methods - Devolve o nome de todos os métodos de verificação do requisito, separados por “;”

• get_requirement_verification_methods_newline - Devolve o nome de todos os métodos de verificação do requisito, separados por uma nova linha

• get_requirement_verification_methods_comments - Devolve todos os comentários dos métodos de verificação do requisito, separados por dupla quebra de linha

• get_requirement_verification_status - Devolve o estado de todos os Métodos de Verificação dos requisitos, separados por “;”

• get_requirement_verification_closeout_refs - Devolve os nomes das referências de fecho para cada Método de Verificação dos requisitos, separados por “;”

• get_requirement_attachments_references - Devolve o nome de todos os anexos dos requisitos, separados por “;”

• get_requirement_custom_field - Devolve o valor de um Campo Personalizado específico no requisito, passado como argumento para a função

Funções de "Format" do documento

As funções utilizadas para formatar o documento final são as seguintes:

• keep_tables_on_one_page - Formata o documento final para impedir que as tabelas tenham conteúdo de células distribuído por páginas diferentes.

• remove_all_empty_headings - Formata o documento final para remover todos os cabeçalhos vazios

• remove_all_but_last_section - Formata o documento final para ter apenas uma secção em vez de várias

• put_images - Substitui o marcador de posição das imagens pelas imagens de cada requisito

• clone_run_props - função auxiliar para copiar as propriedades de uma execução para outra (utilizada para copiar propriedades de texto formatado em HTML)

• put_html_text - Substitui o marcador de posição do texto do requisito pelo texto formatado correspondente, como Negrito, Itálico, Sublinhado, Rasurado e listas com marcas

Transferir o Generic Template, Python Script ou Executable mais recente

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

Elementos a editar antes de executar o script:

O procedimento completo sobre como executar este código, desde a criação dos scripts até à geração do documento, foi ilustrado no vídeo abaixo (sem áudio).
 

Line 27 - Line 30 O utilizador tem de definir o Nome de Utilizador e a Palavra-passe para que o script seja executado. O utilizador pode usar a gestão de segredos e executar o script, ou introduzir diretamente o Nome de Utilizador e a Palavra-passe no script. No entanto, a palavra-passe ficará visível para todos os utilizadores na implementação. Por isso, recomendamos a utilização de “Secrets Management”.

Line 31 Copie o nome da especificação e introduza-o nesta linha.

Line 32 Carregue o modelo de especificação genérico para a gestão de ficheiros, copie o respetivo “ID” e adicione-o nesta linha.

Line 33 Adicione o “ID” do projeto onde se encontra a especificação.

Line 34 Pode atribuir um nome ao documento exportado.

Caso necessite de orientação sobre como alterar o modelo, extrair outras informações para preencher os seus modelos ou tenha qualquer questão relacionada com esta funcionalidade, não hesite em enviar-nos as suas perguntas/pedidos através da nossa Página de Suporte Altium.