Retraction wizard - Step 2: Follow up

[olle]

The first step of the retraction wizard was concerned with marking extracts for retraction, and to produce lists and protocols to simplify finding these in the lab or external storage. The second step will be focused on the follow-up of step 1, where a web form will be presented for a selected retraction object, allowing dates to be entered when different sub-steps are finished. When all sub-steps are marked to have been finished, the items should be marked to be ready for deletion/destruction.

[olle]

Ticket accepted.

[olle]

Traceability note:

• The retraction wizard was introduced in Ticket #526 (Retraction wizard).

[olle]

Background:

The full retraction module is intended to contain 3 parts:
1. Mark extracts for retraction. (Ticket #526)
2. Retraction follow-up (this ticket)
3. Destruction (to be defined later)

Functional specification for the retraction follow-up step:

1. Biosource items of type "Retract" or "RetroNo" should keep track of what parts in the retraction module have been finished. To simplify the discussion, lets assumed that biosource items of type "Retract" or "RetroNo" should support a new enumerated string annotation "RetractStatus" with options "ReadyForDestruction" and "RetractionCompleted" (null is default; option "RetractionCompleted" is intended to be set in part 3 "Destruction").
2. A case name or personal number should be input:
   a. If a case name is input, the patient related to that case should be found. As is described in the next section, the "patient" item will technically be a biosource item of type "Retract" or "RetroNo", instead of "Patient", but for for simplicity, it will be referred to as a patient item in this description.
   b. When part 1, "Mark extracts for retraction", is finished, the patient type is changed to "Retract" or "RetroNo". Part 2, "Retraction follow-up", is not intended to be used until part 1 is finished, so it is natural to include a check that the patient type is correct for retraction. In addition, annotation "RetractStatus" should not have value "RetractionCompleted", since that indicates that the retraction process is already finished for the patient item.
3. a. A form with input fields for seven dates should be presented for the patient in question (regarding requests forwarded to other projects, it is implied that the projects use samples or data stored using the SCAN-B consent):
   

Header	Date sent prompt	Date received prompt	Comment
Laboratory	Date sent	Date received	Dates when retraction request sent to and response received from laboratory (YYYYMMDD)
Blood samples	Date sent	Date received	Dates when retraction request sent and response received for blood samples (YYYYMMDD)
Frozen samples	Date sent	Date received	Dates when retraction request sent and response received for frozen samples (YYYYMMDD)
Forwarded	Date sent		Date when retraction request forwarded to other projects (YYYYMMDD)

b. The date fields should be loaded with previously stored dates for the patient, if any.
c. The date input fields should be coupled to a number of sanity checks: apart from normal checks for date syntax, future dates should not be allowed, and for items with both a sent and received date, the latter should not be allowed to be earlier than the sent date.
d. A "Cancel" and a "Register" button should appear below the form. When the "Register" button is clicked, the data in the date fields should be stored in annotations for the patient.
e. When a registration with all seven date values filled in is made, "RetractStatus" for the patient item is set to "ReadyForDestruction", while if any date value is missing, it is set to null.

[olle]

Design specification for the retraction follow-up step:

1. JSP file index.jsp in resources/ is updated with new entry "Retraction follow-up" under header "Retraction wizard" in section "Personal information wizards". The entry has a link to new JSP file retraction_followup_form.jsp in resources/personal/ and a new data-counter "patientitems-ready-for-retraction-followup". In addition, a new inactive entry "Destruction" is also added, with a data-counter "patientitems-ready-for-destruction".
2. JSP file retraction_followup_form.jsp in resources/personal/ is coupled to Javascript file retraction_followup_form.js, also in resources/personal/.
   a. The JSP file has an input field for entering a case name or personal number. After initial validation of the case name/personal number, function rf.caseNameOnChange() calls servlet RetractionFollowUpFormServlet with command "GetCaseInfo" to obtain a JSONObject with information on all cases for the patient in question, that is processed by function rf.onCaseInfoLoaded(response), to determine if the patient biosource type is correct ("Retract" or "RetroNo" are allowed for the follow-up step).
   c. Function rf.initializeStep2() then calls servlet RetractionFollowUpFormServlet with command "GetCaseInfo" a second time, where the response is processed by function rf.caseInfoLoaded(response), which fills retract data retrieved from the database into input fields in the form. The second step of the form contains input fields for seven retraction request and response dates for the patient in question.
   d. The date fields are coupled to validation checks by functions rf.labDateOnChange(), rf.bloodDateOnChange(), rf.frozenDateOnChange(), and rf.forwardedDateOnChange().
   e. Button "Register" is coupled to function rf.submit(), that sends the retract request and response date values in the form together with the input case name/personal number to servlet RetractionFollowUpFormServlet with command "RegisterRetraction".
3. New java servlet class/file RetractionFollowUpFormServlet.java in src/net/sf/basedb/reggie/servlet/ accepts GET requests for command "GetCaseInfo", and POST request for command "RegisterRetraction". It accesses the database to retrieve the requested information, or update the contents, and sends the results back in JSON format. The functionality for command "GetCaseInfo" is basically identical to that of servlet RetractionFormServlet, while command "RegisterRetraction" stores date values from the form in new annotations for patient items of biosource type "Retract" or "RetroNo". If all seven dates are set, new enumerable string annotation "RetractStatus" is set to value "ReadyForDestruction" (default value is null).
4. XML servlet configuration file servlets.xml in META-INF/ updated with entry for new servlet RetractionFollowUpFormServlet.
5. Java class/file Annotationtype.java in src/net/sf/basedb/reggie/dao/ updated with seven new retract date annotations:
   RETRACT_REQUEST_SENT_TO_LABORATORY_DATE
   RETRACT_RESPONSE_RECEIVED_FROM_LABORATORY_DATE
   RETRACT_REQUEST_SENT_FOR_BLOOD_SAMPLES_DATE
   RETRACT_RESPONSE_RECEIVED_FOR_BLOOD_SAMPLES_DATE
   RETRACT_REQUEST_SENT_FOR_FROZEN_SAMPLES_DATE
   RETRACT_RESPONSE_RECEIVED_FOR_FROZEN_SAMPLES_DATE
   RETRACT_REQUEST_FORWARDED_TO_RELATED_PROJECTS_DATE
   In addition, a new enumerable string annotation RETRACT_STATUS is defined with two options "ReadyForDestruction" and "RetractionCompleted".
6. Java class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) to create the new annotation type items, if not existing.
7. Java class/file CounterService.java in src/net/sf/basedb/reggie/counter/ updated:
   a. Method void count() updated to call new private methods void CountPatientsReadyForRetractionFollowUp(DbControl dc, JSONObject json) and void CountPatientsReadyForDestruction(DbControl dc, JSONObject json).
   b. New private method void CountPatientsReadyForRetractionFollowUp(DbControl dc, JSONObject json) added. It counts the number of biosource items of type "Retract" or "RetroNo" with annotation RETRACT_STATUS set to null.
   c. New private method void CountPatientsReadyForDestruction(DbControl dc, JSONObject json) added. It counts the number of biosource items of type "Retract" or "RetroNo" with annotation RETRACT_STATUS set to "ReadyForDestruction".

