[JN-1486] Referral source + skip pre-enroll + pre-fill pre-enroll [wip]

api-participant/src/main/java/bio/terra/pearl/api/participant/controller/enrollment/EnrollmentController.java

@@ -37,7 +37,11 @@ public EnrollmentController(
 
   @Override
   public ResponseEntity<Object> createEnrollee(
-      String portalShortcode, String envName, String studyShortcode, UUID preEnrollResponseId) {
+      String portalShortcode,
+      String envName,
+      String studyShortcode,
+      UUID preEnrollResponseId,
+      String referralSource) {
     ParticipantUser user = requestUtilService.requireUser(request);
     EnvironmentName environmentName = EnvironmentName.valueOfCaseInsensitive(envName);
     PortalWithPortalUser portalWithPortalUser =
@@ -48,7 +52,8 @@ public ResponseEntity<Object> createEnrollee(
             studyShortcode,
             user,
             portalWithPortalUser.ppUser(),
-            preEnrollResponseId);
+            preEnrollResponseId,
+            referralSource);
 
     return ResponseEntity.ok(hubResponse);
   }
@@ -59,7 +64,8 @@ public ResponseEntity<Object> createGovernedUser(
       String envName,
       String studyShortcode,
       UUID preEnrollResponseId,
-      UUID governedPpUserId) {
+      UUID governedPpUserId,
+      String referralSource) {
     ParticipantUser user = requestUtilService.requireUser(request);
 
     HubResponse response =
@@ -69,7 +75,8 @@ public ResponseEntity<Object> createGovernedUser(
             EnvironmentName.valueOfCaseInsensitive(envName),
             studyShortcode,
             preEnrollResponseId,
-            governedPpUserId);
+            governedPpUserId,
+            referralSource);
 
     return ResponseEntity.ok(response);
   }

api-participant/src/main/java/bio/terra/pearl/api/participant/service/EnrollmentExtService.java

@@ -63,16 +63,17 @@ public HubResponse enrollGovernedUser(
       EnvironmentName envName,
       String studyShortcode,
       UUID preEnrollmentId,
-      UUID governedPpUserId // could be null if a totally new user
-      ) {
+      UUID governedPpUserId, // could be null if a totally new user
+      String referralSource) {
 
     PortalParticipantUser portalParticipantUser =
         authUtilService
             .authParticipantToPortal(operator.getId(), portalShortcode, envName)
             .ppUser();
 
     Enrollee proxy =
-        fetchOrCreateProxyEnrollee(operator, portalParticipantUser, studyShortcode, envName);
+        fetchOrCreateProxyEnrollee(
+            operator, portalParticipantUser, studyShortcode, envName, referralSource);
 
     if (governedPpUserId == null) {
       String governedUserName =
@@ -86,7 +87,8 @@ public HubResponse enrollGovernedUser(
           operator,
           portalParticipantUser,
           preEnrollmentId,
-          governedUserName);
+          governedUserName,
+          referralSource);
     } else {
       PortalParticipantUser governedPpUser =
           authUtilService.authParticipantUserToPortalParticipantUser(
@@ -105,21 +107,24 @@ public HubResponse enrollGovernedUser(
           portalParticipantUser,
           governedUser,
           governedPpUser,
-          preEnrollmentId);
+          preEnrollmentId,
+          referralSource);
     }
   }
 
   private Enrollee fetchOrCreateProxyEnrollee(
       ParticipantUser user,
       PortalParticipantUser ppUser,
       String studyShortcode,
-      EnvironmentName envName) {
+      EnvironmentName envName,
+      String referralSource) {
     return enrolleeService
         .findByParticipantUserIdAndStudyEnv(ppUser.getParticipantUserId(), studyShortcode, envName)
         .orElseGet(
             () ->
                 enrollmentService
-                    .enroll(ppUser, envName, studyShortcode, user, ppUser, null, false)
+                    .enroll(
+                        ppUser, envName, studyShortcode, user, ppUser, null, false, referralSource)
                     .getResponse());
   }
 }

api-participant/src/main/resources/api/openapi.yml

@@ -296,6 +296,7 @@ paths:
         - { name: envName, in: path, required: true, schema: { type: string } }
         - { name: studyShortcode, in: path, required: true, schema: { type: string } }
         - { name: preEnrollResponseId, in: query, required: false, schema: { type: string, format: uuid } }
