...

...

...

Overview

OpenSRP team assignment happens in OpenMRS. OpenMRS has an independent user, location and team management system that we use for role based access controls in Reveal. Team assignment is used to identify which operational areas and plans the user should have access to. If a user is part of a team, they can see locations that that team has access to and they can collect information against the plans that have that jurisdiction assigned to them. So, if a user is assigned to the Tha Luang Village Team, which has been assigned to 3 of the 5 operational areas within that village, they will be able to see the three operational areas and all active plans that are assigned to those three operational areas as well.

End-to-End First Time Setup Steps:

• Create all locations in OpenMRS
• Create all teams in OpenMRS (We need to determine the appropriate level)
• Copy the team UUID to the OpenMRS location attribute labeled "team_id"
• Create a user in OpenMRS
• Assign that user to the team

Regular Admin Tasks:

• Reassign users to different teams within the team management module so they can work in different geographic areas
• Archive users that are in teams in the team management module so they don't have access to those operational areas anymore
• Create new users and add them to a team
• Move teams from one location to the next by changing the OpenMRS location properties so we can move teams around

OpenMRS Team and Location Example

Below is a worked out example of structuring the locations and teams in OpenMRS.

Below is a sample hierarchy in OpenMRS. We will focus on the Two Two Too Release Village which has 5 operational areas (Link)

Image Removed 

Below is a sample team for the Two Two Two Release Village. The team is assigned to the Two Two Two Release Village in the team management module. (Link)

Image Removed

Below is the list of team members assigned to that team (Link)

Image Removed

Below is the Two Two Two Release Village OpenMRS location (Link)

Image Removed

Below is one of the operational areas within that village TwoTwoTwo_01 (Link)

Image Removed

Note that you can see the UUID of the team in the team_id field. We need to maintain these on all operational areas.

We can access all of this information through the OpenMRS API, which is documented elsewhere on the wiki.

Overarching Questions

We need to figure out a number of things as part of this specification. This section defines some of those overarching questions that lead to the eventual design of the solution.

1. At which geographic level should we assign teams?
   1. Currently we assign them at the operational area level in locations
   2. We assign teams at the village level in the team management module
   3. What's the difference here?
2. Are there plan-type specific requirements for assigning teams (FI vs IRS vs ?)
3. Can we assign multiple Teams to a single Jurisdiction? (OA, FA, Spray Area)

Notes

...

Overview

OpenSRP team assignment happens in OpenMRS. OpenMRS has an independent user, location and team management system that we use for role based access controls in Reveal. Team assignment is used to identify which operational areas and plans the user should have access to. If a user is part of a team, they can see locations that that team has access to and they can collect information against the plans that have that jurisdiction assigned to them. So, if a user is assigned to the Tha Luang Village Team, which has been assigned to 3 of the 5 operational areas within that village, they will be able to see the three operational areas and all active plans that are assigned to those three operational areas as well.

End-to-End First Time Setup Steps:

• Create all locations in OpenMRS
• Create all teams in OpenMRS (We need to determine the appropriate level)
• Copy the team UUID to the OpenMRS location attribute labeled "team_id"
• Create a user in OpenMRS
• Assign that user to the team

Regular Admin Tasks:

• Reassign users to different teams within the team management module so they can work in different geographic areas
• Archive users that are in teams in the team management module so they don't have access to those operational areas anymore
• Create new users and add them to a team
• Move teams from one location to the next by changing the OpenMRS location properties so we can move teams around

OpenMRS Team and Location Example

Below is a worked out example of structuring the locations and teams in OpenMRS.

Below is a sample hierarchy in OpenMRS. We will focus on the Two Two Too Release Village which has 5 operational areas (Link)

Image Added 

Below is a sample team for the Two Two Two Release Village. The team is assigned to the Two Two Two Release Village in the team management module. (Link)

Image Added

Below is the list of team members assigned to that team (Link)

Image Added

Below is the Two Two Two Release Village OpenMRS location (Link)

Image Added

Below is one of the operational areas within that village TwoTwoTwo_01 (Link)

Image Added

Note that you can see the UUID of the team in the team_id field. We need to maintain these on all operational areas.

We can access all of this information through the OpenMRS API, which is documented elsewhere on the wiki.

Overarching Questions

We need to figure out a number of things as part of this specification. This section defines some of those overarching questions that lead to the eventual design of the solution.

1. At which geographic level should we assign teams?
   1. Currently we assign them at the operational area level in locations
   2. We assign teams at the village level in the team management module
   3. What's the difference here?
      SG: The Difference is because we can only assign teams to OpenMRS Locations in OpenMRS. However on Reveal Jurisdictions(Spatial Locations) are used. We have to find a way of matching these two since we are using OpenMRS locations to control access to Reveal. We decided to use Operational Area tags since those would be easier to match to Reveal jurisdictions. The other levels of Locations on OpenMRS may not be necessarily mapped to Jurisdictions which are administrative locations. However this can be amended if its guaranteed that location Hierarchy in OpenMRS matches the jurisdictions, then its possible to tag `team_id`  at Higher levels than Operational Area
2. Are there plan-type specific requirements for assigning teams (FI vs IRS vs ?)
   1. AM: IRS will be more dynamic than FI, however, requirements don't differ. Right now, the build seems to be that team assignment to plans happens automatically with FI, thought with IRS these assignments will be done by an end-user. We
3. Can we assign multiple Teams to a single Jurisdiction? (OA, FA, Spray Area)
   1. AM: We need to be able to do this.

IRS Team Assignment Workflow/Considerations

1. 1) Teams should be assigned either at operational area level OR a higher level in the hierarchy above that gives access to all below. Workflow expectation is that there is daily/weekly internet connectivity and teams will be reassigned
   1. Team assignment Workflow:
      1. All areas that are to be visited in next day/week are assigned by a manager. This frequency of assignment is determined based on connectivity as well as the IRS Manager bandwidth to be doing these assignments. Some managers may do this daily. Some may do it only weekly.
      2. Users log in, sync any data from previous day or week's work. Then re-sync the full list of operational areas assigned. 
         1. Requirement: we need to have a way to know if syncing (uploading data and downloading data) is complete (not specific to team assignment dev but necessary for functional workflow)
      3. Users on the client, select the OAs in the hamburger menu that they plan to work in in the next day/week (network dependent, if network every day, can do this daily. When they know they are going out of area for x amount of time, they need to sync enough areas for x amount of time). Sync the plans for each OA (sync all plans if multiple for one OA), sync imagery, sync the tasks.
         
         1. Question: Apart form the user burden of selecting from a long list (we think this won't be huge since they will only have to do this 2 - 3 times per day), does syncing a long list of operational areas take a lot of data/space (if we are not syncing their plans or data). Need to balance the frequency of syncing/internet access with the # of areas whose data is synced to the tablet (limited by connectivity)
   2. Team creation - near-term/immediate, we will create one large team for all IRS teams within a district. This means all users will have access to all operational areas that are assigned.
   1. Requirement: creating multiple teams and being able to change which users are on which team at any time
      1. This necessitates having a view in the web UI to see which teams are assigned where.
   3. 1. Question: Can team assignment be done at other levels of Jurisdiction higher than OA/village that would then allow access to all OAs within that jurisdiction?
      2. Requirement: users should have a permission hierarchy for submitting data on the client and a separate permission for viewing data on the WebUI

FI Team Assignment Workflow/Considerations

Teams should be assigned to the district level, which gives them access to all operational areas//villages within a district or province.

These assignments will be mostly static (won't change daily or weekly).

Notes

• Summary: Need to assign users/teams to geographic hierarchies, define user addition/deletion, and define permissions as appropriate.

User Type Table - permissions need to be coming from OpenMRS

Requirements

1. Location/administrative hierarchy units must be defined.
2. Users and user names / passwords must be defined.
3. A team hierarchy structure must be defined (i.e. team leader, team member) if appropriate
   1. QUESTION: Does Thailand want a flat team/user structure or something more hierarchical?
      1. AM: Christina Riley Pedro Pagalday Olivares please fill out the table above
      2. AM: Derek PollardSameen Babur please fill out table above for Namibia
      3. AM: Derek Pollard please fill out table above for Zambia
4. User permissions must be defined if appropriate
   1. QUESTION: Do all team members have access to all parts of the FI planning module, web dashboards, and mobile client?
      1. Craig Answered 7 Aug: Currently, the answer is no. We separate the web users access controls from the mobile client.. We separate the web users access controls from the mobile client.
      2. AM: Added Requirement: We need to differentiate access to creating/editing plans piece and access to viewing plans in progress and viewing reporting
   2. QUESTION: Can all users access all geographic administrative units? Or are they restricted to a specific OU and below?
      1. Craig Answered 7 Aug: They are restricted to the location of the team where they are assigned
      2. AM: Added Requirement: We need to differentiate access to locations for viewing versus editing data. For example, as a district I need to edit data only in my district but see data for the whole country.
5. User loading into Reveal must be defined - currently this comes from the BIOPHICS holding tables (Pierre Dane looking into this)

6. Users must be mapped into teams and assigned operational areas/operational areas assigned to teams - see Thailand Team/User Mapping

7. Users and teams must be added to OpenMRS and then linked to their locations

   1. QUESTION: Is this the ideal way to do this?
      1. Craig Answered 7 Aug: No, but it's what we currently have in place
   2. QUESTION: How are users/teams deleted?
      1. Craig Answered 7 Aug:
         1. Users can be archived in the OpenMRS UI
         2. User Team Association can be voided in the OpenMRS UI
         3. Teams can be voided in the OpenMRS UI 

...

1. We need to develop a proxy in the OpenSRP server that supports GET /location requests from the OpenMRS API for both the /location and /location/{UUID} endpoint. This proxy will be used to support getting the list of locations from the API
2. Add the ability to log requests through the proxy
3. We need to develop a proxy in the OpenSRP server that supports GET /user requests so we can link team members (practionerspractitioners) to users
4. Android client
   1. We need to expand the Android client to support selecting branching locations. So, if we set the team and the district level, the user will have access to all of the villages and all of the operational areas within those villages. So, a user should be able to walk the tree up to the level where the team is assigned and walk down into the locations below to choose their location.
   2. We may need to change how teams are related to login location in the Android client and any key generation.
      1. It's likely that teams will be roaming and it's possible that team members be swapped between teams regularly. We need to figure out if this impacts login and encryption

...

1. We need to develop a proxy in the OpenSRP server that redirects requests from the web app into the OpenMRS server. This proxy will require the following generic API endpoints
   1. GET teams
   2. (Optional if we want to show the team supervisor) GET teamMember
2. The team management API returns too much information. The module is based on the OpenMRS web services v1.1 and we should upgrade it to v1.2 which adds support for returning a custom response /team/team/v=custom(ENTER_PARAMETERS). This would allow us to request less information from the OpenMRS web API
3. Add the ability to assign multiple teams to a single location in OpenMRS
4. Add the ability to trickle down assignment down the geographic hierarchy when a team is assigned to a particular area

Option 2: Add team management to the OpenSRP server - moving forward with this option

Another option would be to support team assignment in the OpenSRP server. Team assignment will still be used for role based access controls. This is a new domain area for the OpenSRP server that has dependencies on OpenMRS entities. We will need to develop these features with a proxy that queries OpenMRS for the appropriate user information until users are created in OpenSRP, which is an activity that another team is working on for the platform.

...

System terminology crosswalk:

Domain objects

Organization

FHIR Links:

• organization-type code system
• codeableConcept data model

{
  "identifier": "",
  "active": 1,
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/organization-type",
        "code": "team",
        "display": "Team"
      }
    ]
  },
  "name": ""
}

