Xuất thông số kỹ thuật dựa trên mẫu Microsoft Word (cập nhật tháng 11)

Bằng cách tận dụng Python & Rest API của Requirements & Systems Portal, vốn cho phép truy cập đầy đủ vào toàn bộ dữ liệu, và kết hợp với chức năng Merge Fields của Microsoft Word, bạn có thể xuất Requirements Specifications sang tài liệu Word chỉ với một cú nhấp chuột. Tính năng này cho phép bạn chọn những trường yêu cầu nào sẽ được đưa vào tài liệu và cách sắp xếp chúng.

Merge Fields và Template

Merge Fields được dùng làm tham chiếu đến một trường dữ liệu thông qua tên của trường đó. Khi một tài liệu mẫu được mail merge với các giá trị từ một nguồn dữ liệu, thông tin của trường dữ liệu sẽ thay thế merge field tương ứng.

Bằng cách tạo một tài liệu mẫu với các Merge Field khác nhau, bạn có thể nhanh chóng tạo ra cùng một loại tài liệu đầu ra (đặc tả hoặc loại khác) dựa trên chúng.

Tạo một merge field mới

1. Mở tài liệu bạn muốn chỉnh sửa và chuyển đến tab Insert.

2. Mở menu Quick Partd và chọn Field. Hộp thoại Field sẽ mở ra.

3. Trong menu hộp thoại field, chọn Merge Field từ danh sách ở phía bên trái. Nhập tên merge field vào ô văn bản Field name ở phía bên phải và nhấp OK.
   Mẹo: Đặt tên field dựa trên dữ liệu mà bạn muốn nó được thay thế để dễ theo dõi hơn

4. Merge field sẽ được chèn vào tệp Word. Đối tượng này sẽ được tô xám nếu bạn nhấp vào nó.

Các merge field đã có sẵn hàm Python tương ứng là:

«req_id» - Mã định danh yêu cầu
«req_title» - Tiêu đề yêu cầu
«req_text» - Nội dung yêu cầu
«req_state» - Trạng thái yêu cầu 
«req_type» - Loại yêu cầu
«req_rationale» – Phần giải thích/lý do liên quan đến yêu cầu 
«images» – Hình ảnh được đính kèm với yêu cầu
«specification_name» - Bản đặc tả chứa yêu cầu
«section_name» - Phần chứa yêu cầu
«req_compliance» - (Các) tuyên bố tuân thủ của yêu cầu
«req_comp_comment» - Nhận xét về tuân thủ của yêu cầu
«req_owner» - Người phụ trách yêu cầu 
«req_applicability» - Phạm vi áp dụng của yêu cầu
«req_ver_methods» - Phương pháp xác minh của yêu cầu
«req_ver_m_text» - Nhận xét về phương pháp xác minh của yêu cầu
«req_ver_closeout_ref» - Tham chiếu hoàn tất của phương pháp xác minh yêu cầu
«req_ver_status» - Trạng thái phương pháp xác minh của yêu cầu

Tạo Template (để nhân bản template)

Có thể sử dụng kết hợp các Merge Field để tạo các tệp template dùng cho việc tạo tài liệu Specification.

Một ví dụ về template được minh họa bên dưới, trong đó một số field được viết dưới dạng “văn bản thuần”, còn những field khác là một phần của bảng. Ví dụ này là ví dụ cơ sở cho các script Python sẽ được mô tả ở phần tiếp theo.

Kết quả đầu ra của template này sẽ trông tương tự như hình bên dưới

Python Script để điền dữ liệu vào Template

Script Python được dùng để tạo tài liệu dựa trên một template có chứa merge field dựa trên các gói chính sau:

• valispace - Python API của Requirements & Systems Portal cho phép bạn truy cập và cập nhật các đối tượng trong Requirements & Systems Portal.

• docx-mailmerge2 - Thực hiện Mail Merge (thay thế các merge field bằng dữ liệu mong muốn) trên các tệp Office Open XML (Docx) và có thể dùng trên bất kỳ hệ thống nào mà không cần cài đặt Microsoft Office Word.

