Implement Join Household mutation

app/models/grda_warehouse/utility.rb

@@ -200,6 +200,7 @@ def self.modifier(model)
       GrdaWarehouse::Hud::Client,
       GrdaWarehouse::Hud::Project,
       GrdaWarehouse::Hud::User,
+      GrdaWarehouse::Hud::Enrollment,
       GrdaWarehouse::ServiceHistoryEnrollment,
       ActiveStorage::Attachment,
       ActiveStorage::Blob,

db/warehouse/migrate/20250121204933_add_hmis_household_events_table.rb

@@ -0,0 +1,29 @@
+#  Copyright 2016 - 2024 Green River Data Analysis, LLC
+#
+#  License detail: https://github.com/greenriver/hmis-warehouse/blob/production/LICENSE.md
+#
+
+class AddHmisHouseholdEventsTable < ActiveRecord::Migration[7.0]
+  def change
+    create_table :hmis_household_events do |t|
+      t.string :household_id, index: true # hmis_households is a view, not a table
+      t.references :data_source, null: false
+      t.string :event_type, null: false
+      t.jsonb :event_details
+      t.references :user, null: false
+      t.timestamps
+    end
+
+    # Create a join table since Postgres can't put fk constraints on array elements
+    create_table :hmis_household_event_enrollments, id: false do |t|
+      t.references :hmis_household_event, null: false, foreign_key: { to_table: :hmis_household_events }, index: { name: 'idx_hmis_household_event_enrollments_on_event_id' }
+      t.references :enrollment, null: false, foreign_key: { to_table: :Enrollment }, index: true # this is the ID of the enrollment record: Enrollment.id not Enrollment.EnrollmentID
+    end
+
+    # Add a composite unique index to prevent duplicate associations
+    add_index :hmis_household_event_enrollments,
+              [:hmis_household_event_id, :enrollment_id],
+              unique: true,
+              name: 'idx_hmis_household_event_enrollments_on_event_and_enrollment'
+  end
+end

drivers/hmis/app/graphql/mutations/join_household.rb

