#2111-UI format validation bulk withdrawal upload

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

@@ -28,6 +28,7 @@ import {
   ApplicationExceptionService,
   StudentAppealRequestsService,
   ApplicationOfferingChangeRequestService,
+  ApplicationWithdrawalImportTextService,
 } from "./services";
 import {
   ApplicationControllerService,
@@ -162,6 +163,7 @@ import {
     ApplicationExceptionControllerService,
     StudentAppealControllerService,
     ApplicationOfferingChangeRequestService,
+    ApplicationWithdrawalImportTextService,
   ],
 })
 export class AppInstitutionsModule {}

sources/packages/backend/apps/api/src/constants/error-code.constants.ts

@@ -136,3 +136,17 @@ export const OFFERING_PROGRAM_YEAR_MISMATCH = "OFFERING_PROGRAM_YEAR_MISMATCH";
  */
 export const OFFERING_DOES_NOT_BELONG_TO_LOCATION =
   "OFFERING_DOES_NOT_BELONG_TO_LOCATION";
+/**
+ * The text content to perform the application withdrawal is not in the
+ * expected format and cannot be parsed.
+ */
+export const APPLICATION_WITHDRAWAL_TEXT_CONTENT_FORMAT_ERROR =
+  "APPLICATION_WITHDRAWAL_TEXT_CONTENT_FORMAT_ERROR";
+/**
+ * The text content has invalid content, either
+ * 1. Invalid Header record type.
+ * 2. Invalid Footer record type.
+ * 3. Number of records in the footer does not match the no of data records.
+ */
+export const APPLICATION_WITHDRAWAL_INVALID_TEXT_FILE_ERROR =
+  "APPLICATION_WITHDRAWAL_INVALID_TEXT_FILE_ERROR";

sources/packages/backend/apps/api/src/route-controllers/education-program-offering/models/education-program-offering.dto.ts

@@ -9,10 +9,9 @@ import { Allow, IsEnum, IsIn, IsNotEmpty, MaxLength } from "class-validator";
 import { Type } from "class-transformer";
 import {
   OfferingDeliveryOptions,
-  OfferingValidationInfos,
-  OfferingValidationWarnings,
   WILComponentOptions,
 } from "../../../services";
