Add Data Migration documentation to docusite (#3094)

* Add Data Migration documentation to docusite * small adjustments * Update data migration docs * Make necessary changes to the data migration docs --------- Co-authored-by: Peter Lubell-Doughtie <[email protected]>
opensrp · Mar 12, 2024 · 412fff2 · 412fff2
1 parent a252fcc
commit 412fff2
Show file tree

Hide file tree

Showing 6 changed files with 96 additions and 8 deletions.
diff --git a/docs/engineering/android-app/configuring/add-application-flavors.mdx b/docs/engineering/android-app/configuring/add-application-flavors.mdx
@@ -1,12 +1,12 @@
 ---
-sidebar_label: App Flavors
+sidebar_label: App flavors
 ---
 
 # How to Add/Modify App Flavors
 
 ## Product Flavors Configuration
 
-Product flavors are a way to create different versions of the same application with distinct features or characteristics. Each product flavor represents a different version of the application, and you can configure various aspect of the app for each flavor. To set this up, navigate to `fhircore > android > quest > Gradle scripts > build.gradle.kts` in the `quest` module. 
+Product flavors are a way to create different versions of the same application with distinct features or characteristics. Each product flavor represents a different version of the application, and you can configure various aspect of the app for each flavor. To set this up, navigate to `fhircore > android > quest > Gradle scripts > build.gradle.kts` in the `quest` module.
 
 ## Configuration Details
 
@@ -105,7 +105,7 @@ android {
 }
 ```
 
-`create("debugNonProxy") { initWith(getByName("debug")) }` 
+`create("debugNonProxy") { initWith(getByName("debug")) }`
 
 - This line creates a new custom build variant named "debugNonProxy" by inheriting configurations from the existing "debug" variant. Here's a breakdown:
 

diff --git a/docs/engineering/android-app/configuring/config-types/_category_.yml b/docs/engineering/android-app/configuring/config-types/_category_.yml
@@ -1 +1 @@
-label: Config Types
+label: Config types
diff --git a/docs/engineering/android-app/configuring/data-migration.mdx b/docs/engineering/android-app/configuring/data-migration.mdx
@@ -0,0 +1,88 @@
+# Data migration
+
+
+The main functionalities of data migration are:
+- Migrating data by updating resources based on a set of data queries and key-value pairs,
+- Retrieving the latest migration version from shared preferences,
+- Performing the migration only if the new version is greater than the client's latest stored migration version.
+The data migration configuration outlines a set of rules and operations for migrating malformed FHIR resources such as `Task` resource migration on the client app sqlite database. With this configuration one is able to filter the target resource eg `Encounter` or `Task` and read its referenced `PlanDefinition` and its careplans then filter for the task or resource being migrated that lies within the careplan period and read the resulting `careplan id` . The migration then uses the resulting id to replace the malformed attribute such as `Task.basedOn` hence cleaning out the malformed resource attributes that a wrong `StructureMap` may have generated. The feature allows one to filter using data queries and write rules that can query using `forward_include` as well as `rev_include` targeting base resources and any related resources
+
+## Sample JSON for Task migration
+```json
+{
+  "appId": "echis",
+  "configType": "dataMigration",
+  "migrations": [
+    {
+      "resourceType": "Task",
+      "updateValues": [
+        {
+          "jsonPathExpression": "Task.basedOn[0].reference",
+          "valueRule": {
+            "name": "taskBasedOn",
+            "condition": "true",
+            "actions": [
+              "data.put('taskBasedOn', 'CarePlan/' + fhirPath.extractValue(Task, 'Task.basedOn[0].reference') )"
+            ]
+          }
+        }
+      ],
+      "dataQueries": [
+        {
+          "paramName": "status",
+          "operation": "OR",
+          "filterCriteria": [
+            {
+              "dataType": "CODE",
+              "value": {
+                "system": "http://hl7.org/fhir/task-status",
+                "code": "ready"
+              }
+            },
+            {
+              "dataType": "CODE",
+              "value": {
+                "system": "http://hl7.org/fhir/task-status",
+                "code": "requested"
+              }
+            },
+            {
+              "dataType": "CODE",
+              "value": {
+                "system": "http://hl7.org/fhir/task-status",
+                "code": "in-progress"
+              }
+            }
+          ]
+        }
+      ],
+      "purgeAffectedResources": true,
+      "createLocalChangeEntitiesAfterPurge": true,
+      "resourceFilterExpression" : {
+        "conditionalFhirPathExpressions": [
+          "Task.basedOn[0].reference.startsWith('CarePlan').not() and Task.basedOn[0].reference.startsWith('PlanDefinition').not()"
+        ],
+        "matchAll": true
+      },
+      "version": 1
+    }
+  ]
+}
+```
+
+## Config properties
+|Property | Description | Required | Default |
+|--|--|:--:|:--:|
+appId | Provides the ID of the application | Yes | |
+configType | Type of configuration | Yes | dataMigration |
+migrations | List of migrations | Yes | |
+resourceType | The resource to to get/fetch data from e.g Task or Careplan | yes | |
+updateValues | Provides the ID of the application | Yes | |
+configType | Type of configuration | Yes | dataMigration |
+rules | List of rule configurations | Yes | |
+version | Version of the migration configuration| Yes | |
+purgeAffectedResources | Flag indicating whether affected resources should be purged | Yes | false |
+createLocalChangeEntitiesAfterPurge | Flag indicating whether to create local change entities after purging | Yes | true |
+resourceFilterExpression | Expression for filtering resources during migration | Yes |  |
+jsonPathExpression | JSON path expression for locating the value within the resource | Yes |  |
+computedValueKey | Key for the computed value to be updated | Yes | |
diff --git a/docs/engineering/android-app/configuring/event-management/_category_.yml b/docs/engineering/android-app/configuring/event-management/_category_.yml
@@ -1 +1 @@
-label: Event Management
+label: Event management
diff --git a/docs/engineering/android-app/configuring/in-app-reporting.mdx b/docs/engineering/android-app/configuring/in-app-reporting.mdx
@@ -1,4 +1,4 @@
-# In-app Reporting
+# In-app reporting
 
 The in-app reporting feature empowers the health worker to see how she is performing against her daily task list, and allows for offline peer-to-peer syncing of the data collected on a daily basis. This greatly simplifies reporting requirements by eliminating the need for cumbersome paper registries and tally sheets.
 

diff --git a/docs/engineering/android-app/configuring/working-with-rules.mdx b/docs/engineering/android-app/configuring/working-with-rules.mdx
@@ -53,9 +53,9 @@ This rule is used within the rules engine or workflow to be able to determine wh
       "condition": "true",
       "actions": [
         "data.put('isPregnant', service.evaluateToBoolean(data.get('activeConditions'), \"Condition.code.text = 'Pregnant' \", false))"
-      ]  
+      ]
     },
-```   
+```
 
 ### Configuring the properties of the `evaluateToBoolean()`