Generate SCAN-B referral forms in Reggie

[olle]

Currently SCAN-B referral forms are created by use of program BarTender(r), one batch at a time with consecutive SCAN-B id numbers, both in text form and as bar codes. It would be helpful if such a batch of forms could be created directly in Reggie.

• A batch of forms should only concern a single SCAN-B site.
• The last SCAN-B id for which referral forms were created for a site should be stored, allowing the next consecutive SCAN-B id to be suggested as default for the first set of the next batch.
• A number of alternative sets of forms should be available for selection.
• It should be possible to select the number of consecutive SCAN-B id numbers for forms in a batch.
• The created referral forms should be stored in a number of PDF files.

[olle]

Ticket accepted.

[olle]

Ticket description text clarified.

[olle]

Details of the first version of SCAN-B referral form generation:

Definitions:

• A form set consists of forms with the same base SCAN-B ID, i.e. ignoring an optional suffix.
• A form set variant specifies what forms are contained in the set.
• A form batch consists of a number of form sets with consecutive SCAN-B ID's.
• A form batch is distributed as two PDF files, with forms intended for printing on referral form sheets or regular paper, respectively.

Form set variants (Initially, two variants should be available):

• Kit 1 - Standard
• Kit 2 - Neoadjuvant therapy

Batch files:

• Batch file 1 (referral form sheets): One-sided printing, one page per sheet.
• Batch file 2 (regular paper): Double-sided printing, two pages per sheet.

Form sets:

Name	Type	In Kit 1	In Kit 2	In batch file 1	In batch file 2
Patient info	Regular paper	Yes	Yes	No	Yes
Clinical chemistry - biopsy	Referral form sheet	No	Yes	Yes	No
Middle needle biopsy	Referral form sheet	No	Yes	Yes	No
Clinical chemistry	Referral form sheet	Yes	Yes	Yes	No
Clinical pathology	Referral form sheet	Yes	Yes	Yes	No
Consent report	Regular paper	Yes	Yes	No	Yes

Note: The printing option for forms in batch file 2, double-sided printing, two pages per sheet, requires forms with an odd number of pages to be followed by a blank page in the PDF file.

Barcodes are used in several sizes on the referral forms. The encoding used is "Code 128".

[olle]

Ticket description updated by adding that the SCAN-B id numbers are represented both in text and barcode form.

[olle]

Design discussion:

• PDF file creation: Ticket #674 (Generate document with report of sequencing results) addressed many items needed for the current ticket: Creating PDF files by modifying a PDF template with new text and image data. A local java utility class, PdfUtil, was created to simplify this using the open source version of library iText under the Affero General Public License. The current ticket will use the same solution, with possible extensions to the PdfUtil class being added, when needed.
• PDF templates:
  a. Program BarTender(r) was used to create and save templates of needed referral forms as PDF files, after SCAN-B id numbers and barcodes had been removed from the forms.
  b. Documents stored as word-processing files (the patient info), were saved as PDF files, after SCAN-B id numbers had been removed.
  Post-processing: The originally saved template PDF files were each opened by the "Preview" application on an OS-X system, after which they were saved again, in order to decrease the file size. The decrease could be dramatic, e.g. 87.05 -> 0.77 MB. The second PDF copy with decreased file size was then used as template for the further development.
• Barcode generation: Open source java library Barcode4J (​http://barcode4j.sourceforge.net/) uses the Apache License, version 2.0, and allows creation of barcodes using a number of variants and standards, including the required "Code 128". A downside is that there has not been much active development since release of the current version 2.1 2010-12-15. However, since the library was able to produce the needed barcodes, it was decided to use the former in the first version of referral form generation. The library allows several ways to configure the barcode generation, one being use of the Avalon Framework (project now closed), also released under the Apache License, version 2.0. Use of the latter was originally to allow configuration via XML files, but can also be used to configure Barcode4J dynamically. It was therefore included in the solution.
• Barcode human-readable text: Library Barcode4J allows several alternatives to draw an optional human-readable version of the barcode text over or under the barcode image. However, since the iText library also offers these possibilities, it was decided to use the latter via the PdfUtil class to enter human-readable text for barcodes.
• Production of referral forms from the created PDF files: The intention is that the Adobe Reader application should be used to open a created form batch PDF file, and the final referral forms should be printed from this application. Tests printing the unmodified referral form template PDF files this way, revealed:
  a. Output of referral form template PDF files saved from BarTender(r) were identical to those produced by printing directly from the latter program.
  b. Output of the template PDF file saved from a word processing program (patient info) was NOT identical to the one produced by printing directly from the latter program, but differed both in scale and offset at the left and top margin.

Notes on the PDF templates:

• The PDF templates for referral forms have dimensions that nearly, but not exactly, correspond to those of an A4 page. However, all template files saved from BarTender(r) seem to have the same dimensions. This allows (at least) two solutions, when creating the form batch PDF files:
  
  a. The template PDF file could be imported directly, without adjustment, and the SCAN-B id number text and barcodes added to this.
  b. The template PDF file could be adjusted to A4 format when imported, before adding SCAN-B id number text and barcodes.
  
  Alternative (a) leads to slightly simpler code, since the adjustment step is eliminated, but might lead to more problems in the future, if new templates are needed, that not have exactly the same dimensions as the old. Since batch file 2 uses templates both created with BarTender(r) and a word processing program, some adjustment will be needed here in any case. It was therefore decided to use solution (b), where the imported PDF data is adjusted to A4 format.
• The four referral forms to be printed on referral form sheets are divided into two pairs of referral form sheets. In each pair, one member is intended for biopsy and the other for general cases, but where occurrences and placement of SCAN-B ID barcodes and text are identical. The forms intended for biopsy have an additional suffix 'C' appended to the SCAN-B ID:

Form name	Referral form sheet type	SCAN-B ID Suffix
Clinical chemistry - biopsy	9 labels (1 barcode)	C
Middle needle biopsy	6 labels (2 barcodes), 3 labels (1 barcode)	C
Clinical chemistry	9 labels (1 barcode)	-
Clinical pathology	6 labels (2 barcodes), 3 labels (1 barcode)	-

[olle]

Design description of first version of the referral form generation:

External file storage:

• Next SCAN-B id to be used for a site: A list of SCAN-B prefixes and the next SCAN-B id for the site are stored in a tab-delimited text file scanb_referral_start_info.txt placed in BASE user files directory.
• Referral form template PDF files are stored in a directory specified in Reggie configuration file reggie-config.xml in XML tag template-directory-path in new tag referral-form-generation. The filenames are specified in tag template-local-filenames:

Form template	Template file XML key
Patient info	patient-info
Clinical chemistry - biopsy	clinical-chemistry-biopsy
Middle needle biopsy	middle-needle-biopsy
Clinical chemistry	clinical-chemistry
Clinical pathology	clinical-pathology
Consent report	consent-report

[olle]

(In [4011]) Refs #897. Java utility class PdfUtil updated with methods needed for generation of referral forms:

1. Java utility class PdfUtil.java in src/net/sf/basedb/reggie/pdf/ updated:
   a. New public method int getPageNumber() added. It returns the page number of the existing document.
   b. New public method void newPage() added. It creates a new page in the existing document.
   c. New public method void newBlankPage() added. It creates a new blank page in the existing document.
   d. New public method void addText(String text, float fontSize, int align, float x, float y, float rotation) added. It allows text to be added after having been rotated.
   e. New public method void addBoldText(String text, float fontSize, int align, float x, float y, float rotation) added. It allows bold text to be added after having been rotated.
   f. New public method void importPdf(InputStream pdf, float x, float y) added. It imports a PDF document that will be scaled to the height of the current document.
   g. New public method void importPdf(InputStream pdf, int pageNo, float x, float y) added. It imports a PDF document that will be scaled to the height of the current document.
   h. New public method void importPdf(InputStream pdf, int pageNo, float x, float y, float scaleX, float scaleY) added. It imports a PDF document.
   i. New private method void importPdf(PdfReader reader, int pageNo, float x, float y) added. It imports a PDF document that will be scaled to the height of the current document.
   j. New public method void importImage2(byte[] imageByteArray, float x, float y, float width, float height, int align) added. It imports an image into the PDF document and places it at the location specified by the y and y coordinates. The image is stretched to fit within the given width and height.
   k. New public method void importImage2(byte[] imageByteArray, float x, float y, float width, float height, int align, float rotationDegrees) added. It imports an image into the PDF document and places it at the location specified by the y and y coordinates. The image is stretched to fit within the given width and height, and is then rotated.

[olle]

(In [4012]) Refs #897. Java barcode generation library Barcode4J and configuration library Avalon framework added to libraries used for referral form generation.

[olle]

(In [4013]) Refs #897. Reggie configuration file reggie-config.xml in config/ updated with new XML tag referral-form-generation for configuration of storage directory and used names of referral form template PDF files.

[olle]

Functional specification update:

• First version of SCAN-B referral form generation will be based on the following functionality:
  a. A new sub-section "Referral forms" with entry "Generate referral forms" will be added to section "Personal information wizards", and will require a PatientCurator role to be used.
  b. Step 1 of the SCAN-B referral form generation wizard will have two menus, one for the SCAN-B site, and one for selecting the form variant to generate forms for (initially two choices, "Kit 1 - Standard" and "Kit 2 - Neoadjuvant therapy").
  c. Step 2 should contain two input fields, one for the first SCAN-B ID for the form set batch to be created, and the number of form sets in the batch. One button should be shown, "Generate referral forms".
  d. Step 3 should present three buttons, "Download form batch file 1", "Download form batch file 2", and "Update used SCAN-B ID list". As expected, clicking the first or second button should allow the corresponding form batch PDF file to be downloaded to the local system, while clicking on the third button will update the stored list of used SCAN-B ID to prevent the same set of referral form sets to be created again for the same site, provided that the default start SCAN-B ID has not been modified by the user and that the list has been updated after each created form set batch.

Design update:

1. JSP file index.jsp in resources/ updated in section "Personal information wizards" with new sub-section "Referral forms" with entry "Generate referral forms". The entry for generating referral forms is linked to new JSP file generate-referral-forms.jsp in resources/personal/, and requires a PatientCurator role to be used.
2. New JSP file generate-referral-forms.jsp in resources/personal/ added. It is linked to new javascript file generate-referral-forms.js in resources/personal/.
3. New javascript file generate-referral-forms.js in resources/personal/ added.
   a. Function initPage() calls ScanBQuarterMonthReportServlet with command "GetSites" to obtain entries for the site menu, created by callback function sitesLoaded(response).
   b. Function initializeStep2(response) calls ReferralGeneratorServlet with command "GetReferralStartInfo" to obtain the SCAN-B ID for the first form set for the selected site. The default number of form sets in the batch to be created is chosen depending on the selected form set variant (50 for Kit 1, 25 for Kit 2).
   c. Clicking on button "Generate referral forms" activates function generateReferralForms(), that calls ReferralGeneratorServlet with command "GenerateReferralForms" and callback function initializeStep3(response).
   d. Function initializeStep3(response) activates buttons for downloading created form batch files and updating used SCAN-B ID list.
   e. Function downloadFormBatch(batchType) calls ReferralGeneratorServlet with command "DownloadFormBatchFile" to download the corresponding form batch file to the local system.
   f. Function updateUsedScanbIdList() calls ReferralGeneratorServlet with command "UpdateUsedScanbIdList" to updated the used SCAN-B ID list.
4. New java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ added.
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "GetReferralStartInfo", that calls private method JSONObject fetchReferralstartInfo() to obtain a JSONObject to return with info on the start SCAN-B ID values for different sites.
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "UpdateUsedScanbIdList", that retrieves the used start SCAN-B ID and the number of form sets generated, after which the used SCAN-B ID list file is updated for the current site with the value returned by private method String nextScanbId(String scanbId, Integer incr).
   c. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "GenerateReferralForms", that calls a number of private convenience methods to create the desired referral form batch PDF files, with support from utility class PdfUtil.
   d. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "DownloadFormBatchFile", which retrieves a path to the desired form batch PDF file by calling private method String fetchReferralFormBatchFilePath(int batchType), after which it sends the file contents to an output stream, for download by the user.
   e. Private method String fetchReferralStartInfoFilePath() returns a path to the referral start info file.
   f. Private method JSONObject fetchReferralstartInfo() returns a JSONObject with info on the start SCAN-B ID values for different sites.
   g. Private method String fetchReferralFormBatchFilePath(int batchType) returns a path to the desired form batch PDF file.
   h. Private method tring fetchReferralFormBatchFileName(int batchType, String startScanbId, String endScanbId) returns name to be used for the referral form batch file.
   i. Private method String fetchReferralFormTemplateFilePath(String formTemplateName) returns path to be used for referral form template file.
   j. Private method String fetchReferralFormTemplateFilename(String formTemplateName) returns name of referral form template file, obtained from Reggie configuration file.
   k. Private method String fetchReferralFormTemplateFileDirPath() returns directory path for referral form template files, obtained from Reggie configuration file.
   l. Private method String nextScanbId(String scanbId, Integer incr) returns the next SCAN-B ID for a site (same prefix) after a desired incrementation. Any optional suffix is retained.
   m. Private method PdfUtil createPatientInfoForm(PdfUtil pdfUtil, String scanbId) creates PDF contents for a patient info form.
   n. Private method PdfUtil createConsentReportForm(PdfUtil pdfUtil, String scanbId) creates PDF contents for a consent report form.
   o. Private method PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId, String pdfTemplatePath) creates PDF contents for a clinical chemistry form using the desired template (standard or biopsy).
   p. Private method PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId, String pdfTemplatePath) creates PDF contents for a clinical pathology form using the desired template (standard or biopsy).
   q. Private method byte[] createBarcode(String barcodeText, String barcodeType, Integer dpi, Boolean humanReadable, String textPlacement, String fontName, Integer fontSize) returns a byte array of a barcode image corresponding to desired contents. Java library Barcode4J is used to generate the barcode.
   r. Private static method Configuration buildBarcodeCfg(String type, Boolean humanReadable, String textPlacement, String fontName, Integer fontSize) configures the Barcode4J barcode generator.