Practitioner

{
  "identifier": "",
  "active": 1,
  "name": "",
  "userUuid": ""
}

PractitionerRole

{
  "identifier": "",
  "active": 1,
  "organization": "Organization:identifier",
  "practitioner": "Practitioner:identifier",
  "code": {
    "text": "Community Health Worker"
  },
  "location": "Location:identifier"
}

...

OpenSRP already has a location domain object, but we need to add a reference to the managingOrganization, which is how we can make the link to a particular organization and the locations that are managed by that organization

{
  "type": "Feature",
  "id": "ac7ba751-35e8-4b46-9e53-3cbaad193697",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [
            101.16691589355469,
            15.071501959533219
          ],
          [
            101.16562843322754,
            15.069429992157021
          ],
          [
            101.16485595703125,
            15.064913033351885
          ],
          [
            101.16489887237549,
            15.06147344997797
          ],
          [
            101.16584300994873,
            15.058531111669833
          ],
          [
            101.1687183380127,
            15.057702276638427
          ],
          [
            101.17352485656738,
            15.057743718466615
          ],
          [
            101.17944717407227,
            15.058365344921617
          ],
          [
            101.18399620056152,
            15.058945527975887
          ],
          [
            101.18910312652588,
            15.05977435816855
          ],
          [
            101.19189262390137,
            15.062923883477925
          ],
          [
            101.19154930114746,
            15.067109364744775
          ],
          [
            101.19086265563965,
            15.072703691366488
          ],
          [
            101.19060516357422,
            15.07481706536609
          ],
          [
            101.18863105773926,
            15.076806104068151
          ],
          [
            101.18541240692137,
            15.07693041836944
          ],
          [
            101.18215084075926,
            15.077261922817648
          ],
          [
            101.17717266082762,
            15.078090681677569
          ],
          [
            101.17421150207518,
            15.077759178521134
          ],
          [
            101.17215156555176,
            15.07659891340453
          ],
          [
            101.1685037612915,
            15.075355765184456
          ],
          [
            101.16691589355469,
            15.071501959533219
          ]
        ]
      ]
    ]
  },
  "properties": {
    "status": "Active",
    "parentId": "07b09ec1-0589-4a98-9480-4c403ac24d59",
    "externalId": "",
    "name": "TwoTwoTwo_03",
    "managingOrganization": [
      {
        "reference": "Organization:identifier"
      }
    ],
    "geographicLevel": 4,
    "version": 0
  },
  "serverVersion": 1563491965499
}

...