[olle]

(In [3085]) Refs #723. First version of second step of the retraction wizard, which is a follow-up of the first step, that marked samples and extracts for destruction, given a biosource item selected for retraction. The follow-up step keeps track of dates when different types of retraction requests are sent to and responses are received from secondary storage facilities (laboratory, blood, frozen samples, and related projects using the same consent):

1. JSP file index.jsp in resources/ is updated with new entry "Retraction follow-up" under header "Retraction wizard" in section "Personal information wizards". The entry has a link to new JSP file retraction_followup_form.jsp in resources/personal/ and a new data-counter "patientitems-ready-for-retraction-followup". In addition, a new inactive entry "Destruction" is also added, with a data-counter "patientitems-ready-for-destruction".
2. JSP file retraction_followup_form.jsp in resources/personal/ is coupled to Javascript file retraction_followup_form.js, also in resources/personal/.
   a. The JSP file has an input field for entering a case name or personal number. After initial validation of the case name/personal number, function rf.caseNameOnChange() calls servlet RetractionFollowUpFormServlet with command "GetCaseInfo" to obtain a JSONObject with information on all cases for the patient in question, that is processed by function rf.onCaseInfoLoaded(response), to determine if the patient biosource type is correct ("Retract" or "RetroNo" are allowed for the follow-up step).
   c. Function rf.initializeStep2() then calls servlet RetractionFollowUpFormServlet with command "GetCaseInfo" a second time, where the response is processed by function rf.caseInfoLoaded(response), which fills retract data retrieved from the database into input fields in the form. The second step of the form contains input fields for seven retraction request and response dates for the patient in question.
   d. The date fields are coupled to validation checks by functions rf.labDateOnChange(), rf.bloodDateOnChange(), rf.frozenDateOnChange(), and rf.forwardedDateOnChange().
   e. Button "Register" is coupled to function rf.submit(), that sends the retract request and response date values in the form together with the input case name/personal number to servlet RetractionFollowUpFormServlet with command "RegisterRetraction".
