Merge pull request #2776 from ministryofjustice/APS-1750-add-excel-se…

…ed-jobs-to-how-to

APS-1750 Add Excel jobs to how-to and add example files.

doc/how-to/run_seed_job_remotely.md

@@ -2,20 +2,20 @@
 
 ## Run book
 
-To process a seed CSV against a non-local environment:
+To process a seed file against a non-local environment:
 
 - Ensure nobody is deploying a change (or is going to deploy a change shortly.)
 - Change into the 'script' directory in this project
-- Upload the CSV file to the target environments
+- Upload the file (.csv or .xlsx) to the target environments
 
   ```shell
-  ./pod_upload_seed_file preprod /path/to/my_csv.csv
+  ./pod_upload_seed_file preprod /path/to/my_file(.csv|.xlsx)
   ```
 
 - This will output confirmation and provide the name of the pod used e.g.
 
   ```shell
-  File uploaded to /tmp/seed/refresh_nat_users.csv on pod hmpps-approved-premises-api-69cf9df9b8-g4vp2
+  File uploaded to /tmp/seed/my_file(.csv|.xlsx) on pod hmpps-approved-premises-api-69cf9df9b8-g4vp2
   ```
 
 - Connect to the aforementioned pod 
@@ -26,6 +26,8 @@ To process a seed CSV against a non-local environment:
 
 - Run the helper script from within the container to trigger the seed job:
 
+For CSV files:
+
   ```shell
   /app/run_seed_job {seed type} {file name}
   ```
@@ -36,6 +38,18 @@ To process a seed CSV against a non-local environment:
   /app/run_seed_job approved_premises ap_seed_file
   ```
 
+For XLSX files:
+
+  ```shell
+  /app/run_seed_from_excel_job {seed type} {file name}
+  ```
+
+- `seed type` is a value from the [`SeedFromExcelFileType`](https://github.com/ministryofjustice/hmpps-approved-premises-api/blob/9a9ad8df7b8015f63799f191fc986e47900325be/src/main/resources/static/_shared.yml#L3730) enum in the OpenAPI spec.  e.g.
+
+  ```shell 
+  /app/run_seed_from_excel_job cas1_import_site_survey_rooms ap_seed_file
+  ```
+
 - Check the logs using [Azure Application Insights](https://dsdmoj.atlassian.net/wiki/spaces/AP/pages/4154196024/Viewing+and+Tailing+Kubernetes+logs) to see how processing is progressing. The following query will provide seed traces and exceptions only:
   ```
   union traces, exceptions
@@ -46,102 +60,3 @@ To process a seed CSV against a non-local environment:
 ## Local Seeding
 
 For seeding in a local development environment use ./script/run_seed_job
-
-## CSV reference
-
-### User seed job
-
-Required fields:
-
-- `deliusUsername`
-- `roles`
-- `qualifications`
-
-[Example CSV](./example_csvs/user_seeding_example.csv)
-
-### Approved Premises seed job
-
-Required fields:
-
-- `apCode`
-- `qCode`
-- `apArea`
-- `pdu`
-- `probationRegion`
-- `localAuthorityArea`
-- `town`
-- `addressLine1`
-- `addressLine2`
-- `postcode`
-- `latitude`
-- `longitude`
-- `maleOrFemale`
-- `totalBeds`
-- `status`
-- `isIAP`
-- `isPIPE`
-- `isESAP`
-- `isSemiSpecialistMentalHealth`
-- `isRecoveryFocussed`
-- `isSuitableForVulnerable`
-- `acceptsSexOffenders`
-- `acceptsChildSexOffenders`
-- `acceptsNonSexualChildOffenders`
-- `acceptsHateCrimeOffenders`
-- `isCatered`
-- `hasWideStepFreeAccess`
-- `hasWideAccessToCommunalAreas`
-- `hasStepFreeAccessToCommunalAreas`
-- `hasWheelChairAccessibleBathrooms`
-- `hasLift`
-- `hasTactileFlooring`
-- `hasBrailleSignage`
-- `hasHearingLoop`
-- `notes`
-- `emailAddress`
-
-[Example CSV](./example_csvs/approved_premises_seeding_example.csv)
-
-### Approved Premises rooms and beds job
-
-"seed type": `approved_premises_rooms`
-
-Required fields:
-
-- `apCode`
-- `bedCode`
-- `roomNumber`
-- `bedCount`
-- `isSingle`
-- `isGroundFloor`
-- `isFullyFm`
-- `hasCrib7Bedding`
-- `hasSmokeDetector`
-- `isTopFloorVulnerable`
-- `isGroundFloorNrOffice`
-- `hasNearbySprinkler`
-- `isArsonSuitable`
-- `isArsonDesignated`
-- `hasArsonInsuranceConditions`
-- `isSuitedForSexOffenders`
-- `hasEnSuite`
-- `isWheelchairAccessible`
-- `hasWideDoor`
-- `hasStepFreeAccess`
-- `hasFixedMobilityAids`
-- `hasTurningSpace`
-- `hasCallForAssistance`
-- `isWheelchairDesignated`
-- `isStepFreeDesignated`
-- `notes`
-
-[Example CSV](./example_csvs/approved_premises_rooms_seeding_example.csv)
-
-### Approved Premises AP Area (CRU) Email Address Seed Job
-
-"seed type": `approved_premises_ap_area_email_addresses`
-
-Required fields:
-
-- `ap_area_identifier`
-- `email_address`

