Non-patient File Sharing (NPFS)
2.2.1-current - ci-build International flag

Non-patient File Sharing (NPFS), published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 2.2.1-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.NPFS/ and changes regularly. See the Directory of published versions

2:3.87 Submit File [ITI-87]

2:3.87.1 Scope

This transaction allows a File Source to publish a new file and related metadata. It also enables update of an existing file and update its metadata and replacement of a file.

The files are not associated with a patient.

2:3.87.2 Actors Roles

Table 2:3.87.2-1: Actor Roles
Actor: File Source
Role: Sends non-patient files and related metadata to a File Manager
Actor: File Manager
Role: Stores received non-patient files and maintains related metadata


2:3.87.3 Referenced Standards

HL7 FHIR HL7 FHIR Release 4.0

2:3.87.4 Messages

File SourceFile ManagerCreate File RequestSubmit File ResponseUpdate File RequestUpdate File ResponseReplace File RequestSubmit File Response

Figure 2:3.87.4-1: Create File Interactions


2:3.87.4.1 Create File Request Message

The File Source uses this message to submit a new file (Binary Resource) and related metadata (DocumentReference Resource) to a target File Manager using a FHIR transaction.

2:3.87.4.1.1 Trigger Events

The File Source needs to submit a new file to a File Manager. The file may have been created by the File Source itself or by another file creator.

2:3.87.4.1.2 Message Semantics