5. XML configuration file servlets.xml in META-INF updated by adding new java servlet class ReferralGeneratorServlet to the servlet list.

[olle]

(In [4014]) Refs #897. First version of referral form generation added:

1. JSP file index.jsp in resources/ updated in section "Personal information wizards" with new sub-section "Referral forms" with entry "Generate referral forms". The entry for generating referral forms is linked to new JSP file generate-referral-forms.jsp in resources/personal/, and requires a PatientCurator role to be used.
2. New JSP file generate-referral-forms.jsp in resources/personal/ added. It is linked to new javascript file generate-referral-forms.js in resources/personal/.
3. New javascript file generate-referral-forms.js in resources/personal/ added.
   a. Function initPage() calls ScanBQuarterMonthReportServlet with command "GetSites" to obtain entries for the site menu, created by callback function sitesLoaded(response).
   b. Function initializeStep2(response) calls ReferralGeneratorServlet with command "GetReferralStartInfo" to obtain the SCAN-B ID for the first form set for the selected site. The default number of form sets in the batch to be created is chosen depending on the selected form set variant (50 for Kit 1, 25 for Kit 2).
   c. Clicking on button "Generate referral forms" activates function generateReferralForms(), that calls ReferralGeneratorServlet with command "GenerateReferralForms" and callback function initializeStep3(response).
   d. Function initializeStep3(response) activates buttons for downloading created form batch files and updating used SCAN-B ID list.
   e. Function downloadFormBatch(batchType) calls ReferralGeneratorServlet with command "DownloadFormBatchFile" to download the corresponding form batch file to the local system.
   f. Function updateUsedScanbIdList() calls ReferralGeneratorServlet with command "UpdateUsedScanbIdList" to updated the used SCAN-B ID list.
4. New java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ added.
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "GetReferralStartInfo", that calls private method JSONObject fetchReferralstartInfo() to obtain a JSONObject to return with info on the start SCAN-B ID values for different sites.
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "UpdateUsedScanbIdList", that retrieves the used start SCAN-B ID and the number of form sets generated, after which the used SCAN-B ID list file is updated for the current site with the value returned by private method String nextScanbId(String scanbId, Integer incr).
   c. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "GenerateReferralForms", that calls a number of private convenience methods to create the desired referral form batch PDF files, with support from utility class PdfUtil.
   d. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) supports command "DownloadFormBatchFile", which retrieves a path to the desired form batch PDF file by calling private method String fetchReferralFormBatchFilePath(int batchType), after which it sends the file contents to an output stream, for download by the user.
   e. Private method String fetchReferralStartInfoFilePath() returns a path to the referral start info file.
   f. Private method JSONObject fetchReferralstartInfo() returns a JSONObject with info on the start SCAN-B ID values for different sites.
   g. Private method String fetchReferralFormBatchFilePath(int batchType) returns a path to the desired form batch PDF file.
   h. Private method tring fetchReferralFormBatchFileName(int batchType, String startScanbId, String endScanbId) returns name to be used for the referral form batch file.
   i. Private method String fetchReferralFormTemplateFilePath(String formTemplateName) returns path to be used for referral form template file.
   j. Private method String fetchReferralFormTemplateFilename(String formTemplateName) returns name of referral form template file, obtained from Reggie configuration file.
   k. Private method String fetchReferralFormTemplateFileDirPath() returns directory path for referral form template files, obtained from Reggie configuration file.
   l. Private method String nextScanbId(String scanbId, Integer incr) returns the next SCAN-B ID for a site (same prefix) after a desired incrementation. Any optional suffix is retained.
   m. Private method PdfUtil createPatientInfoForm(PdfUtil pdfUtil, String scanbId) creates PDF contents for a patient info form.
   n. Private method PdfUtil createConsentReportForm(PdfUtil pdfUtil, String scanbId) creates PDF contents for a consent report form.
   o. Private method PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId, String pdfTemplatePath) creates PDF contents for a clinical chemistry form using the desired template (standard or biopsy).
   p. Private method PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId, String pdfTemplatePath) creates PDF contents for a clinical pathology form using the desired template (standard or biopsy).
   q. Private method byte[] createBarcode(String barcodeText, String barcodeType, Integer dpi, Boolean humanReadable, String textPlacement, String fontName, Integer fontSize) returns a byte array of a barcode image corresponding to desired contents. Java library Barcode4J is used to generate the barcode.
   r. Private static method Configuration buildBarcodeCfg(String type, Boolean humanReadable, String textPlacement, String fontName, Integer fontSize) configures the Barcode4J barcode generator.
5. XML configuration file servlets.xml in META-INF updated by adding new java servlet class ReferralGeneratorServlet to the servlet list.

[olle]

Functional specification update:

• SCAN-B referral form generation should be updated to store the last date the start SCAN-B ID list was updated for a site:
  a. The date should be automatically updated when the "Update used SCAN-B ID list" button is pressed.
  b. The date should be displayed in step 2 of the SCAN-B referral form generation wizard, next to or near the proposed first SCAN-B ID value for the next form set to be created for a site.

Storage solution:

• The last update date should be stored in an extra column in the tab-separated text file used to store the start SCAN-B ID values for sites.

Design update:

1. JSP file generate-referral-forms.jsp in resources/personal/ updated in step 2 for the start SCAN-B ID message text, by appending information on when the start SCAN-B ID was last updated in a span tag with id "scanbIdLastUpdated".
2. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep2a(response) to obtain a JSONObject jsonSite for the site from JSONObject jsonRefStartInfo, and then obtain the start SCAN-B ID and last updated date from the former. The last updated date is then inserted in span tag with id "scanbIdLastUpdated" in step 2 of the SCAN-B referral form generation wizard.
3. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "UpdateUsedScanbIdList" to obtain a JSONObject jsonSite for each site from JSONObject jsonRefStartInfo, and then obtain the start SCAN-B ID and last updated date from the former. The last updated date is then exchanged for the current date for the site to have its start SCAN-B ID updated, after which both start SCAN-B ID and last update date are written back to the storage file for each site.
   b. Private method JSONObject fetchReferralstartInfo() updated to read start SCAN-B ID and last updated date for each site from the storage file, and store the two former values in a JSONObject jsonSite for each site.

[olle]

(In [4015]) Refs #897. SCAN-B referral form generation updated to store the last date the start SCAN-B ID list was updated for a site:
a. The date is automatically updated when the "Update used SCAN-B ID list" button is pressed.
b. The date is displayed in step 2 of the SCAN-B referral form generation wizard, next to or near the proposed first SCAN-B ID value for the next form set to be created for a site.
c. The last update date is stored in an extra column in the tab-separated text file used to store the start SCAN-B ID values for sites.

1. JSP file generate-referral-forms.jsp in resources/personal/ updated in step 2 for the start SCAN-B ID message text, by appending information on when the start SCAN-B ID was last updated in a span tag with id "scanbIdLastUpdated".
2. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep2a(response) to obtain a JSONObject jsonSite for the site from JSONObject jsonRefStartInfo, and then obtain the start SCAN-B ID and last updated date from the former. The last updated date is then inserted in span tag with id "scanbIdLastUpdated" in step 2 of the SCAN-B referral form generation wizard.
3. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "UpdateUsedScanbIdList" to obtain a JSONObject jsonSite for each site from JSONObject jsonRefStartInfo, and then obtain the start SCAN-B ID and last updated date from the former. The last updated date is then exchanged for the current date for the site to have its start SCAN-B ID updated, after which both start SCAN-B ID and last update date are written back to the storage file for each site.
   b. Private method JSONObject fetchReferralstartInfo() updated to read start SCAN-B ID and last updated date for each site from the storage file, and store the two former values in a JSONObject jsonSite for each site.

[olle]

Functional specification update:

• SCAN-B referral form generation should be updated to display a message after the start SCAN-B ID list has been updated for a site.

Design update:

1. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep3a(response) to call command Wizard.showFinalMessage(response.messsages) to display any servlet message.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated to add JSONArray jsonMessages to returned JSONObject with key "messages".
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "UpdateUsedScanbIdList" to add a message on the updated start SCAN-B ID value to JSONArray jsonMessages.

[olle]

(In [4016]) Refs #897. SCAN-B referral form generation updated to display a message after the start SCAN-B ID list has been updated for a site:

1. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep3a(response) to call command Wizard.showFinalMessage(response.messsages) to display any servlet message.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated to add JSONArray jsonMessages to returned JSONObject with key "messages".
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "UpdateUsedScanbIdList" to add a message on the updated start SCAN-B ID value to JSONArray jsonMessages.

[olle]

(In [4017]) Refs #897. SCAN-B referral form generation updated in step 2 for the start SCAN-B ID message text, to display the date when the start SCAN-B ID was last updated in bold type:

1. JSP file generate-referral-forms.jsp in resources/personal/ updated in step 2 for the start SCAN-B ID message text, to display the date when the start SCAN-B ID was last updated in bold type.

[olle]

Functional specification update:

1. The referral form generation should be updated to allow use of specific templates for each SCAN-B site. Currently 6 form template types are supported; with 9 sites, the number will increase to 54 standard templates.
2. Two SCAN-B sites require special templates:
   a. Uppsala (prefix "88") uses a special clinical chemistry form without tube labels and is intended for printing on regular paper.
   b. Lund (prefix "11") uses an extra referral form for blood.
3. The time and used form template files should be logged when creating form batch files, and the user should be able to access the log data. This gives the user opportunity to find out exactly what version of form templates were used for a specific form batch.
4. If possible, the user should be able to exchange a form template PDF file for a new version.

Design update:

• Item 1. & 4.:
  a. Referral form template files will be stored in the BASE file system, in a sub-directory to directory "/home/SCANB".
  b. Template files for a SCAN-B site will be stored in a sub-directory with the name of the SCAN-B site prefix, e.g. "33" for "Halmstad".
  c. Template files for different SCAN-B sites will have filenames, with the same beginning for the same form type. Reggie configuration file is updated to store the start of these filenames, instead of the complete filenames. Version information is deliberately excluded from the part of the filenames stored in the configuration file, allowing the same configuration to be valid for several versions of form template files.

[olle]

(In [4018]) Refs #897. SCAN-B referral form generation updated to store SCAN-B referral form template PDF files in BASE file system, one template file for each form type and SCAN-B site:

1. Reggie configuration file reggie-config.xml in config/ updated in XML tag referral-form-generation for configuration of stored referral form template PDF files:
   a. The template file directory path is now intended to be in the BASE file system.
   b. Only the start of filenames for SCAN-B referral form template PDF files are now stored (excluding version info). XML tag template-local-filenames is therefore renamed template-filename-start.
   c. Typos in XML tags for form types clinical-chemistry-biopsy and clinical-chemistry fixed (letter 'i' in chemistry was missing).
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by adding first argument DbControl dc when calling private convenience methods creating referral forms.
   b. Private method String fetchReferralFormTemplateFilePath(String formTemplateName) removed, as it is no longer needed.
   c. Private method String fetchReferralFormTemplateFilename(String formTemplateName) renamed String fetchReferralFormTemplateFilenameStart(String formTemplateName) and updated to return start of referral form template filename, obtained from Reggie configuration file.
   d. New private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) added. It returns a BASE file item for the referral form template file.
   e. Private convenience methods
   PdfUtil createPatientInfoForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createConsentReportForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createBiopsyClinChemForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId, String formTemplateName)
PdfUtil createMiddleNeedleBiopsyForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId, String formTemplateName)
   updated with new first argument DbControl dc, and to call new private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) to obtain a BASE file item for the form template file.

[olle]

Functional specification update on logging of generated referral form batches:

• Log data should be stored in a tab-separated text file in the BASE file system, located in the top directory for storing form template PDF files.
• A log file entry should consist of a single line for each created referral form batch, with the following columns:
  a. Date and time for form generation.
  b. Referral variant.
  c. SCAN-B id range of generated referral form sets.
  d. Comma-separated list of filenames for used form template files.

Design update:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by adding extra argument List<String> formTemplateFileList when calling private convenience methods creating referral forms. Also, at the end, new private method void updateReferralFormLogFile(DbControl dc, String referralVariant, String startScanbId, int nofFormSets, List<String> formTemplateFileList) is called, followed by a call of dc.commit().
   b. New private method void updateReferralFormLogFile(DbControl dc, String referralVariant, String startScanbId, int nofFormSets, List<String> formTemplateFileList) added. It updates the BASE referral form generation log file with a new entry line. Private method String nextScanbId(String scanbId, Integer incr) is called to find the end SCAN-B id for the generated form set batch from the start SCAN-B id and the number of form sets in the batch. New private method fetchReferralFormLogFile(DbControl dc) is called to obtain a BASE file item corresponding to the log file. The input list of used referral form template filenames is converted to a comma-separated list string. Since BASE currently doesn't support obtaining an OutputStream for a BASE file in "append" mode, the old contents is first read and then re-written to the file, before the new update is added.
   c. New private method fetchReferralFormLogFile(DbControl dc) added. It returns the BASE file item for the referral form log file.
   d. Private convenience methods
   PdfUtil createPatientInfoForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createConsentReportForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createBiopsyClinChemForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId, String formTemplateName)
PdfUtil createMiddleNeedleBiopsyForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId, String formTemplateName)
   updated with extra argument List<String> formTemplateFileList, and to update the latter with the used referral form template filename, provided the latter is not already contained in the list.

[olle]

(In [4019]) Refs #897. SCAN-B referral form generation updated to log generated referral form batches:

• Log data is stored in a tab-separated text file in the BASE file system, located in the top directory for storing form template PDF files.
• A log file entry consists of a single line for each created referral form batch, with the following columns:
  a. Date and time for form generation.
  b. Referral variant.
  c. SCAN-B id range of generated referral form sets.
  d. Comma-separated list of filenames for used form template files.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by adding extra argument List<String> formTemplateFileList when calling private convenience methods creating referral forms. Also, at the end, new private method void updateReferralFormLogFile(DbControl dc, String referralVariant, String startScanbId, int nofFormSets, List<String> formTemplateFileList) is called, followed by a call of dc.commit().
   b. New private method void updateReferralFormLogFile(DbControl dc, String referralVariant, String startScanbId, int nofFormSets, List<String> formTemplateFileList) added. It updates the BASE referral form generation log file with a new entry line. Private method String nextScanbId(String scanbId, Integer incr) is called to find the end SCAN-B id for the generated form set batch from the start SCAN-B id and the number of form sets in the batch. New private method fetchReferralFormLogFile(DbControl dc) is called to obtain a BASE file item corresponding to the log file. The input list of used referral form template filenames is converted to a comma-separated list string. Since BASE currently doesn't support obtaining an OutputStream for a BASE file in "append" mode, the old contents is first read and then re-written to the file, before the new update is added.
   c. New private method fetchReferralFormLogFile(DbControl dc) added. It returns the BASE file item for the referral form log file.
   d. Private convenience methods
   PdfUtil createPatientInfoForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createConsentReportForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createBiopsyClinChemForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId, String formTemplateName)
PdfUtil createMiddleNeedleBiopsyForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId)
PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId, String formTemplateName)
   updated with extra argument List<String> formTemplateFileList, and to update the latter with the used referral form template filename, provided the latter is not already contained in the list.

[olle]

Functional specification update on location of referral form generation log file:

• Path to the log file in the BASE filesystem should now be stored in Reggie configuration file, in new XML tag referral-form-logfile-path. The default path is the top directory for storing form template PDF files, with default filename "refFormLogFile.txt".

Design update:

1. Reggie configuration file reggie-config.xml in config/ updated in XML tag referral-form-generation for configuration of stored referral form template PDF files:
   a. New XML tag referral-form-logfile-path added for storage of path to the referral form generation log file in the BASE filesystem.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private static final String REF_FORM_LOG_FILENAME renamed REF_FORM_LOG_DEFAULT_FILENAME to reflect the new use of the constant.
   b. Private method fetchReferralFormLogFile(DbControl dc) updated. It now returns the BASE file item for the referral form log file for the path obtained from Reggie configuration file.

[olle]

(In [4020]) Refs #897. SCAN-B referral form generation updated to obtain path to the log file in the BASE filesystem from Reggie configuration file, in new XML tag referral-form-logfile-path. The default path is the top directory for storing form template PDF files, with default filename "refFormLogFile.txt":

1. Reggie configuration file reggie-config.xml in config/ updated in XML tag referral-form-generation for configuration of stored referral form template PDF files:
   a. New XML tag referral-form-logfile-path added for storage of path to the referral form generation log file in the BASE filesystem.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private static final String REF_FORM_LOG_FILENAME renamed REF_FORM_LOG_DEFAULT_FILENAME to reflect the new use of the constant.
   b. Private method fetchReferralFormLogFile(DbControl dc) updated. It now returns the BASE file item for the referral form log file for the path obtained from Reggie configuration file.

[olle]

Functional specification update regarding special forms/templates (item 2 in functional specification update 2016-07-07):

• Two SCAN-B sites require special templates:
  a. Uppsala (prefix "88") uses a special clinical chemistry blood sample form without tube labels and is intended for printing on regular paper.
  b. Lund (prefix "11") uses an extra referral form for blood.

Design update:

1. SCAN-B referral form generation should include the special form, if the site is one of the two mentioned. An alternative is to always check if a form template is available for a site, and if so, use it.
2. Reggie configuration file reggie-config.xml should be updated in tag referral-form-generation, sub-tag template-filename-start, with new tags for the extra blood referral form templates:

Form template	Template file XML key
Clinical chemistry - blood	clinical-chemistry-blood
Clinical chemistry - BC blood	clinical-chemistry-bcblood

3. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. New private static string constants REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD and REF_FORM_TEMPLATE_CLIN_CHEM_BCBLOOD defined for XML keys for the two new blood referral template files.
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by calling new private methods PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) and PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList), if the site is Uppsala or Lund, respectively.
   c. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated by writing a log message if a form template file with a correct name could not be found.
   d. New private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) added. It calls new private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) with value of argument formTemplateName set to string constant REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD.
   e. New private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) added. It calls private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) to obtain the form template PDF file, and then adds data for the current form.
   f. New private method PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) added. It calls new private method PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) with value of argument formTemplateName set to string constant REF_FORM_TEMPLATE_CLIN_CHEM_BCBLOOD.
   g. New private method PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) added. It calls private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) to obtain the form template PDF file, and then adds data for the current form.

[olle]

Design discussion regarding PDF document size and printing:

• During development of support for the new referral forms, it was discovered that the printed output of generated PDF pages depended on whether printing option "Actual size" or "Shrink oversized pages" was selected in Adobe Acrobat Reader DC. This was unexpected, since "Document Properties" in the same program showed that the generated PDF file had dimensions 210 x 297 mm (A4), and the used printer also had A4 paper size as default setting. Still, selecting "Shrink oversized pages" made the program scale the output to 96% of the original size. Unfortunately, the latter printing option had been selected during previous development, and changing the setting to "Actual size" resulted in output, that did not fit the labels area of the referral form sheet.

The reason for Adobe Acrobat Reader to reduce the size of the printed output, although the PDF file has the correct size, might be to provide a safety margin, since printers normally cannot print near the paper edges. Shrinking the output will therefore ensure, that no contents is clipped during printing. However, the PDF templates used for the referral form generation already have margins near the document edges, and therefore do not need any size reduction.

Two obvious solutions exist:

1. Continue further development using the same settings as before, and require that printer setting "Shrink oversized pages" is selected, when the generated PDF files are printed.
2. Update the code to generate PDF files, that produce the correct output using printer option "Actual size", and require that this printer setting is selected, when the generated PDF files are printed. The generated PDF files should still have dimensions 210 x 297 mm (A4).

• Solution 2 will require more work, but seems to be the safest solution in the long run, since future versions of Adobe Acrobat Reader might change the printer selections, but option "Actual size" should by its simplicity have higher probability of being retained. This solution was therefore selected. Code for existing referral forms will be updated before release, but support for new forms will be developed using the new scheme.

For future reference, the original document sizes of referral form templates are as follows:

Form template	Dimensions (mm)	Dimensions (inches)
Patient info	210 x 297 (A4)	8.26 x 11.69 (A4)
Clinical chemistry - biopsy	190 x 287	7.48 x 11.30
Middle needle biopsy	190 x 287	7.48 x 11.30
Clinical chemistry	190 x 287	7.48 x 11.30
Clinical chemistry - blood	190 x 287	7.48 x 11.30
Clinical chemistry - BC blood	184 x 293	7.24 x 11.54
Clinical pathology	190 x 287	7.48 x 11.30
Consent report	190 x 287	7.48 x 11.30

[olle]

(In [4021]) Refs #897. SCAN-B referral form generation updated to support two new special forms/templates:
a. Uppsala (prefix "88") uses a special clinical chemistry blood sample form without tube labels and is intended for printing on regular paper.
b. Lund (prefix "11") uses an extra referral form for blood.

1. Reggie configuration file reggie-config.xml in config updated in tag referral-form-generation, sub-tag template-filename-start, with new tags for the extra blood referral form templates, "clinical-chemistry-blood" and "clinical-chemistry-bcblood".
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. New private static string constants REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD and REF_FORM_TEMPLATE_CLIN_CHEM_BCBLOOD defined for XML keys for the two new blood referral template files.
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by calling new private methods PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) and PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList), if the site is Uppsala or Lund, respectively.
   c. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated by writing a log message if a form template file with a correct name could not be found.
   d. New private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) added. It calls new private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) with value of argument formTemplateName set to string constant REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD.
   e. New private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) added. It calls private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) to obtain the form template PDF file, and then adds data for the current form.
   f. New private method PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) added. It calls new private method PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) with value of argument formTemplateName set to string constant REF_FORM_TEMPLATE_CLIN_CHEM_BCBLOOD.
   g. New private method PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) added. It calls private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) to obtain the form template PDF file, and then adds data for the current form.

[olle]

(In [4022]) Refs #897. SCAN-B referral form generation updated to create referral form PDF files intended to be printed with printer setting "Actual size":

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private convenience methods
   i. PdfUtil createPatientInfoForm(PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList)
   ii. PdfUtil createConsentReportForm(PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList)
   iii. PdfUtil createClinChemForm(PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   iv. PdfUtil createClinPathologyForm(PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   updated to create referral form PDF files intended to be printed with printer setting "Actual size".
   b. Unused code removed.

[olle]

(In [4024]) Refs #897. SCAN-B referral form generation updated in printing options message text, by adding instructions to print generated forms using print size "Actual size":

1. JSP file generate-referral-forms.jsp in resources/personal/ updated in printing options message text, by adding instructions to print generated forms using print size "Actual size".

[olle]

(In [4025]) Refs #897. SCAN-B referral form generation updated in step 1 to display SCAN-B prefix inside brackets next to site name in site menu:

1. Javascript file generate-referral-forms.js in resources/personal/ updated in function sitesLoaded(response) to display SCAN-B prefix inside brackets next to site name in site menu.

[Nicklas Nordborg]

(In [4029]) References #897: Generate SCAN-B referral forms in Reggie

The new JAR files must be specified in the classpath or Eclipse will show a lot of errors.

[Nicklas Nordborg]

(In [4030]) References #897: Generate SCAN-B referral forms in Reggie

Removing unused imports and adding @SuppressWarnings annotation to get rid of lots of warnings in Eclipse.

[olle]

Functional specification update:

• Referral forms for which there do not exist form template PDF files for the selected site, should be omitted from the created referral form batch file. The referral form generation will check for all types of supported referral form templates, irrespective of selected site. The set of referral forms created for a site will therefore simply depend on what referral form template files (with correct filename beginnings) have been installed for the site.

Design update:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by optional generation of blood referral forms for all sites, not just Uppsala and Lund.
   b. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated to not print a log message, if no template file can be found, and the method returns null.
   c. Private convenience methods
   i. PdfUtil createPatientInfoForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList)
   ii. PdfUtil createConsentReportForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList)
   iii. PdfUtil createClinChemForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   iv. PdfUtil createClinPathologyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   v. PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   vi. PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   updated to return the input PdfUtil object directly, if no referral form template file is found for the selected site.