src/main/kotlin/uk/gov/justice/digital/hmpps/approvedpremisesapi/seed/cas1/Cas1SeedPremisesFromCsvJob.kt

@@ -19,6 +19,7 @@ import uk.gov.justice.digital.hmpps.approvedpremisesapi.seed.SeedJob
 import java.util.UUID
 
 @Component
+@Deprecated("Use Cas1SeedRoomsFromSiteSurveyXlsxJob instead")
 class Cas1SeedPremisesFromCsvJob(
   private val premisesRepository: PremisesRepository,
   private val probationRegionRepository: ProbationRegionRepository,

src/main/kotlin/uk/gov/justice/digital/hmpps/approvedpremisesapi/seed/cas1/Cas1SeedPremisesFromSiteSurveyXlsxJob.kt

@@ -23,6 +23,15 @@ import uk.gov.justice.digital.hmpps.approvedpremisesapi.seed.ExcelSeedJob
 import java.io.File
 import java.util.UUID
 
+/**
+ * This job seeds premises information from a site survey xlsx Excel file.
+ * The xlsx file should have two sheets:
+ *  Sheet2: Premises details
+ *  Sheet3: Room and bed characteristic details
+ *
+ * The job can be run by calling the run_seed_from_excel_job script with the following arguments:
+ *  ./script/run_seed_from_excel_job cas1_import_site_survey_premises 'site_survey_file.xlsx'
+ */
 @Component
 class Cas1SeedPremisesFromSiteSurveyXlsxJob(
   private val premisesRepository: ApprovedPremisesRepository,

src/main/kotlin/uk/gov/justice/digital/hmpps/approvedpremisesapi/seed/cas1/Cas1SeedRoomsFromCsvJob.kt

@@ -15,6 +15,7 @@ import java.time.OffsetDateTime
 import java.util.UUID
 
 @Component
+@Deprecated("Use Cas1SeedPremisesFromSiteSurveyXlsxJob instead")
 class ApprovedPremisesRoomsSeedJob(
   private val premisesRepository: PremisesRepository,
   private val roomRepository: RoomRepository,

src/main/kotlin/uk/gov/justice/digital/hmpps/approvedpremisesapi/seed/cas1/Cas1SeedRoomsFromSiteSurveyXlsxJob.kt

@@ -18,6 +18,15 @@ import kotlin.Boolean
 
 class SiteSurveyImportException(message: String) : Exception(message)
 
+/**
+ * This job seeds rooms and beds from a site survey xlsx Excel file.
+ * The xlsx file should have two sheets:
+ *  Sheet2: Premises details
+ *  Sheet3: Room and bed characteristic details
+ *
+ * The job can be run by calling the run_seed_from_excel_job script with the following arguments:
+ *  ./script/run_seed_from_excel_job cas1_import_site_survey_rooms 'site_survey_file.xlsx'
+ */
 @Component
 @Suppress("LongParameterList")
 class Cas1SeedRoomsFromSiteSurveyXlsxJob(