Non-patient File Sharing (NPFS)
2.2.0 - Trial-Implementation International flag

This page is part of the Non-patient File Sharing (NPFS) (v2.2.0: 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.109 Retrieve File [ITI-109]

This section corresponds to transaction [ITI-109] of the IHE Technical Framework. Transaction [ITI-109] is used by the File Consumer and File Manager.

2:3.109.1 Scope

The Retrieve File [ITI-109] transaction is used by the File Consumer to retrieve a File from the File Manager.

2:3.109.2 Actors Roles

Table 2:3.109.2-1: Actor Roles
Actor: File Consumer
Role: Requests a File from the File Manager
Actor: File Manager
Role: Serves the File to the File Consumer


2:3.109.3 Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0

2:3.109.4 Messages

Retrieve File [ITI-109]File ConsumerFile Manager1. Retrieve File [ITI-109]

Figure 2:3.109.4-1: Retrieve File Interactions


2:3.109.4.1 Retrieve File Request Message

This message is an HTTP GET request to retrieve the File.

2:3.109.4.1.1 Trigger Events

The File Consumer wants to obtain a File.

2:3.109.4.1.2 Message Semantics

The File Consumer sends a HTTP GET request to the server. The File Consumer request may be to retrieve the File content referenced by a DocumentReference.content.attachment.url.

The File Consumer may provide HTTP Accept header, according to the semantics of the HTTP protocols (see RFC2616, Section 14.1). This enables the File Consumer to indicate preferred mime-types such that the File Manager could provide the File requested in an encoding other than the encoding indicated in the DocumentReference. For example, indicating application/fhir+json could result in the response from the File Manager being a json FHIR Bundle of type File with all the content encoded as FHIR resources.

The only MIME type assured to be returned is the MIME type indicated in the DocumentReference.content.attachment.contentType.

The HTTP If-Unmodified-Since header shall not be included in the GET request.

2:3.109.4.1.3 Expected Actions

The File Manager shall provide the File in the requested MIME type or reply with an HTTP status code indicating the error condition. The File Manager is not required to transform the File.

2:3.109.4.2 Retrieve File Response Message

This is the return message sent by the File Manager.

2:3.109.4.2.1 Trigger Events

The HTTP Response message is sent upon completion of the Retrieve File Request.

2:3.109.4.2.2 Message Semantics

This message shall be an HTTP Response, as specified by RFC2616. When the requested File is returned, the File Manager shall respond with HTTP Status Code 200. The HTTP message-body shall be the content of the requested File.

Table 2:3.109.4.2.2-1 contains error situations and the HTTP Response.

Table 2:3.109.4.2.2-1: HTTP Error Response Codes and Suggested Text

Situation HTTP Response
URI not known 404 File Not Found
File is Deprecated or not available 410 Gone (or 404 when 410 is unacceptable due to security/privacy policy)
File Manager unable to format File in content types listed the ‘Accept’ field 406 Not Acceptable
HTTP request specified is otherwise not a legal value 403 Forbidden/Request Type Not Supported

The File Manager may return other HTTP Status Codes. Guidance on handling Access Denied related to use of 200, 403 and 404 can be found in ITI TF-2: Appendix Z.7.

The File Manager should complement the returned error code with a human readable description of the error condition.

2:3.109.4.2.3 Expected Actions

The File Consumer processes the results according to application-defined rules.

The .hash and .size, when populated, represent the content in the MIME type indicated in the DocumentReference.content.attachment.contentType.

2:3.109.4.3 CapabilityStatement Resource

File Managers implementing this transaction shall provide a CapabilityStatement Resource as described in ITI TF-2: Appendix Z.3 indicating the transaction has been implemented.

2:3.109.5 Security Considerations

See NPFS Security Considerations.

The files are not Patient specific, but they may have other needs for security controls, such as business knowledge restrictions. Thus, the use of Security may be applicable. Actors involved in this transaction should be aware that even if the Resources exchanged do not contain PHI or other private information, retrieving those Resources could compromise patient care or have other legal ramifications. For general security considerations, see ITI TF-2: Appendix Z.8 (currently in the Appendix Z on HL7 FHIR Trial Implementation Supplement).

2:3.109.5.1 Security Audit Considerations

The File Consumer when grouped with ATNA Secure Node or Secure Application Actor shall be able to record a Retrieve File Consumer Audit Event Log.

The File Manager when grouped with ATNA Secure Node or Secure Application Actor shall be able to record a Retrieve File Manager Audit Event Log.