3. New java servlet class/file RetractionFollowUpFormServlet.java in src/net/sf/basedb/reggie/servlet/ accepts GET requests for command "GetCaseInfo", and POST request for command "RegisterRetraction". It accesses the database to retrieve the requested information, or update the contents, and sends the results back in JSON format. The functionality for command "GetCaseInfo" is basically identical to that of servlet RetractionFormServlet, while command "RegisterRetraction" stores date values from the form in new annotations for patient items of biosource type "Retract" or "RetroNo". If all seven dates are set, new enumerable string annotation "RetractStatus" is set to value "ReadyForDestruction" (default value is null).
4. XML servlet configuration file servlets.xml in META-INF/ updated with entry for new servlet RetractionFollowUpFormServlet.
5. Java class/file Annotationtype.java in src/net/sf/basedb/reggie/dao/ updated with seven new retract date annotations:
   RETRACT_REQUEST_SENT_TO_LABORATORY_DATE
   RETRACT_RESPONSE_RECEIVED_FROM_LABORATORY_DATE
   RETRACT_REQUEST_SENT_FOR_BLOOD_SAMPLES_DATE
   RETRACT_RESPONSE_RECEIVED_FOR_BLOOD_SAMPLES_DATE
   RETRACT_REQUEST_SENT_FOR_FROZEN_SAMPLES_DATE
   RETRACT_RESPONSE_RECEIVED_FOR_FROZEN_SAMPLES_DATE
   RETRACT_REQUEST_FORWARDED_TO_RELATED_PROJECTS_DATE
   In addition, a new enumerable string annotation RETRACT_STATUS is defined with two options "ReadyForDestruction" and "RetractionCompleted".
6. Java class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) to create the new annotation type items, if not existing.
7. Java class/file CounterService.java in src/net/sf/basedb/reggie/counter/ updated:
   a. Method void count() updated to call new private methods void CountPatientsReadyForRetractionFollowUp(DbControl dc, JSONObject json) and void CountPatientsReadyForDestruction(DbControl dc, JSONObject json).
   b. New private method void CountPatientsReadyForRetractionFollowUp(DbControl dc, JSONObject json) added. It counts the number of biosource items of type "Retract" or "RetroNo" with annotation RETRACT_STATUS set to null.
   c. New private method void CountPatientsReadyForDestruction(DbControl dc, JSONObject json) added. It counts the number of biosource items of type "Retract" or "RetroNo" with annotation RETRACT_STATUS set to "ReadyForDestruction".

[olle]

