[Instrument] Rename Data_entry_completion_status & move to its own co…

…lumn in flag (#6876)

This moves Data_entry_completion_status field to its own column in flag following discussion and renames to it to Required_elements_completed. This ensures that the data is stored in the same place regardless of whether it is a json instrument or a SQL table instrument, and resolves confusion between the "Data Entry" (manually entered user flag) and "Data_entry_completion_status" (automatically calculated to determine if required elements are completed flag.)

CHANGELOG.md

@@ -31,6 +31,7 @@ requesting a new account and will be displayed in the User Accounts module (PR #
 - Candidate's age can be retrieved from the Candidate class in days, months, or years (PR #5945)
 - Addition of autoSelect prop to React SelectElement allows for auto-selection of only available select option (PR #6156)
 - An `AcquisitionDate` field has been added to the `files` table (PR #6892)
+- Data_entry_completion_status given its own column in flag, and renamed to Required_elements_completed (PR #6876)
 - The default value of the ScannerID field of the mri_protocol table is now NULL instead of 0 (PR #7496).
 
 #### Bug Fixes
@@ -111,6 +112,8 @@ requesting a new account and will be displayed in the User Accounts module (PR #
 ### Notes For Existing Projects
 - New function Candidate::getSubjectForMostRecentVisit replaces Utility::getSubprojectIDUsingCandID, adding ability to determine which subproject a candidate belongs to given their most recent visit.
 - LINST instrument class was modified to implement the getFullName() and getSubtestList() functions thus making entries in the test_names and instrument_subtests tables respectively unnecessary for LINST instruments (PR #7169)
+- The `Data_entry_completion_status` column of instrument tables has been migrated to its own column in flag, and renamed to `Required_elements_completed`. After script `Set_Required_elements_completed_flag.php` is run, projects will need to delete the `Data_entry_completion_status` column of instrument tables. This can be accomplished by running `Remove_Data_entry_completion_status_instr_column.php`, and then sourcing the patch generated by this script.
+- If `_setDataEntryCompletionStatus`, `_determineDataEntryCompletionStatus`, and/or `updateDataEntryCompletionStatus` are called in any overrides, make sure to replace all instances with their newly named counterparts, `_setRequiredElementsCompletedFlag`, `_determineRequiredElementsCompletedFlag`, `updateRequiredElementsCompletedFlag`
 - Deprecation of `begintable` and `endtable` elements in LINST instruments
 - Deletion of `dateTimeFields` variable in instrument class. all references to this variable should be removed from project instruments.
 - Deletion of `monthYearFields` variable in instrument class. all references to this variable should be removed from project instruments.

SQL/0000-00-00-schema.sql

@@ -275,6 +275,7 @@ CREATE TABLE `flag` (
   `Test_name` varchar(255) NOT NULL default '',
   `CommentID` varchar(255) NOT NULL default '',
   `Data_entry` enum('In Progress','Complete') default NULL,
+  `Required_elements_completed` enum('Y','N') NOT NULL default 'N',
   `Administration` enum('None','Partial','All') default NULL,
   `Validity` enum('Questionable','Invalid','Valid') default NULL,
   `Exclusion` enum('Fail','Pass') default NULL,

SQL/Cleanup_patches/2020-12-08-remove_dataEntryCompletionStatus_conflict_resolver.sql

@@ -0,0 +1,3 @@
+DELETE FROM conflicts_resolved WHERE FieldName='Data_entry_completion_status';
+
+DELETE FROM conflicts_unresolved WHERE FieldName='Data_entry_completion_status';

SQL/New_patches/2020-07-29_Required_elements_completed_flag_column.sql

@@ -0,0 +1,2 @@
+ALTER TABLE flag
+    ADD COLUMN `Required_elements_completed` enum('Y','N') NOT NULL default 'N';

modules/api/php/endpoints/candidate/visit/instrument/instrument.class.inc

@@ -181,7 +181,7 @@ class Instrument extends Endpoint implements \LORIS\Middleware\ETagCalculator
             $this->_instrument->clearInstrument();
             $this->_instrument->_saveValues($data[$instrumentname]);
             $this->_instrument->score();
-            $this->_instrument->updateDataEntryCompletionStatus();
+            $this->_instrument->updateRequiredElementsCompletedFlag();
         } catch (\Throwable $e) {
             error_log($e->getMessage());
             return new \LORIS\Http\Response\JSON\InternalServerError();
@@ -223,7 +223,7 @@ class Instrument extends Endpoint implements \LORIS\Middleware\ETagCalculator
             $instrumentname = $this->_instrument->testName;
             $this->_instrument->_saveValues($data[$instrumentname]);
             $this->_instrument->score();
-            $this->_instrument->updateDataEntryCompletionStatus();
+            $this->_instrument->updateRequiredElementsCompletedFlag();
         } catch (\Throwable $e) {
             error_log($e->getMessage());
             return new \LORIS\Http\Response\JSON\InternalServerError();

modules/imaging_qc/php/imaging_qc.class.inc

@@ -125,7 +125,7 @@ class Imaging_QC extends \NDB_Menu_Filter
             " (SELECT title FROM subproject WHERE SubprojectID=s.SubprojectID)
            as subproject,".
             " CASE
-              WHEN m.Data_entry_completion_status='Incomplete' THEN 'Incomplete'
+              WHEN f.Required_elements_completed='N' THEN 'Incomplete'
               ELSE 'Complete'
            END AS mri_parameter_form,
            CASE

php/libraries/NDB_BVL_Instrument.class.inc

@@ -145,7 +145,6 @@ abstract class NDB_BVL_Instrument extends NDB_Page
             'Testdate',
             'Window_Difference',
             'Candidate_Age',
-            'Data_entry_completion_status',
         ];
 
     /**
@@ -590,7 +589,7 @@ abstract class NDB_BVL_Instrument extends NDB_Page
         if ($this->form->validate()) {
             $this->form->process([&$this, '_saveValues'], true);
             $this->score();
-            $this->updateDataEntryCompletionStatus();
+            $this->updateRequiredElementsCompletedFlag();
         } else {
             $submittedData = $this->form->getSubmitValues();
 
@@ -622,14 +621,14 @@ abstract class NDB_BVL_Instrument extends NDB_Page
      *
      * @return void
      */
-    public function updateDataEntryCompletionStatus(): void
+    public function updateRequiredElementsCompletedFlag(): void
     {
-        // determine the data entry completion status, and store that in
+        // determine the required elements completed flag, and store that in
         // the database
-        $dataEntryCompletionStatus
-            = $this->_determineDataEntryCompletionStatus();
-        $this->_setDataEntryCompletionStatus(
-            $dataEntryCompletionStatus
+        $requiredElementsCompletedFlag
+            = $this->_determineRequiredElementsCompletedFlag();
+        $this->_setRequiredElementsCompletedFlag(
+            $requiredElementsCompletedFlag
         );
     }
 
@@ -1500,15 +1499,15 @@ abstract class NDB_BVL_Instrument extends NDB_Page
     }
 
     /**
-     * Determines what the data entry status flag should be set to
+     * Determines what the required elements completed flag should be set to
      *
-     * @return string  Either 'Complete' or 'Incomplete'
+     * @return string  Either 'Y' or 'N'
      */
-    function _determineDataEntryCompletionStatus(): string
+    function _determineRequiredElementsCompletedFlag(): string
     {
         // don't bother checking anything if the required elements array is empty
         if (empty($this->_requiredElements)) {
-            return 'Complete';
+            return 'Y';
         }
 
         $allData = $this->getInstanceData();
@@ -1520,45 +1519,58 @@ abstract class NDB_BVL_Instrument extends NDB_Page
             if ((is_null($allData[$field] ?? null) || $allData[$field] === "")
                 && empty($allData[$statusField])
             ) {
-                return 'Incomplete';
+                return 'N';
             }
         }
 
-        return 'Complete';
+        return 'Y';
     }
 
 
     /**
      * Gets the data entry completion status for this instrument
      *
-     * @return string Either 'Complete' or 'Incomplete'
+     * @return string Either 'Y' or 'N'
      */
-    function getDataEntryCompletionStatus(): string
+    function getRequiredElementsCompletedFlag(): string
     {
-        $data = $this->getInstanceData();
-        return $data["Data_entry_completion_status"];
+        $db     = Database::singleton();
+        $status = $db->pselectOne(
+            "SELECT Required_elements_completed FROM flag WHERE CommentID=:CID",
+            ['CID' => $this->getCommentID()]
+        );
+        if ($status !== 'Y' && $status !== 'N') {
+            throw new LorisException(
+                "Invalid Data entry completion status encountered"
+            );
+        }
+        return $status;
     }
 
 
     /**
      * Sets the data entry completion status
      *
-     * @param string $status The status - either 'Complete'
-     *                       or 'Incomplete'
+     * @param string $status The status - either 'Y'
+     *                       or 'N'
      *
      * @return void
      */
-    function _setDataEntryCompletionStatus(string $status): void
+    function _setRequiredElementsCompletedFlag(string $status): void
     {
-        if (!in_array($status, ['Complete', 'Incomplete'])) {
+        if (!in_array($status, ['Y', 'N'], true)) {
             throw new InvalidArgumentException(
-                "Invalid status passed to _setDataEntryCompletionStatus - "
+                "Invalid status passed to _setRequiredElementsCompleted - "
                 . "'$status' should have been either "
-                . "'Complete' or 'Incomplete'<br>\n"
+                . "'Y' or 'N'<br>\n"
             );
         }
-
-        $this->_save(["Data_entry_completion_status" => $status]);
+        $DB = Database::singleton();
+        $DB->update(
+            "flag",
+            ["Required_elements_completed" => $status],
+            ['CommentID' => $this->getCommentID()]
+        );
     }
 
     /**
@@ -2331,9 +2343,6 @@ abstract class NDB_BVL_Instrument extends NDB_Page
                 case 'CommentID':
                 case 'UserID':
                     continue 2;
-                case 'Data_entry_completion_status':
-                    $values[$row['COLUMN_NAME']] = 'Incomplete';
-                    break;
                 default:
                     $values[$row['COLUMN_NAME']] = null;
                 }
@@ -2343,6 +2352,8 @@ abstract class NDB_BVL_Instrument extends NDB_Page
 
         // Clear data out of the flag table's Data column
         $db->update('flag', ['Data'=>null], ['CommentID' => $this->commentID]);
+        $this->_setRequiredElementsCompletedFlag('N');
+
         $prepQ = $db->prepare(
             "DELETE FROM conflicts_unresolved
              WHERE (CommentId1=:CID OR CommentId2=:CID)"

php/libraries/NDB_BVL_InstrumentStatus_ControlPanel.class.inc

@@ -254,9 +254,10 @@ class NDB_BVL_InstrumentStatus_ControlPanel extends NDB_BVL_InstrumentStatus
                     if (isset($this->instrument)) {
                         if ($showLink == true) {
                             $CompStatus
-                                = $this->instrument->getDataEntryCompletionStatus();
+                                = $this->instrument
+                                ->getRequiredElementsCompletedFlag();
 
-                            $showLink = $CompStatus == 'Complete';
+                            $showLink = $CompStatus === 'Y';
 
                             if (!$showLink) {
                                 $this->tpl_data['data_entry'][$i]['tooltip']