Adding the sync strategies documentations (#3530)

* - Adding the sync strategies documentations * Correct typos * Update tagging.mdx * correct outline hierarchy * consolidate user assignment until we have more content * update text * remove unused files * minor adjustments to text --------- Co-authored-by: pld <[email protected]>
opensrp · Nov 15, 2024 · 978d050 · 978d050
1 parent 92601d7
commit 978d050
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 12 deletions.
diff --git a/docs/engineering/admin-dashboard/readme.mdx b/docs/engineering/admin-dashboard/readme.mdx
@@ -1,3 +1,19 @@
 # Admin Dashboard
 
-We use [fhir-web](https://github.com/onaio/fhir-web) as the administrative dashboard for OpenSRP 2 projects.
+We use [fhir-web](https://github.com/onaio/fhir-web) as the admin dashboard for OpenSRP 2 projects. This allows you to manage users, teams and view data. See more details on the [admin dashboard features](/features/admin-dashboard-features).
+
+## Users and the FHIR Practitioner resource
+
+OpenSRP2 manages user accounts through an integrated identity and authentication management (IAM) system. Each `user` created in the IAM system has a 1-to-1 link with FHIR `Practitioner` resource in the FHIR health data store.
+
+## User Assignment
+
+User assignment consists of 4 main elements
+- **User (FHIR Practitioner)** - This is the person using the application to collect data and execute workflows
+- **CareTeam** - This is used to define a group of users that provide care as a team.
+- **Team (FHIR Organization)** - Teams are added to CareTeams as the `.managingOrganization`.
+- **Location** - Teams are assigned to Locations to define where they work.
+
+Every user must have at least 1 of the 4 elements above. These assignments affect how data is [synced down](/engineering/backend/info-gateway/data-sync) to the app.
+
+These elements are then downloaded to the app via the **PractitionerDetail** endpoint. This is a custom endpoint that aggregates data related to a user and returns as a single response.
diff --git a/docs/engineering/app/datastore/tagging.mdx b/docs/engineering/app/datastore/tagging.mdx
@@ -19,7 +19,7 @@ System Suffix|Display|Purpose
 `practitioner-tag-id`|Practitioner|This is the Practitioner that is logged into the app when the resource is created.
 `location-tag-id`|Practitioner Location|This is the Location linked to the Organization of the Practitioner that is logged into the app when the resource is created.
 `organisation-tag-id`|Practitioner Organization|This is the Organization linked to the Practitioner that is logged into the app when the resource is created.
-`related-entity-location-tag-id`|Related Entity Location|"Entity" here is a `Patient`, `Group`, Point of Service (as a `Location` resource), or other organizing unit, and this stores the ID of a `Location` resource (or the resource itself if it is a `Location`) lnked to that entity.
+`related-entity-location-tag-id`|Related Entity Location|"Entity" here is a `Patient`, `Group`, Point of Service (as a `Location` resource), or other organizing unit, and this stores the ID of a `Location` resource (or the resource itself if it is a `Location`) linked to that entity.
 
 ## Example Tags
 

diff --git a/docs/engineering/backend/info-gateway.mdx → ...gineering/backend/info-gateway/readme.mdx b/docs/engineering/backend/info-gateway.mdx → ...gineering/backend/info-gateway/readme.mdx
diff --git a/docs/engineering/backend/info-gateway/sync-strategies.mdx b/docs/engineering/backend/info-gateway/sync-strategies.mdx
@@ -0,0 +1,57 @@
+---
+title: Sync Strategies
+---
+
+OpenSRP 2 uses five key data elements in determining how data is synced down from the server. These elements are [added](/engineering/app/datastore/tagging) to every resource created by the OpenSRP mobile app, enabling precise synchronization. These elements are:
+
+- `care-team-tag-id`
+- `practitioner-tag-id`
+- `location-tag-id`
+- `organisation-tag-id`
+- `related-entity-location-tag-id`
+
+### Sync by Practitioner CareTeam
+This strategy syncs data based on the CareTeam that the logged in user (which maps 1-to-1 to a FHIR Practitioner Resource) is assigned to. All resources tagged with the same CareTeam via the `care-team-tag-id` are synced down to the device if the FHIR Practitioner mapping to the logged-in user is assigned to that CareTeam. A sample tag is provided below
+
+```json
+    {
+      "system": "https://smartregister.org/care-team-tag-id",
+      "code": "47d68cac-306f-4b75-9704-b4ed48b24f76",
+      "display": "Practitioner CareTeam"
+    }
+```
+
+### Sync by Practitioner Team (FHIR Organization)
+This sync strategy is based on the team (FHIR Organization) and syncs resources tied to the specific team (FHIR Organization) associated with the logged user's FHIR Practitioner. 
+
+- This sync strategy also includes data from any CareTeams that have the Organization as a [managing organization](https://hl7.org/fhir/R4B/careteam-definitions.html#CareTeam.managingOrganization). A sample tag is provided below
+
+```json
+    {
+      "system": "https://smartregister.org/organisation-tag-id",
+      "code": "ca7d3362-8048-4fa0-8fdd-6da33423cc6b",
+      "display": "Practitioner Organization"
+    }
+```
+### Sync by Practitioner Location
+This sync strategy is based on the FHIR Location and delivers resources tagged with the Location ID of the Location that the logged in user's FHIR Practitioner is assigned to. 
+- This sync strategy also includes data from all the subordinant locations of the Location that the Practitioner is assigned to (ie if `Location B.partOf = Location A` and we are syncing data from `Location A`, any data assigned to `Location B` is also included). A sample tag is provided below
+
+```json
+     {
+      "system": "https://smartregister.org/location-tag-id",
+      "code": "ca7d3362-8048-4fa0-8fdd-6da33423cc6b",
+      "display": "Practitioner Location"
+    }
+```
+### Sync by Related Entity Location
+This strategy uses location information related to other entities (e.g Patient, Family / Group, Service Point), ensuring that data linked to specific locations associated with those entities is synced. 
+- This sync strategy also includes data from all the child locations linked to the Related Entity Location. A sample tag is provided below
+
+```json
+    {
+      "system": "https://smartregister.org/related-entity-location-tag-id",
+      "code": "33f45e09-f96e-41d3-9916-fb96455a4cb2",
+      "display": "Related Entity Location"
+    }
+```
diff --git a/docs/features/admin-dashboard-features/readme.mdx b/docs/features/admin-dashboard-features/readme.mdx
@@ -7,7 +7,7 @@ sidebar_label: Admin Dashboard Features
 
 This guide outlines the steps to follow to manage Users, Care Team, Organization and Locations on OpenSRP. The platform is named FHIR Web and interacts with the Keycloak and HAPI FHIR servers.
 
-### Prerequisites
+## Prerequisites
 To navigate through this user guide, you are required to have admin access to the admin portal. In addition, you will need to understand how the different entities tie to each other. Below is a summary.
 
 A user represents anyone who will interact with the FHIR SDK-based App or FHIR Web. A user is assigned permission through roles defined in Keycloak which maintains all user authentication. Keycloak defines permissions in the form of roles that can be assigned to a user based on the activities they are expected to carry out. Due to the long list of roles, FHIR Web presents the option to create user groups, which represent a collection of roles that can be assigned to a user.
@@ -22,7 +22,7 @@ The steps laid out below ensure a user is able to interact with the
 6. Assign the created careteam to the respective Organization
 7. Assign Users to the careteam
 
-### Access to Admin portal (OpenSRP 2 web portal)
+### Access to Admin portal
 
 1. Access the OpenSRP 2 web portal through the url:
     a. Production - https://web.ProjectName-production.smartregister.org/
@@ -44,7 +44,7 @@ The steps laid out below ensure a user is able to interact with the
 6. Patients Management: helps the users to view the patient registered on App and synced to the server.
 7. Main landing page: has shortcuts to the side menu items.
 
-### User Management
+## User Management
 The OpenSRP web provides the ability to create users, user groups and assign users to user groups. User groups allows categorization of users with common user roles, by default there are two user groups; Provider user group which refers to clinicians whose main role is to collect immunization data on the mobile application while the Super User group refers to users who have all the privileges such as managing  users, teams and locations.
 
 ![user-management](/img/admin_dashboard_features/2.jpg)
@@ -107,7 +107,7 @@ Fields with Asterisks are a must to fill.
 
 10. Click ‘set password’
 
-### How to update User’s detail
+### How to update user’s detail
 
 1. Click on the ‘User management’ menu item or on the main landing page
 2. This will load a page with a list of existing Users.
@@ -122,7 +122,7 @@ Fields with Asterisks are a must to fill.
 
 5. Click ‘Save.
 
-### Location Management
+## Location Management
 This piece of functionality helps the users create locations and add any parent locations for each location. This package is based on the location resource in FHIR. A location hierarchy is defined by assigning parent locations. If a parent is not selected then the location is taken as a root location in the hierarchy.
 
 ### How to create a Location unit
@@ -146,14 +146,14 @@ You can access this page by clicking on the location management menu on the side
 
 3. Click ‘Save.
 
-### Care Team Management
+## Care Team Management
 
 This piece of functionality helps the users create CareTeam to be used to administer the different services in the FHIR Core apps.
     1. This package also allows the different practitioners  to be added to the CareTeam
     2. This package also allows the different groups to be added to the CareTeam
 
-### How to update a Location unit
-You can access this page by clicking on the CareTeam management menu on the sidebar. This will load a page with a list of existing CareTeam. Below is a sample of how the page would look like.
+### How to update a Care Team unit
+You can access this page by clicking on the Care Team management menu on the sidebar. This will load a page with a list of existing CareTeam. Below is a sample of how the page would look like.
 
 ![fhir-care-team](/img/admin_dashboard_features/16.jpg)
 
@@ -166,7 +166,7 @@ You can access this page by clicking on the CareTeam management menu on the side
 4. To assign a Group to that particular CareTeam, click on the ‘Subject’ field and select the groups.
 5. Click ‘Save'.
 
-### How to update CareTeam’s detail
+### How to update Care Team’s detail
 You can access this page by clicking on the CareTeam management menu on the sidebar. This will load a page with a list of existing CareTeam. Below is a sample of how the page would look like.
 
 ![update-care-team](/img/admin_dashboard_features/18.jpg)
@@ -178,7 +178,7 @@ You can access this page by clicking on the CareTeam management menu on the side
 2. This will load a form that allows you to update the CareTeam’s details. Fields with Asterisks are a must to fill.
 3. Click ‘Save.
 
-### Team Management
+## Team Management
 The FHIR web team(organization) management package provides the ability to perform the following functions.
 1. Creating teams (organization).
     a. Assign users to teams (organization).