@@ -0,0 +1,103 @@
+###
+# Copyright 2016 - 2025 Green River Data Analysis, LLC
+#
+# License detail: https://github.com/greenriver/hmis-warehouse/blob/production/LICENSE.md
+###
+
+module Mutations
+  class JoinHousehold < BaseMutation
+    argument :receiving_household_id, ID, required: true
+    argument :joining_enrollment_inputs, [Types::HmisSchema::EnrollmentRelationshipInput], required: true
+
+    field :receiving_household, Types::HmisSchema::Household, null: false
+    field :donor_household, Types::HmisSchema::Household, null: true # Will be null if there are no remaining members
+    # todo @martha - possible that there will be multiple households with same ID? mutation should require project_id?
+    def resolve(receiving_household_id:, joining_enrollment_inputs:)
+      receiving_enrollments = Hmis::Hud::Enrollment.
+        where(household_id: receiving_household_id).
+        viewable_by(current_user).
+        includes(:project, :household)
+      access_denied! if receiving_enrollments.empty?
+
+      receiving_household = receiving_enrollments.first.household
+
+      receiving_project = receiving_enrollments.map(&:project).uniq.sole
+      access_denied! unless current_permission?(permission: :can_split_households, entity: receiving_project)
+
+      # The mutation input is a list, so convert it to a hashmap for ease of access
+      map_enrollment_id_to_relationship = joining_enrollment_inputs.map { |e| [e.enrollment_id, e.relationship_to_hoh] }.to_h
+
+      joining_enrollment_ids = map_enrollment_id_to_relationship.keys
+      joining_enrollments = Hmis::Hud::Enrollment.
+        viewable_by(current_user).
+        where(id: joining_enrollment_ids).
+        includes(:household)
+      access_denied! unless joining_enrollments.count == joining_enrollment_inputs.count
+
+      raise 'Cannot merge enrollments from another project' unless joining_enrollments.pluck(:project_pk).uniq.sole == receiving_project.id
+
+      donor_household = joining_enrollments.map(&:household).uniq.sole
+      remaining_enrollments = Hmis::Hud::Enrollment.
+        viewable_by(current_user). # Restrict to this data source
+        where(household_id: donor_household.household_id).
+        where.not(id: joining_enrollment_ids)
+      remaining_hoh = remaining_enrollments.any? { |enrollment| enrollment.relationship_to_hoh == 1 }
+      raise 'This operation would leave behind a household with no HoH, which is not allowed' unless remaining_enrollments.empty? || remaining_hoh
+
+      # If the receiving household is assigned to a unit, re-assign the joining enrollments to the same unit.
+      # This works for the present-tense, but could be improved to better accommodate past data correction.
+      units = receiving_enrollments.map { |enrollment| enrollment.active_unit_occupancy&.unit }.compact.uniq
+
+      receiving_before_state = Hmis::Hud::Enrollment.snapshot_enrollments(receiving_enrollments)
+      donor_before_state = Hmis::Hud::Enrollment.snapshot_enrollments([*joining_enrollments, *remaining_enrollments])
+
+      Hmis::Hud::Enrollment.transaction do
+        joining_enrollments.each_with_index do |enrollment, index|
+          enrollment.update!(
+            household_id: receiving_household_id,
+            relationship_to_hoh: map_enrollment_id_to_relationship[enrollment.id.to_s],
+          )
+
+          # Whether or not the receiving household has a unit assignment, clear the joining enrollment's current unit assignment
+          enrollment.active_unit_occupancy&.assign_attributes(occupancy_period_attributes: { end_date: Date.current })
+
+          unless units.empty?
+            unit = units[index % units.length] # If the receiving household has multiple units, pick any, deterministically
+            enrollment.assign_unit(unit: unit, start_date: Date.current, user: current_user)
+          end
+
+          enrollment.save!
+        end
+
+        receiving_household.reload
+        donor_household.reload if remaining_enrollments.any?
+
+        joining_event = Hmis::HouseholdEvent.new
+        joining_event.user = current_user
+        joining_event.household = receiving_household
+        joining_event.event_type = Hmis::HouseholdEvent::JOIN
+        joining_event.event_details = {
+          'donorHouseholdId': donor_household.household_id,
+          'before': receiving_before_state,
+          'after': Hmis::Hud::Enrollment.snapshot_enrollments(receiving_household.enrollments),
+        }
+
+        leaving_event = Hmis::HouseholdEvent.new
+        leaving_event.user = current_user
+        leaving_event.household = donor_household
+        leaving_event.event_type = Hmis::HouseholdEvent::SPLIT
+        leaving_event.event_details = {
+          'receivingHouseholdId': receiving_household_id,
+          'before': donor_before_state,
+          'after': Hmis::Hud::Enrollment.snapshot_enrollments(remaining_enrollments),
+        }
+        Hmis::HouseholdEvent.import!([joining_event, leaving_event])
+      end
+
+      {
+        receiving_household: receiving_household,
+        donor_household: remaining_enrollments.any? ? donor_household : nil,
+      }
+    end
+  end
+end

drivers/hmis/app/graphql/schema.graphql

@@ -3511,6 +3511,11 @@ enum EnrollmentFilterOptionStatus {
   INCOMPLETE
 }
 
+input EnrollmentRelationshipInput {
+  enrollmentId: ID!
+  relationshipToHoh: RelationshipToHoH!
+}
+
 """
 HUD Enrollment Sorting Options
 """
@@ -5628,6 +5633,31 @@ Represents untyped JSON
 """
 scalar JSON
 
+"""
+Autogenerated input type of JoinHousehold
+"""
+input JoinHouseholdInput {
+  """
+  A unique identifier for the client performing the mutation.
+  """
+  clientMutationId: String
+  joiningEnrollmentInputs: [EnrollmentRelationshipInput!]!
+  receivingHouseholdId: ID!
+}
+
+"""
+Autogenerated return type of JoinHousehold.
+"""
+type JoinHouseholdPayload {
+  """
+  A unique identifier for the client performing the mutation.
+  """
+  clientMutationId: String
+  donorHousehold: Household
+  errors: [ValidationError!]!
+  receivingHousehold: Household!
+}
+
 """
 Arbitrary JSON Type
 """
@@ -6218,6 +6248,12 @@ type Mutation {
     """
     input: DeleteUnitsInput!
   ): DeleteUnitsPayload
+  joinHousehold(
+    """
+    Parameters for JoinHousehold
+    """
+    input: JoinHouseholdInput!
+  ): JoinHouseholdPayload
   mergeClients(
     """
     Parameters for MergeClients
@@ -8668,6 +8704,7 @@ type ProjectAccess {
   canManageIncomingReferrals: Boolean!
   canManageOutgoingReferrals: Boolean!
   canManageUnits: Boolean!
+  canSplitHouseholds: Boolean!
   canViewDob: Boolean!
   canViewEnrollmentDetails: Boolean!
   canViewFullSsn: Boolean!

drivers/hmis/app/graphql/types/hmis_schema/enrollment_relationship_input.rb

@@ -0,0 +1,12 @@
+###
+# Copyright 2016 - 2025 Green River Data Analysis, LLC
+#
+# License detail: https://github.com/greenriver/hmis-warehouse/blob/production/LICENSE.md
+###
+
+module Types
+  class HmisSchema::EnrollmentRelationshipInput < BaseInputObject
+    argument :enrollment_id, ID, required: true
+    argument :relationship_to_hoh, Types::HmisSchema::Enums::Hud::RelationshipToHoH, required: true
+  end
+end

drivers/hmis/app/graphql/types/hmis_schema/mutation_type.rb

@@ -57,6 +57,8 @@ class HmisSchema::MutationType < Types::BaseObject
     field :merge_clients, mutation: Mutations::MergeClients
     field :bulk_merge_clients, mutation: Mutations::BulkMergeClients
 
+    field :join_household, mutation: Mutations::JoinHousehold
+
     field :create_form_definition, mutation: Mutations::CreateFormDefinition
     field :update_form_definition, mutation: Mutations::UpdateFormDefinition
     field :delete_form_definition, mutation: Mutations::DeleteFormDefinition

drivers/hmis/app/graphql/types/hmis_schema/project.rb

@@ -105,6 +105,7 @@ def self.authorized?(object, ctx)
       can :manage_outgoing_referrals
       can :manage_denied_referrals
       can :manage_external_form_submissions
+      can :split_households
     end
     field :unit_types, [Types::HmisSchema::UnitTypeCapacity], null: false
     field :has_units, Boolean, null: false

drivers/hmis/app/models/hmis/household_event.rb

@@ -0,0 +1,19 @@
+#  Copyright 2016 - 2024 Green River Data Analysis, LLC
+#
+#  License detail: https://github.com/greenriver/hmis-warehouse/blob/production/LICENSE.md
+#
+class Hmis::HouseholdEvent < Hmis::HmisBase
+  JOIN = 'join'.freeze
+  SPLIT = 'split'.freeze
+  EVENT_TYPES = [JOIN, SPLIT].freeze # In the future we may add other events, like add and remove
+
+  belongs_to :user, class_name: 'Hmis::User'
+  belongs_to :household, class_name: 'Hmis::Hud::Household', primary_key: [:data_source_id, :HouseholdID], foreign_key: [:data_source_id, :household_id], inverse_of: :events
+  has_and_belongs_to_many :enrollments,
+                          class_name: 'Hmis::Hud::Enrollment',
+                          join_table: 'hmis_household_event_enrollments',
+                          association_foreign_key: 'enrollment_id',
+                          foreign_key: 'hmis_household_event_id'
+
+  validates :event_type, inclusion: { in: EVENT_TYPES, message: '%{value} is not a valid event type' }
+end

drivers/hmis/app/models/hmis/hud/enrollment.rb

@@ -284,6 +284,15 @@ def self.generate_enrollment_id
     generate_uuid
   end
 
+  def self.snapshot_enrollments(enrollments)
+    enrollments.map do |enrollment|
+      {
+        'enrollmentId': enrollment.id,
+        'relationshipToHoh': enrollment.relationship_to_hoh,
+      }
+    end
+  end
+
   # Data Collection Features that are enabled for this enrollment, thru its project (e.g. Current Living Situation)
   #
   # Is it enabled?

drivers/hmis/app/models/hmis/hud/household.rb

@@ -17,6 +17,7 @@ class Hmis::Hud::Household < Hmis::Hud::Base
   has_many :current_units, through: :enrollments
   has_many :custom_assessments, through: :enrollments
   has_many :staff_assignments, class_name: 'Hmis::StaffAssignment', primary_key: [:data_source_id, :HouseholdID], foreign_key: [:data_source_id, :household_id]
+  has_many :events, class_name: 'Hmis::HouseholdEvent', primary_key: [:data_source_id, :HouseholdID], foreign_key: [:data_source_id, :household_id]
   alias_attribute :household_id, :HouseholdID
 
   replace_scope :viewable_by, ->(user) do

drivers/hmis/app/models/hmis/hud/validators/enrollment_validator.rb

@@ -34,23 +34,24 @@ def self.already_enrolled_full_message
     'Client has another enrollment in this project that conflicts with this entry date.'
   end
 
-  def self.find_conflict_severity(enrollment)
+  def self.find_conflicting_enrollment(enrollment)
     conflict_scope = Hmis::Hud::Enrollment.
       where(personal_id: enrollment.personal_id, data_source_id: enrollment.data_source_id).
       with_conflicting_dates(project: enrollment.project, range: enrollment.entry_date...enrollment.exit_date)
 
     if enrollment.persisted?
       # If the entry date is being changed on an EXISTING enrollment, and it overlaps with another one, it should be a warning
       conflict_scope = conflict_scope.where.not(id: enrollment.id)
-      return :warning if conflict_scope.any?
+      return :warning, conflict_scope.first if conflict_scope.any?
     else
-      min_conflict_date = conflict_scope.minimum(:entry_date)
-      if min_conflict_date
-        # If the entry date is being set on a NEW enrollment, and the entry date is on or after the entry date of any conflicting enrollments, it should be an error.
-        return :error if enrollment.entry_date >= min_conflict_date
-
-        # if the entry date is being set on a NEW enrollment, and the entry date is before the entry date of any conflicting enrollments, it should be a warning
-        return :warning if enrollment.entry_date < min_conflict_date
+      # If the entry date is being set on a NEW enrollment,
+      conflicting_enrollment = conflict_scope.order(entry_date: :asc).first # pick the conflicting enrollment with the earliest entry date
+      if conflicting_enrollment
+        # If the entry date is on or after the entry date of any conflicting enrollments, it should be an error
+        return :error, conflicting_enrollment if enrollment.entry_date >= conflicting_enrollment.entry_date
+
+        # If the entry date is before the entry date of any conflicting enrollments, it should be a warning
+        return :warning, conflicting_enrollment if enrollment.entry_date < conflicting_enrollment.entry_date
       end
     end
   end
@@ -74,8 +75,18 @@ def self.validate_entry_date(enrollment, household_members: nil, options: {})
     errors.add :entry_date, :out_of_range, message: after_exit_message(exit_date), **options if exit_date.present? && exit_date < entry_date
     return errors.errors if errors.any?
 
-    conflict_severity = find_conflict_severity(enrollment)
-    errors.add(:entry_date, :out_of_range, severity: conflict_severity, full_message: already_enrolled_full_message) if conflict_severity
+    conflict_severity, conflicting_enrollment = find_conflicting_enrollment(enrollment)
+    if conflict_severity
+      errors.add(
+        :entry_date,
+        :out_of_range,
+        severity: conflict_severity,
+        full_message: already_enrolled_full_message,
+        data: {
+          conflictingEnrollmentId: conflicting_enrollment.id.to_s,
+        },
+      )
+    end
 
     unless enrollment.head_of_household?
       household_members ||= enrollment.household_members