Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Status: In Progress

Owner: Craig Appl

This scoping document defines the processes and URL endpoints for interacting with the OpenMRS API in order to Create Read and Update locations and teams in OpenMRS.

Workflows

We need to deliver the following workflows that require interactions with the OpenMRS API

  1. Create OpenMRS locations based on the locations in Reveal
  2. Create Teams in OpenMRS
  3. Update OpenMRS location team_id attribute when a team is assigned in the Reveal web UI planning module

OpenMRS API Basics

BaseUrl: https://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1

Credentials: (This needs to be a user with superuser permissions at this time)

Authentication: OpenMRS uses basic auth for to start a session.

  1. Start a session
    1. GET BaseUrl/session
      1. The response will include a response header labeled Set-Cookie. Add the contents of this to subsequent responses
      2. In Nifi, we add a property to the InvokeHttp processor named Cookie with value ${Set-Cookie}
  2. End a session
    1. DELETE BaseUrl/session (with the cookie)

API documentation is available in the OpenMRS Legacy Admin Menu at https://openmrs.reveal-stage.smartregister.org/openmrs/module/webservices/rest/apiDocs.htm (Note that it takes some time to load because it builds it in realtime

Location Interactions

We need to Create, Read and Update locations in OpenMRS based on the location hierarchy that was loaded in to Reveal.

These interactions include the following properties:

Property in UITypeDescriptionUUIDSample POST code
Parent Location
This is the parent uuid of the location in OpenMRS.N/A
"parentLocation": {
    "uuid": "43a992e6-6b73-4767-b63f-abeb16737e27"
}
mspray_location_idattribute

3302b1cd-8e89-4d44-89ae-8a285f2c5583

{
  "attributeType": {
      "uuid": "802e4109-56d0-407f-adcb-ea3a082840fc"
  },
  "value": "055059f5-bbc2-489b-a573-56558556b5e0",
  "voided": false,
  "resourceVersion": "1.9"
}
team_idattribute

802e4109-56d0-407f-adcb-ea3a082840fc

{
  "attributeType": {
	"uuid": "802e4109-56d0-407f-adcb-ea3a082840fc"
  },
  "value": "055059f5-bbc2-489b-a573-56558556b5e0",
  "voided": false,
  "resourceVersion": "1.9"
}
CountrytagThis is a location tag that shows this is the country level. (Thailand: ADM 0)bdae8d24-df16-47c1-b589-ff58038ba7ca
{
  "uuid": "bdae8d24-df16-47c1-b589-ff58038ba7ca"
}
ProvincetagThis is a location tag that shows this is the provincial level. (Thailand: ADM 1)563fba34-7bfa-40f7-a0e0-9dca3c24bfec
{
  "uuid": "563fba34-7bfa-40f7-a0e0-9dca3c24bfec"
}
DistricttagThis is a location tag that shows this is a district level. (Thailand: ADM 2)19592b42-5181-49e4-85ab-2c502e7193c1
{
  "uuid": "19592b42-5181-49e4-85ab-2c502e7193c1"
}
Sub-districttag(Used in Botswana Only) This is a location tag that shows this is the sub-district level.7de14bdc-9e2a-4183-a6c9-3b506daac8e4
{
  "uuid": "7de14bdc-9e2a-4183-a6c9-3b506daac8e4"
}
VillagetagThis is a location tag that shows this is the village level (Thailand: ADM 3)55a54fc4-a6f2-4e14-9132-815687952804
{
  "uuid": "55a54fc4-a6f2-4e14-9132-815687952804"
}
Cantontag(Used in Thailand Only) This is a location tag that shows this is the canton level. (Thailand: ADM 4)de2ec1a0-1609-4071-af32-a91752956e95
{
  "uuid": "de2ec1a0-1609-4071-af32-a91752956e95"
}
Operational AreatagThis is a location tag that shows this is the operational area level. This is the lowest level in any hierarchy. (Thailand: ADM 5)22abf4d2-c138-463c-8c58-568343dd2b5f
{
  "uuid": "22abf4d2-c138-463c-8c58-568343dd2b5f"
}

GET BaseUrl/location

This returns a complete list of locations with just the minimal information

//GET BaseUrl/location?q=TwoTwoTwo_01

{
  "results": [
    {
      "uuid": "5398b9e0-71e8-42a5-892d-e031a9a32ca5",
      "display": "TwoTwoTwo_01",
      "links": [
        {
          "rel": "self",
          "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/location/5398b9e0-71e8-42a5-892d-e031a9a32ca5"
        }
      ]
    }
  ]
}


GET BaseUrl/location/{UUID}

This returns the full location

//GET BaseUrl/location/5398b9e0-71e8-42a5-892d-e031a9a32ca5

{
  "uuid": "5398b9e0-71e8-42a5-892d-e031a9a32ca5",
  "display": "TwoTwoTwo_01",
  "name": "TwoTwoTwo_01",
  "description": null,
  "address1": null,
  "address2": null,
  "cityVillage": null,
  "stateProvince": null,
  "country": null,
  "postalCode": null,
  "latitude": null,
  "longitude": null,
  "countyDistrict": null,
  "address3": null,
  "address4": null,
  "address5": null,
  "address6": null,
  "tags": [
    {
      "uuid": "22abf4d2-c138-463c-8c58-568343dd2b5f",
      "display": "Operational Area",
      "links": [
        {
          "rel": "self",
          "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/locationtag/22abf4d2-c138-463c-8c58-568343dd2b5f"
        }
      ]
    }
  ],
  "parentLocation": {
    "uuid": "43a992e6-6b73-4767-b63f-abeb16737e27",
    "display": "Two Two Two Release Village",
    "links": [
      {
        "rel": "self",
        "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/location/43a992e6-6b73-4767-b63f-abeb16737e27"
      }
    ]
  },
  "childLocations": [],
  "retired": false,
  "attributes": [
    {
      "uuid": "5ecc27f8-5529-4958-8e3d-c08f4608af67",
      "display": "mspray_location_id: 14e2a7a7-fd08-4bed-8cf8-1eeaed303eda",
      "links": [
        {
          "rel": "self",
          "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/location/5398b9e0-71e8-42a5-892d-e031a9a32ca5/attribute/5ecc27f8-5529-4958-8e3d-c08f4608af67"
        }
      ]
    },
    {
      "uuid": "faba93d1-691e-45ce-8612-4a22e2a251dd",
      "display": "team_id: 055059f5-bbc2-489b-a573-56558556b5e0",
      "links": [
        {
          "rel": "self",
          "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/location/5398b9e0-71e8-42a5-892d-e031a9a32ca5/attribute/faba93d1-691e-45ce-8612-4a22e2a251dd"
        }
      ]
    }
  ],
  "address7": null,
  "address8": null,
  "address9": null,
  "address10": null,
  "address11": null,
  "address12": null,
  "address13": null,
  "address14": null,
  "address15": null,
  "links": [
    {
      "rel": "self",
      "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/location/5398b9e0-71e8-42a5-892d-e031a9a32ca5"
    },
    {
      "rel": "full",
      "uri": "http://openmrs.reveal-stage.smartregister.org/openmrs/ws/rest/v1/location/5398b9e0-71e8-42a5-892d-e031a9a32ca5?v=full"
    }
  ],
  "resourceVersion": "2.0"
}

POST BaseUrl/location Template

This 





  • No labels