Measurements and simple assertions
Retrieving a patient’s laboratory result observations
The logical ID (of the patient to retrieve) is passed as part of the URL. The logical ID is found as the result of a search.
GET https://tw171.open.allscripts.com/FHIR/Patient/id/Observation?category=laboratory
GET hhttps://tw171.open.allscripts.com/FHIR/Patient/id/Observation?category=laboratory&date=eq2016-01-01
| Name | Required? | Type | Description |
|---|---|---|---|
| id | yes | URL | The logical ID of the patient. This is retrieved using the search function. |
| date | no | string | A string representing a date to include in the search. See below for more information. |
A DAF Observation is returned.
| Name | Type | Cardinality | Description |
|---|---|---|---|
| identifier | 0..* | Unique identifier for the simple observation instance. This allows observations to be distinguished and referenced. If this is used, then the attributes associated to identifier are required (use, system, value); External ID- is for a lab vendor who sends the results such that this be the ID that they send. | |
| — use | 1..1 | Purpose of this identifier. Identifies the purpose for this identifier, if known. The codes shall be taken from IdentifierUse. Allows the appropriate identifier for a particular context of use to be selected from among a set of identifiers. Note: This is labeled as “Is Modifier” because applications should not mistake a temporary ID for a permanent one. Applications can assume that an identifier is permanent unless it explicitly says that it is temporary. This value set has an inline code system which defines the following codes: Usual, Official, Temp, and Secondary. For more information on this value set, see http://hl7.org/fhir/identifier-use. | |
| — system | 1..1 | System attribute establishes the namespace in which set of possible ID values is unique. There are many sequences of identifiers. To perform matching, we need to know what sequence we’re dealing with. The system identifies a particular sequence or set of unique identifiers. For example, http://www.acme.com/identifiers/patient or urn:ietf:rfc:3986 if the Identifier.value itself is a full URI, Uniform Resource Identifier Reference (RFC 3986 ). Note: URIs are case sensitive. For UUID (urn:uuid:53fefa32-fcbb-4ff8-8a92-55ee120877b7) use all lowercase. | |
| — value | http://www.hl7.org/fhir/daf/daf-resultobs-definitions.html#daf-resultobs.Observation.identifier.value | 1..1 | Portion of the identifier typically displayed to the user and which is unique within the context of the system. If the value is a full URI, then the system shall be urn:ietf:rfc:3986. For example: 123456. |
| status | code | 1..1 | Status of the result value or codes providing the status of an observation. The codes shall be taken from ObservationStatus value set and are used to track the status of individual results as some results are finalized before the whole report is finalized. This value set has an inline code system which defines the following codes: Registered , Preliminary , Final , Amended, Cancelled, Entered in Error, and Unknown. For more information on this value set, see: http://hl7.org/fhir/observation-status. |
| category | CodeableConcept | 1..1 | Fixed category.coding.system that includes several options as to where the observation could have been made such as Social History, Vital Signs, Imaging, Laboratory, Procedure, Survey, Exam and Therapy. For the Lab Results profile, the category is a fixed cateogry.coding.code for Laboratory. For more information on this value set, see: =”http://hl7.org/fhir/observation-category“. |
| code | CodeableConcept | 1..1 | Code refers to the test that was performed. This is element is bound to LOINC codes (US Laboratory Observation Profile Observation Name Codes) and the conformance is extensible such that, if the data type is a CodeableConcept, then one of the coding values shall be from the specified value set if a code applies, but if no suitable code exists in the value set, alternate code(s) may be provided in its place. If no codes, including local codes, are available, then just text may be used. For more information on this value set, see http://hl7.org/fhir/ValueSet/observation-codes. |
| — coding | http://www.hl7.org/fhir/daf/daf-resultobs-definitions.html#daf-resultobs.Observation.code.coding | 1..1 | Standard and local codes may be included here by repeating the coding element with a different coding.system. Requirements allow for translations and alternate encodings within a code system. This also supports communication of the same instance to systems requiring different encodings. NOTE: Codes may be defined very casually in enumerations, or code lists, up to very formal definitions such as SNOMED CT. See the HL7 v3 Core Principles for more information. Ordering of codings is undefined and shall not be used to infer meaning. Generally, at most only one of the coding values will be labelled as UserSelected = true. |
| subject | Reference(Patient, Group, Device, Location) | 1..1 | Patient, or group of patients, location, or device whose characteristics (direct or indirect) are described by the observation and into whose record the observation is placed. Comments: Indirect characteristics may be those of a specimen, fetus, donor, other observer (for example a relative or EMT), or any observation made about the subject. One would expect this element to be a cardinality of 1..1. The only circumstance in which the subject can be missing is when the observation is made by a device that does not know the patient. In this case, the observation shall be matched to a patient through some context/channel matching technique, and at this point, the observation should be updated. If the target of the observation is different than the subject, the general extension observation-focal-subject. may be used. However, the distinction between the patient’s own value for an observation versus that of the fetus, or the donor or blood product unit, etc., are often specified in the observation code. |
| encounter | Reference(Encounter) | 0..1 | Healthcare event (such as a patient and healthcare provider interaction) during which this observation is made. For some observations it may be important to know the link between an observation and a particular encounter. |
| effectiveDateTime | dateTime | 0..1 | For lab tests this is the specimen collection date. For Ask at Order Entry Questions (AOE)’s this is the date the question was asked. |
| effectivePeriod | Period | 0..1 | For lab tests this is the specimen collection period. At least a date should be present unless this observation is a historical report. |
| issued | Hl7.Fhir.Model.Instant | 0..1 | Date and time this observation was made available to providers, typically after the results have been reviewed and verified. Minimum Precision to Day and updated when the result is updated. |
| performer | Reference(Practitioner, Organization, Patient, RelatedPerson) | 0..* | Who was responsible for asserting the observed value as “true”. May give a degree of confidence in the observation and also indicates where follow-up questions should be directed. |
| valueQuantity | Quantity | 0..1 | An observation exists to have a value, though it may not if it is in error, or it represents a group of observations. Quantity is a measured amount (or an amount that can potentially be measured). The value contains the numerical value of the quantity, including an implicit precision. If no comparator is specified, the value is a point value (i.e. ‘=’). The comparator element can never be ignored. |
| valueCodeableConcept | CodeableConcept | 0..1 | Actual result. If codeableConcept, valueCodeableConcept must be selected from SNOMED CT. |
| valueString | String | 0..1 | Actual result in the form of a sequence of Unicode characters. Note that strings shall not exceed 1MB in size. |
| valueRange | Hl7.Fhir.Model.Range | 0..1 | Range is a set of ordered Quantity values defined by a low and high limit. A Range specifies a set of possible values; usually, one value from the range applies (e.g. “give the patient between 2 and 4 tablets”). Ranges are typically used in instructions. The unit and code/system elements of the low or high elements shall match. If the low or high elements are missing, the meaning is that the low or high boundaries are not known and therefore neither is the complete range. |
| valueRatio | Hl7.Fhir.Model.Ratio | 0..1 | Relationship between two Quantity values expressed as a numerator and a denominator. Common factors in the numerator and denominator are not automatically cancelled out. The Ratio data type is used for titers (e.g. “1:128”) and other quantities produced by laboratories that truly represent ratios. Ratios are not simply “structured numbers” - for example blood pressure measurements (e.g. “120/60”) are not ratios. In addition, ratios are used where common factors in the numerator and denominator do not cancel out. |
| valueSampledData | Hl7.Fhir.Model.SampledData | 0..1 | Data that comes from a series of measurements taken by a device, with upper and lower limits. There may be more than one dimension in the data. A SampledData provides a concise way to handle the data produced by devices that sample a physical particular state at a high frequency. A typical use for this is for the output of an ECG or EKG device. |
| valueAttachment | Hl7.Fhir.Model.Attachment | 0..1 | Type is for containing or referencing attachments - additional data content defined in other formats. The most common use of this type is to include images or reports in some report format such as PDF. However it can be used for any data that has a MIME type. The actual content of an Attachment can be conveyed directly using the data element or a URL reference can be provided. If both are provided, the reference shall point to the same content as found in the data. The reference can never be reused to point to some different data (i.e. the reference is version specific). The URL reference shall point to a location that resolves to actual data; some URIs such as cid: meet this requirement. If the URL is a relative reference, it is interpreted in the same way as a resource reference. |
| valueTime | Time | 0..1 | Time during the day, with no date specified (can be converted to a Duration since midnight). Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored. The time “24:00” is not allowed, and neither is a time zone. |
| valueDateTime | dateTime | 0..1 | Date, date-time or partial date (e.g. just year or year + month) as used in human communication. If hours and minutes are specified, a time zone shall be populated. Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored. Dates shall be valid dates. The time “24:00” is not allowed. |
| valuePeriod | Period | 0..1 | Time period defined by a start and end date/time. A period specifies a range of times. The context of use will specify whether the entire range applies (e.g. “the patient was an inpatient of the hospital for this time range”) or one value from the period applies (e.g. “give to the patient between 2 and 4 pm on 24-Jun 2013”). |
| dataAbsentReason | CodeableConcept | 0..1 | Provides a reason why the expected value in the element Observation.value[x] is missing. Codes specifying why the result (Observation.value[x]) is missing. The codes shall be taken from Observation Value Absent Reason value set and include: Unknown, Asked, Temp, Not Asked, Masked, Unsupported, As Text, Error, and Not a Number. Other codes may be used where these codes are not suitable. For more information on this value set, see: http://hl7.org/fhir/ValueSet/observation-valueabsentreason. |
| interpretation | CodeableConcept | 0..1 | Assessment made based on the result of the observation. Intended as a simple compact code often placed adjacent to the result value in reports and flow sheets to signal the meaning/normalcy status of the result. The codes shall be taken from Observation Value Absent Reason value set and include: High, Low, Normal, and so forth. For more information on this value set, see: http://hl7.org/fhir/ValueSet/observation-interpretation. |
| comments | string | 0..1 | May include statements about significant, unexpected or unreliable values, or information about the source of the value where this may be relevant to the interpretation of the result. |
| bodySite | CodeableConcept | 0..1 | Site on the subject’s body where the observation was made (i.e. the target site). Codes describing anatomical locations. May include laterality. Only used if not implicit in code found in Observation.code. For example codes, see the SNOMED CT Body Structures value set: http://www.hl7.org/fhir/valueset-body-site.html . If the use case requires BodySite to be handled as a separate resource instead of an inline coded element (for example, to identify and track separately) then use the standard extension body-site-instance extension: http://www.hl7.org/fhir/extension-body-site-instance.html. |
| method | CodeableConcept | 0..1 | Mechanism used to perform the observation. In some cases, method can impact results and is thus used for determining whether results can be compared or determining significance of results. For more information on the Observation Method value set, see: http://hl7.org/fhir/ValueSet/observation-methods. |
| specimen | Reference(Specimen) | 0..1 | Specimen that was used when this observation was made. Observations are not made on specimens themselves; they are made on a subject, but usually by the means of a specimen. Note that although specimens are often involved, they are not always tracked and reported explicitly. Also note that observation resources may be used in contexts that track the specimen explicitly (for example, a Diagnostic Report). |
| referenceRange | 0..* | Guidance on how to interpret the value by comparison to a normal or recommended range. Knowing what values are considered “normal” can help evaluate the significance of a particular result. Need to be able to provide multiple reference ranges for different contexts. Most observations only have one generic reference range. Systems MAY choose to restrict to only supplying the relevant reference range based on knowledge about the patient (e.g. specific to the patient’s age, gender, weight and other factors), but this may not be possible or appropriate. Whenever more than one reference range is supplied, the differences between them SHOULD be provided in the reference range and/or age properties. | |
| – referenceRange.low | Hl7.Fhir.Model.SimpleQuantity | 0..1 | Low range, if relevant. The value of the low bound of the reference range. The low bound of the reference range endpoint is inclusive of the value (e.g. reference range is >=5 - <=9). If the low bound is omitted, it is assumed to be meaningless (e.g. reference range is <=2.3). |
| – referenceRange.high | Hl7.Fhir.Model.SimpleQuantity | 0..1 | High range, if relevant. The value of the high bound of the reference range. The high bound of the reference range endpoint is inclusive of the value (e.g. reference range is >=5 - <=9). If the high bound is omitted, it is assumed to be meaningless (e.g. reference range is >= 2.3). |
| – referenceRange.meaning | CodeableConcept | 0..1 | Meaning/use of this range of this range. For more information on this value set, see: http://hl7.org/fhir/ValueSet/referencerange-meaning. |
| – referenceRange.age | Hl7.Fhir.Model.Range | 0..1 | Applicable age range, if relevant. The age at which this reference range is applicable. This is a neonatal age (e.g. number of weeks at term) if the meaning says so. |
| – referenceRange.text | string | 0..1 | Text based reference range in an observation which may be used when a quantitative range is not appropriate for an observation. An example would be a reference value of “Negative” or a list or table of ‘normals’. |
| related | 0..* | Set of related observations that together form the panel or battery of this observation. Normally, an observation will have either a value or a set of related observations. A few observations (e.g. Apgar score) may have both a value and a set of related observations or sometimes QuestionnaireResponse from which the measure is derived. | |
| – related.type | code | 1..1 | Code specifying the kind of relationship that exists with the target resource. The codes shall be taken from the ObservationRelationshipType value set and include: Has-member, Derived-from, Sequel-to, Replaces, Qualified-by, and Interfered-by. For more information on this value set, see: http://hl7.org/fhir/ValueSet/observation-relationshiptypes. |
| – related.target | Reference(Observation, QuestionnaireResponse) | 1..1 | Resource (US DAF Component observations) that is related to this one. |
| component | 0..* | Some observations have multiple component observations. These component observations are expressed as separate code value pairs that share the same attributes. Examples include systolic and diastolic component observations for blood pressure measurement and multiple component observations for genetics observations. Component observations share the same attributes in the Observation resource as the primary observation and are always treated a part of a single observation (they are not separable). However, the reference range for the primary observation value is not inherited by the component values and is required when appropriate for each component observation. | |
| – component.code | CodeableConcept | 1..1 | Laboratory test that was performed. This is element and codes are bound to LOINC (US Laboratory Observation Profile Observation Name Codes); however, other codes may be used where these codes are not suitable. For more information on this value set, see: http://hl7.org/fhir/ValueSet/observation-codes. |
| Observation.component.value[x] | http://www.hl7.org/fhir/daf/daf-resultobs-definitions.html#daf-resultobs.Observation.component.value[x] | 0..1 | Information determined as a result of making the observation, if the information has a simple value. Choice of: Quantity, CodeableConcept, string, Range, Ratio, SampledData, Attachment, time, dateTime, Period. Normally, an observation will have either a value or a set of related observations. A few observations (e.g. Apgar score) may have both a value and related observations (for an Apgar score, the observations from which the measure is derived). If a value is present, the datatype for this element should be determined by Observation.code. A CodeableConcept with just a text would be used instead of a string if the field was usually coded, or if the type associated with the Observation.code defines a coded value. For boolean values use valueCodeableConcept and select codes from http://hl7.org/fhir/ValueSet/v2-0136 (These “yes/no” concepts can be mapped to the display name “true/false” or other mutually exclusive terms that may be needed”). The element, Observation.value[x], has a variable name depending on the type as follows: valueQuantity, valueCodeableConcept, valueRatio, valueChoice, valuePeriod, valueSampleData, or valueString (The name format is “‘value’ + the type name” with a capital on the first letter of the type). |
| – component.valueQuantity | Quantity | 0..1 | Actual component result or a measured amount (or an amount that can potentially be measured). The value contains the numerical value of the quantity, including an implicit precision. If no comparator is specified, the value is a point value (i.e. ‘=’). The comparator element can never be ignored. |
| – component.valueCodeableConcept | CodeableConcept | 0..1 | Actual component result. |
| – component.valueString | String | 0..1 | Actual component result. |
| – component.valueRange | Hl7.Fhir.Model.Range | 0..1 | Set of ordered Quantity values defined by a low and high limit. A Range specifies a set of possible values; usually, one value from the range applies (e.g. “give the patient between 2 and 4 tablets”). Ranges are typically used in instructions. The unit and code/system elements of the low or high elements shall match. If the low or high elements are missing, the meaning is that the low or high boundaries are not known and therefore neither is the complete range. The low and the high values are inclusive, and are assumed to have arbitrarily high precision; e.g. the range 1.5 to 2.5 includes 1.50, and 2.50 but not 1.49 or 2.51. |
| – component.valueRatio | Hl7.Fhir.Model.Ratio | 0..1 | Relationship between two Quantity values expressed as a numerator and a denominator. Common factors in the numerator and denominator are not automatically cancelled out. The Ratio data type is used for titers (e.g. “1:128”) and other quantities produced by laboratories that truly represent ratios. Ratios are not simply “structured numbers” - for example blood pressure measurements (e.g. “120/60”) are not ratios. In addition, ratios are used where common factors in the numerator and denominator do not cancel out. A proper ratio has both a numerator and a denominator; however these are not mandatory in order to allow an invalid ratio with an extension with further information. |
| – component.valueSampledData | Hl7.Fhir.Model.SampledData | 0..1 | Data that comes from a series of measurements taken by a device, with upper and lower limits. There may be more than one dimension in the data. A SampledData provides a concise way to handle the data produced by devices that sample a physical particular state at a high frequency. A typical use for this is for the output of an ECG or EKG device. |
| – component.valueAttachment | Hl7.Fhir.Model.Attachment | 0..1 | Type for containing or referencing attachments - additional data content defined in other formats. The most common use of this type is to include images or reports in some report format such as PDF. However it can be used for any data that has a MIME type. |
| – component.valueTime | Time | 0..1 | Time during the day, with no date specified (can be converted to a Duration since midnight). Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored. The time “24:00” is not allowed, and neither is a time zone. |
| – component.valueDateTime | dateTime | 0..1 | Date, date-time or partial date (e.g. just year or year + month) as used in human communication. If hours and minutes are specified, a time zone shall be populated. Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored. Dates shall be valid dates. The time “24:00” is not allowed. |
| – component.valuePeriod | Period | 0..1 | Time period defined by a start and end date/time. A period specifies a range of times. The context of use will specify whether the entire range applies (e.g. “the patient was an inpatient of the hospital for this time range”) or one value from the period applies (e.g. “give to the patient between 2 and 4 pm on 24-Jun 2013”). If the start element is missing, the start of the period is not known. If the end element is missing, it means that the period is ongoing, or the start may be in the past, and the end date in the future, which means that period is expected/planned to end at the specified time. The end value includes any matching date/time. For example, the period 2011-05-23 to 2011-05-27 includes all the times from the start of the 23rd May through to the end of the 27th of May. |
| – component.dataAbsentReason | CodeableConcept | 0..1 | Reason why the expected value in the element Observation.value[x] is missing. The codes shall be taken from the ObservationValueAbsentReason value set and include the following 9 values: Unknown, Asked, Temp, Not Asked, Masked, Unsupported, As Text, Error, Not a Number. For more information on this value set, see: http://hl7.org/fhir/ValueSet/observation-valueabsentreason. |
| – component.referenceRange | 0..* | Guidance on how to interpret the value by comparison to a normal or recommended range. Knowing what values are considered “normal” can help evaluate the significance of a particular result. Need to be able to provide multiple reference ranges for different contexts. Most observations only have one generic reference range. Systems MAY choose to restrict to only supplying the relevant reference range based on knowledge about the patient (e.g. specific to the patient’s age, gender, weight and other factors), but this may not be possible or appropriate. Whenever more than one reference range is supplied, the differences between them SHOULD be provided in the reference range and/or age properties. |
Searching by date
Dates are passed as query parameters on the URL. Since the URL parameters cannot handle comparators (for example, >, <=) these are passed as part of the date.
date=eq2016-01-01
date=gt2016-01-01
The following comparators are supported:
| Comparator | Description |
|---|---|
| eq | equal |
| gt | greater than |
| ge | greater than or equal |
| lt | less than |
| le | less than or equal |
To search for a date range, pass in the date twice.
e.g. date=ge2010-01-01&date=le2010-12-31
This search would include every day in the year 2010.