#1978 - Request an Offering Change: Student View Request (#2196)

## **As a part of this PR, the follow tasks were completed:**

- [x] Added a view request link in requests and history assessment table
which redirects to view request page.
- [x] Added the logic to the "Review changes" button to redirect to the
view request page.
- [x] On the view request page, added tabs for "Requested change" and
"Active application details".
- [x] Added migration scripts to add `student_consent` column in the
`application_offering_change_requests` relation in the database.
- [x] Created modal with SABC declaration when "Allow change" is
clicked.
- [x] Created modal to decline the application offering change request
when "Decline change" is clicked.
- [x] Created migration scripts to add the declaration attribute to the
application offering change request entity.
- [x] Added toast message for "allow" and "decline" scenarios -- "Your
decision has been submitted successfully".
- [x] Renamed the "Active application details" tab to "Previous
application details" in the view request page when the ministry approves
the application offering change request.
- [x] Enabled the route redirection back to the application tracker
after the student submits the application offering change request.
- [x] Removed the "Decline change" and "Allow change" buttons when
student submits the application offering change request decision.
- [x] The logic for the below scenarios was adjusted:
1. Text under the "Application Details" and "Request Details" headings
is only displayed when the application offering change request is "In
progress with student."
        2. Program costs are not shown for the students.
        3. Status next to the student name reflects the feature status.

# **Screenshots**

### View Request Link in the Requests and History Tables
<img width="1918" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/f9ee51f9-ac00-4877-b3c5-3540ed7b670e">

### "Requested change" tab
<img width="1917" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/e1910580-d2fa-4b09-af3d-9a49fe7b75ed">

### "Active application details" tab
<img width="1917" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/0bf67b82-13c1-4785-b85b-b6db234db69f">

### Decline Application Offering Change Request Modal
<img width="1916" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/2587e3c9-e3c2-450c-8fc0-88836cee5e3c">

### Approve Application Offering Change Request Modal
<img width="1914" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/67fce378-90d5-441d-a3d3-833c848e9e97">

### Application Offering Change Request in progress with SABC
<img width="1916" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/4ea29b39-8e9e-4d12-bde6-d3641b7c49cc">

### Application Offering Change Request Approved by SABC
<img width="1914" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/60ccff31-e20a-4e54-9189-7077facc8605">

### Validation Error in the Approve Application Modal Dialog when the
student consent is not given
<img width="1917" alt="image"
src="https://github.com/bcgov/SIMS/assets/7859295/a43c60d0-7929-424f-8a1b-fffb3b51768a">

### **Note:**
As per discussion with the team, I have not created a common component
for the two tabs: "Requested details" and "Active application details".

##
**Next PR:**
- [ ]  **e2e tests**

Author: sh16011993

sources/packages/backend/apps/api/src/app.institutions.module.ts

@@ -66,6 +66,7 @@ import {
   NoteInstitutionsController,
   RestrictionControllerService,
   ApplicationOfferingChangeRequestInstitutionsController,
+  ApplicationOfferingChangeRequestControllerService,
 } from "./route-controllers";
 import { AuthModule } from "./auth/auth.module";
 import {
@@ -163,6 +164,7 @@ import {
     ApplicationExceptionControllerService,
     StudentAppealControllerService,
     ApplicationOfferingChangeRequestService,
+    ApplicationOfferingChangeRequestControllerService,
     ApplicationWithdrawalImportTextService,
   ],
 })

sources/packages/backend/apps/api/src/app.students.module.ts

@@ -35,6 +35,8 @@ import {
   EducationProgramStudentsController,
   StudentAccountApplicationStudentsController,
   EducationProgramOfferingStudentsController,
+  ApplicationOfferingChangeRequestStudentsController,
+  ApplicationOfferingChangeRequestControllerService,
   EducationProgramOfferingControllerService,
   RestrictionStudentsController,
   ProgramYearStudentsController,
@@ -77,6 +79,7 @@ import { ATBCIntegrationModule } from "@sims/integrations/atbc-integration";
     ATBCStudentController,
     ProgramYearStudentsController,
     OverawardStudentsController,
+    ApplicationOfferingChangeRequestStudentsController,
   ],
   providers: [
     WorkflowClientService,
@@ -117,6 +120,7 @@ import { ATBCIntegrationModule } from "@sims/integrations/atbc-integration";
     OverawardControllerService,
     StudentAppealControllerService,
     ConfirmationOfEnrollmentService,
+    ApplicationOfferingChangeRequestControllerService,
     ApplicationOfferingChangeRequestService,
   ],
 })

