File attachments - Release 1

The file attachments work includes:

• an increase of the file size limit
• a switch to direct file upload and download
• the introduction of malware scanning

File size limit

For a long time, e-RS has maintained a file size limit of 5MB.

To support new care settings and share high-resolution media, the e-RS will be increasing the maximum supported file size. The maximum file size will increase to 100MB, and may increase beyond this in the future.

Direct upload/download

To enable fast, efficient transfer of large files, new endpoints will be introduced. These endpoints will allow direct file transfer to and from the e-RS object store.

The 5MB limit for the existing upload and download endpoints will remain in place.

Malware scanning

Alongside the file size increase, the e-RS will scan all file uploads for malware. This will impact how you process file downloads.

All partners integrated with either API endpoint:

• Retrieve attachment (A006, FHIR STU3) 
• Upload file to document store (A020, FHIR STU3)

What are we doing and why

With the introduction of direct uploads, files will be processed asynchronously. Processing will include file validation and malware scanning.

Asynchronous processing means that an uploaded file may not always be ready for download immediately.

Files will only be available after processing is complete, validation passes, and no threats are detected.

We will be introducing an availability status for each attachment.

An attachment can be in one of 4 states:

1. AVAILABLE - the file is available for download.

2. PENDING - the file is being scanned and cannot be retrieved.

3. VALIDATION_FAILED - the file has failed validation and cannot be retrieved.

4. THREATS_DETECTED - the file has been quarantined after detecting a threat and cannot be retrieved.

What you need to do

Check file availability status

The availability status of an attachment should be checked before attempting to download it.

This can be retrieved via any endpoint that provides attachment metadata in its response, for example:

• Retrieve referral request (A005, FHIR STU3)
• Retrieve advice and guidance request summary (A024, FHIR STU3)
• Retrieve advice and guidance conversation (A025, FHIR STU3)

Only the AVAILABLE status will be present in the metadata from Release 1.

The other availability states will start to be returned in Release 2 (date to be confirmed).

Wait for a scan to complete before downloading

If the file is currently being scanned, it cannot be retrieved.

The attachment status of the file will be PENDING.

You must wait at least 5 minutes before checking its availability again.

If an attempt is made to retrieve the file, an error will be returned. See Retrieve attachment (A006, FHIR STU3)/Retrieve attachment (A042, FHIR R4) for further details.

Create a process to manage files that can't be downloaded

An attachment cannot be retrieved if validation failed or threats were detected.

The attachment status of the file will be VALIDATION_FAILED or THREATS_DETECTED.

Your software should ask the user to contact the organisation that uploaded the file to resolve the issue and get the information you require.

The attachment metadata will include:

• details of the organisation (Extension-eRS-AttachedBy-Organisation-1)
• the user (Extension-eRS-AttachedBy-1) who attached the file

If an attempt is made to retrieve the file an error will be returned. See Retrieve attachment (A006, FHIR STU3)/Retrieve attachment (A042, FHIR R4) for further details.

What are we doing and why

To allow faster and more efficient transfer of large files, a new endpoint is required to facilitate download directly from the e-RS object store.

The Retrieve attachment (A006, FHIR STU3) endpoint will only support a maximum file size of 5MB (5242880 bytes) and will be deprecated.

The new Retrieve attachment (A042, FHIR R4) endpoint must be used to download larger attachments.

What you need to do

When the file size limit is increased to 100MB (Release 4), it will be possible for users to upload files greater than 5MB.

To support receiving these large files, you must integrate with the new Retrieve attachment (A042, FHIR R4) download endpoint, or implement manual processes to manage larger files.

Integrate with the new download endpoint

Enable your software to download large file attachments by integrating with the new Retrieve attachment (A042, FHIR R4) download endpoint.

See Migrating to the new Retrieve attachment (A042) endpoint for further information.

Implement manual processes to manage larger files

Partners can continue to use Retrieve attachment (A006, FHIR STU3).

However, the endpoint will only support the download of files up to 5MB, and will be deprecated.

Your software should:

• check the attachment size metadata before retrieval to ensure the size is supported
• put in place processes to enable your users to gain access to larger files

You must direct users to manually download these files using the e-RS professional web application.

If an attempt is made to retrieve a file that is over 5MB an error will be returned. See Retrieve attachment (A006, FHIR STU3) for further details.

What we are doing and why

To allow faster and more efficient transfer of large files, a new endpoint is required to facilitate upload directly to the e-RS object store.

The new Upload file to document store (A039, FHIR R4) endpoint will support the upload of files, up to 100MB.

The existing Upload file to document store (A020, FHIR STU3) upload endpoint will continue to be restricted to 5MB (5242880 bytes). This endpoint will be deprecated when the new FHIR R4 endpoint is released.

There is no direct impact for existing users of A020. However, if partners want to take advantage of larger file attachments they must integrate with the new endpoint.

The new upload endpoint will be made available in Release 3 (date to be confirmed).

What you need to do

Partners wanting to upload file attachments greater than 5MB must integrate with the new upload upload endpoint - Upload file to document store (A039, FHIR R4)

Once the new endpoint is released, the existing upload endpoint (Upload file to document store (A020, FHIR STU3)) will be deprecated and then retired from service one year later. This is inline with our sunsetting policy.

Partners will need to migrate to the new endpoint before this date.

If you have a query or need further information about file attachments, please contact us at [email protected].