Assertion Manager

How to update page numbers in Assertion Manager ?

Assertion Manager is the Gazelle tool to handle the assertions that vendors shall respect to be compliant with a profile. Each profile is identified with a unique idScheme, which is associated with a PDF document, the official reference of the profile.

When someone enters a new assertion, he needs to fill in the page number where the assertion is found, and the section / figure / table number.

The main problem is when the document is updated, the pages numbers are not good anymore, and it’s then needed to update every assertion, which could be very time consuming manually. This guide will help you to automate the process at best.

Get the table of contents

This step requires to use Microsoft Word if the document is in doc/docx format. With OpenOffice / LibreOffice the content may be shift, and the page number won’t be the same as in the official documentation.

The first step consists in extracting the table of contents from the technical reference. The technical reference is often published in both DOC and PDF. If available in DOC format, consider downloading this file, and check that the document is properly formated (with numbered sections). The document have probably a table of content, but it may not be fully detailed. It’s very important to have the most detailed table of contents you can have.

To do this, go to the bottom of the page of your doc document and insert a table of content as the following :

  1. Click on the “References” tab
  2. Click on the “Table of contents” arrow button
  3. Go to the table of contents tab
  4. Put the maximum number at the “levels” section
  5. To add tables to the table of contents, click on the “Options” button
  6. Find the entry “Table Title”, and add any number in the “Level” field
  7. Validate

It’s important to insert the table of content at the bottom of the document, otherwise the page numbers will be shift by your new table of contents.

Now, you should have a detailed table of contents like below, with the section (or table) number on the left, and the page number on the right.

Once you have a properly formated table of contents, the next step will be to transform it into an association between sections and page numbers.

## Associate the section and the page number

The easiest way to associate the section and the page number is to use regular expression (regex) to delete the useless content. You can do regex with many software (vim, oxygen) but one of the most user-friendly way to check in real time your regex is to use an online regex editor as regex101.com

Copy and paste your table of contents in the “Test String” section. With a table of content generated through Word, you can use the following regex :

With /gm option enabled (the regex will apply on multiple lines) :

^\[a-zA-Z ]\*((\d?\.?)\*(-\d)?).+\t(.+)

This regex will work for a table of contents which uses digits or letters as first indices.

^(-Text- )*(\[A-Z](\.\d(\.\d)?)*)*(-\d)?.+\t(.+)

This regex will work for a table of contents which has text before listing the first index of each content line. Simply replace “-Text-“ with the text to separate (eg. : “Appendix A” can be returned as “A”).

It will seperate the section number in different groups, depending on the regex, as you can see in the image below :

It’s then easy to apply an sql script which updates page number from the section number.

A PL/SQL function can be found in the gazelle-assertion-gui project (under src/main/database/update), and is named “update_page_number_based_on_document_id_ignore_section_or_table”. It takes 3 input parameters : The document’s id (which you can find in the ‘Documents’ section of Assertion Manager) The section The page number

Then, you just have to use the “Substitution” function of regex101 to replace the content with :

select update_page_number_based_on_scheme('IDDOCUMENT', '\1', '\3');
  • IDDOCUMENT must be replaced with the id of the document you work on
  • \1 will put the content of the group captured in the firsts parenthesis (section number)
  • \3 will put the content of the group captured in the thirds parenthesis (page number)

(Be sure to check the group numbers which may change depending on the regex you use)

A typical page update query will then look like the following :

select update_page_number_based_on_document_id_ignore_section_or_table(24, '1.1', '12');

This will update the document id n°24 to point any section marked as “Section 1.1” to page 12.

Create and apply the SQL script

The last step simply consists in creating a SQL file with the result of the regex substitution and apply it.

Create a new SQL file and copy / paste the content of the regex substitution function Apply the script on assertion-manager database with plsql :

psql -U gazelle -d assertion-manager < ~/yourPageUpdateFileName.sql

The assertion-manager database has a caching system. You may have to wait 3 minutes before seeing the changes on the pages numbers.

Updating section or table numbers

As the documents evolve, the sections or tables and their content might be updated (or deleted), and the assertion might not be up to date and point to the wrong section of the document.

To update this, a PL/SQL function can be found in the gazelle-assertion-gui project (under src/main/database/updateSection.sql), called “update_section_number_based_scheme_and_assertion_id”.

It requires 3 parameters :

  • idscheme, the assertion scheme’s name (eg. : ATNA)
  • assertion_id, the assertion’s identifier (eg. : ATNA-1)
  • sectionnumber, the updated section number to which you want the assertion to point

A fourth, optional parameter allows you to modify the name between a section, a table, or a figure (if the content of an assertion moved from a section to a table, for example) :

  • name, which can be ‘Section’, ‘Table’, or ‘Figure’.

For ease of use, it is recommended to create an SQL file in which you update all the assertions where you found the section to be wrong.

An example of a typical section update :

select update_section_number_based_scheme_and_assertion_id('ATNA', 'ATNA-10', '9.1-1');

An example of a name update :

select update_section_number_based_scheme_and_assertion_id('ATNA', 'ATNA-10', '9.1.1', 'Section');

The above line would change the tag from, for example, “Table 9.1-1” to “Section 9.1.1”.

Once your file is complete, you can apply the script using plsql, as before :

psql -U gazelle -d assertion-manager < ~/yourSectionUpdateFileName.sql