Added eventing to case management for flex

- Add EventsManager and connect eventing between BusinessProcess and Case (in the dummy example)
    - Add/Update dummy application classes for acceptance testing
- Update testing, as appropriate
- Other minor cleanup

Author: MichaelCrawfordNava

template/{{app_name}}/engines/flex/app/helpers/flex/events_manager.rb

@@ -0,0 +1,28 @@
+module Flex
+  class EventsManager
+    def self.subscribe(event_key, callback)
+      subscription = ActiveSupport::Notifications.subscribe(event_key) do |name, _started, _finished, _unique_id, payload|
+        callback.call({
+          name: name,
+          payload: payload
+        })
+      end
+
+      subscription
+    end
+
+    def self.unsubscribe(subscription)
+      ActiveSupport::Notifications.unsubscribe(subscription)
+    end
+
+    def self.publish(event_key, payload = {})
+      ActiveSupport::Notifications.instrument(event_key, payload)
+    end
+
+    private
+
+    def initialize
+      # setting initialize to private so that we cannot make new instances of it
+    end
+  end
+end

template/{{app_name}}/engines/flex/app/models/concerns/flex/task_handler_service.rb

@@ -0,0 +1,9 @@
+module Flex
+  module TaskHandlerService
+    extend ActiveSupport::Concern
+
+    def create_task(kase:)
+      raise NoMethodError, "#{self.class} must implement execute method"
+    end
+  end
+end

template/{{app_name}}/engines/flex/app/models/flex/application_form.rb

@@ -10,7 +10,14 @@ class ApplicationForm < ApplicationRecord
 
     def submit_application
       self[:status] = :submitted
-      save
+      save!
+      publish_event
+    end
+
+    protected
+
+    def event_payload
+      { id: id }
     end
 
     private
@@ -23,5 +30,9 @@ def prevent_changes_if_submitted
       errors.add(:base, "Cannot modify a submitted application")
       throw :abort
     end
+
+    def publish_event
+      EventsManager.publish("application_submitted", self.event_payload)
+    end
   end
 end

template/{{app_name}}/engines/flex/app/models/flex/business_process.rb

@@ -4,12 +4,15 @@ class BusinessProcess
 
     attr_accessor :name, :description, :steps, :start, :transitions
 
-    def initialize(name:, description: "", steps: {}, start: "", transitions: {})
+    def initialize(name:, type:, description: "", steps: {}, start: "", transitions: {})
+      @subscriptions = {}
       @name = name
+      @type = type # recognizing this is a code smell that we will want to address in the future
       @description = description
-      @steps = steps
-      @start = start
-      @transitions = transitions
+      define_start(start)
+      define_steps(steps)
+      define_transitions(transitions)
+      start_listening_for_events
     end
 
     def execute(kase)
@@ -25,7 +28,47 @@ def define_steps(steps)
     end
 
     def define_transitions(transitions)
+      if @subscriptions.any?
+        stop_listening_all_events
+      end
+
       @transitions = transitions
+      start_listening_for_events
+    end
+
+    private
+
+    def handle_event(event)
+      kase = @type.find(event[:payload][:case_id])
+      current_step = kase.business_process_current_step
+      next_step = @transitions[current_step][event[:name]]
+      kase.business_process_current_step = next_step
+      kase.save!
+      if next_step == "end"
+        kase.close
+      else
+        @steps[next_step].execute(kase)
+      end
+    end
+
+    def get_event_names_from_transitions
+      @transitions.values.flat_map(&:keys).uniq
+    end
+
+    def start_listening_for_events
+      get_event_names_from_transitions.each do |event_name|
+        new_subscription = EventsManager.subscribe(event_name, ->(event) {
+          handle_event(event)
+        })
+        @subscriptions[event_name] = new_subscription
+      end
+    end
+
+    def stop_listening_all_events
+      @subscriptions.each do |event_name, subscription|
+        EventsManager.unsubscribe(subscription)
+      end
+      @subscriptions.clear
     end
   end
 end

