Responsible team member	Christina Riley
Current Team Member
Status
Targeted release Date
Scoping Complete Date
Jira Issue
LOE
Priority


Responsible Person:	Christina Riley
Other parties to review/input:	Annie Martin Craig Appl Pedro Pagalday Olivares Vivek Agrawal Jins Thomas Pierre Dane
FYI:
Targeted release date:

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.

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

	Location edit unit (planning and client data collection)	Location View unit (dashboards)	Client (data collection)	Plan create/edit	View dashboards/reporting	Administrator
Thailand SubDistrict VBDU	Provincial	Provincial	Y (for Household, RACD, Net, BCC)	Y (add/edit)	Y	N
Thailand District VBDU	Provincial	Provincial	Y (for Household, RACD, Net, BCC)	Y (add/edit)	Y	N
Thailand Province VBDC	Province	Province	Y (for Mosquito and larvae)	(Y add/edit)	Y	N
Thailand Regional ODPC	Region	Region	N	Y (add/edit)	Y	N
Thailand National	National	National	N	Y ( only edit)	Y	Y
Namibia District	District	District	Y	Y	Y	N
Namibia Region	Region	Region	N	Y	Y	N
Namibia National	National	National	N	Y	Y	Y

Requirements

Location/administrative hierarchy units must be defined.
Users and user names / passwords must be defined.
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 Pollard Sameen Babur please fill out table above for Namibia
  3. AM: Derek Pollard please fill out table above for Zambia
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.
User loading into Reveal must be defined - currently this comes from the BIOPHICS holding tables (Pierre Dane looking into this)
Users must be mapped into teams and assigned operational areas/operational areas assigned to teams - see Thailand Team/User Mapping
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.

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
Add the ability to log requests through the proxy
We need to develop a proxy in the OpenSRP server that supports GET /user requests so we can link team members (practitioners) to users
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.

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
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
Add the ability to assign multiple teams to a single location in OpenMRS
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:

OpenMRS	FHIR
Team	Organization
Team Member	Practitioner
Team Role	PractitionerRole
Location	Location

Domain objects

Organization

Name	Description	DataType	Notes
identifier	This is the identifier of the organization	GUID
active	This is a boolean status of whether this organization is active	boolean
type.coding.system	The system referred to the code	string	value = "organization-type"
type.coding.code	The code referred to in the system	string	value = "team"
type.coding.display	The display of the code	string	value = "Team"
name	The name of the organization	string

FHIR Links:

Sample Organization JSON

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

Practitioner

Name	Description	DataType	Notes
identifier	This is the identifier of the practitioner in the OpenSRP system	GUID
active	This is a boolean notifying if the practitioner is active	boolean
name	This is the human name of the practitioner	string
userUuid	This is the uuid of the user from OpenMRS (not in FHIR spec)	GUID	We will use this to link practitioners to users in OpenMRS

Sample Practitioner JSON

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

PractitionerRole

Name	Description	DataType	Notes
identifier	This is the identifier of the practitionerRole in the OpenSRP system	GUID
active	This ia boolean notifying if the practitionerRole is active	boolean
organization	This is a reference to the organization linked to this practitionerRole	reference	i.e. "Organization:{identifier}"
practitioner	This is a reference to the practitioner linked to this practitionerRole	reference	i.e. "Practitioner:{identifier}"
code	This is the type of role the practitioner plays based on the practitioner-role value set	reference	Values include doctor, nurse, community health worker
location	This is a reference to a location where this role is active	reference	i.e. "Location:{identifier}"

Sample PractitionerRole JSON

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

Name	Description	DataType	Notes
properties.managingOrganization	This is a one to many relationship between the location and the managing organization	reference	i.e. ("Location:{identifier}"

Sample Location JSON with managing 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

GET Organization - Get a list of organizations
GET Organization/{identifier} - Get a specific organization details by their identifier
PUT Organization - Update the organization (includes archiving)
POST Organization - Create an organization
GET Practitioner - Get a list of practitioners
GET Practitioner/{identifier} - Get a specific practitioner by their identifier
PUT Practitioner - Update the practitioner
POST Practitioner - Create a practitioner
GET PractitionerRole - Get a list of practitionerRoles
GET PractitionerRole/{identifier} - Get a specific practitionerRole
PUT practitionerRole - Update a practitionerRole
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?

Browser not supported