CLDC-1788 Add bulk upload guidance page (#1335)

* feat: add new guidance page with corresponding template links for sales and lettings log

* feat: add specification files and links for sales/lettings

* refactor: tidying

* feat: change pseudo csv to xlsx to reflect reality

* feat: add tests for guidance page routing and content

* feat: add tests for lettings too

app/controllers/bulk_upload_lettings_logs_controller.rb

@@ -21,6 +21,11 @@ class BulkUploadLettingsLogsController < ApplicationController
     end
   end
 
+  def guidance
+    @form = Forms::BulkUploadLettings::PrepareYourFile.new
+    render "bulk_upload_shared/guidance"
+  end
+
 private
 
   def current_year

app/controllers/bulk_upload_sales_logs_controller.rb

@@ -21,6 +21,11 @@ class BulkUploadSalesLogsController < ApplicationController
     end
   end
 
+  def guidance
+    @form = Forms::BulkUploadSales::PrepareYourFile.new
+    render "bulk_upload_shared/guidance"
+  end
+
 private
 
   def current_year

app/models/forms/bulk_upload_lettings/prepare_your_file.rb

@@ -29,6 +29,10 @@ module Forms
         "/files/bulk-upload-lettings-template-v1.xlsx"
       end
 
+      def specification_path
+        "/files/bulk-upload-lettings-specification-2022-23.xlsx"
+      end
+
       def year_combo
         "#{year}/#{year + 1 - 2000}"
       end

app/models/forms/bulk_upload_sales/prepare_your_file.rb

@@ -27,6 +27,10 @@ module Forms
         "/files/bulk-upload-sales-template-v1.xlsx"
       end
 
+      def specification_path
+        "/files/bulk-upload-sales-specification-2022-23.xlsx"
+      end
+
       def year_combo
         "#{year}/#{year + 1 - 2000}"
       end

app/views/bulk_upload_lettings_logs/forms/prepare_your_file.html.erb

@@ -13,7 +13,7 @@
       <h2 class="govuk-heading-m">Create your file</h2>
       <ul class="govuk-list govuk-list--bullet">
         <li>Download the <%= govuk_link_to "bulk lettings template", @form.template_path %></li>
-        <li>Export the data from your housing management system, matching the template</li>
+        <li>Export the data from your housing management system, matching the template. <%= govuk_link_to "Find out more about exporting your data", guidance_bulk_upload_lettings_logs_path %></li>
         <li>If you cannot export it in this format, you may have to input it manually</li>
         <li>You can not have a file with both general needs logs and supported housing logs. These must be in separate files</li>
       </ul>

app/views/bulk_upload_sales_logs/forms/prepare_your_file.html.erb

@@ -13,7 +13,7 @@
       <h2 class="govuk-heading-m">Create your file</h2>
       <ul class="govuk-list govuk-list--bullet">
         <li>Download the <%= govuk_link_to "bulk sales template", @form.template_path %></li>
-        <li>Export the data from your housing management system, matching the template</li>
+        <li>Export the data from your housing management system, matching the template. <%= govuk_link_to "Find out more about exporting your data", guidance_bulk_upload_sales_logs_path %></li>
         <li>If you cannot export it in this format, you may have to input it manually</li>
       </ul>
 

app/views/bulk_upload_shared/guidance.html.erb

@@ -0,0 +1,52 @@
+<% content_for :before_content do %>
+  <%= govuk_back_link href: :back %>
+<% end %>
+
+<div class="govuk-grid-row">
+  <div class="govuk-grid-column-two-thirds">
+
+    <h1 class="govuk-heading-l">How to upload logs in bulk</h1>
+
+    <div class="govuk-!-padding-bottom-4">
+      <h2 class="govuk-heading-s">Uploading sales and lettings logs</h2>
+      <p class="govuk-body">You can upload one sales or lettings log at a time, or many at once (known as ‘bulk upload’) with a comma-separated values (CSV) spreadsheet file.</p>
+      <p class="govuk-body">Bulk upload may be easier if your organisation deals with many logs, or if you can export CSV data from your Housing Management System (HMS). If your organisation only deals with a small amount of logs, or you cannot export CSV data, it’s probably easier to enter logs individually.</p>
+      <%= govuk_warning_text text: "You cannot upload lettings and sales logs with the same template - you must export each data type separately, then upload them" %>
+    </div>
+
+    <div class="govuk-!-padding-bottom-4">
+      <h2 class="govuk-heading-s">Creating your CSV files</h2>
+      <p class="govuk-body">To bulk upload successfully, all spreadsheets must be in the correct CSV format.</p>
+      <p class="govuk-body">In most programs, you must resave files as CSV - it’s not usually the default setting. CSV files are also unformatted, so any formatting added before saving (for example colours) will automatically disappear.</p>
+      <%= govuk_details(summary_text: "More about CSV") do %>
+        <p class="govuk-body">A CSV file is a basic spreadsheet with data values in plain text, and columns separated by commas. Each data row is a new text line.</p>
+        <p class="govuk-body">CSV data is easier to process than more common advanced spreadsheet formats, for example Excel. It means CSV is well suited to upload large, or multiple data sets.</p>
+      <% end %>
+    </div>
+
+    <div class="govuk-!-padding-bottom-4">
+      <h2 class="govuk-heading-s">Exporting CSV data</h2>
+      <p class="govuk-body">Export CSV data directly from your current systems, or export then adjust it to CSV.</p>
+      <p class="govuk-body">You can then upload it via a button at the top of the lettings and sales logs pages.</p>
+      <%= govuk_details(summary_text: "My organisation has a CMS") do %>
+        <p class="govuk-body">Some HMS providers sell an add-on "eCORE" module, which exports CSV data for you.</p>
+        <p class="govuk-!-font-weight-bold">It can take HMS providers a while to update these per new collection year, so you may have to wait for updates to export, or adjust your data manually post-export.</p>
+      <% end %>
+      <%= govuk_details(summary_text: "My organisation does not have a CMS") do %>
+        <p class="govuk-body">Your organisation’s IT team may be able to export CSV data for you - <%= govuk_link_to "find out more about data specification", @form.specification_path %>. This document outlines:</p>
+        <ul class="govuk-list govuk-list--bullet">
+          <li>required fields</li>
+          <li>each field's valid response</li>
+          <li>if/when certain fields can be left blank</li>
+        </ul>
+        <p class="govuk-body">Fields can appear in any order, as long as you include the <%= govuk_link_to "template document", @form.template_path %> headers, to easily identify what each column represents. You can rearrange data columns to match your system exports, copy-pasting multiple columns at once. For data stored in multiple systems, you can copy-paste all columns for one system next to each other, repeating this for subsequent system exports.</p>
+      <% end %>
+    </div>
+
+    <div class="govuk-!-padding-bottom-4">
+      <h2 class="govuk-heading-s">Getting help</h2>
+      <p class="govuk-body">There is no step-by-step bulk upload guide like there is with single log upload. However, you can download <%= govuk_link_to "our template", @form.template_path %>, which you can copy-paste data into from your systems column-by-column. You can also view a post-upload report showing any data errors, and our <%= govuk_link_to "data specification", @form.specification_path %> can help fix these.</p>
+      <p class="govuk-body">If you still need support mapping data in the way we need, DLUHC’s helpdesk can help. If your data is across multiple systems, or is hard to export as a single file in the correct format, you could try different exports, or copy-pasting data by hand.</p>
+    </div>
+  </div>
+</div>

config/routes.rb

@@ -131,6 +131,7 @@ Rails.application.routes.draw do
       resources :bulk_upload_lettings_logs, path: "bulk-upload-logs", only: %i[show update] do
         collection do
           get :start
+          get "guidance", to: "bulk_upload_lettings_logs#guidance"
         end
       end
 
@@ -165,6 +166,7 @@ Rails.application.routes.draw do
       resources :bulk_upload_sales_logs, path: "bulk-upload-logs" do
         collection do
           get :start
+          get "guidance", to: "bulk_upload_sales_logs#guidance"
         end
       end
 

spec/requests/bulk_upload_lettings_logs_controller_spec.rb

@@ -31,4 +31,28 @@ RSpec.describe BulkUploadLettingsLogsController, type: :request do
       end
     end
   end
+
+  describe "GET /lettings-logs/bulk-upload-logs/guidance" do
+    context "when not in crossover period" do
+      let(:expected_year) { FormHandler.instance.forms["current_lettings"].start_date.year }
+
+      it "shows guidance page with correct title" do
+        Timecop.freeze(2022, 1, 1) do
+          get "/lettings-logs/bulk-upload-logs/guidance", params: {}
+
+          expect(response.body).to include("How to upload logs in bulk")
+        end
+      end
+    end
+
+    context "when in crossover period" do
+      it "shows guidance page with correct title" do
+        Timecop.freeze(2023, 6, 1) do
+          get "/lettings-logs/bulk-upload-logs/guidance", params: {}
+
+          expect(response.body).to include("How to upload logs in bulk")
+        end
+      end
+    end
+  end
 end

spec/requests/bulk_upload_sales_logs_controller_spec.rb

@@ -31,4 +31,28 @@ RSpec.describe BulkUploadSalesLogsController, type: :request do
       end
     end
   end
+
+  describe "GET /sales-logs/bulk-upload-logs/guidance" do
+    context "when not in crossover period" do
+      let(:expected_year) { FormHandler.instance.forms["current_sales"].start_date.year }
+
+      it "shows guidance page with correct title" do
+        Timecop.freeze(2022, 1, 1) do
+          get "/sales-logs/bulk-upload-logs/guidance", params: {}
+
+          expect(response.body).to include("How to upload logs in bulk")
+        end
+      end
+    end
+
+    context "when in crossover period" do
+      it "shows guidance page with correct title" do
+        Timecop.freeze(2023, 6, 1) do
+          get "/sales-logs/bulk-upload-logs/guidance", params: {}
+
+          expect(response.body).to include("How to upload logs in bulk")
+        end
+      end
+    end
+  end
 end