template/{{app_name}}/engines/flex/app/models/flex/user_task.rb

@@ -10,7 +10,7 @@ def initialize(name:, task_management_service:)
     end
 
     def execute(kase)
-      @task_management_service.create_task(name, "eventually will contain details about a case instead of static string")
+      @task_management_service.create_task(kase: kase)
     end
   end
 end

template/{{app_name}}/engines/flex/spec/acceptance/flex/passport_application_case_acceptance_spec.rb

@@ -8,10 +8,11 @@ module Flex
       # create new application
       test_form.save!
 
-      # check case created
+      # check case created and open with correct current step
       kase = PassportCase.find(test_form.case_id)
       expect(kase).not_to be_nil
-      expect(kase.business_process_current_step).to eq ("collect application info")
+      expect(kase.status).to eq ("open")
+      expect(kase.business_process_current_step).to eq ("collect_application_info")
 
       # submit application
       test_form.first_name = "John"
@@ -20,15 +21,24 @@ module Flex
       test_form.save!
       test_form.submit_application
       kase.reload
-      expect(kase.business_process_current_step).to eq ("verify identity")
+      expect(kase.business_process_current_step).to eq ("verify_identity")
 
       # verify identity (simulate action that an adjudicator takes)
-      kase.verify_identity
-      expect(kase.business_process_current_step).to eq ("review passport photo")
+      EventsManager.publish("identity_verified", { case_id: kase.id })
+      kase.reload
+      expect(kase.business_process_current_step).to eq ("review_passport_photo")
+
+      # approve passport photo
+      EventsManager.publish("passport_photo_approved", { case_id: kase.id })
+      kase.reload
+      expect(kase.business_process_current_step).to eq ("notify_user_passport_approved")
 
-      # approve application
-      kase.approve
+      # notify user
+      EventsManager.publish("notification_completed", { case_id: kase.id })
+      kase.reload
       expect(kase.business_process_current_step).to eq ("end")
+
+      # check case status
       expect(kase.status).to eq ("closed")
     end
   end

template/{{app_name}}/engines/flex/spec/dummy/app/business_processes/flex/passport_application_business_process_manager.rb

@@ -13,27 +13,59 @@ def initialize
     def create_passport_application_business_process
       business_process = BusinessProcess.new(
         name: 'Passport Application Process',
+        type: PassportCase,
         description: 'Process for applying for a passport'
       )
-      business_process.define_steps(self.create_passport_application_business_process_steps)
+      business_process.define_steps(
+        {
+          "collect_application_info" => UserTask.new(
+            name: "Collect App Info",
+            task_management_service: UserTaskCreatorService
+          ),
+          "verify_identity" => SystemProcess.new(name: "Verify Identity", callback: ->(kase) {
+            IdentityVerifierService.new(kase).verify_identity # IdentityVerifierService would publish an event when verify_identity completes
+          }),
+          "manual_adjudicator_review" => UserTask.new(name: "Manual Adjudicator Review", task_management_service: AdjudicatorTaskCreatorService), # create an adjudicator task for manual review
+          "review_passport_photo" => SystemProcess.new(name: "Review Passport Photo", callback: ->(kase) {
+            PhotoVerifierService.new(kase).verify_photo # PhotoVerifierService would publish an event when verify_photo completes
+          }),
+          "notify_user_passport_approved" => SystemProcess.new(name: "Notify Passport Approval", callback: ->(kase) {
+            UserNotifierService.new(kase).send_notification("approval") # UserNotifierService would publish an event when send_notification completes
+          }),
+          "notify_user_passport_rejected" => SystemProcess.new(name: "Notify Passport Rejection", callback: ->(kase) {
+            UserNotifierService.new(kase).send_notification("rejection") # UserNotifierService would publish an event when send_notification completes
+          })
+        }
+      )
       business_process.define_transitions(
         {
-          "collect application info" => 'verify identity',
-          "verify identity" => 'review passport photo',
-          "review passport photo" => 'end'
+          "collect_application_info" => {
+            "application_submitted" => 'verify_identity',
+            "application_cancelled" => 'end'
+          },
+          "verify_identity" => {
+            "identity_verified" => 'review_passport_photo',
+            "identity_warning" => 'manual_adjudicator_review'
+          },
+          "manual_adjudicator_review" => {
+            "identity_verified" => 'review_passport_photo',
+            "identity_rejected" => 'application_rejected'
+          },
+          "review_passport_photo" => {
+            "passport_photo_approved" => 'notify_user_passport_approved',
+            "passport_photo_rejected" => 'review_passport_photo'
+          },
+          "notify_user_passport_approved" => {
+            "notification_completed" => "end"
+          },
+          "notify_user_passport_rejected" => {
+            "notification_completed" => 'end'
+          }
         }
       )