The File Source shall issue an HTTP request according to requirements defined in the HL7® FHIR® standard for “create” interaction (http://hl7.org/fhir/R4/http.html#create ). The message uses an HTTP POST method to submit a FHIR Bundle Resource.

The Bundle Resource:

The File Source shall submit FHIR resources in either XML format or JSON format. Values for media-type of the request message are defined in the ITI TF-2: Appendix Z.6 (currently in the Appendix Z on HL7 FHIR Trial Implementation Supplement).

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

Sections below provide specific guidance about how handle metadata for stylesheets, workflow definitions, and privacy policies. If other files types will be managed, local policy should establish values for type, category, format, mime-type and masterIdentifier elements.

2:3.87.4.1.2.1 category element

Codes in the category element shall be from ValueSet: NPFS DocumentReference category, if any of the codes within the value set can apply to the concept being communicated. If the table does not cover the concept (based on human review), an alternate code may be used instead.

2:3.87.4.1.2.2 type element

This section identifies specific guidelines for the type element which depends on the “class” of the file:

  • If the file submitted is a Workflow Definition template, the type element could be valued with the workflow definition reference of the Workflow Definition profile (see workflowDefinitionReference as defined by the XDW Profile; see ITI TF-3: 5.4.2.2).

  • If the file submitted is a Patient Privacy Policy (see ITI TF-1: 19.2.1 Basic Patient Privacy Consent), the type element should be valued with the LOINC code 57017-6 “Privacy policy Organization Document” as shown in ValueSet: NPFS DocumentReference category.

  • If the file submitted is a Stylesheet, the type element will be valued with a codeable concept defined by local policy that classifies the type of the stylesheet. The codeable concept of the type element shall be defined by both a code and a system (e.g., code= “laboratory” system=”http://localdomain.org/stylesheetstype”).

2:3.87.4.1.2.3 File relationships

The relatesTo element holds relationships that the file has with other non-patient files. The DocumentReference.relatesTo element allows for the creation of those relationships (i.e., replacement, sign, transform, or append).

2:3.87.4.1.2.4 MasterIdentifier element

This section identifies specific requirements for the masterIdentifier element, if used:

  • If the file submitted is a Workflow Definition template, the masterIdentifier element shall be valued with the workflowDefinitionReference as defined by the XDW Profile (see ITI TF-3: 5.4.2.2) .

  • If the file submitted is a Patient Privacy Policy (see ITI TF-1: 19.2.1 Basic Patient Privacy Consent), the masterIdentifier element shall be valued with the associated Patient Privacy Policy Identifier.

Local policies should define how to handle this element in case of file’s revision, update or replacement.

2:3.87.4.1.2.5 Create File request message example

For an example of a Create File Request Bundle see Example Bundle: Create Document Bundle.

2:3.87.4.1.3 Expected Actions

The File Manager shall support all the media-types defined in ITI TF-2: Appendix Z.6 (currently in the Appendix Z on HL7 FHIR Trial Implementation Supplement).

On receipt of the Create File Request, the File Manager shall validate the Resources and respond with one of the HTTP codes defined in Section 3.87.4.4.2 Message Semantics.

The File Manager shall process the Bundle atomically.

The File Manager shall support Create File Request messages that contain one Binary Resource and one DocumentReference Resource. The File Manager shall store these resources and make them available for further processing, e.g., file update or replacement [ITI-87], file metadata update [ITI-89], search [ITI-88], and retrieve [ITI-109].

If the File Manager receives a Create File Request message that contains resources other than the required ones, it may respond to the File Source with a failure (see Section 3.87.4.4.2).

2:3.87.4.2 Update File Request Message

The File Source uses this message to update a file already existing on the File Manager.

This message is used when there is a prior file that does not need to be preserved.

The File Manager is not required to support FHIR resource versioning (https://www.hl7.org/fhir/R4/versions.html).

2:3.87.4.2.1 Trigger Events

The File Source needs to update a file that exists on the File Manager.

Prior to sending the update, the File Source shall discover the resource ids of the existing DocumentReference Resource and the Binary Resource to be updated.

2:3.87.4.2.2 Message Semantics

The File Source shall issue an HTTP request according to requirements defined in the HL7® FHIR® standard for “update” interaction (http://hl7.org/fhir/R4/http.html#update).

The message uses an HTTP POST to submit a FHIR Bundle that contains the updated Binary and DocumentReference Resources. For each resource in the Bundle, the bundle.entry.request.method shall be valued with the HTTP PUT Method.

The Bundle Resource shall contain:

The File Source shall submit FHIR resources in either XML format or JSON format. Values for media-type of the request message are defined in the ITI TF-2: Appendix Z.6 (currently in the Appendix Z on HL7 FHIR Trial Implementation Supplement).

2:3.87.4.2.2.1 Update File Request message example

For an example of a Update File Request Bundle see Example Bundle: Update Document Bundle.

2:3.87.4.2.3 Expected Actions

The File Manager shall support all the media-type defined in ITI TF-2: Appendix Z.6 (currently in the Appendix Z on HL7 FHIR Trial Implementation Supplement).

On receipt of the Update File Request, the File Manager shall respond with one of the HTTP codes defined in Section 3.87.4.4.2 Message Semantics.

The File Manager shall process the Bundle atomically.

The File Manager shall support Update File Request messages that contain one Binary Resource and one DocumentReference Resource. The File Manager shall store these resources and make them available for further processing, e.g., file update or replacement [ITI-87], file metadata update [ITI-89], search [ITI-88], and retrieve [ITI-109].

The previous content in the updated Binary and DocumentReference Resources will be no longer accessible, and the new file will be retrievable using the same bundle.entry.fullUrl as the previous one.

If the File Manager receives an Update File Request message that contains resources other than the required ones, it may respond to the File Source with a failure (see Section 3.87.4.4.2).

2:3.87.4.3 Replace File Request Message

The File Source uses this message to replace a file already existing on the File Manager.

This message is used when there is a prior file that needs to be preserved, so the existing Binary and Document Reference Resources will be superseded (i.e., deprecated).

The File Manager is not required to support FHIR resource versioning (https://www.hl7.org/fhir/R4/versions.html).

2:3.87.4.3.1 Trigger Events

The File Source needs to replace a file that exists on the File Manager.

The replace mechanism will be handled by creating a new file and updating the previous DocumentReference Resource in one message.

2:3.87.4.3.2 Message Semantics

This message uses an HTTP POST to submit a FHIR Bundle that contains the new Binary and DocumentReference Resources and also the prior DocumentReference Resource that needs to be replaced.

The Bundle Resource shall contain:

  • one Binary Resource representing the new file, valued according to Section 3.87.4.1.2, with the bundle.entry.request.method element set to POST

  • one DocumentReference Resource with metadata for the new file, where the DocumentReference.status shall be set to “current”, the relatesTo.code shall be set to “replaces”, and the relatesTo.target to the URL of the previous DocumentReference Resource, and the bundle.entry.request.method element set to POST

  • one DocumentReference Resource with metadata of the previous file, valued as specified in Section 3.89.4.1.1 with the bundle.entry.request.method element set to PUT and the DocumentReference.status to “superseded”

2:3.87.4.3.3 Expected Actions

The File Manager shall support all the media-types defined in ITI TF-2: Appendix Z.6 (currently in the Appendix Z on HL7 FHIR Trial Implementation Supplement).

On receipt of the Replace File Request, the File Manager shall validate the Resources and respond with one of the HTTP codes defined in Section 3.87.4.4.2 Message Semantics.

The File Manager shall process the Bundle atomically.

The File Manager shall store these resources and make the new file available for further processing, e.g., file update or replacement [ITI-87], file metadata update [ITI-89], search [ITI-88], and retrieve [ITI-109].

If the File Manager receives a Replace File Request message that contains resources other than the required ones, it may respond to the File Source with a failure (see Section 3.87.4.4.2).

2:3.87.4.4 Submit File Response Message

The File Manager sends a Submit File Response message in response to a Create File Request, an Update File Request, or a Replace File Request Message.

2:3.87.4.4.1 Trigger Events

When the File Manager has finished creating or updating the file and metadata received from the File Source, the File Manager sends this message to the File Source acknowledging the result of the create, update or replace request.

2:3.87.4.4.2 Message Semantics

When the File Manager has processed the request, it shall return an HTTP response with an overall status code.

The File Manager returns a HTTP status code appropriate to the processing, conforming to the transaction specification requirements as specified in http://hl7.org/fhir/R4/http.html#transaction-response.

To allow the File Source to know the outcome of processing the transaction, and the identities assigned to the resources by the File Manager, the File Manager shall return a Bundle, with type set to transaction-response, that contains one entry for each entry in the request, in the same order as received, with the outcome of processing the entry. Each entry element shall contain a response element with an HTTP Status Code which details the outcome of processing of the request entry.

If the operation is a success, the HTTP status code of the response shall be a 2xx code.

If the operation is a failure, the File Manager shall be capable of returning the following status code:

  • 422 – Unprocessable Entity:

  • When the FHIR Resource DocumentReference.type is not supported by the File Manager

  • If the Bundle Resource contains resources other than Binary, DocumentReference Resources and the resources referenced by the DocumentReference Resource

The File Manager can return other status codes 4xx or 5xx in accordance to internal business rules that are out of scope for this transaction.

2:3.87.4.4.3 Expected Actions

The File Source processes the response according to application-defined rules.

2:3.87.4.5 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.87.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, actions such creating, updating, or replacing 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.87.5.1 Security Audit Considerations

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

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

The File Source and File Manager may also record fundamental AuditEvents for each individual resource Created or Updated, using the BALP basic profile for REST events.