• python-docx - Thư viện Python để tạo và cập nhật tệp Microsoft Word (.docx).

• htmldocx - Thư viện Python để chuyển HTML sang Docx. Được dùng để giữ nguyên định dạng từ Requirements & Systems Portal sang Word (đậm, nghiêng, danh sách bullet…)

Mã nguồn được chia thành 3 loại hàm:

• Master functions - Bao gồm các hàm main và create_specification_document, chứa logic để xuất các yêu cầu vào tài liệu cuối cùng bằng cách điền dữ liệu vào template đã cho

• Requirement data extract functions- Là tất cả các hàm dùng để trích xuất dữ liệu yêu cầu như loại yêu cầu, trạng thái, hình ảnh…

• Document "Format" functions- Các hàm thực hiện định dạng như loại bỏ khoảng trắng, đảm bảo bảng không bị ngắt quãng trong tài liệu cuối cùng được tạo ra

Trong tiểu mục sau, chúng tôi sẽ giải thích ngắn gọn các hàm này.

Master Functions - Main

Hàm này cho phép người dùng nhập tên miền, tên người dùng và mật khẩu, mã định danh dự án để tạo các bản đặc tả, cùng với đường dẫn đến tệp Template

Sau đó, hàm sẽ dùng thông tin này để:

1. Đăng nhập vào Requirements & Systems Portal bằng Python API;

2. Tải xuống dữ liệu chung của dự án như specification, hình ảnh, loại yêu cầu và các dữ liệu khác;

3. Gọi hàm create_specification_documentcho từng specification trong dự án đã chọn.

Master Functions - Create_specification_document

Các hàm này sẽ tạo tệp specification bằng cách điền dữ liệu yêu cầu tương ứng vào các Merge Field trong template.

Ban đầu, cần thu thập tất cả yêu cầu của specification đã chọn:

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

Sau đó, hàm sẽ sắp xếp dữ liệu yêu cầu theo từng section, bắt đầu với các yêu cầu không thuộc section nào.

Để lấy các yêu cầu không thuộc section này, hàm hỗ trợ get_requirements_without_section được dùng để lọc tất cả yêu cầu của specification không có group (cách section được lưu trong backend của Requirements & Systems Portal) và sắp xếp chúng theo thứ tự alphabet.

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

Bây giờ khi tất cả yêu cầu không thuộc section đã được thu thập, đã đến lúc chuẩn bị dữ liệu sẽ điền vào các merge field. Dữ liệu này được lấy với sự trợ giúp của Requirement data extract functions và sẽ được lưu trong danh sách Python như minh họa trong đoạn mã dưới đây.

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

Đối với phần lớn các merge field, dữ liệu được ánh xạ trực tiếp, nhưng với imagesvàreq_text thì dữ liệu sẽ được merge ở giai đoạn sau:

• Đối với images, một cờ cho biết yêu cầu có hình ảnh hay không sẽ được lưu lại dưới dạng dữ liệu

• Đối với req_text, một placeholder được lưu lại dưới dạng dữ liệu. Placeholder này cũng sẽ được dùng làm Key trong một danh sách chứa kết quả của việc phân tích nội dung yêu cầu từ HTML sang Word như trong đoạn mã dưới đây

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

Quy trình tương tự sẽ được lặp lại cho các yêu cầu có section, và sau khi hoàn tất, dữ liệu sẽ được merge vào các field của template và lưu thành một tệp mới:

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

Cuối cùng, chúng tôi sẽ dùng Document "Format" functions để hoàn thiện tài liệu bằng cách xóa các section trống và tiêu đề trống, giữ bảng trên cùng một trang, chèn nội dung văn bản đã định dạng của yêu cầu và hình ảnh của chúng vào tài liệu

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

Các hàm trích xuất dữ liệu yêu cầu

Các hàm hiện có để trích xuất dữ liệu từ yêu cầu như sau:

• get_requirements_without_section - Trả về danh sách đã sắp xếp của tất cả yêu cầu không thuộc section

