This page documents the process for managing teams in Reveal. This document is temporary in nature until we deliver the ability to perform these actions in the Web UI.

Prep

We need to prepare team information before we are able to configure it.

1. We need all locations with their geography so they can be loaded into Reveal and OpenMRS
2. We need a complete list of users
3. We need a list of teams linked to the location where they will work. This can be at the operational area level or one up (i.e. district, village)

Create users in OpenMRS

The first step is to create users in OpenMRS and copy their OpenMRS UUID into an excel spreadsheet so they can be used later. You will need the OpenMRS Username, Name and UUID to be able to link the OpenMRS user to a Practitioner in Reveal

• Login to the OpenMRS system (you will see the OpenMRS legacy UI)
• Click Administration
• Click Manage Users in the left column
• Click Add User
• Click the Next button under the text "Create a new person"
• Complete the form
  • Make sure the Roles include "Provider"
• Click Save User
• Search for the user in the Manage users page
• Click the user's Id to enter their record
• Scroll down and click Show Advanced Options
• Copy the UUID (in grey) to a spreadsheet for reference later
  

Create locations in OpenMRS and Update Reveal with properties.OpenMRS_Id

We currently need to create locations in OpenMRS and ensure they are linked to Reveal's location using the OpenMRS_Id property in the GeoJSON. These locations are often created in bulk through the import scripts defined by VitalWave. The VitalWave scripts do not add the OpenMRS_Id property to the list because we only import a subset of the total locations in a country to OpenMRS. As a result, we need to get a list of the locations that were imported into OpenMRS and get their UUIDs into Reveal.

Steps

• Get the list of OpenMRS location UUIDs per location that was imported from VitalWave
• Match those locations to Reveal and run a Nifi processor group that:
  • Define a list of Reveal locations to query
  • GET the location from Reveal 
  • (https://reveal-stage.smartregister.org/opensrp/rest/location/{identifier}?is_jurisdiction=true)
  • Check to see if the OpenMRS_Id property is already on the location
  • Update the location to add the OpenMRS_Id property
  • PUT the location back to Reveal (https://reveal-stage.smartregister.org/opensrp/rest/location/?is_jurisdiction=true)

Create Practitioners in Reveal

We need to create practitioners in Reveal. Practitioners are effectively users in OpenMRS.

{
  "identifier": "437cc699-cfa7-414c-ba27-1668b6b517e6",
  "active": true,
  "name": "Test User Lusaka",
  "userId": "cad04f1e-9b05-4eac-92ce-4b38aa478644",
  "username": "lusaka"
}

Steps:

• Copy all of the information from OpenMRS into Excel
• Create the JSON above in excel
  • (You can copy and paste unique identifiers to excel from an online GUID generator if you like)
  • Sample Excel Formula: ="{""identifier"": """&A2&""",""active"": true,""name"": """&C2&""",""userId"": """&D2&""",""username"": """&B2&"""},"

• POST this JSON to the /practitioner endpoint (one user at a time) (https://reveal-stage.smartregister.org/opensrp/rest/practitioners)

Create Organizations in Reveal

The next step is to create organizations in Reveal. An organization can be defined as anything. We define these as teams who work together and can be assigned together to a subset of operational areas in the system. In Namibia, each team is assigned to a number of clusters and users are assigned to teams. We ultimately need a list of users, teams that they are assigned to and locations where they are assigned, either a list of all locations, or districts.

{
  "identifier": "fcc19470-d599-11e9-bb65-2a2ae2dbcce4",
  "active": true,
  "name": "The Luang",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/organization-type",
        "code": "team",
        "display": "Team"
      }
    ]
  }
}

Steps:

• Create the organization JSON as above
• POST to the /organization endpoint (https://reveal-stage.smartregister.org/opensrp/rest/organization)

Create Practitioner Roles

Practitioner Roles link practitioners to organizations. This is how we assign users to teams in the new process The setup involves linking the practitioners to their organization, often done in excel.

{
  "identifier": "85771b10-1d77-40c8-bdf2-d6eb74380f76",
  "active": true,
  "organization": "0c7fd90f-5b99-4ed9-b337-0b42d51eab97",
  "practitioner": "d7c9c000-e9b3-427a-890e-49c301aa48e6",
  "code": {
    "text": "Community Health Worker"
  }
}

Steps:

• Create the practitionerRole for each practitioner
• POST to the /practitionerRole endpoint (https://reveal-stage.smartregister.org/opensrp/rest/practitionerRole)

Create a Plan

Make sure to create a plan in the system. This can be done in the web UI. Once posted, you need to get a list of plans and extract the identifier by GET /plans endpoint.

Create Location and Plan Assignments

This is the process for assigning organizations to locations and plans. We do this so that we can perform role based access controls based on the plans where the organization is assigned. Users roles are linked to the organization and the organization is what's linked to the plan and location.

[{
  "organization": "",
  "jurisdiction": "304cbcd4-0850-404a-a8b1-486b02f7b84d",
  "plan": "144f4d78-a406-5a4f-a45c-8f2b66919e35",
  "fromDate": "2019-09-17T00:00:00.000Z",
  "toDate": "2019-12-01T00:00:00.000Z"
}]

Steps:

• Create the JSON as defined above (usually done in Excel)
• POST the entire list of changes to the endpoint, we don't post them individually (https://reveal-stage.smartregister.org/opensrp/rest/organization/assignLocationsAndPlans)