(In [3086]) Refs #723. Retraction follow-up wizard updated to use own CSS file, in order to make "Next"-button in step 1 have same vertical placement as in other wizards:

1. New CSS file retractionfollowupform.css in resources/css/ added. It is identical to retractionform.css, except that it lacks entry "#wizard-status".
2. JSP file retraction_followup_form.jsp in resources/personal/ updated by exchanging CSS file retractionform.css for retractionfollowupform.css.

[olle]

(In [3087]) Refs #723. Retraction follow-up wizard updated by removal of CSS file retractionfollowupform.css in resources/css/, since it is currently not necessary:

1. CSS file retractionfollowupform.css in resources/css/ removed, since its functionality is currently not used.
2. JSP file retraction_followup_form.jsp in resources/personal/ updated by removing reference to CSS file retractionfollowupform.css.

[olle]

(In [3088]) Refs #723. Retraction follow-up wizard updated to disable step 1 part of form, when action has continued to step 2 (the case name input field is already disabled). This is normally handled by Wizard functionality, but the call structure of the follow-up wizard is complicated by the necessity of making a database query to check the biosource type of the patient item, before continuing to step 2:

1. Javascript file retraction_followup_form.js in resources/personal/ updated in function rf.caseInfoLoaded(response) by adding command "Doc.addClass('step-1', 'disabled');" after "Wizard.setCurrentStep(2);".

If a way is found to disable step 1 using Wizard functionality, while retaining the ability to check the patient biosource type before continuing, this would be a preferred solution.

[olle]

(In [3089]) Refs #723. Retraction follow-up wizard updated to disable step 1 part of form, after action has continued to step 2, using Wizard functionality (thanks to Nicklas Nordborg for pointing out the solution):

1. Javascript file retraction_followup_form.js in resources/personal/ updated:
   a. Function rf.onCaseInfoLoaded(response) updated by adding command "Wizard.goNext(true);" at the end of code section for valid patient data input. Code has been cleaned up by removal of a number of unnecessary commands.
2. Javascript file retraction_followup_form.js in resources/personal/ updated in function rf.caseInfoLoaded(response) by removal of command "Doc.addClass('step-1', 'disabled');" after "Wizard.setCurrentStep(2);", since this is now no longer needed.

[olle]

(In [3090]) Refs #723. Retraction follow-up wizard updated by using Javascript string function indexOf(searchstring) to check if a string starts with a special sub-string (the function equals 0 in this case, since this is the index position of the start of the sub-string in the string of interest). This makes definition of a new string function startsWith(searchstring) unnecessary:

1. Javascript file retraction_followup_form.js in resources/personal/ updated:
   a. Function rf.onCaseInfoLoaded(response) updated by using Javascript string function indexOf(searchstring) to check if a string starts with a special sub-string.
   b. Function rf.caseInfoLoaded(response) updated by using Javascript string function indexOf(searchstring) to check if a string starts with a special sub-string.

[olle]

(In [3091]) Refs #723. Retraction follow-up wizard updated by using shorter names of retract date annotations, since these are visible in some parts of the GUI, and shorter names increase clarity. The shortened names are created according to a simple logical scheme, in order to make the meaning clear, although the name is short ("Tx" = "Transmit", "Rx" = "Receive", "BB" = "BioBank", a swedish storage facility for biological samples, including blood samples):

1. Java class/file Annotationtype.java in src/net/sf/basedb/reggie/dao/ updated with shorter names for seven retract date annotations.
2. Java class/file InstallServlet.java in src/net/sf/basedb/reggie/servlet/ updated in protected method void doGet(HttpServletRequest req, HttpServletResponse resp) to create the new annotation type items, if not existing.
3. Java class/file RetractionFollowUpFormServlet.java in src/net/sf/basedb/reggie/servlet/ updated in private method void loadPatientInfo(DbControl dc, Patient patient) and protected method void doPost(HttpServletRequest req, HttpServletResponse resp) to use the new shorter names of retract date annotations.