[olle]

(In [4033]) Refs #897. SCAN-B referral form generation updated to check for all types of supported referral form templates, irrespective of selected site. Referral forms for which there do not exist form template PDF files for the selected site, are omitted from the created referral form batch file:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by optional generation of blood referral forms for all sites, not just Uppsala and Lund.
   b. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated to not print a log message, if no template file can be found, and the method returns null.
   c. Private convenience methods
   i. PdfUtil createPatientInfoForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList)
   ii. PdfUtil createConsentReportForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList)
   iii. PdfUtil createClinChemForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   iv. PdfUtil createClinPathologyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   v. PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   vi. PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList)
   updated to return the input PdfUtil object directly, if no referral form template file is found for the selected site.

[olle]

Functional specification update:

• Sites using a clinical chemistry blood sample form without tube labels (like Uppsala), also send a special form copy to Lund. Support for this blood sample form copy to Lund should be added. The latter form has SCAN-B ID barcodes and text strings in same sizes and positions as for the original blood sample form, but some of the other text differs, so a special PDF template should be used.

Design update:

1. Reggie configuration file reggie-config.xml in config updated in tag referral-form-generation, sub-tag template-filename-start, with new tag for the blood referral form Lund copy template, "clinical-chemistry-blood-lundcopy".
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. New private static string constant REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD_LUNDCOPY defined for the XML key for the new blood referral form Lund copy template file. Its value is set to "clinical-chemistry-blood-lundcopy".
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by calling new private method PdfUtil createClinChemBloodLundCopyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) after call of PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList).
   c. New private method PdfUtil createClinChemBloodLundCopyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) added. It calls private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) with value of argument formTemplateName set to string constant REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD_LUNDCOPY.

[olle]

(In [4035]) Refs #897. SCAN-B referral form generation updated to create a clinical chemistry blood sample Lund copy form:

1. Reggie configuration file reggie-config.xml in config updated in tag referral-form-generation, sub-tag template-filename-start, with new tag for the blood referral form Lund copy template, "clinical-chemistry-blood-lundcopy".
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. New private static string constant REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD_LUNDCOPY defined for the XML key for the new blood referral form Lund copy template file. Its value is set to "clinical-chemistry-blood-lundcopy".
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" by calling new private method PdfUtil createClinChemBloodLundCopyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) after call of PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList).
   c. New private method PdfUtil createClinChemBloodLundCopyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) added. It calls private method PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) with value of argument formTemplateName set to string constant REF_FORM_TEMPLATE_CLIN_CHEM_BLOOD_LUNDCOPY.

[olle]

(In [4036]) Refs #897. SCAN-B referral form generation updated by fix of typo in method name:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated by changing name of private method fetchReferralstartInfo() to fetchReferralStartInfo() (with uppercase "S" in "Start"), in order to adhere to the CamelCase naming convention.

[olle]

Design update:

• It was decided to set BASE file system paths for referral form template file directories and referral form generation log file in the application code, instead of in Reggie configuration file, and let Reggie installation program create the needed directories, if not existing.

1. Reggie configuration file reggie-config.xml in config/ updated in tag referral-form-generation by removing sub-tags template-directory-path and referral-form-logfile-path.
2. Java class/file Reggie.java in src/net/sf/basedb/reggie/ updated by defining new static final String constants for form template directory paths, REFERRAL_FORM_TEMPLATES_DIR and REFERRAL_FORM_TEMPLATES_OLD_DIR, set to "/home/SCANB/ReferralFormTemplatesInUse" and "/home/SCANB/ReferralFormTemplatesOld", respectively.
3. Java servlet class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) for commands "Validate" and "Install" to create form template directories in BASE file system, if not existing, together with sub-directories for each SCAN-B site, named after the site prefix.
4. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Static final String constant REF_FORM_LOG_DEFAULT_FILENAME renamed REF_FORM_LOG_FILENAME, since its value is now used as filename for the log file.
   b. Private method String fetchReferralFormTemplateFileDirPath() removed, since the path is now specified in Reggie.REFERRAL_FORM_TEMPLATES_DIR.
   c. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated by using Reggie.REFERRAL_FORM_TEMPLATES_DIR for referral form template file directory path, instead of calling method String fetchReferralFormTemplateFileDirPath().
   d. Private method fetchReferralFormLogFile(DbControl dc) updated by getting path for log file from constants Reggie.REFERRAL_FORM_TEMPLATES_DIR and REF_FORM_LOG_FILENAME.

[olle]

(In [4039]) Refs #897. SCAN-B referral form generation updated to set BASE file system paths for referral form template file directories and referral form generation log file in the application code, instead of in Reggie configuration file, and let Reggie installation program create the needed directories, if not existing:

1. Reggie configuration file reggie-config.xml in config/ updated in tag referral-form-generation by removing sub-tags template-directory-path and referral-form-logfile-path.
2. Java class/file Reggie.java in src/net/sf/basedb/reggie/ updated by defining new static final String constants for form template directory paths, REFERRAL_FORM_TEMPLATES_DIR and REFERRAL_FORM_TEMPLATES_OLD_DIR, set to "/home/SCANB/ReferralFormTemplatesInUse" and "/home/SCANB/ReferralFormTemplatesOld", respectively.
3. Java servlet class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) for commands "Validate" and "Install" to create form template directories in BASE file system, if not existing, together with sub-directories for each SCAN-B site, named after the site prefix.
4. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Static final String constant REF_FORM_LOG_DEFAULT_FILENAME renamed REF_FORM_LOG_FILENAME, since its value is now used as filename for the log file.
   b. Private method String fetchReferralFormTemplateFileDirPath() removed, since the path is now specified in Reggie.REFERRAL_FORM_TEMPLATES_DIR.
   c. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated by using Reggie.REFERRAL_FORM_TEMPLATES_DIR for referral form template file directory path, instead of calling method String fetchReferralFormTemplateFileDirPath().
   d. Private method fetchReferralFormLogFile(DbControl dc) updated by getting path for log file from constants Reggie.REFERRAL_FORM_TEMPLATES_DIR and REF_FORM_LOG_FILENAME.

[Nicklas Nordborg]

(In [4042]) References #897: Generate SCAN-B referral forms in Reggie

The patientCuratorUse permissions should not be used together with effectivePermissionsUse since they have conflicting permissions for the "SCAN-B" project.

[olle]

(In [4048]) Refs #897. SCAN-B referral form generation updated for clinical pathology referral forms by making the smallest bar codes wider, in order to increase automatic readability:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated in private method PdfUtil createClinPathologyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList) to make the smallest bar codes wider.

[olle]

Functional specification update:

• Referral template PDF files should be allowed to have names prefixed with the site name in upper case letters, where any Swedish letters "ÅÄÖåäö" first have been replaced by "AAOaao", respectively, followed by either a hyphen "-", or an underscore "_" character before the part of the filename, identifying the type of template.

Design update:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated to call new private method String fetchUpperCaseAnglifiedSiteName(String prefix), and check if a template file can be found with this prefix followed by either a hyphen "-", or an underscore "_" character before the part of the filename, identifying the type of template.
   b. New private method String fetchUpperCaseAnglifiedSiteName(String prefix) added. It gets the site name for the given prefix and then calls new private method String anglifyString(String text) to replace special Swedish characters with their English lower case root characters, after which the upper case string is returned.
   c. New private method String anglifyString(String text) added. It replaces special Swedish characters with their English lower case root characters.

[olle]

(In [4057]) Refs #897. SCAN-B referral form generation updated to allow referral template PDF files to have names prefixed with the site name in upper case letters, where any Swedish letters "ÅÄÖåäö" first have been replaced by "AAOaao", respectively, followed by either a hyphen "-", or an underscore "_" character before the part of the filename, identifying the type of template.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated to call new private method String fetchUpperCaseAnglifiedSiteName(String prefix), and check if a template file can be found with this prefix followed by either a hyphen "-", or an underscore "_" character before the part of the filename, identifying the type of template.
   b. New private method String fetchUpperCaseAnglifiedSiteName(String prefix) added. It gets the site name for the given prefix and then calls new private method String anglifyString(String text) to replace special Swedish characters with their English lower case root characters, after which the upper case string is returned.
   c. New private method String anglifyString(String text) added. It replaces special Swedish characters with their English lower case root characters.

[olle]

(In [4063]) Refs #897. SCAN-B referral form generation updated in method for replacing national Swedish characters in a string with their root characters, to not change case:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:[BR]]a. Private method String anglifyString(String text) updated to not change case, when modifying national Swedish characters to their root characters.

[olle]

Functional specification update:

• SCAN-B ID's should be unique also when ignoring the two-character site prefix. The file containing SCAN-B referral start information can therefore be simplified to a single line with two columns, separated by a tab character: The first column contains the next pure SCAN-B ID (SCAN-B ID without site prefix) to be used (including any initial zeroes), while the second column contains the date, the file was last updated, in "YYYY-MM-DD" format.

Design update:

1. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep2a(response) to obtain pure start SCAN-B ID and date for last update from JSONObject in response via JSON keys "startScanbIdPure" and "lastUpdated", respectively, and create start SCAN-B ID by adding site prefix to the pure start SCAN-B ID.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "UpdateUsedScanbIdList" to obtain the pure SCAN-B ID from the input start SCAN-B ID parameter, and use the former as input when calling private method String nextScanbId(String scanbId, Integer incr) to obtain the next pure SCAN-B ID to use after increment with the number of created form sets. The SCAN-B referral start information file is then updated with the new next pure SCAN-B ID and today's date in "YYYY-MM-DD" format.
   b. Private method JSONObject fetchReferralStartInfo() updated to read the next pure SCAN-B ID and date the file was last updated from the SCAN-B referral start information file, and store the strings in the returned JSONObject via JSON keys "startScanbIdPure" and "lastUpdated", respectively.
   c. Private method String nextScanbId(String scanbId, Integer incr) updated to support an input SCAN-B ID without site prefix, in addition to a complete SCAN-B ID.

[olle]

(In [4064]) Refs #897. SCAN-B referral form generation updated to make SCAN-B ID's unique also when ignoring the two-character site prefix. The file containing SCAN-B referral start information is therefore simplified to a single line with two columns, separated by a tab character: The first column contains the next pure SCAN-B ID (SCAN-B ID without site prefix) to be used (including any initial zeroes), while the second column contains the date, the file was last updated, in "YYYY-MM-DD" format.

1. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep2a(response) to obtain pure start SCAN-B ID and date for last update from JSONObject in response via JSON keys "startScanbIdPure" and "lastUpdated", respectively, and create start SCAN-B ID by adding site prefix to the pure start SCAN-B ID.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "UpdateUsedScanbIdList" to obtain the pure SCAN-B ID from the input start SCAN-B ID parameter, and use the former as input when calling private method String nextScanbId(String scanbId, Integer incr) to obtain the next pure SCAN-B ID to use after increment with the number of created form sets. The SCAN-B referral start information file is then updated with the new next pure SCAN-B ID and today's date in "YYYY-MM-DD" format.
   b. Private method JSONObject fetchReferralStartInfo() updated to read the next pure SCAN-B ID and date the file was last updated from the SCAN-B referral start information file, and store the strings in the returned JSONObject via JSON keys "startScanbIdPure" and "lastUpdated", respectively.
   c. Private method String nextScanbId(String scanbId, Integer incr) updated to support an input SCAN-B ID without site prefix, in addition to a complete SCAN-B ID.

[olle]

Functional specification update:

• SCAN-B referral form generation should create a SCAN-B referral start information file, if it does not exist. The next pure SCAN-B ID should be set to "16000", and the date for last update to today's date in "YYYY-MM-DD" format.

Design update:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method JSONObject fetchReferralStartInfo() updated to check if the SCAN-B referral start information file exists, and if not, call new private method void createReferralStartInfoFile() to create it.
   b. New private method void createReferralStartInfoFile() added. It creates a SCAN-B referral start information file, and sets the next pure SCAN-B ID to "16000", and the date for last update to today's date in "YYYY-MM-DD" format.

[olle]

(In [4065]) Refs #897. SCAN-B referral form generation updated tp create a SCAN-B referral start information file, if it does not exist. The next pure SCAN-B ID should be set to "16000", and the date for last update to today's date in "YYYY-MM-DD" format.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method JSONObject fetchReferralStartInfo() updated to check if the SCAN-B referral start information file exists, and if not, call new private method void createReferralStartInfoFile() to create it.
   b. New private method void createReferralStartInfoFile() added. It creates a SCAN-B referral start information file, and sets the next pure SCAN-B ID to "16000", and the date for last update to today's date in "YYYY-MM-DD" format.

[olle]

Functional specification update:

• SCAN-B referral form generation should count the number of pages in known multi-page PDF templates for batch file 2 (regular paper, double-sided printing, two pages per sheet), and add an extra blank page, if the number of pages is odd. This allows the number of pages in the template to be changed later, without a code update.

Design update:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method PdfUtil createPatientInfoForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) updated to try to add a new page from the template PDF file, until an exception is thrown. Public PdfUtil method void importPdf(InputStream pdf, int pageNo, ...) throws a java.lang.IllegalArgumentException, if an illegal page number is used. This exception is catched by the code, and the number of successfully added pages until that is counted. If the number of pages is odd, an extra blank page is added.

[olle]

(In [4066]) Refs #897. SCAN-B referral form generation updated to count the number of pages in known multi-page PDF templates for batch file 2 (regular paper, double-sided printing, two pages per sheet), and add an extra blank page, if the number of pages is odd. This allows the number of pages in the template to be changed later, without a code update.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method PdfUtil createPatientInfoForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList) updated to try to add a new page from the template PDF file, until an exception is thrown. Public PdfUtil method void importPdf(InputStream pdf, int pageNo, ...) throws a java.lang.IllegalArgumentException, if an illegal page number is used. This exception is catched by the code, and the number of successfully added pages until that is counted. If the number of pages is odd, an extra blank page is added.

[olle]

Functional specification update:

• SCAN-B referral form generation should support creation of several referral forms of the same creation type, but with different templates, for the same SCAN-B ID. Referral form templates are regarded as belonging to the same creation type, if they require SCAN-B ID information to be added as text and/or bar codes in the exact same layout.

Implementation:

1. Referral form template PDF files for the same creation type should be placed in the BASE file system form template directory for the site in question, and have filenames beginning with the specified key string for the form creation type.
2. SCAN-B referral form generation should be updated to create a referral form for all template files with filenames beginning with the specified key string for the form creation type.

Design update:

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated to return a list List<File> of all template PDF files for the site with filenames beginning with the specified key string for the form creation type.
   b. Private methods for creating a referral form of a specific creation type,
   i. PdfUtil createPatientInfoForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList),
   ii. PdfUtil createConsentReportForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList),
   iii. PdfUtil createClinChemForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   iv. PdfUtil createClinPathologyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   v. PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   vi. PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   each split into two, where the first now obtains a list of template PDF files from the call to private method List<File> fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName). The new second method is called for each of the template PDF files in the list, with the file as third argument. The new second method has the same name as the first and the same arguments, except that for a new third argument File pdfFile, and the lack of argument String formTemplateName. All previous code for adding SCAN-B ID information as text and/or bar codes are moved to the second method, which returns an (optionally) updated PdfUtil object.

[olle]

(In [4068]) Refs #897. SCAN-B referral form generation updated to support creation of several referral forms of the same creation type, but with different templates, for the same SCAN-B ID. Referral form templates are regarded as belonging to the same creation type, if they require SCAN-B ID information to be added as text and/or bar codes in the exact same layout. SCAN-B referral form generation is updated to create a referral form for all template files with filenames beginning with the specified key string for the form creation type.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Private method File fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName) updated to return a list List<File> of all template PDF files for the site with filenames beginning with the specified key string for the form creation type.
   b. Private methods for creating a referral form of a specific creation type,
   i. PdfUtil createPatientInfoForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList),
   ii. PdfUtil createConsentReportForm(DbControl dc, PdfUtil pdfUtil, String scanbId, List<String> formTemplateFileList),
   iii. PdfUtil createClinChemForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   iv. PdfUtil createClinPathologyForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   v. PdfUtil createClinChemBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   vi. PdfUtil createClinChemBcBloodForm(DbControl dc, PdfUtil pdfUtil, String scanbId, String formTemplateName, List<String> formTemplateFileList),
   each split into two, where the first now obtains a list of template PDF files from the call to private method List<File> fetchReferralFormTemplateFile(DbControl dc, String scanbId, String formTemplateName). The new second method is called for each of the template PDF files in the list, with the file as third argument. The new second method has the same name as the first and the same arguments, except that for a new third argument File pdfFile, and the lack of argument String formTemplateName. All previous code for adding SCAN-B ID information as text and/or bar codes are moved to the second method, which returns an (optionally) updated PdfUtil object.

[olle]

Functional specification update:

• SCAN-B referral form generation should be updated in step 2, when a start SCAN-B ID is entered with a pure SCAN-B ID (SCAN-B ID excluding site prefix) < the stored start pure SCAN-B ID, to require a check button to be checked before the "Next" button can be clicked. This is to avoid creating referral forms with already existing SCAN-B ID numbers by mistake.

Design update:

1. JSP file generate-referral-forms.jsp in resources/personal/ updated by removing button with id "goreferralgeneration" and title "Generate referral forms", since its functionality is going to be replaced by the standard button with id "gonext" and title "Next".
2. Javascript file generate-referral-forms.js in resources/personal/ updated:
   a. Variable refStartScanbIdPure made global, so the value retrieved in function initializeStep2a(response) will be available for comparison in function caseNameOnChange(). It is initialized to an empty string in function initPage().
   b. Other updates in function initPage(): Functionality previously performed by button with id "goreferralgeneration" is now performed by standard button with id "gonext". The latter will therefore by coupled to standard action Wizard.goNextOnClick(), instead of function initializeStep2a(response). Validation of step 1 is now coupled to new function validateStep1(event), which calls function initializeStep2a(response) (currently the only functionality in the former function). Function validateStep2() is now correctly coupled to validation of step 2.
   c. Function caseNameOnChange() updated to disable the "Next" button at the beginning, and then enabling it at the end, if all case name tests passed successfully. After testing for a valid case name (SCAN-B ID), a test is added to check if the current start pure SCAN-B ID is smaller than the stored start pure SCAN-B ID, in which case standard function Wizard.showGoNextConfirmation(...) is called to require the user to check a check box, before being able to continue with the entered SCAN-B ID.
   d. Function validateStep2(event) moved to a more logical place in the code after other functions related to step 2, and updated by calling function generateReferralForms() at the end.

[olle]

(In [4074]) Refs #897. SCAN-B referral form generation updated in step 2, when a start SCAN-B ID is entered with a pure SCAN-B ID (SCAN-B ID excluding site prefix) < the stored start pure SCAN-B ID, to require a check button to be checked before the "Next" button can be clicked. This is to avoid creating referral forms with already existing SCAN-B ID numbers by mistake.

1. JSP file generate-referral-forms.jsp in resources/personal/ updated by removing button with id "goreferralgeneration" and title "Generate referral forms", since its functionality is going to be replaced by the standard button with id "gonext" and title "Next".
2. Javascript file generate-referral-forms.js in resources/personal/ updated:
   a. Variable refStartScanbIdPure made global, so the value retrieved in function initializeStep2a(response) will be available for comparison in function caseNameOnChange(). It is initialized to an empty string in function initPage().
   b. Other updates in function initPage(): Functionality previously performed by button with id "goreferralgeneration" is now performed by standard button with id "gonext". The latter will therefore by coupled to standard action Wizard.goNextOnClick(), instead of function initializeStep2a(response). Validation of step 1 is now coupled to new function validateStep1(event), which calls function initializeStep2a(response) (currently the only functionality in the former function). Function validateStep2() is now correctly coupled to validation of step 2.
   c. Function caseNameOnChange() updated to disable the "Next" button at the beginning, and then enabling it at the end, if all case name tests passed successfully. After testing for a valid case name (SCAN-B ID), a test is added to check if the current start pure SCAN-B ID is smaller than the stored start pure SCAN-B ID, in which case standard function Wizard.showGoNextConfirmation(...) is called to require the user to check a check box, before being able to continue with the entered SCAN-B ID.
   d. Function validateStep2(event) moved to a more logical place in the code after other functions related to step 2, and updated by calling function generateReferralForms() at the end.

[olle]

Functional specification update:

• SCAN-B referral form generation should warn the user, when more than one referral template PDF file exists for a form creation type for the selected site, and require a check button to be checked before continuing. Multiple template files for the same form creation type are allowed, and will result in forms being generated for each template. The warning/confirmation discussed is intended to avoid unwanted versions of forms to be created, e.g. after new versions of templates have been installed, but the old versions have not been removed.

Design discussion:

1. Use of standard action Wizard.showGoNextConfirmation(...) in the Javascript file to add a check button before being able to continue, is designed to work with the standard "Next" button coupled to standard action Wizard.goNextOnClick(). Only one confirmation check box per step is supported, and an optional confirmation check box is already implemented in step 2, when a start SCAN-B ID is entered with a pure SCAN-B ID (SCAN-B ID excluding site prefix) < the stored start pure SCAN-B ID. Since all information required to determine what template files will be used is entered in step 1 (site and form set variant), it is natural to add the new confirmation check box here.
2. Changes in the two menus for site and form set variant in step 1 should be coupled to a siteAndVariantOnChange() function, that checks if a confirmation check box for multiple template files for the same form creation type should be added. To ensure that this function is always called at least once, both menus cannot have allowed default values. Since it is more probable that the form set will be "Kit 1 - Standard", than that the default site is the desired one, the site menu should be changed to have an empty string as default value, coupled to menu text "- Select site -".
3. Step one should be updated to have the "Next" button to be disabled at start. If function siteAndVariantOnChange() (or, more correctly, its callback function preValidateStep1(response) after calling servlet ReferralGeneratorServlet with new command "GetReferralTemplateInfo") determines that both site and form set variant have allowed values and no multiple template files exists for the site, it enables the "Next" button.

Design update:

1. JSP file generate-referral-forms.jsp in resources/personal/ updated for step 1 by adding new div tag with id "step1message" after the step table. The new tag will be used to display information on multiple template files for the same form creation type and selected site.
2. Javascript file generate-referral-forms.js in resources/personal/ updated:
   a. Function initPage() updated to couple changes in menus for site and form set variant to new siteAndVariantOnChange() function. Also, the "Next" button will be disabled at start.
   b. Function sitesLoaded(response) updated to add new default option "- Select site -" to the site menu. The new default option has an empty string as value.
   c. New function siteAndVariantOnChange() added. It obtains values for site and form set variant, and if they are valid, calls servlet ReferralGeneratorServlet with new command "GetReferralTemplateInfo" and callback function preValidateStep1(response). If the values are invalid, the "Next" button is disabled (it may have been enabled by the user having selected valid menu options previously).
   d. New callback function preValidateStep1(response) added. It obtains a JSONArray of optional multiple template files. If the JSONArray is empty, the "Next" button is enabled, otherwise a JSONObject is obtained for each multiple template file and a table showing a list of filename and template type for multiple template files is added to div tag with id "step1message", and a confirmation check box is added with standard action Wizard.showGoNextConfirmation(...).
   e. Unused variables removed.
3. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated with new command "GetReferralTemplateInfo". It obtains values for site and form set variant from the request, and calls new private method JSONArray fetchMultipleTemplateFiles(DbControl dc, String scanbIdPrefix, String formTemplateName, JSONArray jsonMultipleTemplFiles) for the relevant form template names to update a JSONArray with info on any multiple template files for the same form creation type and site. The JSONArray is added to the returned JSON object with JSON key "multTemplates".
   b. New private method JSONArray fetchMultipleTemplateFiles(DbControl dc, String scanbIdPrefix, String formTemplateName, JSONArray jsonMultipleTemplFiles) added. It returns a JSONArray of JSONObjects for multiple BASE file items for given form creation type and site.

[olle]

(In [4080]) Refs #897. SCAN-B referral form generation updated to warn the user, when more than one referral template PDF file exists for a form creation type for the selected site, and require a check button to be checked before continuing. Multiple template files for the same form creation type are allowed, and will result in forms being generated for each template. The warning/confirmation discussed is intended to avoid unwanted versions of forms to be created, e.g. after new versions of templates have been installed, but the old versions have not been removed.

1. JSP file generate-referral-forms.jsp in resources/personal/ updated for step 1 by adding new div tag with id "step1message" after the step table. The new tag will be used to display information on multiple template files for the same form creation type and selected site.
2. Javascript file generate-referral-forms.js in resources/personal/ updated:
   a. Function initPage() updated to couple changes in menus for site and form set variant to new siteAndVariantOnChange() function. Also, the "Next" button will be disabled at start.
   b. Function sitesLoaded(response) updated to add new default option "- Select site -" to the site menu. The new default option has an empty string as value.
   c. New function siteAndVariantOnChange() added. It obtains values for site and form set variant, and if they are valid, calls servlet ReferralGeneratorServlet with new command "GetReferralTemplateInfo" and callback function preValidateStep1(response). If the values are invalid, the "Next" button is disabled (it may have been enabled by the user having selected valid menu options previously).
   d. New callback function preValidateStep1(response) added. It obtains a JSONArray of optional multiple template files. If the JSONArray is empty, the "Next" button is enabled, otherwise a JSONObject is obtained for each multiple template file and a table showing a list of filename and template type for multiple template files is added to div tag with id "step1message", and a confirmation check box is added with standard action Wizard.showGoNextConfirmation(...).
   e. Unused variables removed.
3. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated with new command "GetReferralTemplateInfo". It obtains values for site and form set variant from the request, and calls new private method JSONArray fetchMultipleTemplateFiles(DbControl dc, String scanbIdPrefix, String formTemplateName, JSONArray jsonMultipleTemplFiles) for the relevant form template names to update a JSONArray with info on any multiple template files for the same form creation type and site. The JSONArray is added to the returned JSON object with JSON key "multTemplates".
   b. New private method JSONArray fetchMultipleTemplateFiles(DbControl dc, String scanbIdPrefix, String formTemplateName, JSONArray jsonMultipleTemplFiles) added. It returns a JSONArray of JSONObjects for multiple BASE file items for given form creation type and site.

[olle]

(In [4081]) Refs #897. SCAN-B referral form generation updated to display better progress information, when generating referral forms.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. Value of static constant String REFERRAL_GENERATION_PROGRESS_ID set to "ref-gen-progress", which is used in Javascript generate-referral-forms.js in resources/personal/.
   b. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated for command "GenerateReferralForms" to estimate fractions of time spent on generating forms for batch file 1 and 2, respectively, based on the assumption that one form for each relevant form creation type will be generated. The progress percentage for creating forms for batch file 2 will be offset with the percentage used on creating forms for batch file 1.

[olle]

(In [4082]) Refs #897. SCAN-B referral form generation updated to display better progress information, when generating referral forms.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) for command "GenerateReferralForms" to use title "Generating referral forms..." for the progress information, and to set the title to an empty string for the final progress report at 100%, so not to interfere with the display of any result messages.