+import { ValidationResultAPIOutDTO } from "../../models/common.dto";
 
 export class StudyBreakAPIOutDTO {
   breakStartDate: string;
@@ -230,14 +229,3 @@ export class OfferingBulkInsertValidationResultAPIOutDTO {
   infos: ValidationResultAPIOutDTO[];
   warnings: ValidationResultAPIOutDTO[];
 }
-
-/**
- * Represents an error considered not critical for
- * an offering and provides a user-friendly message
- * and a type that uniquely identifies this warning
- * or info.
- */
-export class ValidationResultAPIOutDTO {
-  typeCode: OfferingValidationWarnings | OfferingValidationInfos;
-  message: string;
-}

sources/packages/backend/apps/api/src/route-controllers/models/common.dto.ts

@@ -1,5 +1,9 @@
 import { IsNotEmpty, IsOptional, ValidateIf } from "class-validator";
 import { COUNTRY_CANADA, OTHER_COUNTRY } from "../utils/address-utils";
+import {
+  OfferingValidationInfos,
+  OfferingValidationWarnings,
+} from "../../services";
 
 /**
  * Common DTO for Address.
@@ -111,3 +115,15 @@ export class FileCreateAPIOutDTO {
   size: number;
   mimetype: string;
 }
+
+/**
+ * Represents an error considered not critical for
+ * an offering or application withdrawal
+ * and provides an user-friendly message
+ * and a type that uniquely identifies this warning
+ * or info.
+ */
+export class ValidationResultAPIOutDTO {
+  typeCode: OfferingValidationWarnings | OfferingValidationInfos | string;
+  message: string;
+}

sources/packages/backend/apps/api/src/route-controllers/student-scholastic-standings/models/student-scholastic-standings.dto.ts

@@ -4,6 +4,7 @@ import { IsNotEmptyObject } from "class-validator";
 import { ActiveApplicationDataAPIOutDTO } from "../../../route-controllers/institution-locations/models/application.dto";
 import { JSON_10KB } from "../../../constants";
 import { StudentScholasticStandingChangeType } from "@sims/sims-db";
+import { ValidationResultAPIOutDTO } from "../../models/common.dto";
 
 /**
  * The API will also allow other properties that are not added below.
@@ -35,3 +36,18 @@ export class ScholasticStandingSubmittedDetailsAPIOutDTO extends IntersectionTyp
   ScholasticStandingData,
   ActiveApplicationDataAPIOutDTO,
 ) {}
+
+/**
+ * Represents the possible errors that can happen during the
+ * application bulk withdrawal and provides a detailed description
+ * for every record that has an error.
+ */
+export interface ApplicationBulkWithdrawalValidationResultAPIOutDTO {
+  recordIndex: number;
+  sin?: string;
+  applicationNumber?: string;
+  withdrawalDate?: Date;
+  errors: string[];
+  infos: ValidationResultAPIOutDTO[];
+  warnings: ValidationResultAPIOutDTO[];
+}

sources/packages/backend/apps/api/src/route-controllers/student-scholastic-standings/student-scholastic-standings.controller.service.ts

@@ -1,7 +1,17 @@
-import { Injectable, NotFoundException } from "@nestjs/common";
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from "@nestjs/common";
 import { StudentScholasticStandingsService } from "../../services";
-import { ScholasticStandingSubmittedDetailsAPIOutDTO } from "./models/student-scholastic-standings.dto";
+import {
+  ApplicationBulkWithdrawalValidationResultAPIOutDTO,
+  ScholasticStandingSubmittedDetailsAPIOutDTO,
+} from "./models/student-scholastic-standings.dto";
 import { transformToActiveApplicationDataAPIOutDTO } from "../institution-locations/models/application.dto";
+import { ApiProcessError } from "../../types";
+import { APPLICATION_WITHDRAWAL_TEXT_CONTENT_FORMAT_ERROR } from "../../constants";
+import { ApplicationWithdrawalTextValidationResult } from "../../services/application-bulk-withdrawal/application-bulk-withdrawal-text.models";
 
 /**
  * Scholastic standing controller service.
@@ -40,4 +50,36 @@ export class ScholasticStandingControllerService {
       ...transformToActiveApplicationDataAPIOutDTO(application, offering),
     };
   }
+  /**
+   * Verify if all text file validations were performed with success and throw
+   * a BadRequestException in case of some failure.
+   * @param textValidations validations to be verified.
+   */
+  assertTextValidationsAreValid(
+    textValidations: ApplicationWithdrawalTextValidationResult[],
+  ) {
+    const textValidationsErrors = textValidations.filter(
+      (textValidation) => textValidation.errors.length,
+    );
+    if (textValidationsErrors.length) {
+      // At least one error was detected and the text must be fixed.
+      const validationResults: ApplicationBulkWithdrawalValidationResultAPIOutDTO[] =
+        textValidationsErrors.map((validation) => ({
+          recordIndex: validation.index,
+          sin: validation.textModel.sin,
+          applicationNumber: validation.textModel.applicationNumber,
+          withdrawalDate: validation.textModel.withdrawalDate,
+          errors: validation.errors,
+          infos: [],
+          warnings: [],
+        }));
+      throw new BadRequestException(
+        new ApiProcessError(
+          "One or more text data fields received are not in the correct format.",
+          APPLICATION_WITHDRAWAL_TEXT_CONTENT_FORMAT_ERROR,
+          validationResults,
+        ),
+      );
+    }
+  }
 }

sources/packages/backend/apps/api/src/route-controllers/student-scholastic-standings/student-scholastic-standings.institutions.controller.ts