-      business_process.define_start('collect application info')
-      business_process
-    end
+      business_process.define_start('collect_application_info')
 
-    def create_passport_application_business_process_steps
-      {
-        'collect application info' => SystemProcess.new(name: "Collect Application Info", callback: ->(kase) { kase.mark_application_info_collected }), # simulate collecting application info
-        'verify identity' => SystemProcess.new(name: "Verify Identity", callback: ->(kase) { kase.verify_identity }), # simulate verifying identity
-        'review passport photo' => SystemProcess.new(name: "Review Passport Photo", callback: ->(kase) { kase.approve }), # simulate reviewing passport photo
-        'end' => SystemProcess.new(name: "End", callback: ->(kase) { kase.close }) # close case
-      }
+      business_process
     end
   end
 end

template/{{app_name}}/engines/flex/spec/dummy/app/models/flex/passport_application_form.rb

@@ -1,5 +1,3 @@
-require_relative "../../../../../app/models/flex/application_form"
-
 module Flex
   class PassportApplicationForm < ApplicationForm
     before_create :create_passport_case, unless: -> { has_case_id? }
@@ -18,11 +16,14 @@ def has_all_necessary_fields?
     end
 
     def submit_application
-      if has_all_necessary_fields?
-        super
-        # this is temporary and will be changed in another PR when implementing an event-based approach
-        PassportCase.find(case_id).mark_application_info_collected
-      end
+      has_all_necessary_fields? ? super : false
+    end
+
+    protected
+
+    def event_payload
+      parent_payload = super
+      parent_payload.merge({ case_id: case_id })
     end
 
     private

template/{{app_name}}/engines/flex/spec/dummy/app/models/flex/passport_case.rb

@@ -2,26 +2,15 @@ module Flex
   class PassportCase < Case
     readonly attribute :passport_id, :string, default: SecureRandom.uuid # always defaults to a new UUID
 
-    attribute :business_process_current_step, :string, default: "collect application info"
-    private def business_process_current_step=(value)
-      self[:business_process_current_step] = value
-    end
-
-    @business_process = PassportApplicationBusinessProcessManager.instance.business_process
+    attribute :business_process_current_step, :string, default: "collect_application_info"
 
-    def mark_application_info_collected
-      self[:business_process_current_step] = "verify identity"
-      save!
-    end
+    after_create :initialize_business_process
 
-    def verify_identity
-      self[:business_process_current_step] = "review passport photo"
-      save!
-    end
+    private
 
-    def approve
-      self[:business_process_current_step] = "end"
-      close
+    def initialize_business_process
+      business_process = PassportApplicationBusinessProcessManager.instance.business_process
+      business_process.execute({ case_id: id })
     end
   end
 end

template/{{app_name}}/engines/flex/spec/dummy/app/services/flex/adjudicator_task_creator_service.rb

@@ -0,0 +1,8 @@
+module Flex
+  class AdjudicatorTaskCreatorService
+    include TaskHandlerService
+
+    def self.create_task(kase:)
+    end
+  end
+end