New Zealand HPI Implementation Guide
0.9.0 - CI Build
New Zealand HPI Implementation Guide, published by Ministry of Health. This is not an authorized publication; it is the continuous build for version 0.9.0). This version is based on the current content of https://github.com/HL7NZ/hpi/ and changes regularly. See the Directory of published versions
The following notes apply to all resources in this implementation.
Resources can be expressed either as Json or XML, and both formats are supported by this implementation.
All of the FHIR resources in this implementation have both an id and an identifier.
The id is the ‘physical’ identity of the resource, and the identifier is the business identifier.
In this implementation, the id of the resource will always be the same as the value of the identifier assigned by the HPI with a use value of ‘official’. (There will only ever be a single identifier with this use type and system in a resource). Thus the id for the resource above would be ‘99ZZZZ’, and the url something like:
http://hpi.moh.nz/fhir/Practitioner/99ZZZZ
(The actual root url for the HPI has not yet been determined).
This design allows an implementer to retrieve a resource from the HPI and save it on their own system, but still be able to retrieve the original to check for updates. This can be done in 2 ways.
Extract the value of the identifier where the value of the use element is ‘official’, and use that as the id for a direct read from the server.
http://hpi.moh.nz/fhir/Practitioner/prac-X99ZZZZ
Use the identifier in a search query.
Example:
http://hpi.moh.nz/fhir/Practitioner?identifier=https://standards.digital.health.nz/id/hpi|99ZZZZ
(Note that both system and value are included in the query, with values separated by a ‘|’. When making the query, the ‘|’ needs to be url-escaped)
This example will return a bundle of Practitioner resources with only a single entry (as the system enforces uniqueness of the HPI identifier). Other queries - eg name - may well return multiple instances.
References are directional - from a source to a target. There are 2 ways that references between resources can be represented in this implementation.
The following example shows a reference to a Practitioner with the id of “example”
"practitioner": {
"reference": "Practitioner/example",
"display": "Dr Marcus welby"
}
...
This is a relative reference (ie the target is on the same server as the source) from a property called ‘practitioner’ to the practitioner resource. This format is used when possible.
...
"practitioner": {
"identifier": {
"system": "https://standards.digital.health.nz/id/hpi",
"value": "99ZZZZ"
},
"type":"Practitioner",
"display": "Dr Adam Careful"
}
...
This is a reference from a property called ‘practitioner’ to a Practitioner resource that has the identifier 99ZZZZ in the system https://standards.digital.health.nz/id/hpi It has the disadvantage that if the client wishes to retrieve the target resource, then it must do a query by identifier. There are also a number of search queries that require a direct reference rather than an identifier.
In some cases, a single entity may have been accidentally assigned multiple identifiers. When this is discovered to have occurred, one of the identifiers is deprecated and becomes a ‘dormant’ identifier, leaving the other as the active one. Both identifiers will appear in the active resource identifier list, with the dormant identifiers having a use value of ‘old’ and the active having a use value of ‘official’.
When reading the resource, if the deprecated id is used, then the resource that is returned will have the deprecated id, but the identifiers will be the correct ones (ie the
For example, assume that there are 2 Practitioner resources exposed by the HPI, each with a single identifier. The id of the resource matches the identifier value.
{
"resourceType":"Practitioner",
"id" : "99ZZZZ",
"identifier" : [
{"system":"https://standards.digital.health.nz/id/hpi-person","value":"99ZZZZ","use":"official"}
]
… other data
}
(returned by GET [host]/Practitioner/99ZZZZ)
And
{
"resourceType":"Practitioner",
"id" : "96YYY",
"identifier" : [
{"system":"https://standards.digital.health.nz/id/hpi-person","value":"96YYY","use":"official"}
]… other data (may be different to 99ZZZZ)
}
(returned by GET [host]/Practitioner/96YYY)
They are determined to be the same person, and the identifier 96YYY is deprecated (made dormant) in favour of 99ZZZZ.
A GET call of GET [host]/Practitioner/99ZZZZ) will return
{
"resourceType":"Practitioner",
"id" : "99ZZZZ",
"identifier" : [
{"system":"https://standards.digital.health.nz/id/hpi-person","value":"99ZZZZ","use":"official"},
{"system":"https://standards.digital.health.nz/id/hpi-person","value":"96YYY","use":"old"}
]
… other data
}
And a get call of GET [host]/Practitioner/96YYY) will return
{
"resourceType":"Practitioner",
"id" : "96YYY",
"identifier" : [
{"system":"https://standards.digital.health.nz/id/hpi-person","value":"99ZZZZ","use":"official"},
{"system":"https://standards.digital.health.nz/id/hpi-person","value":"96YYY","use":"old"}
]
… other data - the same as GET [host]/Practitioner/99ZZZZ
}
(note that in this case the id of the resource does not match the official HPI value)
Resources that reference the Practitioner (such as the PractitionerRole resource) can use either id. For example, to return PractitionerRole resources for this Practitioner, either of the following queries will return the same set of PractitionerRole resources:
GET [host]/PractitionerResource?practitioner=99ZZZZ
GET [host]/PractitionerResource?practitioner=96YYY
The ‘must support’ indicator means that the client must have a strategy to deal with this element. details here
For this IG, that means that if the element is present, the client must know how to interpret it. For example display it to the user or store in in the local store.
Contained resources are where the referenced (target) resource is contained within the source resource.