+        - { name: referralSource, in: query, required: false, schema: { type: string } }
       responses:
         '200':
           description: hub response with enrollee
@@ -315,6 +316,7 @@ paths:
         - { name: studyShortcode, in: path, required: true, schema: { type: string } }
         - { name: preEnrollResponseId, in: query, required: false, schema: { type: string, format: uuid } }
         - { name: governedPpUserId, in: query, required: false, schema: { type: string, format: uuid } }
+        - { name: referralSource, in: query, required: false, schema: { type: string } }
       responses:
         '200':
           description: hub response with enrollee

api-participant/src/test/java/bio/terra/pearl/api/participant/service/EnrollmentExtServiceTest.java

@@ -69,6 +69,7 @@ void testEnrollGovernedUser_NewProxy(TestInfo info) {
             portalEnv.getEnvironmentName(),
             studyService.find(studyEnvironment.getStudyId()).get().getShortcode(),
             null,
+            null,
             null);
 
     List<EnrolleeRelation> relationsAfter =
@@ -111,7 +112,8 @@ void testEnrollGovernedUser_ExistingProxyNewStudy(TestInfo info) {
             portalEnv.getEnvironmentName(),
             studyService.find(studyEnvironment2.getStudyId()).get().getShortcode(),
             null,
-            governedPpUser.getId());
+            governedPpUser.getId(),
+            null);
 
     Enrollee createdProxy =
         enrolleeService

core/src/main/java/bio/terra/pearl/core/model/participant/Enrollee.java

