Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
Child pages
  • Patient Resource
Skip to end of metadata
Go to start of metadata

This is the API documentation  for the OpenMRS FHIR Module , Patient Resource. 

Patient Resource provides Demographics and other administrative information about a person or animal receiving care or other health-related services. For more information please refer http://hl7-fhir.github.io/patient.html


Shown below is an example of how an OpenMRS Patient objects would map to FHIR Patient resource, as proposed by Grahame Grieve.

The left side of the relationship indicates the OpenMRS attribute, while the right indicated the FHIR resource mapping.

Patient
 Integer patientId :: n/a - unused
 Set<PatientIdentifier> identifiers :: Patient.identifier
   Integer patientIdentifierId :: not mapped
   Patient patient :: not mapped
   String identifier :: patient.identifier.value
   PatientIdentifierType identifierType ::
   Integer patientIdentifierTypeId :: mapping table, type id ==> URL
   String format :: not mapped
   Boolean required = Boolean.FALSE :: not mapped
   String formatDescription :: not mapped
   Boolean checkDigit = Boolean.FALSE :: not mapped
   String validator :: not mapped
   LocationBehavior locationBehavior :: not mapped
   UniquenessBehavior uniquenessBehavior :: not mapped
   Location location :: Patient.identifier.assigner (URL)
   Boolean preferred = false :: if true, Patient.identifier.use = usual
Set<PersonAddress> addresses = null :: Person.address
  Integer personAddressId :: not mapped
  Person person :: not mapped
  Boolean preferred = false :: Patient.address.use ? mapping
  String address1 :: Person.address.line
  String address2 :: Person.address.line
  String address3 :: Person.address.line
  String address4 :: Person.address.line
  String address5 :: Person.address.line
  String address6 :: Person.address.line
  String cityVillage :: Patient.address.city
  String countyDistrict :: Person.address.extension : "http://hl7.org/fhir/Profile/iso-21090#address-part-county", valueString
  String stateProvince :: Person.address.state
  String country :: Person.address.country
  String postalCode :: Person.address.zip
  String latitude :: Person.address.extension -> Location
  String longitude :: Person.address.extension -> Location
  Date startDate :: Person.address.period.start
  Date endDate ::  Person.address.period.end
