New Zealand Rheumatic Fever FHIR Implementation Guide
0.4.9 - draft
New Zealand Rheumatic Fever FHIR Implementation Guide
0.4.9 - draft
New Zealand Rheumatic Fever FHIR Implementation Guide, published by Te Whatu Ora. This guide is not an authorized publication; it is the continuous build for version 0.4.9 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/tewhatuora/fhir-rheumatic-fever/ and changes regularly. See the Directory of published versions
This section defines standards that apply when mapping data to the New Zealand rheumatic fever FHIR representation.
All rheumatic fever resource instances should be tagged with the SNOMED code 58718002 "Rheumatic Fever (disorder)"
This is done in FHIR by adding a tag in the metadata of each instance (so the FHIRPath expression meta.tag.code=58718002 is true).
This consistent tagging enables proper scoping of data access controls as well as facilitating analytics across the rheumatic fever FHIR data set.
The rheumatic fever resource profiles on FHIR CarePlan, Condition, CareTeam, Observation (DiagnosisGroup), MedicationRequest and Patient resources specify an invariant which requires use of the RF SNOMED code tag when creating valid instances.
Applications may label rheumatic fever resource instances with the R "restricted" security label, when they contain sensitive content. The presence of this label on an instance will require API consumers to obtain additional privilege before accessing the tagged instance.
This is done in FHIR by adding a label in the metadata of each instance (so the FHIRPath expression meta.security.code=R is true).
CarePlan.statusMapping care plan status between the RFCCS national system and FHIR is straightforward as given by the following table.
| Patient registration status value (RCCCS) | FHIR CarePlan status code (binding) | FHIR status definition |
|---|---|---|
| New (Draft) | #draft |
The request (CarePlan) has been created but is not yet complete or ready for action. |
| Care Underway (Active) | #active |
The request (CarePlan) is in force and ready to be acted upon. |
| Care On-Hold (On-Hold) | #on-hold |
The request (CarePlan) and any implicit authorization to act) has been temporarily withdrawn but is expected to resume in the future. |
| Completed | #completed |
The activity described by the request has been fully performed. No further activity will occur. |
| Revoked (TBC) | #revoked |
The request (CarePlan) has been terminated prior to the known full completion of the intended actions. No further activity should occur. |
Applies to patient's current address.
| *RFCCS value | FHIR Address.use code | FHIR Address.type code | FHIR Date(s) in Address.period |
|---|---|---|---|
| Home | #home |
none | period.start = date when patient registered / address recorded $ |
| Work | #work |
none | period.start = date when patient registered / address recorded $ |
| Temporary | #temp |
none | period.start = date when patient registered / address recorded $ |
| Inactive | #old |
none | No period, or period.end = any date in the past ^ |
| Physical | none | #physical |
period.start = date when patient registered / address recorded $ |
| Postal | none | #postal |
period.start = date when patient registered / address recorded $ |
| Current | none | none | period.start = any date in the past; period.end, if specified, must be in the future |
Notes
'none' means no code is set - ie. the element is absent in the FHIR JSON representation
$ Use date of patient registration as the default value for Address.period.start
^ When there is neither a use nor type code and Address.period is present with the current date in range, this maps to ‘Current’ in RFCCS. If Address.period is missing, the address shall be mapped to 'Inactive'
Representation of locations where rheumatic fever secondary prophylaxis encounters take place.
| *RFCCS value | FHIR Location.typeServiceDeliveryLocationRoleType code |
FHIR code meaning |
|---|---|---|
| Hospital | #HOSP |
Hospital |
| Home | #PTRES |
Patient's residence |
| School | #SCHOOL |
School |
| Work | #WORK |
Work |
| Clinic | #PC |
Primary care clinic |
| Virtual | special case code #VR in ActEncounterCode system |
virtual |
Patient.contact[]As whanau/relative members of a rheumatic fever patient's care team need to have contact details, role and relationship to the patient represented, this IG uses Patient.contact rather than an instance of CareTeam resource.
The logic for mapping data between the RFCCS national system and FHIR is given by the following table.
| RFCCS data field | FHIR element of Patient resource |
FHIR data type | translation | FHIR data example 1 | FHIR data example 2 |
|---|---|---|---|---|---|
| care team member role | .whanauMemberCareRole extension |
coding (SNOMED) | - | $sct#58626002 Legal Guardian | $sct#394738000 Other related persons (person) |
| care team member relationship to patient (freetext) | .whanauMemberCareRelationship extension |
string | - | "mother" |
"brother in law" |
| first name | name.given |
string | - | "Beryl" |
"Mike" |
| last name | name.family |
string | - | "Hackett" |
"Westbrook" |
| primary contact (yes/no) | .whanauMemberCarePrimary extension |
boolean | - | true |
false |
| status (active/inactive) | .period.start - period.end |
datetime x2 | Consider member an ACTIVE contact unless BOTH dates are in the past, in which case INACTIVE | "2023-06-01" to "2026-05-31" |
"2021-01-01" to "2021-01-01" |
Applies to patient's preferred language.
Patient language is represented in the Patient.communication.language element.
Two character codes in the preferred CommonLanguages binding are not sufficient to encode the patient languages available in RFCCS.
Therefore the Te Whatu Ora Shared Care API uses ISO 639-3 three character language codes which is allowed by the AllLanguages (maximum) binding on Patient.communication.language.
The translation between RFCCS language and FHIR is given in the table below.
| English name of language | ISO 639-3 language code</br> to use for FHIR mapping | RFCCS Health Cloud language | IANA primary language SUBTAG (BCP47) |
|---|---|---|---|
| English | eng | English | en |
| Spanish (Castilian) | spa | Spanish | es |
| Afrikaans | afr | Afrikaans | af |
| Arabic | ara | Arabic | ar |
| Rarotongan | rar | Cook Islands Maori | |
| Dutch | dut | Dutch | nl |
| French | fre | French | fr |
| German | ger | German | de |
| Gujarati | guj | Gujarati | gu |
| Hindi | hin | Hindi | hi |
| Italian | ita | Italian | it |
| Japanese | jpn | Japanese | ja |
| Korean | kor | Korean | ko |
| Mandarin Chinese | cmn | Mandarin | |
| Maori | mao | Maori | mi |
| New Zealand Sign Language | nzs | New Zealand Sign Language | |
| Jinyu Chinese | cjy | "Northern Chinese" | |
| Panjabi; Punjabi | pan | Punjabi | pa |
| Russian | rus | Russian | ru |
| Samoan | smo | Samoan | sm |
| Tagalog | tgl | Tagalog | - |
| Tamil | tam | Tamil | ta |
| Thai | tha | Thai | th |
| Tonga (Tonga Islands) | ton | Tongan | to |
| Vietnamese | vie | Vietnamese | vi |
| Yue Chinese (Cantonese) | yue | Cantonese |
See the example patient Sage Westbrook for how to correctly code language for FHIR representation of rheumatic fever patients.
Rheumatic heart disease severity is the driving factor for severity of a patient's rheumatic fever diagnosis.
To fully represent severity values supported by the RFCCS national application, three FHIR elements need to be used:
Condition.severity: this is the basic severity classifier in a stock FHIR Condition
RheumaticFeverCondition.rhdSeverity - this is a profile extension which allows a Condition to capture a specific SNOMED code matching the patient's rheumatic heart disease situation.
RheumaticFeverCondition.assessmentDate - another profile extension to Condition which allows a specific date of assessment to be recorded (.recordedDate in Condition is already used to capture date of diagnosis).
Translation between the RFCCS RHD severity value and FHIR representation is given by the following table.
| RFCCS - Rheumatic Heart Disease Severity classification | FHIR Condition.severity (SNOMED) | rhdSeverity extension in RheumaticFeverCondition (SNOMED) | FHIR NzCondition.long-term-condition indicator ^ |
|---|---|---|---|
| “none” | do not map | #260413007 None (qualifier value) | TRUE |
| “trivial” | do not map | #300171000210106 Trivial (qualifier value) | TRUE |
| “mild” | #255604002 Mild (qualifier value) | #255604002 Mild (qualifier value) | TRUE |
| “moderate” | #1255665007 Moderate (qualifier value) | #1255665007 Moderate (qualifier value) | TRUE |
| “severe” | #24484000 Severe (severity modifier) (qualifier value) | #24484000 Severe (severity modifier) (qualifier value) | TRUE |
| “Post valve repair” | #24484000 Severe (severity modifier) (qualifier value) | Post valve repair or replacement #59391000119102 History of heart valve repair (situation) | TRUE |
| “Post valve replacement” | #24484000 Severe (severity modifier) (qualifier value) | #301561000210102 History of heart valve replacement (situation) | TRUE |
| “Unknown” | do not map | #261665006 Unknown (qualifier value) | TRUE |
^ Note: The FHIR representation of rheumatic fever condition includes setting the long-term condition extension as the disease is considered in NZ a long term condition.