@@ -37,6 +37,7 @@ public class Enrollee extends BaseEntity implements StudyEnvAttached {
     private boolean consented;
     @Builder.Default
     private EnrolleeSourceType source = EnrolleeSourceType.PORTAL_SITE;
+    private String referralSource;
 
     @Builder.Default
     private List<FamilyEnrollee> familyEnrollees = new ArrayList<>();

core/src/main/java/bio/terra/pearl/core/service/export/EnrolleeImportService.java

@@ -424,7 +424,7 @@ private RegistrationService.RegistrationResult registerIfNeeded(String portalSho
 
             HubResponse<Enrollee> response = enrollmentService.enroll(regResult.portalParticipantUser(), studyEnv.getEnvironmentName(),
                     studyShortcode, regResult.participantUser(), regResult.portalParticipantUser(),
-                    null, enrolleeInfo.isSubject(), EnrolleeSourceType.IMPORT);
+                    null, enrolleeInfo.isSubject(), EnrolleeSourceType.IMPORT, null);
             Enrollee newEnrollee = response.getEnrollee();
             //update createdAt
             if (enrolleeInfo.getCreatedAt() != null) {
@@ -444,7 +444,7 @@ private RegistrationService.RegistrationResult registerIfNeeded(String portalSho
 
         Optional<Enrollee> enrollee = enrolleeService.findByParticipantUserIdAndStudyEnvId(registration.participantUser().getId(), studyEnv.getId());
 
-        return enrollee.orElseGet(() -> this.enrollmentService.enroll(registration.portalParticipantUser(), studyEnv.getEnvironmentName(), studyShortcode, registration.participantUser(), registration.portalParticipantUser(), null, false).getEnrollee());
+        return enrollee.orElseGet(() -> this.enrollmentService.enroll(registration.portalParticipantUser(), studyEnv.getEnvironmentName(), studyShortcode, registration.participantUser(), registration.portalParticipantUser(), null, false, null).getEnrollee());
     }
 
     protected Profile importProfile(Map<String, String> enrolleeMap, Profile registrationProfile,

core/src/main/java/bio/terra/pearl/core/service/participant/WithdrawnEnrolleeService.java

@@ -130,7 +130,8 @@ private void recreateEnrolleeAsProxy(ParticipantUser user, Enrollee withdrawnEnr
                 user,
                 ppUser,
                 null,
-                false
+                false,
+                null
         ).getResponse();
 
         for (EnrolleeRelation relation : relations) {

core/src/main/java/bio/terra/pearl/core/service/workflow/EnrollmentService.java

@@ -121,8 +121,9 @@ public HubResponse<Enrollee> enroll(PortalParticipantUser operator,
                                         ParticipantUser user,
                                         PortalParticipantUser ppUser,
                                         UUID preEnrollResponseId,
-                                        boolean isSubject) {
-        return enroll(operator, envName, studyShortcode, user, ppUser, preEnrollResponseId, isSubject, EnrolleeSourceType.PORTAL_SITE);
+                                        boolean isSubject,
+                                        String referralSource) {
+        return enroll(operator, envName, studyShortcode, user, ppUser, preEnrollResponseId, isSubject, EnrolleeSourceType.PORTAL_SITE, referralSource);
     }
 
     @Transactional
@@ -133,7 +134,8 @@ public HubResponse<Enrollee> enroll(PortalParticipantUser operator,
                                         PortalParticipantUser ppUser,
                                         UUID preEnrollResponseId,
                                         boolean isSubject,
-                                        EnrolleeSourceType source) {
+                                        EnrolleeSourceType source,
+                                        String referralSource) {
         log.info("creating enrollee for user {}, study {}", user.getId(), studyShortcode);
         StudyEnvironment studyEnv = studyEnvironmentService.findByStudy(studyShortcode, envName)
                 .orElseThrow(() -> new NotFoundException("Study environment %s %s not found".formatted(studyShortcode, envName)));
@@ -146,7 +148,7 @@ public HubResponse<Enrollee> enroll(PortalParticipantUser operator,
 
         // if the user is signed up, but not a subject, we can just return the existing enrollee,
         // otherwise create a new one for them
-        Enrollee enrollee = findOrCreateEnrolleeForEnrollment(user, ppUser, studyEnv, studyShortcode, preEnrollResponseId, isSubject, source);
+        Enrollee enrollee = findOrCreateEnrolleeForEnrollment(user, ppUser, studyEnv, studyShortcode, preEnrollResponseId, isSubject, source, referralSource);
 
         if (preEnrollResponse != null) {
             preEnrollResponse.setCreatingParticipantUserId(user.getId());
@@ -166,7 +168,7 @@ public HubResponse<Enrollee> enroll(PortalParticipantUser operator,
 
     private Enrollee findOrCreateEnrolleeForEnrollment(ParticipantUser user, PortalParticipantUser ppUser, StudyEnvironment studyEnv,
                                                        String studyShortcode, UUID preEnrollResponseId, boolean isSubjectEnrollment,
-                                                       EnrolleeSourceType source) {
+                                                       EnrolleeSourceType source, String referralSource) {
         return enrolleeService
                 .findByParticipantUserIdAndStudyEnv(user.getId(), studyShortcode, studyEnv.getEnvironmentName())
                 .filter(e -> {
@@ -190,6 +192,7 @@ private Enrollee findOrCreateEnrolleeForEnrollment(ParticipantUser user, PortalP
                             .preEnrollmentResponseId(preEnrollResponseId)
                             .subject(isSubjectEnrollment)
                             .source(source)
+                            .referralSource(referralSource)
                             .build();
                     return enrolleeService.create(newEnrollee);
                 });
@@ -290,18 +293,18 @@ protected boolean isProxyEnrollment(EnvironmentName envName, String studyShortco
      */
     @Transactional
     public HubResponse<Enrollee> enrollAsProxy(EnvironmentName envName, String studyShortcode, ParticipantUser proxyUser,
-                                               PortalParticipantUser ppUser, UUID preEnrollResponseId) {
+                                               PortalParticipantUser ppUser, UUID preEnrollResponseId, String referralSource) {
         String governedUserName = registrationService.getGovernedUsername(proxyUser.getUsername(), proxyUser.getEnvironmentName());
-        return this.enrollAsProxy(envName, studyShortcode, proxyUser, ppUser, preEnrollResponseId, governedUserName);
+        return this.enrollAsProxy(envName, studyShortcode, proxyUser, ppUser, preEnrollResponseId, governedUserName, referralSource);
     }
 
     @Transactional
     public HubResponse<Enrollee> enrollAsProxy(EnvironmentName envName, String studyShortcode, ParticipantUser proxyUser,
-                                               PortalParticipantUser ppUser, UUID preEnrollResponseId, String governedUsername) {
+                                               PortalParticipantUser ppUser, UUID preEnrollResponseId, String governedUsername, String referralSource) {
         Enrollee proxyEnrollee = enrolleeService.findByParticipantUserIdAndStudyEnv(proxyUser.getId(), studyShortcode, envName)
-                .orElseGet(() -> this.enroll(ppUser, envName, studyShortcode, proxyUser, ppUser, null, false).getEnrollee());
+                .orElseGet(() -> this.enroll(ppUser, envName, studyShortcode, proxyUser, ppUser, null, false, referralSource).getEnrollee());
         HubResponse<Enrollee> governedResponse =
-                this.registerAndEnrollGovernedUser(envName, studyShortcode, proxyEnrollee, proxyUser, ppUser, preEnrollResponseId, governedUsername);
+                this.registerAndEnrollGovernedUser(envName, studyShortcode, proxyEnrollee, proxyUser, ppUser, preEnrollResponseId, governedUsername, referralSource);
         governedResponse.setEnrollee(proxyEnrollee);
 
         return governedResponse;
@@ -314,7 +317,8 @@ public HubResponse<Enrollee> registerAndEnrollGovernedUser(EnvironmentName envNa
                                                                ParticipantUser proxyUser,
                                                                PortalParticipantUser proxyPpUser,
                                                                UUID preEnrollResponseId,
-                                                               String governedUserName) {
+                                                               String governedUserName,
+                                                               String referralSource) {
         ParticipantUser governedUserParticipantUserOpt = participantUserService.findOne(governedUserName, envName).orElse(null);
         // Before this, at time of registration we have registered the proxy as a participant user, but now we need to both register and enroll the child they are enrolling
         RegistrationService.RegistrationResult registrationResult =
@@ -328,7 +332,8 @@ public HubResponse<Enrollee> registerAndEnrollGovernedUser(EnvironmentName envNa
                 proxyPpUser,
                 registrationResult.participantUser(),
                 registrationResult.portalParticipantUser(),
-                preEnrollResponseId);
+                preEnrollResponseId,
+                referralSource);
     }
 
     public HubResponse enrollGovernedUser(EnvironmentName envName,
@@ -338,15 +343,17 @@ public HubResponse enrollGovernedUser(EnvironmentName envName,
                                           PortalParticipantUser proxyPpUser,
                                           ParticipantUser governedUser,
                                           PortalParticipantUser governedPpUser,
-                                          UUID preEnrollResponseId) {
+                                          UUID preEnrollResponseId,
+                                          String referralSource) {
         HubResponse<Enrollee> hubResponse =
                 this.enroll(proxyPpUser,
                         envName,
                         studyShortcode,
                         governedUser,
                         governedPpUser,
                         preEnrollResponseId,
-                        true);
+                        true,
+                        referralSource);
 
         EnrolleeRelation relation = EnrolleeRelation.builder()
                 .enrolleeId(governingEnrollee.getId())
@@ -396,10 +403,10 @@ private PreEnrollmentResponse validatePreEnrollResponse(PortalParticipantUser op
      * as a proxy. If they are, it will call the enrollAsProxy method, otherwise it will call the enroll method.
      */
     public HubResponse enroll(EnvironmentName environmentName, String studyShortcode, ParticipantUser user,
-                              PortalParticipantUser portalParticipantUser, UUID preEnrollResponseId) {
+                              PortalParticipantUser portalParticipantUser, UUID preEnrollResponseId, String referralSource) {
         if (preEnrollResponseId != null && isProxyEnrollment(environmentName, studyShortcode, preEnrollResponseId)) {
-            return enrollAsProxy(environmentName, studyShortcode, user, portalParticipantUser, preEnrollResponseId);
+            return enrollAsProxy(environmentName, studyShortcode, user, portalParticipantUser, preEnrollResponseId, referralSource);
         }
-        return enroll(portalParticipantUser, environmentName, studyShortcode, user, portalParticipantUser, preEnrollResponseId, true);
+        return enroll(portalParticipantUser, environmentName, studyShortcode, user, portalParticipantUser, preEnrollResponseId, true, referralSource);
     }
 }

core/src/main/resources/db/changelog/changesets/2024_11_22_enrollee_referral_source.yaml

@@ -0,0 +1,9 @@
+databaseChangeLog:
+  - changeSet:
+      id: "enrollee_referral_source"
+      author: mbemis
+      changes:
+        - addColumn:
+            tableName: enrollee
+            columns:
+              - column: { name: referral_source, type: text }

core/src/main/resources/db/changelog/db.changelog-master.yaml

@@ -359,6 +359,9 @@ databaseChangeLog:
   - include:
       file: changesets/2024_11_14_system_settings.yaml
       relativeToChangelogFile: true
+  - include:
+      file: changesets/2024_11_22_enrollee_referral_source.yaml
+      relativeToChangelogFile: true
 
 
 # README: it is a best practice to put each DDL statement in its own change set. DDL statements