feat(subsequences): migrate old SubmissionExtras to SubmissionSupplemental DEV-934

kobo/apps/subsequences/README.md

@@ -117,6 +117,31 @@ POST to `/api/v2/assets/{uid_asset}/advanced-features/` with:
 }
 ```
 
+**Example: Enable Qual action**
+
+```json
+{
+  "question_xpath": "text_question",
+  "action": "qual",
+  "params": [
+    {
+      "type": "qualSelectOne",
+      "uuid": "1a8b748b-f470-4c40-bc09-ce2b1197f503",
+      "labels": { "_default": "Was this a first-hand account?" },
+      "choices": [
+        { "uuid": "3c7aacdc-8971-482a-9528-68e64730fc99", "labels": { "_default": "Yes" } },
+        { "uuid": "7e31c6a5-5eac-464c-970c-62c383546a94", "labels": { "_default": "No" } }
+      ]
+    },
+    {
+      "type": "qualInteger",
+      "uuid": "1a2c8eb0-e2ec-4b3c-942a-c1a5410c081a",
+      "labels": { "_default": "How many characters appear in the story?" }
+    }
+  ]
+}
+```
+
 ---
 
 ### 2.2 Add Submission Supplement
@@ -149,6 +174,20 @@ PATCH /api/v2/assets/<asset_uid>/data/<submission_root_uuid>/supplement/
 }
 ```
 
+#### Example: Qual action
+
+```json
+{
+  "_version": "20250820",
+  "text_question": {
+    "qual": {
+      "uuid": "q_uuid",
+      "value": "sentiment_pos"
+    }
+  }
+}
+```
+
 ---
 
 ### 2.3 Sequence Diagram (End-to-End Flow)
@@ -285,6 +324,31 @@ It describes the configuration stored on a `QuestionAdvancedFeature` when an act
 }
 ```
 
+**Example: enabling Qual**
+
+```json
+{
+  "question_xpath": "text_question",
+  "action": "qual",
+  "params": [
+    {
+      "type": "qualSelectOne",
+      "uuid": "1a8b748b-f470-4c40-bc09-ce2b1197f503",
+      "labels": { "_default": "Was this a first-hand account?" },
+      "choices": [
+        { "uuid": "3c7aacdc-8971-482a-9528-68e64730fc99", "labels": { "_default": "Yes" } },
+        { "uuid": "7e31c6a5-5eac-464c-970c-62c383546a94", "labels": { "_default": "No" } }
+      ]
+    },
+    {
+      "type": "qualInteger",
+      "uuid": "1a2c8eb0-e2ec-4b3c-942a-c1a5410c081a",
+      "labels": { "_default": "How many characters appear in the story?" }
+    }
+  ]
+}
+```
+
 ---
 
 ### 3.2 `data_schema`
@@ -312,6 +376,14 @@ Each action has its own expected format:
   { "language": "en", "value": null }
   ```
 
+- **Qual**
+  ```json
+  {
+    "uuid": "q_uuid",
+    "value": "sentiment_pos"
+  }
+  ```
+
 ---
 
 ### 3.3 `external_data_schema`
@@ -348,28 +420,61 @@ The structure is the same for both manual and automatic actions:
 
 - Metadata about the action itself (`_dateCreated`, `_dateModified`).
 - A list of versions under `_versions`, each containing:
-  - The properties defined by `data_schema` (manual) or `external_data_schema` (automatic).
+  - A nested `_data` object with properties from either `data_schema` (manual) or `external_data_schema` (automatic).
   - Audit fields (`_dateCreated`, `_dateAccepted`, `_uuid`).
 
-**Generic Example**
+**Manual Action Example**
+
+```json
+{
+  "_dateCreated": "2025-08-21T20:55:42Z",
+  "_dateModified": "2025-08-21T20:57:28Z",
+  "_versions": [
+    {
+      "_data": {
+        "language": "en",
+        "value": "My manual transcript"
+      },
+      "_dateCreated": "2025-08-21T20:57:28Z",
+      "_dateAccepted": "2025-08-21T20:57:28Z",
+      "_uuid": "4dcf9c9f-e503-4e5c-81f5-74250b295001"
+    },
+    {
+      "_data": {
+        "language": "en",
+        "value": "My previous manual transcript"
+      },
+      "_dateCreated": "2025-08-21T20:55:42Z",
+      "_dateAccepted": "2025-08-21T20:55:42Z",
+      "_uuid": "850e6359-50e8-4252-9895-e9669a27b1ea"
+    }
+  ]
+}
+```
+
+**Automatic Action Example**
 
 ```json
 {
   "_dateCreated": "2025-08-21T20:55:42Z",
   "_dateModified": "2025-08-21T20:57:28Z",
   "_versions": [
     {
-      "language": "en",
-      "value": "My automatic result",
-      "status": "complete",
+      "_data": {
+        "language": "en",
+        "value": "My automatic result",
+        "status": "complete"
+      },
       "_dateCreated": "2025-08-21T20:57:28Z",
       "_dateAccepted": "2025-08-21T20:57:28Z",
       "_uuid": "4dcf9c9f-e503-4e5c-81f5-74250b295001"
     },
     {
-      "language": "en",
-      "value": "Previous revision",
-      "status": "complete",
+      "_data": {
+        "language": "en",
+        "value": "My previous automatic result",
+        "status": "complete"
+      },
       "_dateCreated": "2025-08-21T20:55:42Z",
       "_dateAccepted": "2025-08-21T20:55:42Z",
       "_uuid": "850e6359-50e8-4252-9895-e9669a27b1ea"
@@ -378,6 +483,52 @@ The structure is the same for both manual and automatic actions:
 }
 ```
 
