Reverse the association between application forms and cases (#71)

## Changes

- ApplicationForm publishes Created event on create
- Minor: Rename application form id in ApplicationFormSubmitted event
payload from id to application_form_id
- BusinessProcess now always starts when an ApplicationForm is created.
We moved the case creation logic from ApplicationForm to the
BusinessProcess. The business process now listens for
ApplicationFormCreated events and creates the case and executes the
start step when
- Get rid of BusinessProcess.execute for now since business processes
start when an application form is created and cannot be manually started
(this means BusinessProcess currently doesn't properly implement the
Step interface)
- Decoupled executing of BusinessProcess from the Case class, so Case no
longer has an execute_business_process method that's called after_create
- Reversed the association between case and application form. Case now
has an application_form_id, while ApplicationForm no longer has a
case_id

Migrations for test app (will need to do for demo too)
- Add application_form_id to passport_cases and test_cases
- Remove case_id from test_application_forms and
passport_application_forms

Misc
- Fix the publish_event_with_payload rspec matcher
- Replaces some `puts` lines with `Rails.logger.debug`
- Order methods in BusinessProcess alphabetically within each visibility
section

## Context

Moving in a direction that decouples application form from case based on
this conversation
https://nava.slack.com/archives/C03G1SWD9H7/p1747252433304899

Note: This currently breaks a couple of things about BusinessProcess
which we can address in a future PR:
- BusinessProcess no longer implements execute, so it no longer can act
as a step in another BusinessProcess (note that it doesn't seem like we
had a test for this, or maybe we did and I got rid of it by accident)
- Relatedly: BusinessProcess can only trigger on an
ApplicationFormCreated event, not manually through execute or through
any other start event. An upcoming PR should generalize the start
functionality to allow different start events (e.g. see BPMN
https://www.trisotech.com/bpmn-101-three-ways-a-process-starts/). We'll
need to update BusinessProcess to allow multiple start events and to
have a separate handler for start events.

Author: lorenyu

app/helpers/flex/event_manager.rb

@@ -17,7 +17,7 @@ def unsubscribe(subscription)
       end
 
       def publish(event_key, payload = {})
-        puts "Event Manager: Publishing event '#{event_key}' with payload: #{payload.inspect}"
+        Rails.logger.debug "Event Manager: Publishing event '#{event_key}' with payload: #{payload.inspect}"
         ActiveSupport::Notifications.instrument(event_key, payload)
       end
     end

app/models/flex/application_form.rb

@@ -4,26 +4,24 @@ class ApplicationForm < ApplicationRecord
 
     include Flex::Attributes
 
-    attribute :case_id, :string
-
     attribute :status, :integer, default: 0
     protected attr_writer :status, :integer
     enum :status, in_progress: 0, submitted: 1
 
-    before_create :create_case, unless: ->(application_form) { application_form.case_id? }
+    after_create :publish_created
     before_update :prevent_changes_if_submitted, if: :was_submitted?
 
     def submit_application
       puts "Submitting application with ID: #{id}"
       self[:status] = :submitted
       save!
-      publish_event
+      publish_submitted
     end
 
     protected
 
     def event_payload
-      { id: id }
+      { application_form_id: id }
     end
 
     protected
@@ -48,8 +46,13 @@ def prevent_changes_if_submitted
       throw :abort
     end
 
-    def publish_event
-      puts "Publishing event #{self.class.name}Submitted for application with ID: #{id}"
+    def publish_created
+      Rails.logger.debug "Publishing event #{self.class.name}Created for application with ID: #{id}"
+      EventManager.publish("#{self.class.name}Created", self.event_payload)
+    end
+
+    def publish_submitted
+      Rails.logger.debug "Publishing event #{self.class.name}Submitted for application with ID: #{id}"
       EventManager.publish("#{self.class.name}Submitted", self.event_payload)
     end
   end

app/models/flex/business_process.rb

@@ -9,86 +9,75 @@ module Flex
   #     # Define steps - can be UserTask or SystemProcess
   #     bp.step('collect_info',
   #       Flex::UserTask.new("Collect Information", TaskCreationService))
-  #     
+  #
   #     bp.step('process_data',
   #       Flex::SystemProcess.new("Process Data", ->(kase) {
   #         DataProcessor.new(kase).process
   #       }))
-  #     
+  #
   #     # Set the starting step
   #     bp.start('collect_info')
-  #     
+  #
   #     # Define transitions between steps based on events
   #     bp.transition('collect_info', 'form_submitted', 'process_data')
   #     bp.transition('process_data', 'processing_complete', 'end')
   #   end
   #
   # Steps can be either:
-  # - UserTask: Tasks that require human interaction
-  # - SystemProcess: Automated tasks that run without user intervention
+  # - UserTask: Tasks that require human interaction, created through a TaskCreationService
+  # - SystemProcess: Automated tasks that run without user intervention, defined with a callable
   #
   # The process automatically listens for events and transitions between steps
-  # based on the defined transitions. When a step transitions to 'end',
-  # the case is automatically closed.
+  # based on the defined transitions. Events can be triggered by either user actions
+  # or system processes. When a step transitions to 'end', the case is automatically closed.
+  #
+  # Event payloads must contain either case_id or application_form_id to identify the case.
   #
   # @see Flex::UserTask
   # @see Flex::SystemProcess
   #
   # Key Methods:
-  # - execute(kase): Starts or resumes execution of the process for a case
   # - start_listening_for_events: Starts listening for events that trigger transitions
   # - stop_listening_for_events: Stops listening for events (useful for cleanup)
   #
   # Class Methods:
   # @method define(name, case_class)
-  #   Creates a new BusinessProcess definition
+  #   Creates a new BusinessProcess definition. Also automatically starts listening for events.
   #   @param [Symbol] name The name of the business process
   #   @param [Class] case_class The case class this process operates on
-  #   @yield [BusinessProcessBuilder] builder DSL for defining the process
-  #   @return [BusinessProcess] The configured business process
+  #   @yield [BusinessProcessBuilder] builder DSL for defining the process steps and transitions
+  #   @return [BusinessProcess] The configured and activated business process
   #
   # Instance Methods:
-  # @method execute(kase)
-  #   Starts or resumes execution of the process for a case
-  #   @param [ApplicationRecord] kase The case to execute the process on
-  #
   # @method start_listening_for_events
-  #   Starts listening for events that can trigger transitions
+  #   Starts listening for events that can trigger transitions. Called automatically by define.
   #
   # @method stop_listening_for_events
-  #   Stops listening for events, useful for cleanup in tests
+  #   Stops listening for events and cleans up subscriptions. Useful for cleanup in tests.
   #
   class BusinessProcess
     include Step
 
-    attr_accessor :name, :description, :steps, :start, :transitions, :case_class
+    attr_accessor :name, :description, :steps, :transitions, :case_class
 
-    def initialize(name:, case_class:, description: "", steps: {}, start: "", transitions: {})
+    def initialize(name:, case_class:, description: "", steps: {}, start_step_name: "", transitions: {})
       @subscriptions = {}
       @name = name
       @case_class = case_class
       @description = description
-      @start = start
       @steps = steps
+      @start_step_name = start_step_name
       @transitions = transitions
       @listening = false
     end
 
-    def execute(kase)
-      if kase.business_process_current_step.blank?
-        kase.business_process_current_step = @start
-      end
-      steps[start].execute(kase)
-      kase.save!
-    end
-
     def start_listening_for_events
       if @listening
         Rails.logger.debug "Flex::BusinessProcess with name #{name} already listening for events"
         return
       end
 
-      get_event_names_from_transitions.each do |event_name|
+      get_event_names.each do |event_name|
         Rails.logger.debug "Flex::BusinessProcess with name #{name} subscribing to event: #{event_name}"
         @subscriptions[event_name] = EventManager.subscribe(event_name, method(:handle_event))
       end
@@ -109,25 +98,70 @@ def stop_listening_for_events
 
     private
 
-    def handle_event(event)
-      Rails.logger.debug "Handling event: #{event[:name]} for case ID: #{event[:payload][:case_id]}"
-      kase = @case_class.find(event[:payload][:case_id])
-      current_step = kase.business_process_current_step
-      next_step = @transitions&.dig(current_step, event[:name])
-      Rails.logger.debug "Current step: #{current_step}, Next step: #{next_step}"
-      return unless next_step # Skip processing if no valid transition exists
+    def create_case_from_event(event)
+      Rails.logger.debug "Creating case from event: #{event[:name]} with payload: #{event[:payload]}"
+      raise "Cannot create case from event #{event[:name]}. Event must be an ApplicationFormCreated event" unless event[:name].end_with?("ApplicationFormCreated")
+      kase = @case_class.create!(
+        application_form_id: event[:payload][:application_form_id],
+        business_process_current_step: @start_step_name
+      )
+      kase
+    end
 
-      kase.business_process_current_step = next_step
-      kase.save!
-      if next_step == "end"
+    def execute_current_step(kase)
+      step_name = kase.business_process_current_step
+      Rails.logger.debug "Executing current step: #{step_name} for case ID: #{kase.id}"
+      if step_name == "end"
         kase.close
       else
-        @steps[next_step].execute(kase)
+        @steps[step_name].execute(kase)
+      end
+    end
+
+    def get_case_from_event(event)
+      Rails.logger.debug "Getting case from event: #{event[:name]} with payload: #{event[:payload]}"
+      if event[:payload].key?(:application_form_id)
+        Rails.logger.debug "Getting case from event payload with application_form_id"
+        @case_class.find_by(application_form_id: event[:payload][:application_form_id])
+      else
+        Rails.logger.debug "Getting case from event payload with case_id"
+        @case_class.find(event[:payload][:case_id])
       end
     end
 
-    def get_event_names_from_transitions
-      @transitions.values.flat_map(&:keys).uniq
+    def get_event_names
+      @transitions.values.flat_map(&:keys).uniq | [ start_event_name ]
+    end
+
+    def get_next_step(kase, event_name)
+      current_step = kase.business_process_current_step
+      next_step = @transitions&.dig(current_step, event_name)
+      next_step
+    end
+
+    def handle_event(event)
+      Rails.logger.debug "Handling event: #{event[:name]} with payload: #{event[:payload]}"
+      if start_event?(event[:name])
+        kase = create_case_from_event(event)
+      else
+        kase = get_case_from_event(event)
+        next_step = get_next_step(kase, event[:name])
+        return unless next_step
+
+        Rails.logger.debug "Transitioning to step #{next_step} and executing the step"
+        kase.business_process_current_step = next_step
+        kase.save!
+      end
+
+      execute_current_step(kase)
+    end
+
+    def start_event?(event_name)
+      event_name == start_event_name
+    end
+
+    def start_event_name
+      @case_class.name.sub("Case", "ApplicationFormCreated")
     end
 
     class << self

app/models/flex/business_process_builder.rb

@@ -11,7 +11,7 @@ def initialize(name, case_class)
     end
 
     def start(step_name)
-      @start = step_name
+      @start_step_name = step_name
     end
 
     def step(name, step)
@@ -29,7 +29,7 @@ def build
         case_class: @case_class,
         description: "",
         steps: @steps,
-        start: @start,
+        start_step_name: @start_step_name,
         transitions: @transitions
       )
     end

app/models/flex/case.rb

@@ -2,6 +2,8 @@ module Flex
   class Case < ApplicationRecord
     self.abstract_class = true
 
+    attribute :application_form_id, :string
+
     attribute :status, :integer, default: 0
     protected attr_writer :status, :integer
     enum :status, open: 0, closed: 1
@@ -10,8 +12,6 @@ class Case < ApplicationRecord
 
     protected attr_accessor :business_process
 
-    after_create :execute_business_process
-
     def close
       self[:status] = :closed
       save
@@ -21,11 +21,5 @@ def reopen
       self[:status] = :open
       save
     end
-
-    protected
-
-    def execute_business_process
-      business_process.execute(self)
-    end
   end
 end

spec/acceptance/flex/passport_application_case_acceptance_spec.rb

@@ -1,15 +1,15 @@
 require 'rails_helper'
 
 module Flex
-  RSpec.describe PassportApplicationForm, type: :model do
-    let(:test_form) { described_class.new }
+  RSpec.describe PassportBusinessProcess, type: :model do
+    let(:test_form) { PassportApplicationForm.new }
 
     it "creates a passport case upon starting a passport application form and properly progresses through steps" do
       # create new application
       test_form.save!
 
       # check case created and open with correct current step
-      kase = PassportCase.find(test_form.case_id)
+      kase = PassportCase.find_by_application_form_id(test_form.id)
       expect(kase).not_to be_nil
       expect(kase.status).to eq ("open")
       expect(kase.business_process_current_step).to eq ("collect_application_info")

spec/dummy/app/models/passport_application_form.rb

@@ -6,11 +6,6 @@ class PassportApplicationForm < Flex::ApplicationForm
 
   flex_attribute :date_of_birth, :memorable_date
 
-  attribute :case_id, :integer
-  private def case_id=(value)
-    self[:case_id] = value
-  end
-
   def has_all_necessary_fields?
     !first_name.nil? && !last_name.nil? && !date_of_birth.nil?
   end
@@ -22,17 +17,4 @@ def submit_application
   def full_name
     "#{first_name} #{last_name}"
   end
-
-  protected
-
-  def event_payload
-    parent_payload = super
-    parent_payload.merge({ case_id: case_id })
-  end
-
-  private
-
-  def has_case_id?
-    !case_id.nil?
-  end
 end

spec/dummy/config/environments/test.rb

@@ -61,4 +61,8 @@
 
   # Raise error when a before_action's only/except options reference missing actions
   config.action_controller.raise_on_missing_callback_actions = true
+
+  # Set log level to debug
+  # config.log_level = :debug
+  # config.logger = ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT))
 end

spec/dummy/db/migrate/20250515211539_add_test_application_form_ref_to_test_cases.rb

@@ -0,0 +1,5 @@
+class AddTestApplicationFormRefToTestCases < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :test_cases, :application_form, type: :string
+  end
+end

spec/dummy/db/migrate/20250515211550_add_passport_application_form_ref_to_passport_cases.rb

@@ -0,0 +1,6 @@
+class AddPassportApplicationFormRefToPassportCases < ActiveRecord::Migration[8.0]
+  def change
+    execute "DELETE FROM passport_cases"
+    add_reference :passport_cases, :application_form, type: :string
+  end
+end