diff --git a/app/controllers/bulk_upload_lettings_logs_controller.rb b/app/controllers/bulk_upload_lettings_logs_controller.rb index 391651cde..9b37cd2b5 100644 --- a/app/controllers/bulk_upload_lettings_logs_controller.rb +++ b/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 diff --git a/app/controllers/bulk_upload_sales_logs_controller.rb b/app/controllers/bulk_upload_sales_logs_controller.rb index 5f9b8d9a6..2b3432399 100644 --- a/app/controllers/bulk_upload_sales_logs_controller.rb +++ b/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 diff --git a/app/models/forms/bulk_upload_lettings/prepare_your_file.rb b/app/models/forms/bulk_upload_lettings/prepare_your_file.rb index 5bfc0a2aa..bfaa622b2 100644 --- a/app/models/forms/bulk_upload_lettings/prepare_your_file.rb +++ b/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 diff --git a/app/models/forms/bulk_upload_sales/prepare_your_file.rb b/app/models/forms/bulk_upload_sales/prepare_your_file.rb index 5c7e775ef..52d70a85c 100644 --- a/app/models/forms/bulk_upload_sales/prepare_your_file.rb +++ b/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 diff --git a/app/views/bulk_upload_lettings_logs/forms/prepare_your_file.html.erb b/app/views/bulk_upload_lettings_logs/forms/prepare_your_file.html.erb index 199d87e5f..e48a190f9 100644 --- a/app/views/bulk_upload_lettings_logs/forms/prepare_your_file.html.erb +++ b/app/views/bulk_upload_lettings_logs/forms/prepare_your_file.html.erb @@ -13,7 +13,7 @@

Create your file

diff --git a/app/views/bulk_upload_sales_logs/forms/prepare_your_file.html.erb b/app/views/bulk_upload_sales_logs/forms/prepare_your_file.html.erb index 0157b66eb..d2a6bd70c 100644 --- a/app/views/bulk_upload_sales_logs/forms/prepare_your_file.html.erb +++ b/app/views/bulk_upload_sales_logs/forms/prepare_your_file.html.erb @@ -13,7 +13,7 @@

Create your file

diff --git a/app/views/bulk_upload_shared/guidance.html.erb b/app/views/bulk_upload_shared/guidance.html.erb new file mode 100644 index 000000000..0c1f67bcc --- /dev/null +++ b/app/views/bulk_upload_shared/guidance.html.erb @@ -0,0 +1,52 @@ +<% content_for :before_content do %> + <%= govuk_back_link href: :back %> +<% end %> + +
+
+ +

How to upload logs in bulk

+ +
+

Uploading sales and lettings logs

+

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.

+

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.

+ <%= 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" %> +
+ +
+

Creating your CSV files

+

To bulk upload successfully, all spreadsheets must be in the correct CSV format.

+

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.

+ <%= govuk_details(summary_text: "More about CSV") do %> +

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.

+

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.

+ <% end %> +
+ +
+

Exporting CSV data

+

Export CSV data directly from your current systems, or export then adjust it to CSV.

+

You can then upload it via a button at the top of the lettings and sales logs pages.

+ <%= govuk_details(summary_text: "My organisation has a CMS") do %> +

Some HMS providers sell an add-on "eCORE" module, which exports CSV data for you.

+

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.

+ <% end %> + <%= govuk_details(summary_text: "My organisation does not have a CMS") do %> +

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:

+
    +
  • required fields
  • +
  • each field's valid response
  • +
  • if/when certain fields can be left blank
  • +
+

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.

+ <% end %> +
+ +
+

Getting help

+

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.

+

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.

+
+
+
diff --git a/config/routes.rb b/config/routes.rb index 74b613989..02a9cb707 100644 --- a/config/routes.rb +++ b/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 diff --git a/public/files/bulk-upload-lettings-specification-2022-23.xlsx b/public/files/bulk-upload-lettings-specification-2022-23.xlsx new file mode 100644 index 000000000..15cec38b6 Binary files /dev/null and b/public/files/bulk-upload-lettings-specification-2022-23.xlsx differ diff --git a/public/files/bulk-upload-sales-specification-2022-23.xlsx b/public/files/bulk-upload-sales-specification-2022-23.xlsx new file mode 100644 index 000000000..b1e825fbb Binary files /dev/null and b/public/files/bulk-upload-sales-specification-2022-23.xlsx differ diff --git a/spec/requests/bulk_upload_lettings_logs_controller_spec.rb b/spec/requests/bulk_upload_lettings_logs_controller_spec.rb index fc27ed0d1..b915b571c 100644 --- a/spec/requests/bulk_upload_lettings_logs_controller_spec.rb +++ b/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 diff --git a/spec/requests/bulk_upload_sales_logs_controller_spec.rb b/spec/requests/bulk_upload_sales_logs_controller_spec.rb index 348179dd2..3e2aa5910 100644 --- a/spec/requests/bulk_upload_sales_logs_controller_spec.rb +++ b/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