Set<PersonName> names = null :: Person.name
  Integer personNameId :: not mapped
  Person person ::  not mapped
  Boolean preferred = false :: Patient.name.use = usual/old
  String prefix :: Person.name.prefix
  String givenName :: Person.name.given
  String middleName :: Person.name.given
  String familyNamePrefix :: folded into Patent.name.family (else, Patient.name.family with extension http://hl7.org/fhir/Profile/iso-21090#name-qualifer, valueCode = PFX)
  String familyName :: Person.name.family
  String familyName2 :: Person.name.family
  String familyNameSuffix :: Person.name.suffix
  String degree :: Person.name.suffix
Set<PersonAttribute> attributes = null ::
  integer personAttributeTypeId :: mapping table that defines how attributes map - whether existing elements or extensions
  String value :: depends on mapping
String gender :: Person.gender (mapped: code = M or code = F, code system is http://hl7.org/fhir/v2/0001)
Date birthdate :: Person.birthDate
Boolean birthdateEstimated = false :: Extension if worth mapping
Boolean deathdateEstimated = false :: Extension if worth mapping

Shown below is a sample FHIR Patient Resource.

FHIR Patient Resource
{
  "resourceType": "Patient",
  "id": "example",
  "identifier": [
    {
      "use": "usual",
      "label": "MRN",
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345",
      "period": {
        "start": "2001-05-06"
      },
      "assigner": {
        "display": "Acme Healthcare"
      }
    }
  ],
  "name": [
    {
      "use": "official",
      "family": [
        "Chalmers"
      ],
      "given": [
        "Peter",
        "James"
      ]
    },
    {
      "use": "usual",
      "given": [
        "Jim"
      ]
    }
  ],
  "telecom": [
    {
      "use": "home"
    },
    {
      "system": "phone",
      "value": "(03) 5555 6473",
      "use": "work"
    }
  ],
  "gender": "male",
  "birthDate": "1974-12-25",
  "deceasedBoolean": false,
  "address": [
    {
      "use": "home",
      "line": [
        "534 Erewhon St"
      ],
      "city": "PleasantVille",
      "state": "Vic",
      "postalCode": "3999"
    }
  ],
  "active": true
}

Available RESTful web services for the Patient Resource supported by the API

GET(Search Requests)

Operations
URLDescription
/ws/fhir/Patient/{id}Above request will fetch the Patient for the given unique uuid. Here id represents, the logical resource id associated with the resource.

/ws/fhir/Patient?identifier={identifier} or

/ws/fhir/Patient?identifier={identifier|identifierType}

Above request will fetch all the Patients using the given identifier value. This will give a List of Patient as the response. Here identifier parameter represents, patient identifier.
/ws/fhir/Patient?_id={id}Above request will fetch all the Patients using the given id value. This will give a List of Patients as the response. Here _id parameter represents, the logical resource id associated with the resource.
/ws/fhir/Patient?name={name}Above request will fetch all the Patients using the name parameter. This will give a List of Patients as the response. Here name parameter represents the name of the patient.
/ws/fhir/Patient?given={givenName}Above request will fetch all the Patients using the given name. This will give a List of Patients as the response. Here name parameter represents the given name of the patient.
/ws/fhir/Patient?active={value}Above request will fetch all the Patients using the active parameter. This will give a List of Patients as the response. Here active parameter represents whether the patient record is active.

POST (Create Requests)

Operations
URLDescription
/ws/fhir/Patient

Create a Patient Resource for the given representation.

one none delete name and gender attributes are compulsory

/ws/fhir/Patient/$everything

With body : <Parameters xmlns="http://hl7.org/fhir"/

This request will return bundle all the clinical resources that associate with patient which associate with given patient Id

DELETE (Delete Requests)

Operations
URLDescription
/ws/fhir/Patient/{id}This request will retire the Patient with the given uuid. If the resource does not exist, a 404 is returned. If the OpenMRS API refuses to retire the patient, the status code 405 is returned.

PUT (Update Requests)

Operations
URLDescription
/ws/fhir/Patient/{id}
  • If the Patient with the given uuid exists, update the existing attributes according to the representation.
  • If the Patient with the given uuid doesn't exists, Create a Patient Resource with the given uuid.

Update operation cannot update an existing name or address. If you don't wish to update an existing name or address, you should keep those fields empty. All names and addresses contain in the representation will be added to the Person resource, as new names and addresses.

Conditional Update
/ws/fhir/Patient?[search parameters]

When the server processes this update, it performs a search using its standard search facilities for the resource type, with the goal of resolving a single logical id for this request. The action it takes depends on how many matches are found:

  • No matches: The server performs a create operation
  • One Match: The server performs the update against the matching resource
  • Multiple matches: The server returns a 412 Precondition Failed error indicating the the client's criteria were not selective enough

Ex: /ws/fhir/Patient?name=John

/ws/fhir/Patient?givenName=John

 /ws/fhir/Patient?identifier=432MN

OpenMRS specific constrains

  • When you POST a Patient name and gender attributes are compulsory. In the name attribute there should be atleast one "usual"/"official" name.
  • When you Update an existing Patient Name/Adresses, the existing names and addresses will be retired and new name/addresses will be created. 
  • A valid Patient identifier is required.

Samples

{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "system": "Old Identification Number",
      "value": "103"
    }
  ],
  "name": [
    {
      "use": "usual",
      "family": [
        "Patient"
      ],
      "given": [
        "Johnny"
      ],
      "prefix": [
        "Mr."
      ],
      "suffix": [
        "Mr."
      ]
    }
  ],
  "gender": "male",
  "birthDate": "1975-01-01",
  "deceasedBoolean": false,
  "address": [
    {
      "use": "home",
      "line": [
        "555 Johnson Rd.",
        "Apt. 555"
      ],
      "city": "Indianapolis",
      "state": "IN",
      "postalCode": "46202",
      "country": "USA"
    }
  ],
  "active": true
}
  • No labels