[olle]

(In [4083]) Refs #897. SCAN-B referral form generation updated to display a message with information on the SCAN-B ID range for which referral forms had been created.

1. Javascript file generate-referral-forms.js in resources/personal/ updated in function initializeStep3(response) to add standard action Wizard.showFinalMessage(response.messages).
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) for command "GenerateReferralForms" to add a message string to JSONArray jsonMessages at the end, containing information on the SCAN-B ID range for which referral forms had been created.

[olle]

Functional specification update:

• It was decided to move configuration information for SCAN-B referral form generation from Reggie configuration file reggie-config.xml to the servlet code, in order not to clutter the former file. The background for the decision was that there were few use cases where a change in SCAN-B referral form generation could be restricted to a change in the configuration file only.

Design update:

1. Reggie configuration file reggie-config.xml in config updated by removing tag referral-form-generation, since the information therein has been moved to the servlet code.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. New private static string constants defined for beginnings of filenames for referral form templates of different form creation types.
   b. New private static hash map HashMap<String,String> refFormTemplNameStartHM defined. It will map a form template type to beginning of filenames for template files for the type.
   c. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated to call new private method void initializeRefFormTemplNameStartHashMap() before executing any request command.
   d. New private method void initializeRefFormTemplNameStartHashMap() added. It initializes new private static hash map HashMap<String,String> refFormTemplNameStartHM using private static string constants for form template creation types and beginnings of filenames for referral form templates for these types.
   e. Private method String fetchReferralFormTemplateFilenameStart(String formTemplateName) updated to get infomation from new private static hash map HashMap<String,String> refFormTemplNameStartHM using argument String formTemplateName as key, instead of getting the information from the Reggie configuration file.

[olle]

(In [4088]) Refs #897. SCAN-B referral form generation updated by moving configuration information for SCAN-B referral form generation from Reggie configuration file reggie-config.xml to the servlet code, in order not to clutter the former file. The background for the decision was that there were few use cases where a change in SCAN-B referral form generation could be restricted to a change in the configuration file only.

1. Reggie configuration file reggie-config.xml in config updated by removing tag referral-form-generation, since the information therein has been moved to the servlet code.
2. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated:
   a. New private static string constants defined for beginnings of filenames for referral form templates of different form creation types.
   b. New private static hash map HashMap<String,String> refFormTemplNameStartHM defined. It will map a form template type to beginning of filenames for template files for the type.
   c. Protected method void doGet(HttpServletRequest req, HttpServletResponse resp) updated to call new private method void initializeRefFormTemplNameStartHashMap() before executing any request command.
   d. New private method void initializeRefFormTemplNameStartHashMap() added. It initializes new private static hash map HashMap<String,String> refFormTemplNameStartHM using private static string constants for form template creation types and beginnings of filenames for referral form templates for these types.
   e. Private method String fetchReferralFormTemplateFilenameStart(String formTemplateName) updated to get infomation from new private static hash map HashMap<String,String> refFormTemplNameStartHM using argument String formTemplateName as key, instead of getting the information from the Reggie configuration file.

[olle]

(In [4091]) Refs #897. SCAN-B referral form generation updated when retrieving list of referral form template PDF files of specific form type in BASE file system to order the files in ascending order alphabetically by filename.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated in private method List<File> fetchReferralFormTemplateFileList(DbControl dc, String scanbId, String formTemplateName) to order returned file items in ascending order alphabetically by filename.

[olle]

(In [4096]) Refs #897. SCAN-B referral form generation updated by removing or commenting out log messages for normal referral generation.

1. Java servlet class/file ReferralGeneratorServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) for command "GenerateReferralForms" by removing or commenting out log messages for normal referral generation.

[olle]

Ticket closed as the first version of referral form generation is ready for testing.

[olle]

Summary of the first version of SCAN-B referral form generation (2016-09-13):

Definitions:

• A form set consists of forms with the same base SCAN-B ID, i.e. ignoring an optional suffix.
• A form set variant specifies what forms are contained in the set.
• A form batch consists of a number of form sets with consecutive SCAN-B ID's.
• A form batch is distributed as two PDF files, with forms intended for printing on referral form sheets or regular paper, respectively.

Form set variants (Initially, two variants should be available):

• Kit 1 - Standard
• Kit 2 - Neoadjuvant therapy

Batch files:

• Batch file 1 (referral form sheets): One-sided printing, one page per sheet.
• Batch file 2 (regular paper): Double-sided printing, two pages per sheet.

Forms in batch file 2 with templates having an odd number of pages, will have an extra blank page added in the PDF file, in order to be used for double-sided printing, two pages per sheet.

Form sets:

Form set	Type	Kit 1	Kit 2	File 1	File 2
Patient info	Regular paper	x	x		x
Clinical chemistry - biopsy	Form sheet		x	x
Clinical chemistry - blood	Form sheet	x	x		x
Clinical chemistry - blood Lund copy	Form sheet	x	x		x
Clinical chemistry - BC blood	Form sheet	x	x	x
Middle needle biopsy	Form sheet		x	x
Clinical chemistry	Form sheet	x	x	x
Clinical pathology	Form sheet	x	x	x
Consent report	Regular paper	x	x		x

Barcodes are used in several sizes on the referral forms. The encoding used is "Code 128".

Installation instructions:

• The referral form generation uses template PDF files for creating the forms.
• A template contains all information except SCAN-B ID text and barcodes, which are added, when the complete form is generated.
• In order for the patient curator to be able to replace templates with new versions, the template files are placed in the BASE file system. Also, in order to support variations in the text and layout of templates for different sites (other than the SCAN-B text and barcodes), templates for different sites are placed in separate sub-directories.

1. Create referral form template directories in BASE file system.

• The template top directory is /home/SCANB/ReferralFormTemplatesInUse/.
• Each site has a sub-directory named after the site's SCAN-B prefix. e.g. /home/SCANB/ReferralFormTemplatesInUse/88/ for Uppsala with prefix "88".
• Create a similar directory structure with top directory /home/SCANB/ReferralFormTemplatesOld/ for back-up use (not used by the software).

2. Give referral form template PDF files names indicating the form type.

• The application identifies a template's type based on the start of its filename.
• A start string should be unique and not be a sub-string of another start string.
• A start string should not include version information, and normally not site-specific information.
• A form template filename, however, is recommended to contain version information in part of the filename following the start string, since the complete filenames of used templates for a referral form generation session are included in an entry in the referral form generation log file.
• When generating referral forms for a site, the application looks for templates of all type of forms.
  a. If no template file with a valid filename is found for a specific form type and site, that form type is skipped in the output.
  b. If a single template file with a valid filename is found for a specific form type and site, a referral form is created for that template.
  c. If more than one template file with a valid filename is found for a specific form type and site, first a warning is displayed, followed by a check box, where the user can confirm, that the form generation shall continue. If OK, referral forms are created for all the valid templates, in alphabetical order of the template filenames.

Form type	Start of template filenames *
Patient info	Patinfo
Clinical chemistry - biopsy	KlinKemBiopsy-SCAN-B-remiss
Clinical chemistry - blood	KlinKem-SCAN-B-blood-biobanken_remiss
Clinical chemistry - blood Lund copy	KlinKem-SCAN-B-blood-biobanken-lundkopia_remiss
Clinical chemistry - BC blood	KlinKem-SCAN-B-bcblood-remiss
Middle needle biopsy	PathBiopsy-SCAN-B-remiss
Clinical chemistry	Klinkem-SCAN-B-remiss
Clinical pathology	Path-SCAN-B-remiss
Consent report	Consent-SCAN-B-remiss

As an example, the patient info form template may have the full filename "Patinfo_3_0_120109_SCAN-B.pdf", and the clinical pathology form template the full filename "Path-SCAN-B-remiss_v7.pdf".

* The first version of the referral form generation allows referral template PDF files to have names prefixed with the site name in upper case letters, where any Swedish letters "ÅÄÖåäö" first have been replaced by "AAOAAO", respectively, followed by either a hyphen "-", or an underscore "_" character before the part of the filename, identifying the type of template, e.g. a clinical pathology template file for Malmö might be named "MALMO_Path-SCAN-B-remiss_v7.pdf", where the key string "Path-SCAN-B-remiss" identifies that the template is intended for clinical pathology forms.

3. Copy referral form template files to use to sub-directory for each site.

• For all form types supported for a site, copy the corresponding form template PDF file to the sub-directory for the site.
• For the first release, the following table may be of help:

Form type	Supported by site[s]
Patient info	All
Clinical chemistry - biopsy	All
Clinical chemistry - blood	Uppsala (88) only
Clinical chemistry - blood Lund copy	Uppsala (88) only
Clinical chemistry - BC blood	Lund (11) only
Middle needle biopsy	All
Clinical chemistry	All except Uppsala (88)
Clinical pathology	All
Consent report	All

Log file with info on generated referral forms:

• A text file named refFormLogFile.txt is stored in the referral form template top directory /home/SCANB/ReferralFormTemplatesInUse/ in BASE file system, and contains an entry line for each referral form creation session.
• A log entry contains date and time, kit selected, range of SCAN-B ID for created forms, and a comma-separated list of filenames for used template PDF files. If the template filenames contain version information (after the string identifying the form type), this provides a way to check what template versions were used to create a specific batch of referral forms.

[Nicklas Nordborg]

(In [4117]) References #897: Generate SCAN-B referral forms in Reggie

Get rid of compiler warnings.