Add REDCap automatic session creation

modules/redcap/CONFIGURATION.md

@@ -20,6 +20,11 @@ The configuration is of the following form:
         <visit-label>visit_1</visit-label>
         <redcap-arm-name>arm_1</redcap-arm-name>
         <redcap-event-name>event_1</redcap-event-name>
+        <create-session>
+          <site-name>My Site</site-name>
+          <project-name>My Project</project-name>
+          <cohort-name>My Cohort</cohort-name>
+        </create-session>
       </visit>
     </project>
   </instance>
@@ -28,6 +33,8 @@ The configuration is of the following form:
 
 ## Detailed description
 
+### General configuration
+
 The configuration nodes are the following:
 - `redcap` (required): Root node of the LORIS REDCap configuration.
 - `instance` (required, multiple allowed): The list of instance entries to synchronize with LORIS.
@@ -36,15 +43,27 @@ In an `instance` entry, the configuration parameters are the following:
 - `redcap-url` (required): The URL of the REDCap instance. This is also the URL of the REDCap instance API without the `api` suffix.
 - `project` (required, multiple allowed): The list of project entries in this REDCap instance to synchronize with LORIS.
 
+### Project configuration
+
 In a `project` entry, the configuration parameters are the following:
 - `redcap-project-id` (required): The REDCap project ID of the REDCap project described by this entry.
 - `redcap-api-token` (required): The REDCap API token used by LORIS to retrieve REDCap data for this project.
 - `prefix-instrument-variable` (optional): Whether or not the instrument field variable names are prefixed by their instrument name in REDCap. The two options are `true` or `false`. If not present, `false` is used.
 - `redcap-participant-id` (optional): The type of REDCap participant identifier used to map the REDCap participants with the LORIS candidates. The two options are `record_id` and `survey_participant_id`. If not present, `record_id` is used.
 - `candidate-id` (optional): The type of LORIS candidate identifier used to map the REDCap participants with the LORIS candidates. The two options are `candid` and `pscid`. If not present, `pscid` is used.
-- `visit` (optional, multiple allowed): The list of visit entries that describe how REDCap arms and events are mapped to LORIS visits. If not present, the REDCap arms are ignored and the REDCap event names are matched to LORIS visit labels with the same name.
+- `visit` (optional, multiple allowed): A list of visit mappings that describe how REDCap arms and events are mapped to LORIS visits. If not present, the REDCap arms are ignored and the REDCap event names are matched to LORIS visit labels with the same name.
+
+### Visit mapping configuration
 
 In a `visit` entry, the configuration parameters are the following:
 - `visit-label` (required): The LORIS visit label of the visit to which to attach the instrument responses that match this entry.
 - `redcap-arm-name` (optional): The REDCap arm name that the instrument responses must match to be attached to this visit. If not present, the arm name is ignored when filtering instrument responses.
 - `redcap-event-name` (optional): The REDCap event name that the instrument responses must match to be attached to this visit. If not present, the event name is ignored when filtering instrument responses.
+- `create-session` (optional): The information needed to create the LORIS session for the candidate and visit associated with a REDCap event if it does not already exist.
+
+###  Session creation configuration
+
+In a `create-session` entry, the configuration parameters are the following:
+- `site-name`: The name of the LORIS site for which to create the session if it does not already exist.
+- `project-name`: The name of the LORIS project for which to create the session visit if it does not already exist.
+- `cohort-name`: The name of the LORIS cohort for which to create the session visit if it does not already exist.

modules/redcap/php/client/models/mappings/iredcapinstrumentevent.class.inc