@@ -2,11 +2,16 @@ import {
   BadRequestException,
   Body,
   Controller,
+  DefaultValuePipe,
   Get,
   Param,
+  ParseBoolPipe,
   ParseIntPipe,
   Post,
+  Query,
   UnprocessableEntityException,
+  UploadedFile,
+  UseInterceptors,
 } from "@nestjs/common";
 import {
   ApiBadRequestResponse,
@@ -19,11 +24,13 @@ import { IInstitutionUserToken } from "../../auth/userToken.interface";
 import {
   AllowAuthorizedParty,
   HasLocationAccess,
+  IsInstitutionAdmin,
   UserToken,
 } from "../../auth/decorators";
 import {
   APPLICATION_NOT_FOUND,
   ASSESSMENT_ALREADY_IN_PROGRESS,
+  ApplicationWithdrawalImportTextService,
   FormService,
   INVALID_OPERATION_IN_THE_CURRENT_STATUS,
   StudentAssessmentService,
@@ -33,13 +40,26 @@ import { ApiProcessError, ClientTypeBaseRoute } from "../../types";
 import { CustomNamedError } from "@sims/utilities";
 import BaseController from "../BaseController";
 import { FormNames } from "../../services/form/constants";
-import { APPLICATION_CHANGE_NOT_ELIGIBLE } from "../../constants";
+import {
+  APPLICATION_CHANGE_NOT_ELIGIBLE,
+  APPLICATION_WITHDRAWAL_INVALID_TEXT_FILE_ERROR,
+} from "../../constants";
 import {
   ScholasticStandingAPIInDTO,
   ScholasticStandingSubmittedDetailsAPIOutDTO,
 } from "./models/student-scholastic-standings.dto";
 import { ScholasticStandingControllerService } from "./student-scholastic-standings.controller.service";
 import { ScholasticStanding } from "../../services/student-scholastic-standings/student-scholastic-standings.model";
+import { FileInterceptor } from "@nestjs/platform-express";
+import {
+  APPLICATION_BULK_WITHDRAWAL_MAX_UPLOAD_PARTS,
+  APPLICATION_BULK_WITHDRAWAL_UPLOAD_MAX_FILE_SIZE,
+  MAX_UPLOAD_FILES,
+  textFileFilter,
+  uploadLimits,
+} from "../../utilities";
+import { PrimaryIdentifierAPIOutDTO } from "../models/primary.identifier.dto";
+import { ApplicationWithdrawalTextModel } from "../../services/application-bulk-withdrawal/application-bulk-withdrawal-text.models";
 
 /**
  * Scholastic standing controller for institutions Client.
@@ -53,6 +73,7 @@ export class ScholasticStandingInstitutionsController extends BaseController {
     private readonly studentScholasticStandingsService: StudentScholasticStandingsService,
     private readonly studentAssessmentService: StudentAssessmentService,
     private readonly scholasticStandingControllerService: ScholasticStandingControllerService,
+    private readonly applicationWithdrawalImportTextService: ApplicationWithdrawalImportTextService,
   ) {
     super();
   }
@@ -139,4 +160,83 @@ export class ScholasticStandingInstitutionsController extends BaseController {
       userToken.authorizations.getLocationsIds(),
     );
   }
+  /**
+   * Process a text file with application to be withdrawn.
+   * @param file text file content with all information needed to withdraw application.
+   * @param validationOnly if true, will execute all validations and return the
+   * errors and warnings. These validations are the same executed during the
+   * final creation process. If not present or false, the file will be processed
+   * and the records will be inserted.
+   * @returns when successfully executed, the list of all withdrawn application ids.
+   * When an error happen it will return all the records (with the error) and
+   * also a user friendly description of the errors to be fixed.
+   */
+  @ApiBadRequestResponse({
+    description:
+      "Error while parsing text file or " +
+      "one or more text data fields received are not in the correct format or " +
+      "there are no records to be imported.",
+  })
+  @ApiUnprocessableEntityResponse({
+    description:
+      "Application withdrawal has invalid data or " +
+      "some error happen with one or more application withdrawal and the entire process was aborted.",
+  })
+  @IsInstitutionAdmin()
+  @Post("application-bulk-withdrawal")
+  @UseInterceptors(
+    FileInterceptor("file", {
+      limits: uploadLimits(
+        MAX_UPLOAD_FILES,
+        APPLICATION_BULK_WITHDRAWAL_MAX_UPLOAD_PARTS,
+        APPLICATION_BULK_WITHDRAWAL_UPLOAD_MAX_FILE_SIZE,
+      ),
+      fileFilter: textFileFilter,
+    }),
+  )
+  async bulkWithdrawal(
+    @UploadedFile() file: Express.Multer.File,
+    @Query("validation-only", new DefaultValuePipe(false), ParseBoolPipe)
+    validationOnly: boolean,
+  ): Promise<PrimaryIdentifierAPIOutDTO[]> {
+    // Read the entire file content.
+    const fileContent = file.buffer.toString();
+    // Convert the file raw content into text models.
+    let textModels: ApplicationWithdrawalTextModel[];
+    try {
+      textModels =
+        this.applicationWithdrawalImportTextService.readText(fileContent);
+    } catch (error: unknown) {
+      let errorMessage = "Error while parsing text file.";
+      if (
+        error instanceof CustomNamedError &&
+        error.name === APPLICATION_WITHDRAWAL_INVALID_TEXT_FILE_ERROR
+      ) {
+        errorMessage = error.message;
+      }
+      throw new BadRequestException(
+        new ApiProcessError(
+          errorMessage,
+          APPLICATION_WITHDRAWAL_INVALID_TEXT_FILE_ERROR,
+        ),
+      );
+    }
+    // Validate the text models.
+    const textValidations =
+      this.applicationWithdrawalImportTextService.validateTextModels(
+        textModels,
+      );
+    // Assert successful validation.
+    this.scholasticStandingControllerService.assertTextValidationsAreValid(
+      textValidations,
+    );
+
+    if (validationOnly) {
+      // If the endpoint is called only to perform the validation and no error was found
+      // return an empty array because no record will be created.
+      return [];
+    }
+
+    // TODO create a block to do database updates for Application withdrawal.
+  }
 }