IA-5375 allow import/export of mappings

docs/pages/users/how_to/import_export_dhis2_mappings.en.md

@@ -0,0 +1,84 @@
+# Import and export DHIS2 mappings
+
+To export submissions to DHIS2, each question of a form is mapped to a DHIS2 data element (see the
+"DHIS2 mappings" section of the [user guide](../reference/user_guide.md)). This page explains how to
+reuse those mappings instead of redoing them by hand.
+
+## Which mapping type to choose
+
+The mapping type depends on how many submissions the form gets, and on what they must become in
+DHIS2:
+
+| Mapping type | Use it when | Each submission becomes, in DHIS2 |
+|---|---|---|
+| **Aggregate** | there is **one submission per org unit and period** (monthly report, quantity form...). The form needs a period type. | a data value set of a **dataset**, for the org unit and period of the submission; the dataset is marked as complete. A second submission for the same org unit and period overwrites the values of the first one. |
+| **Event** | there are **several submissions per org unit and period**, with no person to follow (consultations, visits, surveys...) | an event of an **event program without registration**. Its date is the creation date or the start of the period of the submission (**Event date source**). |
+| **Event Tracker** | the **same person (or object) is followed over time** | a tracked entity of a **tracker program** (found by its identifier, or created), with its attributes, an enrollment and an event per program stage. A repeat group can create related tracked entities, linked by a relationship. |
+
+The **Derived** type does not export to DHIS2: it computes a statistics form from another form, see
+[Deduce a form from another form](deduce_form_from_another_form.md).
+
+## A mapping per form version
+
+A mapping is attached to one **version** of a form, not to the form itself: questions can be added,
+removed or renamed from one version to the next.
+
+When you upload a new version of a form, IASO copies the mappings of the previous version:
+
+- mappings of questions still present in the new version are kept;
+- mappings of questions that no longer exist are dropped;
+- new questions are not mapped yet: map them, or mark them as never mapped.
+
+## Export the mappings of a version
+
+On the mapping page of a form version, click **Export mappings**. A `.json` file is downloaded with
+the question mappings and the DHIS2 dataset (aggregate mappings) or program (event and tracker
+mappings) they target. Questions marked as never mapped are not exported.
+
+Use it to keep a copy before a big change, or to copy the mappings to another server or account.
+
+## Import mappings
+
+On the mapping page of the form version to complete, click **Import mappings**. Nothing is changed
+until you confirm the last step.
+
+### 1. Pick the mappings to reuse
+
+Choose either:
+
+- another **version of the same form** that uses the same DHIS2 data source, or
+- a **mapping export** (`.json`), for example made on another account or another server.
+
+A file is refused when it is not a mapping export, or when it was made for another mapping type
+(e.g. a tracker export into an aggregate mapping). When it was made for another DHIS2 dataset or
+program, a warning asks you to check that its data elements belong to this one.
+
+### 2. Review the differences
+
+The incoming mappings are compared with the current ones, question by question, in four tabs:
+
+| Tab | What it contains | Default decision |
+|---|---|---|
+| **Conflicts** | the question is already mapped (or marked as never mapped) to something else | **Keep** the current mapping |
+| **To add** | the question is not mapped yet in this version | **Add** the incoming mapping |
+| **Identical** | same DHIS2 target on both sides, nothing to resolve | no change |
+| **Dropped** | cannot be imported: the question does not exist in this version, or the mapping is not valid for this mapping type | not imported |
+
+For each conflict, choose **Keep** or **Overwrite**; for each addition, **Add** or **Skip**. The
+buttons above the table decide for all the rows of the tab at once (**Keep current everywhere**,
+**Overwrite everywhere**, **Add all**, **Skip all**).
+
+### 3. Apply
+
+Click **Apply** (the button shows the number of changes). A message sums up how many mappings were
+added, overwritten, kept and not imported.
+
+!!! warning
+    The DHIS2 ids of the imported mappings are not checked against DHIS2. If a data element does not
+    exist in the target dataset or program, the error only shows up when exporting submissions.
+
+## Go back to a previous mapping
+
+Every change of a mapping version, including an import, is recorded. On the mapping page, the
+**Link to changes log** shows the history, with the mappings before and after each change: use it
+to find a mapping that was overwritten by mistake.

docs/pages/users/how_to/import_export_dhis2_mappings.fr.md