@@ -24,11 +24,11 @@ namespace LORIS\redcap\client\models\mappings;
 interface IRedcapInstrumentEvent
 {
     /**
-     * Get the REDCap event name.
+     * Get the REDCap unique event name.
      *
      * @return string
      */
-    public function getEventName(): string;
+    public function getUniqueEventName(): string;
 
     /**
      * Get the REDCap form name.

modules/redcap/php/client/models/mappings/redcapinstrumenteventmap.class.inc

@@ -61,11 +61,11 @@ class RedcapInstrumentEventMap implements IRedcapInstrumentEvent
     }
 
     /**
-     * Get the REDCap event name.
+     * Get the REDCap unique event name.
      *
      * @return string
      */
-    public function getEventName(): string
+    public function getUniqueEventName(): string
     {
         return $this->unique_event_name;
     }

modules/redcap/php/client/models/mappings/redcaprepeatinginstrumentevent.class.inc

@@ -26,12 +26,11 @@ use LORIS\redcap\client\RedcapProps;
 class RedcapRepeatingInstrumentEvent implements IRedcapInstrumentEvent
 {
     /**
-     * Redcap Event name.
-     * This is linked to a UNIQUE event name.
+     * A REDCap unique event name.
      *
      * @var string
      */
-    public readonly string $event_name;
+    public readonly string $unique_event_name;
 
     /**
      * Redcap Form name.
@@ -57,19 +56,19 @@ class RedcapRepeatingInstrumentEvent implements IRedcapInstrumentEvent
     {
         $props = new RedcapProps('repeating_instrument', $props);
 
-        $this->event_name   = $props->getString('event_name');
-        $this->form_name    = $props->getString('form_name');
-        $this->custom_label = $props->getStringNullable('custom_form_label');
+        $this->unique_event_name = $props->getString('event_name');
+        $this->form_name         = $props->getString('form_name');
+        $this->custom_label      = $props->getStringNullable('custom_form_label');
     }
 
     /**
-     * Get the REDCap event name.
+     * Get the REDCap unique event name.
      *
      * @return string
      */
-    public function getEventName(): string
+    public function getUniqueEventName(): string
     {
-        return $this->event_name;
+        return $this->unique_event_name;
     }
 
     /**
@@ -91,7 +90,7 @@ class RedcapRepeatingInstrumentEvent implements IRedcapInstrumentEvent
     {
         return [
             'form_name'         => $this->form_name,
-            'event_name'        => $this->event_name,
+            'event_name'        => $this->unique_event_name,
             'custom_form_label' => $this->custom_label
         ];
     }

modules/redcap/php/client/models/records/redcaprecord.class.inc

@@ -12,6 +12,8 @@
 
 namespace LORIS\redcap\client\models\records;
 
+use LORIS\redcap\client\RedcapProps;
+
 /**
  * This represents a redcap record.
  *
@@ -23,6 +25,20 @@ namespace LORIS\redcap\client\models\records;
  */
 class RedcapRecord implements IRedcapRecord
 {
+    /**
+     * The date at which the record was completed if it was completed using a
+     * survey.
+     */
+    public readonly ?\DateTimeImmutable $datetime;
+
+    /**
+     * The record completion status.
+     * 0 = incomplete / partial survey response
+     * 1 = unverified
+     * 2 = complete
+     */
+    public readonly int $complete;
+
     private string $_form_name;
 
     private array $_props;
@@ -37,6 +53,18 @@ class RedcapRecord implements IRedcapRecord
     {
         $this->_form_name = $form_name;
         $this->_props     = $props;
+
+        $props = new RedcapProps('record', $props);
+
+        $datetime_string = $props->getStringNullable("{$form_name}_timestamp");
+        if ($datetime_string !== null) {
+            $datetime = new \DateTimeImmutable($datetime_string);
+        } else {
+            $datetime = null;
+        }
+
+        $this->datetime = $datetime;
+        $this->complete = $props->getInt("{$form_name}_complete");
     }
 
     /**

modules/redcap/php/client/models/redcapnotification.class.inc

@@ -29,7 +29,7 @@ class RedcapNotification
     public readonly string $project_id;
     public readonly string $instrument_name;
     public readonly string $record_id;
-    public readonly string $event_name;
+    public readonly string $unique_event_name;
     public readonly string $username;
     public readonly string $complete;
 
@@ -75,7 +75,7 @@ class RedcapNotification
         $this->project_id        = $props['project_id'];
         $this->project_url       = $props['project_url'];
         $this->record_id         = $props['record'];
-        $this->event_name        = $props['redcap_event_name'];
+        $this->unique_event_name = $props['redcap_event_name'];
         $this->instance_url      = $props['redcap_url'];
         $this->complete          = $props[$complete_key] ?? '';
         $this->username          = $props['username'];
@@ -104,7 +104,7 @@ class RedcapNotification
             'project_url'       => $this->project_url,
             'received_dt'       => $this->received_datetime->format('Y-m-d H:i:s'),
             'record'            => $this->record_id,
-            'redcap_event_name' => $this->event_name,
+            'redcap_event_name' => $this->unique_event_name,
             'redcap_url'        => $this->instance_url,
             'complete'          => $this->complete,
             'username'          => $this->username,