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.

...

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

...

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

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

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?
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. 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
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 (practioners) 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

This section contains notes on what needs to be developed that were generated 23rd July to support estimating:

...

• Verify the Thailand Team/User Mapping to ensure all information needed is captured.

...

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

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.

Image Added

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