+**Qual Action Example**
+
+```json
+{
+  "q1_uuid_here": {
+    "_dateCreated": "2025-08-21T20:55:42Z",
+    "_dateModified": "2025-08-21T20:57:28Z",
+    "_versions": [
+      {
+        "_data": {
+          "uuid": "q1_uuid_here",
+          "value": "sentiment_pos"
+        },
+        "_dateCreated": "2025-08-21T20:57:28Z",
+        "_dateAccepted": "2025-08-21T20:57:28Z",
+        "_uuid": "4dcf9c9f-e503-4e5c-81f5-74250b295001"
+      },
+      {
+        "_data": {
+          "uuid": "q1_uuid_here",
+          "value": "sentiment_neg"
+        },
+        "_dateCreated": "2025-08-21T20:55:42Z",
+        "_dateAccepted": "2025-08-21T20:55:42Z",
+        "_uuid": "850e6359-50e8-4252-9895-e9669a27b1ea"
+      }
+    ]
+  },
+  "q2_uuid_here": {
+    "_dateCreated": "2025-08-21T20:55:42Z",
+    "_dateModified": "2025-08-21T20:57:28Z",
+    "_versions": [
+      {
+        "_data": {
+          "uuid": "q2_uuid_here",
+          "value": 8
+        },
+        "_dateCreated": "2025-08-21T20:57:28Z",
+        "_dateAccepted": "2025-08-21T20:57:28Z",
+        "_uuid": "91ab5f30-0f73-4e2e-b91f-8ad2f67a4729"
+      }
+    ]
+  }
+}
+```
+
 > For manual actions, the inner version objects correspond to `data_schema`.
 >
 > For automatic actions, they correspond to `external_data_schema`.
@@ -398,9 +549,11 @@ In this case, a `_dependency` property is added to the persisted JSON.
   "_dateModified": "2025-09-01T12:17:28Z",
   "_versions": [
     {
-      "language": "fr",
-      "value": "Mon audio a été traduit automatiquement",
-      "status": "complete",
+      "_data": {
+        "language": "fr",
+        "value": "Mon audio a été traduit automatiquement",
+        "status": "complete"
+      },
       "_dateCreated": "2025-09-01T12:17:28Z",
       "_uuid": "91ab5f30-0f73-4e2e-b91f-8ad2f67a4729",
       "_dependency": {

kobo/apps/subsequences/models.py

@@ -36,6 +36,8 @@ def __repr__(self):
     @staticmethod
     def revise_data(asset: 'kpi.Asset', submission: dict, incoming_data: dict) -> dict:
 
+        from .utils.versioning import migrate_submission_supplementals
+
         if not asset.advanced_features_set.exists():
             raise InvalidAction
 
@@ -46,8 +48,10 @@ def revise_data(asset: 'kpi.Asset', submission: dict, incoming_data: dict) -> di
             raise NotImplementedError
 
         if schema_version != SCHEMA_VERSIONS[0]:
-            # TODO: migrate from old per-submission schema
-            raise NotImplementedError
+            migrated_data = migrate_submission_supplementals(incoming_data)
+            if migrated_data is None:
+                raise InvalidAction
+            incoming_data = migrated_data
 
         submission_uuid = remove_uuid_prefix(submission[SUBMISSION_UUID_FIELD])  # constant?
         supplemental_data = SubmissionExtras.objects.get_or_create(
@@ -153,8 +157,10 @@ def retrieve_data(
             raise NotImplementedError
 
         if schema_version != SCHEMA_VERSIONS[0]:
-            # TODO: migrate from old per-submission schema
-            raise NotImplementedError
+            migrated_data = migrate_submission_supplementals(supplemental_data)
+            if migrated_data is None:
+                raise InvalidAction
+            supplemental_data = migrated_data
 
         retrieved_supplemental_data = {}
         data_for_output = {}

kobo/apps/subsequences/schemas.py

@@ -37,7 +37,7 @@
 
 
 def validate_submission_supplement(asset: 'kpi.models.Asset', supplement: dict):
-    jsonschema.validate(get_submission_supplement_schema(asset), supplement)
+    jsonschema.validate(supplement, get_submission_supplement_schema(asset))
 
 
 def get_submission_supplement_schema(asset: 'kpi.models.Asset') -> dict: