This page is part of the Sharing Valuesets, Codes, and Maps (SVCM) (v1.5.1: Publication) based on FHIR R4. This is the current published version. For a full list of available versions, see the Directory of published versions

2:3.98 Lookup Code [ITI-98]

This section corresponds to transaction [ITI-98] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-98] is used by the Terminology Consumer and Terminology Repository Actors.

2:3.98.1 Scope

This transaction is used by the Terminology Consumer to lookup a given code to return the full details. The request is received by the Terminology Repository. The Terminology Repository processes the request and returns a response of the code details as a Parameters Resource.

2:3.98.2 Actor Roles

Table 2:3.98.2-1: Actor Roles

2:3.98.3 Referenced Standards

• HL7 FHIR standard R4 http://hl7.org/fhir/R4/index.html

2:3.98.4 Messages

Figure 2:3.98.4-1: Interaction Diagram

2:3.98.4.1 Lookup Code Request Message

The Lookup Code Request message is a FHIR $lookup operation on the CodeSystem Resource.

2:3.98.4.1.1 Trigger Events

A Terminology Consumer triggers a Lookup Code Request to a Terminology Repository according to the business rules for the lookup. These business rules are outside the scope of this transaction.

2:3.98.4.1.2 Message Semantics

A Terminology Consumer initiates an $lookup request using HTTP GET as defined at http://hl7.org/fhir/codesystem-operation-lookup.html on the CodeSystem Resource. The required input parameters are identified in Table 2:3.98.4.1.2-1.

The URL for this operation is: [base]/CodeSystem/$lookup?[parameter=value]

Where [base] is the URL of Terminology Repository.

See ITI TF-2: Appendix W for informative implementation material for this transaction.

Table 2:3.98.4.1.2-1: Lookup Code Message HTTP Input Parameters

2:3.98.4.1.2.1 Example Request Message

An example request message from http://hl7.org/fhir/codesystem-operation-lookup.html is:

GET [base]/CodeSystem/$lookup?system=http://loinc.org&code=1963-8

2:3.98.4.1.3 Expected Actions

The Terminology Repository shall process the input parameters to discover the code that matches the parameters given and return a response as per Section 2:3.98.4.2 or an OperationOutcome Resource with an error message.

2:3.98.4.2 Lookup Code Response Message

2:3.98.4.2.1 Trigger Events

The Terminology Repository found the code matching the input parameters specified by the Terminology Consumer as a result of a Lookup Code Request.

2:3.98.4.2.2 Message Semantics

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for handling guidance for Access Denied.

The response message is a FHIR Parameters Resource with properties of the code based on the out parameters defined at http://hl7.org/fhir/codesystem-operation-lookup.html and reproduced in Table 2:3.98.4.2.2-1.

Table 2:3.98.4.2.2-1: Lookup Code Message HTTP Output Parameters

2:3.98.4.2.2.1 Example Response Message

An example successful response message from http://hl7.org/fhir/codesystem-operation-lookup.html is:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType" : "Parameters",
  "parameter" : [
    {
      "name" : "name",
      "valueString" : "LOINC"
    },
    {
      "name" : "version",
      "valueString" : "2.48"
    },
    {
      "name" : "display",
      "valueString" : "Bicarbonate [Moles/volume] in Serum"
    },
    {
      "name" : "abstract",
      "valueString" : "false"
    },
    {
      "name" : "designation",
      "part" : [
        {
          "name" : "value",
          "valueString" : "Bicarbonate [Moles/volume] in Serum"
        }
      ]
    }
  ]
}

An example failed response message from http://hl7.org/fhir/codesystem-operation-lookup.html is:

HTTP/1.1 200 OK
[other headers]

{
  "resourceType": "OperationOutcome",
  "id": "exception",
  "text": {
    "status": "additional",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Code "ABC-23" not found</div>"
  },
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Code "ABC-23" not found"
      }
    }
  ]
}

2:3.98.4.2.3 Expected Actions

The Terminology Consumer has received the response and continues with its workflow.

2:3.98.5 Security Considerations

See the general Security Consideration in ITI TF-1: 51.5.

2:3.98.5.1 Security Audit Considerations

Note that the same audit message is recorded by both Terminology Consumer and Repository. The difference being the Audit Source element. Both sides record to show consistency between the message sent by the Consumer and the action taken at the Registry.

The actors involved shall record audit events according to the Audit Event for Lookup Code by the Terminology Consumer and Repository.