sources/packages/backend/apps/api/src/route-controllers/application-offering-change-request/application-offering-change-request.controller.service.ts

@@ -0,0 +1,96 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import { ApplicationOfferingChangeRequestService } from "../../services";
+import {
+  ApplicationOfferingChangesAPIOutDTO,
+  ApplicationOfferingDetailsAPIOutDTO,
+} from "./models/application-offering-change-request.dto";
+import { getUserFullName } from "../../utilities";
+
+@Injectable()
+export class ApplicationOfferingChangeRequestControllerService {
+  constructor(
+    private readonly applicationOfferingChangeRequestService: ApplicationOfferingChangeRequestService,
+  ) {}
+
+  /**
+   * Get the Application Offering Change Request by its id for the institution.
+   * @param applicationOfferingChangeRequestId the Application Offering Change Request id.
+   * @param options method options:
+   * - `locationId`: location id for institution authorization.
+   * @returns application offering change request.
+   */
+  async getApplicationOfferingChangeRequest(
+    applicationOfferingChangeRequestId: number,
+    options: {
+      locationId: number;
+    },
+  ): Promise<ApplicationOfferingChangesAPIOutDTO>;
+
+  /**
+   * Get the Application Offering Change Request by its id for the student.
+   * @param applicationOfferingChangeRequestId the Application Offering Change Request id.
+   * @param options method options:
+   * - `studentId`: student id for student authorization.
+   * - `applicationOfferingDetails`: boolean true indicates that only the required application offering details for the student are requested.
+   * @returns application offering change request.
+   */
+  async getApplicationOfferingChangeRequest(
+    applicationOfferingChangeRequestId: number,
+    options: {
+      studentId: number;
+      applicationOfferingDetails: boolean;
+    },
+  ): Promise<ApplicationOfferingDetailsAPIOutDTO>;
+
+  /**
+   * Get the Application Offering Change Request by its id.
+   * @param applicationOfferingChangeRequestId the Application Offering Change Request id.
+   * @param options method options:
+   * - `studentId`: student id for student authorization.
+   * - `locationId`: location id for institution authorization.
+   * - `applicationOfferingDetails`: boolean true indicates that only the required application offering details for the student are requested.
+   * @returns application offering change request.
+   */
+  async getApplicationOfferingChangeRequest(
+    applicationOfferingChangeRequestId: number,
+    options: {
+      studentId?: number;
+      locationId?: number;
+      applicationOfferingDetails?: boolean;
+    },
+  ): Promise<
+    ApplicationOfferingChangesAPIOutDTO | ApplicationOfferingDetailsAPIOutDTO
+  > {
+    const request = await this.applicationOfferingChangeRequestService.getById(
+      applicationOfferingChangeRequestId,
+      { studentId: options?.studentId, locationId: options?.locationId },
+    );
+    if (!request) {
+      throw new NotFoundException(
+        "Not able to find an Application Offering Change Request.",
+      );
+    }
+    const applicationOfferingDetails = {
+      status: request.applicationOfferingChangeRequestStatus,
+      applicationNumber: request.application.applicationNumber,
+      locationName: request.application.location.name,
+      requestedOfferingId: request.requestedOffering.id,
+      activeOfferingId: request.activeOffering.id,
+      reason: request.reason,
+    };
+    if (options?.applicationOfferingDetails) {
+      return applicationOfferingDetails;
+    }
+    return {
+      ...applicationOfferingDetails,
+      id: request.id,
+      applicationId: request.application.id,
+      requestedOfferingDescription: request.requestedOffering.name,
+      requestedOfferingProgramId: request.requestedOffering.educationProgram.id,
+      requestedOfferingProgramName:
+        request.requestedOffering.educationProgram.name,
+      assessedNoteDescription: request.assessedNote?.description,
+      studentFullName: getUserFullName(request.application.student.user),
+    };
+  }
+}

sources/packages/backend/apps/api/src/route-controllers/application-offering-change-request/application-offering-change-request.institutions.controller.ts

@@ -53,6 +53,7 @@ import {
   OFFERING_PROGRAM_YEAR_MISMATCH,
 } from "../../constants";
 import { InjectLogger, LoggerService } from "@sims/utilities/logger";