• get_specification_sections - Trả về danh sách tất cả section của specification đã cho

• get_section_requirements - Trả về danh sách đã sắp xếp của tất cả yêu cầu trong section đã cho

• get_requirement_images - Trả về một mảng chứa tất cả hình ảnh của yêu cầu

• get_requirement_type - Trả về tên của loại yêu cầu

• get_requirement_state - Trả về tên của trạng thái yêu cầu

• get_requirement_owner - Trả về các User Group và họ tên của người phụ trách yêu cầu

• get_requirement_applicability - Trả về danh sách tất cả Block Type áp dụng cho yêu cầu, được phân tách bằng dấu “;”

• get_requirement_verification_methods - Trả về tên của tất cả phương pháp xác minh của yêu cầu, được phân tách bằng dấu “;”

• get_requirement_verification_methods_newline - Trả về tên của tất cả phương pháp xác minh của yêu cầu, được phân tách bằng ký tự xuống dòng

• get_requirement_verification_methods_comments - Trả về tất cả nhận xét của phương pháp xác minh yêu cầu, được phân tách bằng hai ký tự xuống dòng

• get_requirement_verification_status - Trả về trạng thái của tất cả các Verification Method của requirement, được phân tách bằng dấu “;”

• get_requirement_verification_closeout_refs - Trả về tên các tham chiếu closeout cho từng Verification Method của requirement, được phân tách bằng dấu “;”

• get_requirement_attachments_references - Trả về tên của tất cả các tệp đính kèm của requirement, được phân tách bằng dấu “;”

• get_requirement_custom_field - Trả về giá trị của một Custom Field cụ thể trên requirement, được truyền vào như một đối số cho hàm

Các hàm "Format" của tài liệu

Các hàm được dùng để định dạng tài liệu cuối cùng như sau:

• keep_tables_on_one_page - Định dạng tài liệu cuối cùng để không cho phép nội dung ô của bảng trải dài qua các trang khác nhau.

• remove_all_empty_headings - Định dạng tài liệu cuối cùng để xóa tất cả các tiêu đề trống

• remove_all_but_last_section - Định dạng tài liệu cuối cùng để chỉ có một section thay vì nhiều section

• put_images - Thay thế chỗ giữ chỗ của hình ảnh bằng hình ảnh của từng requirement

• clone_run_props - hàm phụ trợ để sao chép các thuộc tính của một run sang run khác (dùng để sao chép thuộc tính của văn bản được định dạng HTML)

• put_html_text - Thay thế chỗ giữ chỗ của văn bản requirement bằng văn bản đã được định dạng tương ứng, chẳng hạn như in đậm, in nghiêng, gạch chân, gạch ngang và danh sách đầu dòng

Tải xuống Generic Template, Python Script hoặc tệp Executable mới nhất

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

Những nội dung cần chỉnh sửa trước khi chạy script:

Toàn bộ quy trình chạy đoạn mã này, từ việc tạo script đến tạo tài liệu, đã được minh họa trong video bên dưới (không có âm thanh).
 

Line 27 - Line 30 Người dùng cần xác định Username và Password để script chạy. Người dùng có thể sử dụng secret management để chạy script hoặc nhập trực tiếp Username và Password vào script. Tuy nhiên, password sẽ hiển thị với tất cả người dùng trong deployment. Vì vậy, chúng tôi khuyến nghị bạn sử dụng “Secrets Management”.

Line 31 Sao chép tên của đặc tả và nhập vào dòng này.

Line 32 Tải Generic specification template lên file management, sao chép “ID” của nó và thêm vào dòng này.

Line 33 Thêm “ID” của project chứa đặc tả.

Line 34 Bạn có thể đặt tên cho tài liệu được xuất ra.

Trong trường hợp bạn cần hướng dẫn về cách thay đổi template, trích xuất thông tin khác để điền vào template của mình, hoặc có bất kỳ câu hỏi nào liên quan đến tính năng này, vui lòng gửi câu hỏi/yêu cầu cho chúng tôi qua Trang Hỗ trợ Altium.