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)

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)

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

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

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

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.
      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 

Examples

Views

We anticipate the following views to be impacted on with the creation of this feature:

Mock-ups

Software Requirements Specification(s)

We have a number of technical decisions to make depending on the complexity of the path forward. Ultimately the goal is to have team management as part of the Reveal Web UI and we need to determine if the short term needs warrant delivering an enhancement to the current process or a shift of team management to OpenSRP.

Core technical requirements:

• We must retain the capability to assign teams to locations as a mechanism for role based access controls
• We need the ability to assign multiple teams to a single location
• Users must be assigned to teams
• We need the ability to assign teams to multiple locations and display
• (I'm not sure about this) We need the ability to link patients to teams so we can determine the list of patients who are assigned to teams.

Software Development Required Regardless of the option selected

We need to develop the following features regardless of the option that's selected because we are dependent on OpenMRS at this time.

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 (practitioners) 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

Option 1: Update OpenMRS team management module

OpenSRP relies on the team management module as described above. This module has limitations that prevent us from delivering team management as is needed from Reveal. This section identifies the requirements for updating the team management module to support team assignment in the web. The team management module is currently used in OpenSRP for role based access controls. If a user is assigned to a team and that team is assigned to a location, the user has access to that location. There is currently a 1-to-1 map between a team at the village level. Currently, OpenSRP only supports assigning team_id to a location, so multiple teams are not able to work on the same location.

Current Team Management Module Data Structure

Domain Objects

• Team
  • teamId - integer
  • teamIdentifier - string
  • teamName - string
  • supervisor - TeamMember
  • location - location
• TeamMember
  • teamMemberId - integer
  • identifier - string
  • team - Team
  • person - Person
  • joinDate - date
  • leaveDate - date
  • locations - set<locations>
  • patients - set<teamMemberPatientRelation>
  • teamRole - teamRole
  • isDataProvider - boolean
• TeamMemberPatientRelation
  • teamMemberpatientRelationId - integer
  • teamMember - TeamMember
  • status - string
  • patient - Patient
  • date - dateAssigned
  • location - Location
  • reason - String
• TeamRole
  • teamRoleId - integer
  • name - string
  • identifier - string
  • ownsTeam - boolean
  • reportTo - TeamRole

Work to be developed

We need to develop the following features to support continued use of the team management module.

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.

We believe it's appropriate to implement a FHIR pattern in the OpenSRP server so that we can better support FHIR resources in our platform as part of this process. The mCSD standard is a good model for associating people with locations that they work. We will not implement the full mCSD standard at this time. We will implement the relationship between an organization, practitioner and location.

The diagram below is taken from the mCSD standard and it shows the relationship between the domain objects in FHIR. We will implement practitioners who area member of an organization as defined in the practitionerRole, organizations which are independent domain objects and we will update locations so they can be linked to a managingOrganization. We will not implement services at this time.

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"
}

User

We need to retain a link to the user in the OpenMRS system so that we can ensure the role based access controls and authentication provided by OpenMRS is retained. We need to make sure that the practitioner link to the userUuid is retrieved from the OpenMRS system as are all other interactions (this was defined above in the section labeled Software development required regardless of the option selected).

Location

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
}

API Endpoints

We need to create the following API endpoints in the OpenSRP server

1. GET Organization - Get a list of organizations
2. GET Organization/{identifier} - Get a specific organization details by their identifier
3. PUT Organization - Update the organization (includes archiving)
4. POST Organization - Create an organization
5. GET Practitioner - Get a list of practitioners
6. GET Practitioner/{identifier} - Get a specific practitioner by their identifier
7. PUT Practitioner - Update the practitioner
8. POST Practitioner - Create a practitioner
9. GET PractitionerRole - Get a list of practitionerRoles
10. GET PractitionerRole/{identifier} - Get a specific practitionerRole
11. PUT practitionerRole - Update a practitionerRole
12. POST practitionerRole - Create a practitionerRole

Justification

Need to be able to add users to the system and do so within a given hierarchy for permission-level setting and appropriate task flow.

Dependencies

• User names and passwords are currently in BIOPHICS holding tables 
• QUESTION: Will this need to be updated from the BIOPHICS side? What input format is needed for new usernames & passwords for integration between Reveal and BIOPHICS?

Questions