+import { ApplicationOfferingChangeRequestControllerService } from "./application-offering-change-request.controller.service";
 
 /**
  * Application offering change request controller for institutions client.
@@ -65,6 +66,7 @@ import { InjectLogger, LoggerService } from "@sims/utilities/logger";
 @HasLocationAccess("locationId")
 export class ApplicationOfferingChangeRequestInstitutionsController extends BaseController {
   constructor(
+    private readonly applicationOfferingChangeRequestControllerService: ApplicationOfferingChangeRequestControllerService,
     private readonly applicationOfferingChangeRequestService: ApplicationOfferingChangeRequestService,
     private readonly applicationService: ApplicationService,
   ) {
@@ -238,36 +240,15 @@ export class ApplicationOfferingChangeRequestInstitutionsController extends Base
   @ApiNotFoundResponse({
     description: "Not able to find an Application Offering Change Request.",
   })
-  async getById(
+  async getApplicationOfferingChangeRequest(
     @Param("applicationOfferingChangeRequestId", ParseIntPipe)
     applicationOfferingChangeRequestId: number,
     @Param("locationId", ParseIntPipe) locationId: number,
   ): Promise<ApplicationOfferingChangesAPIOutDTO> {
-    const request = await this.applicationOfferingChangeRequestService.getById(
+    return this.applicationOfferingChangeRequestControllerService.getApplicationOfferingChangeRequest(
       applicationOfferingChangeRequestId,
       { locationId },
     );
-    if (!request) {
-      throw new NotFoundException(
-        "Not able to find an Application Offering Change Request.",
-      );
-    }
-    return {
-      id: request.id,
-      status: request.applicationOfferingChangeRequestStatus,
-      applicationId: request.application.id,
-      applicationNumber: request.application.applicationNumber,
-      locationName: request.application.location.name,
-      activeOfferingId: request.activeOffering.id,
-      requestedOfferingId: request.requestedOffering.id,
-      requestedOfferingDescription: request.requestedOffering.name,
-      requestedOfferingProgramId: request.requestedOffering.educationProgram.id,
-      requestedOfferingProgramName:
-        request.requestedOffering.educationProgram.name,
-      reason: request.reason,
-      assessedNoteDescription: request.assessedNote?.description,
-      studentFullName: getUserFullName(request.application.student.user),
-    };
   }
 
   /**

sources/packages/backend/apps/api/src/route-controllers/application-offering-change-request/application-offering-change-request.students.controller.ts

@@ -0,0 +1,167 @@
+import {
+  Body,
+  Controller,
+  Get,
+  NotFoundException,
+  Param,
+  ParseIntPipe,
+  Patch,
+  UnprocessableEntityException,
+} from "@nestjs/common";
+import {
+  ApiNotFoundResponse,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from "@nestjs/swagger";
+import { AuthorizedParties } from "../../auth/authorized-parties.enum";
+import { AllowAuthorizedParty, UserToken } from "../../auth/decorators";
+import { ClientTypeBaseRoute } from "../../types";
+import BaseController from "../BaseController";
+import {
+  ApplicationOfferingChangeRequestStatusAPIOutDTO,
+  ApplicationOfferingDetailsAPIOutDTO,
+  StudentApplicationOfferingChangeRequestAPIInDTO,
+} from "./models/application-offering-change-request.dto";
+import { StudentUserToken } from "../../auth";
+import { ApplicationOfferingChangeRequestControllerService } from "./application-offering-change-request.controller.service";
+import { ApplicationOfferingChangeRequestService } from "../../services";
+import { ApplicationOfferingChangeRequestStatus } from "@sims/sims-db";
+
+/**
+ * Application offering change request controller for students client.
+ */
+@AllowAuthorizedParty(AuthorizedParties.student)
+@Controller("application-offering-change-request")
+@ApiTags(`${ClientTypeBaseRoute.Student}-application-offering-change-request`)
+export class ApplicationOfferingChangeRequestStudentsController extends BaseController {
+  constructor(
+    private readonly applicationOfferingChangeRequestService: ApplicationOfferingChangeRequestService,
+    private readonly applicationOfferingChangeRequestControllerService: ApplicationOfferingChangeRequestControllerService,
+  ) {
+    super();
+  }
+
+  /**
+   * Gets the Application Offering Change Request details.
+   * @param applicationOfferingChangeRequestId the Application Offering Change Request id.
+   * @param studentUserToken student user token to authorize the user.
+   * @returns Application Offering Change Request details.
+   */
+  @Get(":applicationOfferingChangeRequestId")
+  @ApiNotFoundResponse({
+    description: "Not able to find an Application Offering Change Request.",
+  })
+  async getApplicationOfferingChangeRequest(
+    @Param("applicationOfferingChangeRequestId", ParseIntPipe)
+    applicationOfferingChangeRequestId: number,
+    @UserToken()
+    studentUserToken: StudentUserToken,
+  ): Promise<ApplicationOfferingDetailsAPIOutDTO> {
+    return this.applicationOfferingChangeRequestControllerService.getApplicationOfferingChangeRequest(
+      applicationOfferingChangeRequestId,
+      {
+        studentId: studentUserToken.studentId,
+        applicationOfferingDetails: true,
+      },
+    );
+  }
+
+  /**
+   * Gets the Application Offering Change Request status.
+   * @param applicationOfferingChangeRequestId the Application Offering Change Request id.
+   * @param studentUserToken student user token to authorize the user.
+   * @returns Application Offering Change Request status.
+   */
+  @Get(
+    ":applicationOfferingChangeRequestId/application-offering-change-request-status",
+  )
+  @ApiNotFoundResponse({
+    description:
+      "Not able to get the Application Offering Change Request Status.",
+  })
+  async getApplicationOfferingChangeRequestStatus(
+    @Param("applicationOfferingChangeRequestId", ParseIntPipe)
+    applicationOfferingChangeRequestId: number,
+    @UserToken()
+    studentUserToken: StudentUserToken,
+  ): Promise<ApplicationOfferingChangeRequestStatusAPIOutDTO> {
+    const applicationOfferingChangeRequestStatus =
+      await this.applicationOfferingChangeRequestService.getApplicationOfferingChangeRequestStatusById(
+        applicationOfferingChangeRequestId,
+        {
+          studentId: studentUserToken.studentId,
+        },
+      );
+    if (!applicationOfferingChangeRequestStatus) {
+      throw new NotFoundException(
+        "Application Offering Change Request not found.",
+      );
+    }
+    return { status: applicationOfferingChangeRequestStatus };
+  }
+
+  /**
+   * Updates an application offering change request status.
+   * @param applicationOfferingChangeRequestId application offering change request id.
+   * @param userToken user token to authorize the user.
+   * @param payload information to update the application offering change request status.
+   */
+  @Patch(":applicationOfferingChangeRequestId")
+  @ApiNotFoundResponse({
+    description:
+      "Application offering change not found or not in valid status to be updated.",
+  })
+  @ApiUnprocessableEntityResponse({
+    description:
+      "Invalid application offering change status or student consent not provided",
+  })
+  async updateApplicationOfferingChangeRequestStatus(
+    @Param("applicationOfferingChangeRequestId", ParseIntPipe)
+    applicationOfferingChangeRequestId: number,
+    @UserToken()
+    userToken: StudentUserToken,
+    @Body()
+    payload: StudentApplicationOfferingChangeRequestAPIInDTO,
+  ): Promise<void> {
+    const applicationOfferingChangeRequest =
+      await this.applicationOfferingChangeRequestService.applicationOfferingChangeRequestExists(
+        applicationOfferingChangeRequestId,
+        {
+          applicationOfferingChangeRequestStatus:
+            ApplicationOfferingChangeRequestStatus.InProgressWithStudent,
+          studentId: userToken.studentId,
+        },
+      );
+    if (!applicationOfferingChangeRequest) {
+      throw new NotFoundException(
+        "Application offering change not found or not in valid status to be updated.",
+      );
+    }
+    if (
+      !(
+        payload.applicationOfferingChangeRequestStatus ===
+          ApplicationOfferingChangeRequestStatus.InProgressWithSABC ||
+        payload.applicationOfferingChangeRequestStatus ===
+          ApplicationOfferingChangeRequestStatus.DeclinedByStudent
+      )
+    ) {
+      throw new UnprocessableEntityException(
+        "Invalid application offering change request status.",
+      );
+    }
+    if (
+      payload.applicationOfferingChangeRequestStatus ===
+        ApplicationOfferingChangeRequestStatus.InProgressWithSABC &&
+      !payload.studentConsent
+    ) {
+      throw new UnprocessableEntityException(
+        "Student consent is required to update the application offering change request status.",
+      );
+    }
+    await this.applicationOfferingChangeRequestService.updateApplicationOfferingChangeRequest(
+      applicationOfferingChangeRequestId,
+      payload.applicationOfferingChangeRequestStatus,
+      payload.studentConsent,
+    );
+  }
+}