@@ -0,0 +1,90 @@
+# Importer et exporter des mappings DHIS2
+
+Pour exporter des soumissions vers DHIS2, chaque question d'un formulaire est mappée vers un data
+element DHIS2 (voir la section « Correspondances avec DHIS2 » du [guide utilisateur](../reference/user_guide.md)).
+Cette page explique comment réutiliser ces mappings au lieu de les refaire à la main.
+
+## Quel type de mapping choisir
+
+Le type de mapping dépend du nombre de soumissions du formulaire, et de ce qu'elles doivent devenir
+dans DHIS2 :
+
+| Type de mapping | À utiliser quand | Chaque soumission devient, dans DHIS2 |
+|---|---|---|
+| **Aggregate** | il y a **une soumission par unité d'organisation et par période** (rapport mensuel, formulaire de quantités...). Le formulaire doit avoir un type de période. | un ensemble de valeurs d'un **dataset**, pour l'unité d'organisation et la période de la soumission ; le dataset est marqué comme complet. Une deuxième soumission pour la même unité d'organisation et la même période écrase les valeurs de la première. |
+| **Event** | il y a **plusieurs soumissions par unité d'organisation et par période**, sans personne à suivre (consultations, visites, enquêtes...) | un évènement d'un **programme d'évènements sans enregistrement** (event program without registration). Sa date est la date de création ou le début de la période de la soumission (**Source pour la date d'évènement**). |
+| **Event Tracker** | la **même personne (ou le même objet) est suivie dans le temps** | une entité suivie (tracked entity) d'un **programme tracker** (retrouvée par son identifiant, ou créée), avec ses attributs, une inscription (enrollment) et un évènement par étape du programme. Un groupe répété peut créer des entités suivies liées, reliées par une relation. |
+
+Le type **Derived** n'exporte pas vers DHIS2 : il calcule un formulaire de statistiques à partir
+d'un autre formulaire, voir [Déduire un formulaire à partir d'un autre formulaire](deduce_form_from_another_form.md).
+
+## Un mapping par version de formulaire
+
+Un mapping est attaché à une **version** d'un formulaire, pas au formulaire lui-même : des questions
+peuvent être ajoutées, supprimées ou renommées d'une version à l'autre.
+
+Quand vous chargez une nouvelle version d'un formulaire, IASO copie les mappings de la version
+précédente :
+
+- les mappings des questions encore présentes dans la nouvelle version sont gardés ;
+- les mappings des questions qui n'existent plus sont supprimés ;
+- les nouvelles questions ne sont pas encore mappées : mappez-les, ou marquez-les comme jamais mappées.
+
+## Exporter les mappings d'une version
+
+Sur la page de mapping d'une version de formulaire, cliquez sur **Exporter les mappings**. Un
+fichier `.json` est téléchargé avec les mappings des questions et le dataset DHIS2 (mappings
+agrégés) ou le programme (mappings event et tracker) qu'ils visent. Les questions marquées comme
+jamais mappées ne sont pas exportées.
+
+Utilisez-le pour garder une copie avant un gros changement, ou pour copier les mappings vers un
+autre serveur ou un autre compte.
+
+## Importer des mappings
+
+Sur la page de mapping de la version de formulaire à compléter, cliquez sur **Importer des
+mappings**. Rien n'est modifié avant la confirmation de la dernière étape.
+
+### 1. Choisir les mappings à réutiliser
+
+Choisissez :
+
+- une autre **version du même formulaire** qui utilise la même source de données DHIS2, ou
+- un **export de mapping** (`.json`), fait par exemple sur un autre compte ou un autre serveur.
+
+Un fichier est refusé s'il n'est pas un export de mapping, ou s'il a été fait pour un autre type de
+mapping (par exemple un export tracker dans un mapping agrégé). S'il a été fait pour un autre
+dataset ou programme DHIS2, un avertissement vous demande de vérifier que ses data elements font
+partie de celui-ci.
+
+### 2. Vérifier les différences
+
+Les mappings importés sont comparés aux mappings actuels, question par question, dans quatre
+onglets :
+
+| Onglet | Contenu | Décision par défaut |
+|---|---|---|
+| **Conflits** | la question est déjà mappée (ou marquée comme jamais mappée) vers autre chose | **Garder** le mapping actuel |
+| **À ajouter** | la question n'est pas encore mappée dans cette version | **Ajouter** le mapping importé |
+| **Identiques** | même cible DHIS2 des deux côtés, rien à résoudre | aucun changement |
+| **Ignorés** | ne peuvent pas être importés : la question n'existe pas dans cette version, ou le mapping n'est pas valide pour ce type de mapping | non importé |
+
+Pour chaque conflit, choisissez **Garder** ou **Écraser** ; pour chaque ajout, **Ajouter** ou
+**Ignorer**. Les boutons au-dessus du tableau décident pour toutes les lignes de l'onglet à la fois
+(**Garder l'actuel partout**, **Écraser partout**, **Tout ajouter**, **Tout ignorer**).
+
+### 3. Appliquer
+
+Cliquez sur **Appliquer** (le bouton indique le nombre de changements). Un message résume combien
+de mappings ont été ajoutés, écrasés, gardés et non importés.
+
+!!! warning "Attention"
+    Les identifiants DHIS2 des mappings importés ne sont pas vérifiés auprès de DHIS2. Si un data
+    element n'existe pas dans le dataset ou le programme visé, l'erreur n'apparaît qu'à l'export des
+    soumissions.
+
+## Revenir à un mapping précédent
+
+Chaque modification d'une version de mapping, import compris, est enregistrée. Sur la page de
+mapping, le **Lien vers le Journal des modifications** affiche l'historique, avec les mappings
+avant et après chaque modification : utilisez-le pour retrouver un mapping écrasé par erreur.

docs/pages/users/reference/user_guide.en.md

@@ -309,13 +309,13 @@ In the Form view you can see details of:
 
 -   Versions
 
--   Type of the form :
+-   Type of the mapping (see [which mapping type to choose](../how_to/import_export_dhis2_mappings.md#which-mapping-type-to-choose)):
 
-    -   Aggregate : fix
+    -   Aggregate : one submission per org unit and period, exported to a DHIS2 dataset
 
-    -   Event : series of singular events
+    -   Event : several submissions per org unit and period, exported to an event program without registration
 
-    -   Event Tracker : continuous
+    -   Event Tracker : the same person followed over time, exported to a tracker program
 
 -   Number of questionnaire to be mapped
 
@@ -342,6 +342,9 @@ box by using the name, code or ID and then confirm.
 
 Once confirmed, the question will turn to green and be counted.
 
+To reuse the mappings of another form version or of an export file, see
+[Import and export DHIS2 mappings](../how_to/import_export_dhis2_mappings.md).
+
 <img src="./user_guide_attachments/image115.png"
 style="width:7.03646in;height:3.20249in" />
 

docs/pages/users/reference/user_guide.fr.md

@@ -270,10 +270,10 @@ Dans la vue du formulaire, vous pouvez consulter les détails suivants :
 - Actions
 - Nom des formulaires disponibles pour les correspondances
 - Versions
-- Type du formulaire :
-  - Aggregate : données fixes
-  - Event : série d'événements singuliers
-  - Event Tracker : continu
+- Type du mapping (voir [quel type de mapping choisir](../how_to/import_export_dhis2_mappings.md#quel-type-de-mapping-choisir)) :
+  - Aggregate : une soumission par unité d'organisation et par période, exportée vers un dataset DHIS2
+  - Event : plusieurs soumissions par unité d'organisation et par période, exportées vers un programme d'évènements sans enregistrement
+  - Event Tracker : la même personne suivie dans le temps, exportée vers un programme tracker
 - Nombre de questionnaires à mapper
 - Nombre total de questionnaires
 - Couverture des correspondances
@@ -289,6 +289,9 @@ Si la question doit être mappée, recherchez l'élément correspondant dans le
 
 Une fois confirmée, la question deviendra verte et sera comptabilisée.
 
+Pour réutiliser les mappings d'une autre version du formulaire ou d'un fichier d'export, voir
+[Importer et exporter des mappings DHIS2](../how_to/import_export_dhis2_mappings.md).
+
 ### Complétude
 
 Cette fonctionnalité est destinée aux cas où des périodes ont été définies pour les formulaires de collecte de données.

hat/assets/js/apps/Iaso/domains/app/translations/en.json

@@ -1118,11 +1118,55 @@
     "iaso.map.shape.editLocationDisabled": "Location edition is disabled on this account",
     "iaso.map.title.markerClustering": "Clustering",
     "iaso.mapping.mappingType": "Mapping type",
+    "iaso.mappings.changeLog": "Link to changes log",
     "iaso.mappings.changeMapping": "Change the mapping to existing one :",
     "iaso.mappings.confirm": "Confirm",
     "iaso.mappings.coverage": "Coverage",
     "iaso.mappings.create": "Create Mapping",
     "iaso.mappings.currentMapping": "Current mapping",
+    "iaso.mappings.export": "Export mappings",
+    "iaso.mappings.import.addAll": "Add all",
+    "iaso.mappings.import.allAdditions": "All additions:",
+    "iaso.mappings.import.applyChanges": "Apply {count} changes",
+    "iaso.mappings.import.bucket.add": "To add ({count})",
+    "iaso.mappings.import.bucket.conflict": "Conflicts ({count})",
+    "iaso.mappings.import.bucket.dropped": "Dropped ({count})",
+    "iaso.mappings.import.bucket.identical": "Identical ({count})",
+    "iaso.mappings.import.chooseFile": "Choose a file",
+    "iaso.mappings.import.compareLabel": "Comparing {source} with version {versionId}. Nothing is applied until you confirm.",
+    "iaso.mappings.import.decision": "Decision",
+    "iaso.mappings.import.done": "{added} mappings added, {overwritten} overwritten, {kept} kept, {ignored} not imported",
+    "iaso.mappings.import.droppedHint": "These mappings cannot be imported: the question does not exist in this version, or the mapping is not valid for this mapping type.",
+    "iaso.mappings.import.fileMeta": "Exported from {formName} - {versionId}",
+    "iaso.mappings.import.fromFile": "Or import a mapping export (.json), for example from another account.",
+    "iaso.mappings.import.identicalHint": "Same DHIS2 target on both sides. Nothing to resolve.",
+    "iaso.mappings.import.incomingMapping": "Incoming mapping",
+    "iaso.mappings.import.invalidFormat": "This file is not a mapping export.",
+    "iaso.mappings.import.invalidJson": "This file is not valid JSON.",
+    "iaso.mappings.import.invalidMapping": "Not valid for a {type} mapping",
+    "iaso.mappings.import.keep": "Keep",
+    "iaso.mappings.import.keepEverywhere": "Keep current everywhere",
+    "iaso.mappings.import.mappingsCount": "{count} mappings",
+    "iaso.mappings.import.mappingTypeMismatch": "This export was made for another mapping type.",
+    "iaso.mappings.import.markedNeverMapped": "Marked as never mapped",
+    "iaso.mappings.import.matchCount": "{matching} / {total} match this version",
+    "iaso.mappings.import.noChange": "No change",
+    "iaso.mappings.import.noSource": "No other mapping version uses this data source with the same DHIS2 dataset or program.",
+    "iaso.mappings.import.notImportable": "Not importable",
+    "iaso.mappings.import.noValidMapping": "This file contains no mapping valid for a {type} mapping.",
+    "iaso.mappings.import.otherDataset": "This export was made for another DHIS2 dataset ({name}). Check that its data elements belong to this one.",
+    "iaso.mappings.import.otherProgram": "This export was made for another DHIS2 program ({name}). Check that its data elements belong to this one.",
+    "iaso.mappings.import.overwrite": "Overwrite",
+    "iaso.mappings.import.overwriteEverywhere": "Overwrite everywhere",
+    "iaso.mappings.import.pickSource": "Pick the mappings to reuse. Nothing is applied until you confirm.",
+    "iaso.mappings.import.questionAbsent": "Question absent from version {versionId}",
+    "iaso.mappings.import.resolveAllConflicts": "Resolve all conflicts:",
+    "iaso.mappings.import.skip": "Skip",
+    "iaso.mappings.import.skipAll": "Skip all",
+    "iaso.mappings.import.summary": "{added} to add, {overwritten} to overwrite, {ignored} not imported",
+    "iaso.mappings.import.title": "Import mappings",
+    "iaso.mappings.import.versionMeta": "Last updated {date}",
+    "iaso.mappings.import.versionTitle": "Version {versionId}",
     "iaso.mappings.label.atLeastAMapping": "at least a mapping",
     "iaso.mappings.label.dataset": "Dataset",
     "iaso.mappings.label.duplicateMappingAlert": "Duplicate mapping ! Will be used in both {duplicates}",