Clone wiki

itk-payloads / pages / CodedEntries

Coded Entries

Many HL7v3 documents allow for clinical codes to be included in the message content. In most cases a specific vocabulary will also be specified that lists the possible code values that can be listed in the coded entry field.

The vocabularies are published along with the message specification, and may be updated periodically. Every vocabulary is identified with a unique “OID” (object identifier).

To simplify the use of coded entries, the itk-payloads library provides java enumerations for vocabulary entries. These can be used to simplify the entry of coded items – for example:


In the above example “Sex” is a vocabulary provided with the library. The JavaDoc comment for a coded entry field will specify the name of the enumeration to use. The enumeration includes entries for the display name but also for the codes so you can use the code value if that is preferable (the below is identical to the previous example):


If you are using some vocabularies often in your code, you could also simplify the above using a static import:

import static uk.nhs.interoperability.payloads.vocabularies.generated.Sex.*;

The underscore at the start is to allow for entries that start with a numeric, which is not allowed in Java method names.

If you want to provide a code from a different vocabulary, or want to explicitly specify the code, OID and display name, you can do that by using the CodedValue class directly:

fields.setJobRoleName(new CodedValue("1234", "Java Developer", "2.16.840.1.113883."));

Some coded entries allow for locally defined codes to be used in the field in addition to the pre-defined ones in the vocabulary. In the message specifications these are listed as “CWE” fields (Coded With Extension). In these cases, a local code and display name can be provided and the OID can be omitted:

fields.setJobRoleName(new CodedValue("1234", "Java Developer"));