From ba449913a7921d875de4319acf7a9cacb1c667c9 Mon Sep 17 00:00:00 2001
From: fumimowdan <tecknuovo@zemis.co.uk>
Date: Mon, 4 Dec 2023 16:55:06 +0000
Subject: [PATCH] Extra documentation

* Report Template

* Form analytics
---
 docs/form_funnel.md     | 10 ++++++
 docs/report-template.md | 75 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 docs/form_funnel.md
 create mode 100644 docs/report-template.md

diff --git a/docs/form_funnel.md b/docs/form_funnel.md
new file mode 100644
index 00000000..e4e4a031
--- /dev/null
+++ b/docs/form_funnel.md
@@ -0,0 +1,10 @@
+# Form Funnel Analytics
+
+## Description
+This feature captures form events when a form step is submitted and later analyzes them to gather information.
+
+## Events
+An event is tracked when an instance of a model is created, updated, or deleted, including any changes made to the model's fields. Certain fields can be filtered out using the `config/events/filtered_attributes.yml` file.
+
+## Form Funnel Query
+The `FormsFunnelQuery` class builds a hash representation of the funnel for eligible and ineligible forms. This is achieved by iterating over the registered steps in `StepFlow` and counting the number of forms grouped by eligibility.
diff --git a/docs/report-template.md b/docs/report-template.md
new file mode 100644
index 00000000..41f77f36
--- /dev/null
+++ b/docs/report-template.md
@@ -0,0 +1,75 @@
+# Report Template
+
+## Description
+The report template model captures information on how to use a saved template. It includes the file name, file payload, the report that can use the template, and its configuration.
+
+## Home Office Excel
+For Reports::HomeOfficeExcel, the configuration is a hash data containing the following keys:
+- `worksheet_name`: identifies the name of the sheet in the Excel file to save the report output.
+- `header_mapping`: a hash mapping the template column name to the application fields to be extracted. Each key is a column in the Excel file, and the value is an array of application fields.
+
+If the array of application fields contains more than one field, the output is concatenated using the SQL CONCAT function.
+
+### Validation
+The ReportTemplate model uses the HomeOfficeReportConfigValidator to perform basic checks on the report template file. These checks include:
+- Parsing the Excel file.
+- Verifying the existence of a worksheet name specified in the configuration.
+- Checking the presence of the `header_mapping` in the configuration.
+
+### Usage
+#### Adding a template
+To add a report template, follow these steps:
+
+1. Create a `report_template_seed.rb` file, assuming you have an Excel file ready at `./tmp/template.xlsx` and you are in the Rails console. The Excel file should have a sheet named `sheet2`, and the first row of that sheet should contain the columns: `Id`, `fullname`, and `field 1`.
+
+```ruby
+template_path = Rails.root.join('tmp/template.xlsx')
+template = File.open(template_path)
+configuration = {
+  worksheet_name: "sheet2",
+  header_mapping: {
+    "Id" => ["reference"],
+    "fullname" => ["first_name", "last_name"],
+    "field 1" => ["relations.field_1"],
+  },
+}
+
+report_template = ReportTemplate.new(
+  filename: "template.xlsx",
+  file: file,
+  config: configuration,
+  report_class: Reports::HomeOffice
+)
+
+if report_template.valid?
+open(Rails.root.join('db/report_template.rb', 'w')) do |f|
+  f.write("ReportTemplate.create(#{report_template.attributes})")
+end
+else
+  report_template.errors
+end
+```
+
+2. Copy the seed file to the environment:
+
+```sh
+$ kubectl -n <namespace> cp db/report_template_seed.rb <pod-id>:/app/db/report_template_seed.rb
+$ make <environment> ssh
+$ rails c
+```
+
+3. Load the seed file:
+
+```ruby
+load(Rails.root.join('db/report_template_seed.rb')
+```
+
+#### Updating a template
+To update a template, follow these steps:
+
+1. Identify the previous report template.
+2. Create a backup seed file.
+3. Reproduce the steps for "Adding a template".
+4. Delete the previous report template.
+
+If an error occurs, rollback the report template using the backup seed file.