Merge pull request #32 from unicef/feature/aurora/231563

Author: domdinicola

docs/src/.pages

@@ -5,3 +5,5 @@ nav:
   - settings.md
   - dev_helpers.md
   - flows
+  - Interfaces: interfaces.md
+  - Import Data: import_data

docs/src/import_data/.pages

@@ -0,0 +1,4 @@
+nav:
+  - XLS: xls.md
+  - Aurora: aurora.md
+  - Kobo: kobo.md

docs/src/import_data/aurora.md

@@ -0,0 +1,43 @@
+# Import data from Aurora
+
+[Aurora](https://unicef.github.io/hope-aurora/) is the official online registration tool for HOPE. Developed in 2022 for the Ukraine emergency, it quickly became the de-facto standard for online registration in almost all the countries served online by UNICEF.
+
+---
+
+### Prerequisites
+
+1. Before using the system, ensure that the following variables
+```
+AURORA_API_URL
+AURORA_API_TOKEN
+```
+are defined in the Constance configuration within the [Admin Interface](../interfaces.md#admin-interface):
+```
+Home › Constance › Config > Remote System Tokens
+```
+
+2. Additionally, select the appropriate **checkers** for both **Households** and **Individuals** corresponding to the specific program.
+
+---
+
+### Processing
+
+To begin, in the [Collector Interface](../interfaces.md#collector-interface), navigate to the menu
+
+    Program
+
+menu, then press the **[Import Data]** button and select the **[Aurora]** tab. Here, you can configure the import settings:
+
+- **Batch Name** – Specify a custom batch name if needed.
+
+By default, will be used: *<"Batch " + the current datetime>*
+
+- **Registration** – Select the specific Aurora registration to import. If needed, [synchronize](../interfaces.md#synchronize-unified-classifiers) registrations before proceeding.
+- **Check Before** – Enable this option to prevent the import if errors are detected.
+- **Household Name Column** – Specify which Individual's column contains the Household's name.
+
+By default, this is set to *family_name*.
+
+- **Fail if Alien** – Enable this option to fail the import if any unexpected fields (not defined in the validator) are found.
+
+Once all settings are correctly configured, press **[Import]** to proceed or **[Close]** to cancel. After initiating the import, you will be redirected to the **Jobs** page, where you can track the progress and details of the import job.

docs/src/import_data/index.md

@@ -0,0 +1,3 @@
+# Import data
+
+To begin, in the [Collector Interface](../interfaces.md#collector-interface), navigate to the **Program** page , then press the **[Import Data]** button and select the corresponding tab. Follow the on-screen instructions to proceed.

docs/src/import_data/kobo.md

@@ -0,0 +1 @@
+# Import data from Kobo

docs/src/import_data/xls.md

@@ -0,0 +1 @@
+# Import data from XLS

docs/src/index.md

@@ -2,8 +2,7 @@
 title: Documentation
 ---
 
-
-[<img src="./img/hope_workspace.png" style="margin-left: auto;margin-right: auto;width:300px;display:block"/>](./docs/src/img/hope_workspace.png)
+[<img src="./img/hope_workspace.png" style="margin-left: auto;margin-right: auto;width:300px;display:block"/>](./img/hope_workspace.png)
 
 
 Hope Workspace is part of the  [UNICEF HOPE](https://github.com/unicef/hope) ecosystem and manages the data import and cleansing phase of the beneficiary
@@ -13,7 +12,7 @@ management process.
 
 ### Implemented Features
 
-- Import data from Kobo / Aurora / XLS (RDI format)
+- [Import data](import_data/index.md) from [Kobo](import_data/kobo.md) / [Aurora](import_data/aurora.md) / [XLS](import_data/xls.md) (RDI format)
 - Data validation
 - Data cleaning and updates
 - Push data to HOPE

docs/src/interfaces.md

@@ -0,0 +1,63 @@
+# Hope Workspace Interfaces
+
+Hope Workspace provides two interfaces for different roles:
+
+### **Collector Interface**
+
+The primary interface for data collection and processing, offering an enhanced user experience with additional workspace features.
+
+
+
+#### Households Page / Individuals Page
+
+Displays a list of households and individuals related to the selected program, with filtering options and the ability to validate the entire program.
+
+When selecting an item, you can view or edit the imported data by columns, make necessary corrections, and validate the data for the chosen entry to detect any potential issues.
+
+---
+
+#### Program page
+
+Provides complete information about the selected program, along with available actions accessible via buttons, including:
+
+??? abstract "[Household Columns]"
+    ##### **[Household Columns]**
+    Allows the user to configure mandatory columns for the Household Checker, which will be used with Household records.
+
+??? abstract "[Individual Columns]"
+    ##### **[Individual Columns]**
+    Allows the user to configure mandatory columns for the Individual Checker, which will be used with Individual records.
+
+??? abstract "[Update Records]"
+    ##### **[Update Records]**
+    Imports column updates from a file for either Household or Individual records.
+
+??? abstract "[Import data]"
+    ##### **[Import data]**
+    Import Household and Individual data from different sources to ensure seamless integration into the system. This process supports multiple data formats and validation steps to maintain data consistency. For more details, refer to the [Import Data](import_data/index.md).
+
+For convenience, the **Program** page includes a dedicated button, represented by a shield icon, allowing quick access to essential admin functions.
+
+---
+
+#### Batch page
+
+Displays a list of batches. A batch is an entity that contains references to imported data sources for the selected program. The page includes filtering options, allowing users to refine the list. For a selected batch, you can view the imported records.
+
+---
+#### Jobs Page
+
+Displays a list of asynchronous jobs with filtering options. For a selected job, you can perform various actions, such as *inspect*, *queue*, *revoke*, or *terminate* it.
+
+---
+
+###  **Admin Interface**
+A standard Django admin panel used for managing diverse configurations, setting up flex fields, controlling user access, and synchronizing Unified Classifiers with the HOPE main system.
+
+---
+
+## Synchronize Unified Classifiers
+
+**Unified Classifiers** are centralized reference data that categorize key elements essential for process unification, including *offices*, *programs*, and *registrations*.
+
+To synchronize data in the admin interface, press the **[SYNC]** button for the corresponding classifier.

mkdocs.yml

@@ -18,6 +18,7 @@ exclude_docs: |
 
 markdown_extensions:
   - admonition
+  - pymdownx.details
   - pymdownx.magiclink
   - pymdownx.superfences:
       custom_fences:

src/country_workspace/admin/program.py

@@ -25,7 +25,7 @@ class ProgramAdmin(BaseModelAdmin):
 
     @button()
     def invalidate_cache(self, request: HttpRequest, pk: str) -> None:
-        obj: [Program] = Program.objects.select_related("country_office").get(pk=pk)
+        obj: Program = Program.objects.select_related("country_office").get(pk=pk)
         cache_manager.incr_cache_version(program=obj)
 
     @link(change_list=False)
@@ -61,4 +61,4 @@ def sync(self, request: HttpRequest) -> None:
         from country_workspace.contrib.hope.sync.office import sync_programs
 
         totals = sync_programs()
-        self.message_user(request, f"{totals['add']} created - {totals['upd']} updated")
+        self.message_user(request, f"{totals['add']} created - {totals['upd']} updated - {totals['skip']} skipped")