Merge pull request #477 from bcgov/feature/display-peach-onhold-reasons

feat: display peach on hold reasons and update applicant request reason mapping

Author: kyle1morel

app/peachSync.ts

@@ -4,35 +4,36 @@ import { refreshCodeCaches } from './src/db/codes/cache.ts';
 import { getLogger } from './src/utils/log.ts';
 import { state } from './state.ts';
 
-import type { Permit } from './src/types';
+import type { UpdatedPermitWithNote } from './src/types';
 
 const log = getLogger(module.filename);
 
 async function syncPeachToPcns() {
   if (!state.features.peach) return;
 
   const started = Date.now();
-  let updatedPermits: Permit[];
+  let updatedPermitsWithNotes: UpdatedPermitWithNote[];
 
   log.info('PEACH sync job started');
   try {
-    updatedPermits = await syncPeachRecords();
+    updatedPermitsWithNotes = await syncPeachRecords();
 
     log.info('PEACH sync completed', {
       durationMs: Date.now() - started,
-      updatedCount: updatedPermits.length
+      updatedCount: updatedPermitsWithNotes.length
     });
   } catch (error) {
     log.error('PEACH sync FAILED during data sync', error);
     process.exitCode = 1;
     return;
   }
 
-  if (updatedPermits.length === 0) return;
+  if (updatedPermitsWithNotes.length === 0) return;
 
   try {
-    for (const permit of updatedPermits) {
-      await sendPermitUpdateNotifications(permit, true);
+    for (const permitWithNote of updatedPermitsWithNotes) {
+      const { permit, note } = permitWithNote;
+      await sendPermitUpdateNotifications(permit, true, note);
     }
   } catch (error) {
     log.warn('PEACH sync completed but sending notifications failed', error);

app/src/controllers/generalProject.ts

@@ -147,6 +147,7 @@ const generateGeneralProjectData = async (
         statusLastVerifiedTime: null,
         issuedPermitId: null,
         state: PermitState.IN_PROGRESS,
+        onHoldCode: null,
         submittedDate: x.submittedDate,
         submittedTime: x.submittedTime,
         decisionDate: null,
@@ -176,6 +177,7 @@ const generateGeneralProjectData = async (
         statusLastVerifiedTime: null,
         issuedPermitId: null,
         state: PermitState.NONE,
+        onHoldCode: null,
         submittedDate: null,
         submittedTime: x.submittedTime,
         decisionDate: null,

app/src/controllers/housingProject.ts

@@ -205,6 +205,7 @@ const generateHousingProjectData = async (
         statusLastVerifiedTime: null,
         issuedPermitId: null,
         state: PermitState.IN_PROGRESS,
+        onHoldCode: null,
         submittedDate: x.submittedDate,
         submittedTime: x.submittedTime,
         decisionDate: null,
@@ -234,6 +235,7 @@ const generateHousingProjectData = async (
         statusLastVerifiedTime: null,
         issuedPermitId: null,
         state: PermitState.NONE,
+        onHoldCode: null,
         submittedDate: null,
         submittedTime: x.submittedTime,
         decisionDate: null,

app/src/controllers/peach.ts

@@ -1,4 +1,4 @@
-import { PermitStage, PermitState } from '../db/codes/enums.ts';
+import { PermitStage, PermitState, PiesOnHold } from '../db/codes/enums.ts';
 import { transactionWrapper } from '../db/utils/transactionWrapper.ts';
 import { generateUpdateStamps } from '../db/utils/utils.ts';
 import { parsePeachRecords, summarizePeachRecord } from '../parsers/peach.ts';
@@ -10,7 +10,13 @@ import { PeachIntegratedSystem } from '../utils/enums/permit.ts';
 
 import type { Request, Response } from 'express';
 import type { PrismaTransactionClient } from '../db/dataConnection.ts';
-import type { PeachSummary, Permit, Record as PeachRecord, PermitTracking } from '../types/index.ts';
+import type {
+  PeachSummary,
+  Permit,
+  Record as PeachRecord,
+  PermitTracking,
+  UpdatedPermitWithNote
+} from '../types/index.ts';
 
 const log = getLogger(module.filename);
 
@@ -78,7 +84,7 @@ export const getPeachSummaryController = async (req: Request<never, never, Permi
  * Syncs PEACH data for permit tracking to PCNS, returns a list of permits used for sending update notifications
  * @returns Array of updated permits
  */
-export const syncPeachRecords = async (): Promise<Permit[]> => {
+export const syncPeachRecords = async (): Promise<UpdatedPermitWithNote[]> => {
   const systemRecordPermits: { recordId: string; systemId: string; permit: Permit }[] = [];
   await transactionWrapper<void>(async (tx: PrismaTransactionClient) => {
     // Only fetch permits that have a peach integrated system permit type
@@ -110,7 +116,7 @@ export const syncPeachRecords = async (): Promise<Permit[]> => {
     }
   });
 
-  // TODO: May need rate limiting in the future
+  // Note: May need rate limiting in the future
   const results = await Promise.allSettled(
     systemRecordPermits.map((srp) => getPeachRecord(srp.recordId, srp.systemId))
   );
@@ -137,7 +143,7 @@ export const syncPeachRecords = async (): Promise<Permit[]> => {
 
   const parsedRecords: Record<string, PeachSummary> = parsePeachRecords(records);
 
-  const updatedPermits: Permit[] = [];
+  const updatedPermits: UpdatedPermitWithNote[] = [];
 
   await transactionWrapper<void>(async (tx: PrismaTransactionClient) => {
     for (const systemRecordPermit of systemRecordPermits) {
@@ -167,14 +173,21 @@ export const syncPeachRecords = async (): Promise<Permit[]> => {
       const lastChangedDatesEqual = compareDates(peachStatusChangedDatetime, pcnsStatusChangedDatetime) === 0;
       const stagesEqual = peachSummary.stage === (pcnsPermit.stage as PermitStage);
       const statesEqual = peachSummary.state === (pcnsPermit.state as PermitState);
+      const onHoldCodesEqual = peachSummary.onHoldCode === pcnsPermit.onHoldCode;
 
+      const stageOrStateHasDiff = !stagesEqual || !statesEqual;
       const hasDiff =
-        !stagesEqual || !statesEqual || !submittedDatesEqual || !decisionDatesEqual || !lastChangedDatesEqual;
+        stageOrStateHasDiff ||
+        !onHoldCodesEqual ||
+        !submittedDatesEqual ||
+        !decisionDatesEqual ||
+        !lastChangedDatesEqual;
 
       if (!hasDiff) continue;
 
       pcnsPermit.stage = peachSummary.stage;
       pcnsPermit.state = peachSummary.state;
+      pcnsPermit.onHoldCode = peachSummary.onHoldCode;
 
       pcnsPermit.submittedDate = peachSummary.submittedDate;
       pcnsPermit.submittedTime = peachSummary.submittedTime;
@@ -198,11 +211,16 @@ export const syncPeachRecords = async (): Promise<Permit[]> => {
       pcnsPermit.updatedBy = updatedBy;
 
       const cleanedPermit = omit(pcnsPermit, ['permitTracking', 'permitType']);
-
       const updatedPermit = await upsertPermit(tx, cleanedPermit);
+      const applicantRequestedHold = !onHoldCodesEqual && peachSummary.onHoldCode === PiesOnHold.APPLICANT_REQUEST;
+      let note: string | undefined = undefined;
+
+      if (applicantRequestedHold) {
+        note = 'This application has been placed on hold at the applicant’s request';
+      }
 
-      // Only return permits and notes that have had a status change for notifications
-      if (!stagesEqual || !statesEqual) updatedPermits.push(updatedPermit);
+      // For notifications, only return permits that have had a status change or is now on hold by applicant's request.
+      if (stageOrStateHasDiff || applicantRequestedHold) updatedPermits.push({ permit: updatedPermit, note });
     }
   });
 

app/src/db/codes/enums.ts

@@ -136,3 +136,12 @@ export const PermitState = {
 } as const;
 
 export type PermitState = (typeof PermitState)[keyof typeof PermitState];
+
+export const PiesOnHold = {
+  APPLICANT_REQUEST: 'APPLICANT_REQUEST',
+  LEGAL_ACTION: 'LEGAL_ACTION',
+  MISSING_INFORMATION: 'MISSING_INFORMATION',
+  PENDING_EXTERNAL_DECISION: 'PENDING_EXTERNAL_DECISION'
+} as const;
+
+export type PiesOnHold = (typeof PiesOnHold)[keyof typeof PiesOnHold];

app/src/db/migrations/20260526000000_064-pies-on-hold-codes.ts

@@ -0,0 +1,103 @@
+import stamps from '../stamps.ts';
+import {
+  createAuditLogTrigger,
+  createUpdatedAtTrigger,
+  dropAuditLogTrigger,
+  dropUpdatedAtTrigger
+} from '../utils/utils.ts';
+
+import type { Knex } from 'knex';
+
+export async function up(knex: Knex): Promise<void> {
+  return (
+    Promise.resolve()
+      // Create code tables
+      .then(() =>
+        knex.schema.createTable('pies_on_hold_code', (table) => {
+          // Constrains to SCREAMING_SNAKE w/ no double or trailing underscores
+          table.text('code').primary().checkRegex('^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$');
+          table.text('display').unique().notNullable();
+          table.text('definition').notNullable();
+          table.boolean('active').notNullable().defaultTo(true);
+          stamps(knex, table);
+        })
+      )
+
+      // Create before update & audit triggers
+      .then(async () => await createUpdatedAtTrigger(knex, 'public', 'pies_on_hold_code'))
+      .then(async () => await createAuditLogTrigger(knex, 'public', 'pies_on_hold_code'))
+
+      // Seeding code table
+      .then(() => {
+        const onHoldCodes = [
+          {
+            code: 'APPLICANT_REQUEST',
+            display: 'Applicant Request',
+            definition: 'The application is paused as requested by applicant and supported by staff.'
+          },
+          {
+            code: 'LEGAL_ACTION',
+            display: 'Legal Action',
+            definition:
+              'The application is subject to legal proceedings, or legal counsel has advised that processing be paused.'
+          },
+          {
+            code: 'MISSING_INFORMATION',
+            display: 'Missing Information',
+            definition: 'More information is required from the applicant to proceed with the review.'
+          },
+          {
+            code: 'PENDING_EXTERNAL_DECISION',
+            display: 'Pending External Decision',
+            definition:
+              'The application requires decision, approval, or input from another agency or an external process.'
+          }
+        ];
+
+        return knex('pies_on_hold_code').insert(onHoldCodes);
+      })
+
+      // Add on_hold_code to permit table
+      .then(() =>
+        knex.schema.alterTable('permit', function (table) {
+          table
+            .text('on_hold_code')
+            .references('code')
+            .inTable('pies_on_hold_code')
+            .onUpdate('CASCADE')
+            .onDelete('SET NULL');
+        })
+      )
+
+      // Set on_hold_code to MISSING_INFORMATION for PEACH integrated permits in 'Pending client action' state
+      .then(() => {
+        const peachIntegratedPermitTypes = [32, 34, 35, 8, 9, 11, 12, 10, 7, 31, 21, 19, 20, 22, 23];
+
+        return knex('permit')
+          .where('state', 'PENDING_APPLICANT_ACTION')
+          .whereIn('permit_type_id', peachIntegratedPermitTypes)
+          .update({
+            on_hold_code: 'MISSING_INFORMATION'
+          });
+      })
+  );
+}
+
+export async function down(knex: Knex): Promise<void> {
+  return (
+    Promise.resolve()
+      // Drop on_hold_code column
+      .then(() =>
+        knex.schema.alterTable('permit', function (table) {
+          table.dropColumn('on_hold_code');
+        })
+      )
+
+      // Drop triggers
+      .then(async () => await dropUpdatedAtTrigger(knex, 'public', 'pies_on_hold_code'))
+      .then(async () => await dropAuditLogTrigger(knex, 'public', 'pies_on_hold_code'))
+
+      // Drop code table
+      .then(() => knex.schema.dropTableIfExists('pies_on_hold_code'))
+  );
+}