Interface SpecificationNational Endoscopy Database (NED)
National Endoscopy Database (NED)
Interface Specification
Version: 1.16
Date: 06/10/2017
1Contents
1Contents
2Introduction
2.1Background
2.2Purpose of this document
2.3Scope
2.4Assumptions
2.5References
2.6Abbreviations & Terminology
3Upload Interface
4Queue Update Service Interface
5Security
6Batch processing
2Introduction
This document provides information concerning how to communicate with the National Endoscopy Database and describes the scope, purpose and an overview of this project.
2.1Background
The JAG is introducing a facility to enable Endoscopy System Suppliers to submit, electronically, procedure information on behalf of endoscopists to a national database, NED.
Endoscopy System Suppliers who wish to use the NED Import service must register with the JAG to do so.
Use of the NED Import service will remove the need for endoscopists to manually key in procedure data thus saving time, improve quality and increase coverage of procedures recorded throughout England.
2.2Purpose of this document
This document defines the electronic communication between local endoscopy systems and the National Endoscopy Database.
It is aimed, primarily, at technicians who need a detailed understanding of how to transmit messages that have been defined in the document Business Message Specification.
2.3Scope
This document is one of a number that when taken together describes the NED Import service. The complete documentation set is shown in the following table, with this document highlighted.
Business Message Specification
SendBatchMessage
/ Defines the content of the business message that will pass from the Local Endoscopy System to NED.
Business Message Specification
GetBatchStatusMessage
/ Defines the content of the messagereceived by the Local Endoscopy System when querying the status of a procedure batch in NED.
Interface Specification
/ Defines the operational interface and security requirements for connecting to NED Import service including the transmission of data.
The focus of this document is the Interface specification for the transfer of messages containing procedure information to NED.
2.4Assumptions
The content of this document is based on the following assumptions.
- The Reader is familiar with the Business Message specification document.
- Have an understanding of Web Service technology.
2.5References
The table below lists references to other relevant documentation. References to these documents, within the text of this document, are made using the square-bracket notation shown in the “Ref” column of the table.
Ref / Description[1] / Business message specification document.
2.6Abbreviations & Terminology
This section provides definitions of abbreviations and unusual terminology used in this document.
Abbreviations
Abbreviation / MeaningES / Endoscopy System Supplier
NED / National Endoscopy Database
JETS / JAG Endoscopy Training System (
JAG / Joint Advisory Group on GI Endoscopy (
ODS / Organisation Data Service (ODS) codes
For example: RGQ for IPSWICH HOSPITAL NHS TRUST.
A complete listing can be found in the blow
(
ERS / Endoscopy Reporting System
Terminology
Term / MeaningNone specified
3Upload Interface
The following web service method is provided to allow procedure information to be uploaded into NED.
Response Object =WebService.Send(organisationApiKey,organisationCode,batchId, messageData,isCompressed);
Request parameters
There are 7 parameters to this method and these are described below.
Parameter / Type / Description1 / organisationApiKey / string / A unique key used to identify the hospital sending the data
2 / organisationCode / string / The national (ODS) code of the hospital sending the data.
3 / batchId / string / This is defined locally for each transmission to uniquely identify the batch. Used to understand which batches have and have not been imported via the Queue status method.
4 / messageData / byte[] / The xml business message being transmitted to NED represented in bytes.
See business Message Specification for the format of this message.
5 / isCompressed / bool / To reduce bandwidth messages MessageData can be transmitted in a compressed format.
Note that currently only GZipStreamcompression format is supported and is an optional feature.
Responseobject
The return is a single complex type consisting of 2 fields which are described below.
Parameter / Type / Description1 / Queued / bool / This field indicates that the message has been successfully queued.
If the message has not been successfully queued the exception message field will contain a reason why the submission has failed.
2 / ExceptionMessage / string / Reason for failure (ifQueued is false).
4Queue Update Service Interface
The following methodsare provided to allow ERSsuppliers to query the NED import queue. It uses the principle of checking for the latest results based on the supplier’s unique tracking id.
To obtain an update of a single batch use this method
Response Object = WebService.GetSingle(organisationApiKey,organisationCode, supplierBatchId);
To obtain an update of multiple batches use this method
Response Object = WebService.GetMultiple (organisationApiKey,organisationCode, supplierBatchId*);
Request object
There are 4 parameters to this method and these are described below.
Parameter / Type / Description1 / organisationApiKey / string / A unique key used to identify the hospital sending the data
2 / organisationCode / string / The national (ODS) code of the hospital sending the data.
3 / supplierBatchId / String / The tracking number provided by the ERS to identify the batch.
4 / supplierBatchId* / String[] / The tracking number provided by the ERS to identify the batch.
Response object
The return is a single complex type consisting of 2 fields which are described below.
Parameter / Type / Description1 / ExceptionMessage / string / Reason for failure (if Queued is false).
2 / MessageData / byte[] / The xml business message providing the results since the last time the interface was polled.
See Appendix A- hospital.GetBatchStatusMessagefor the format of this message.
5Delete Procedure Service Interface
The following methods are provided to allow ERS suppliers to delete existing procedures that have been uploaded by their system.
To delete a single procedure use this method
Response Object = WebService.DeleteSingle(organisationApiKey,organisationCode, siteCode, localProcedureId);
To delete multiple procedures use this method
Response Object = WebService.DeleteMultiple (organisationApiKey,organisationCode, siteCode, localProcedureId*);
Request object
There are 5 parameters to this method and these are described below.
Parameter / Type / Description1 / organisationApiKey / string / A unique key used to identify the hospital sending the data
2 / organisationCode / string / The national (ODS) code of the hospital sending the data.
3 / siteCode / String / The site where the procedures being deleted belong to.
4 / localProcedureId / String / The local procedure Id provided by the ERS in a previous upload.
5 / localProcedureId* / String[] / The local procedure Id provided by the ERS in a previous upload (Array)
Response object
The ERS system should check the ExceptionMessage string from the returned complex type to know if there was an issue deleting a procedure.
Parameter / Type / Description1 / ExceptionMessage / string / Reason for failure (if Queued is false).
6Security
Connection
The connection to the NED Interface is preformed over Secure Socket Layers (SSL).
The service itself is hosted on the internet and accessed via port 443. Therefore each Endoscopy supplier will need to liaise with their customersto ensure that this portisnot blocked.
The test environment is available using the below address:
Credentials
Each web service callwill comprise of:
- Organisation API Key.
- Organisation ODS Code.
These are setup by the NED System administrators. Test accounts will be provided to the NED working group members during its intial trial.
Requests for new live accounts should be directed to .
7Batch processing
It is recommended that batches of no more than 50 procedures are sent within 30 minutes of the last transmission carried out by the site.
8Document Control
Date / Version / Change20/01/2014 / 1.01 / Initial version
06/10/2017 / 1.16 / Document version number updated to bring in line versioning with Schema and “Business Message Specification –SendBatchMessage”.
Two new webservice methods introduced in this release:
- DeleteSingle (Delete a single Procedure)
- DeleteMultiple (Delete a multiple Procedures)
Version 1.16Page 1 of 10