Main title goes here EDT Hub API Specification v2.9

Transcription

1 Main title goes here EDT Hub API Specification v2.9 Prepared by: Philip Young, PCTI IS2 Folder: Internal\Technical\Products\EDT Date: Monday, 24 September 2007 Revision No: 2.9 (EDT Hub version upwards) Updated 25 th January 2013 by Richard Clark This document contains information that is proprietary to PCTI Solutions Limited and must not be disclosed in whole or in part to any third party. Copyright PCTI Solutions Limited All Trademarks are hereby acknowledged. Inbound Web Service

2 2 Contents Contents... 1 Document Revision History... 3 Introduction... 4 Overview... 6 The EDT Hub API (Inbound Web Service)... 9 EDT_AddDocumentXML EDT_SetDocStatus EDT_GetDocStatus EDT_GetDocStatusExt EDT_GetDocStatusList EDT_GetDocIDfromSourceID EDT_GetEndPointList EDT_GetEndPointList "rsxmlout" Example Contents EDT_GetEndPointStatus EDT_GetEndPointStatus "rsxmlout" Example Contents EDT_GetPracticeCodefromGPCode EDT_GetPracticeList EDT_GetPracticeList rsxmlout Example Contents EDT_GetSourceTypes EDT_GetSourceTypes rsxmlout Example Contents EDT_GetPracticeStatus EDT_GetPracticeStatus rsxmlout Example Contents Guidance for Implementation Use the test harness to connect to the Test Web Service Create your own message Test Harness Feature List Recommended approach to adding a document Supplying an updated version of a document that has already been added to EDT Hub Handling Errors returned by the API EDT_AddDocumentXML EDT_SetDocStatus EDT_GetDocStatus and EDT_GetDocStatusExt EDT_GetDocIDFromSourceID EDT_GetEndPointList EDT_GetEndPointStatus EDT_GetPracticeCodeFromGPCode EDT_GetPracticeList EDT_GetPracticeStatus EDT_GetSourceTypes General errors returned by any API method... 56

3 3 Document Revision History Revision: 2.6 Date: 09/06/2011 I. Added EDT_GetEndPointList method II. Added EDT_GetEndPointStatus method III. Changed EDT_GetPracticeList to return End Points of type "Practice" only. IV. Changed EDT_GetPracticeStatus to return End Points of type "Practice" only. V. Added error message summary for EDT_GetEndPointList VI. Added error message summary for EDT_GetEndPointStatus VII. Added additional error messages to summary of EDT_AddDocumentXML Revision: 2.7 Date: 15/11/2011 I. Updated Screenshots and text to reflect changes to the Test Harness in the section titled Guidance for Implementation. Revision: 2.8 Date: 14/12/2011 I. Updated Screenshots and text to reflect changes to the Test Harness in the section titled Guidance for Implementation. Specifically the Add Document section, which has a new feature titled Apply DTD Checks. Revision: 2.9 Date: 15/10/2012 I. Added description for method EDT_GetDocStatusList.

4 4 Introduction This document describes the API available to systems wishing to interface with a PCTI EDT Hub. It should be read in conjunction with the PCTI EDT Message Specification which describes the required message content when adding a document to EDT Hub. The API currently supports messages based on the widely used Kettering Specialist Service Report Message with additional elements required to support clinical document transfer to GP practices. The EDT Hub API is presented as a Web Service interface. All documents added to EDT Hub should be added via this web service either directly or indirectly e.g. via the EDT Folder Monitor or EDT Document Capture Interface (please see the separate documentation relating to these applications). Support for the legacy COM interface was deprecated in edition 2.01 of the API. Required Reference Material PCTI EDT Message Specification PCTI EDT Document Type Definition (DTD) Sample Message containing an HTML document payload Sample Message containing a binary encoded TIFF document payload EDT Hub Test Harness application Test System A fully functioning test interface is available on the internet at: For those unfamiliar with a.net based web service, a full service description is available at: Use of this web service requires a unique supplier key. These keys are generated by PCTI and applied to each live EDT Hub installation.

5 5 Test Appliances For full end-to-end testing a VMWare Image of Docman (the GP side) is available. Please speak to your PCTI contact should you like to request either of these images. Developer Testing The Test Harness application allows a developer to issue web methods against an EDT Hub and inspect the returned XML content. This can be used to check that actual results conform to the reference results returned by the test application. Please see the Guidance for Implementation section later in this document. Developer Support Whilst developing the interface to EDT Hub any queries should be directed to devsupport@pcti.co.uk which is a distribution list monitored by developers that are able to assist. This same team can be reached on the following direct dial telephone number:

6 6 Overview This document describes the interface requirements for the API only. However, it is helpful to understand how the API fits into the overall EDT architecture: EDT Hub comprises of a number of elements: 1. An RDBMS used to manage the entire application (EDT DB) 2. A public Inbound Web Service Based API to support incoming EDT Hub Documents posted within a Kettering style message structure known as the EDT Hub Message specification (EDT WSAPI) 3. A private Outbound Web Service allowing outgoing documents to be collected securely by GP practices via Docman EDT software (EDT WSAPI) 4. A role based browser based configuration, viewing and reporting application used to maintain the system and for inspecting incoming and outgoing transmissions (EDT ADMIN) 5. A windows service application that maintains the database, removes old data from the live database into archives, reports telemetry to the service desk dashboard application, handles software licensing and software updates. It is also used to send SMTP notifications to users specified by the EDT ADMIN application (EDT MAINT) 6. A print capture desktop application that allows any application (eg MS Word) to send documents via the EDT web service by providing an interface for metadata capture and an outbox view of sent documents (EDT PCAP). 7. A light weight collection agent (EDT Connect Lite) that can be distributed to any user who has access to the EDT Hub for document collection. This is not required by practices who have Docman EDT (EDT CONNECT LITE) 8. An application adapter for CfH s Interoperability Toolkit (ITK) allowing compliant messaging from an accredited ITK web service host to EDT. (EDT ITK) In addition: 9. A generic folder monitor application that provides an xml document interface for non-web service enabled applications (EDT FMON). Note: this application is provided outside of the main EDT Hub deliverables and responsibility for its configuration and monitoring lies with the implementer.

7 7

8 8

9 9 The EDT Hub API (Inbound Web Service) Introduction All incoming documents are passed into EDT via this API. The API is presented as a synchronous web service over HTTPS (HTTP in non-live environments). Note: We insist that all sites implement SSL but ultimately the responsibility for network security lies with the customer. The API using the Microsoft.net platform which makes it easy for integrators using Visual Studio to consume the web service as a web reference. The API communicates directly with the database which is either hosted locally (as per diagram above) or remotely in a secure managed environment. There is no direct access to the EDT Hub infrastructure other than through this API. Sending applications may use the API to check on the current status of posted documents in order to find out if they have been collected or rejected by the receiving practice. EDT Hub is ITK 1.x compliant and has been accredited for CDA document messaging. See Legacy Systems that do not support XML There may be applications within a trusts infrastructure that are unable to support XML or web service messaging. EDT Hub contains the tools to make integration possible: Automated Document Creation Systems If sending applications are unable to send SOAP messages or communicate directly with a.net web service, XML conforming to the EDT Hub message specification can be dropped in a specified folder. Implementer s may use the folder monitor to checks this location and handles the posting to the API. However, this should only be used where there is absolutely no other way to communicate since the sending application needs to manage rejections and generally administer the drop folder directory structure itself. Manual Document Creation Systems Many documents in healthcare are typed and therefore Word is the document creation system. There are several ways you can integration, one being word macros which will build the metadata and package the xml before onward posting to the web service. Alternatively, you can use the EDT Print Capture utility to post any document to the EDT Hub Web Service via a simply dialog. This can also be used to check on sent documents and view any practice rejections.

10 10 Functionality The API exposes several methods in order to provide the following functionality: Supply (add) a new document embedded in an xml string conforming to the PCTI EDT Message Specification. Update a given documents status (onhold, waiting, deleted etc) Obtain a given documents internal EDT ID by passing in the sending systems unique reference id Obtain the current status of a given document. Get a list of practices and GP s within a given practice Get a list of document source types available on the EDT Hub Look up a practice code from a given GP code Retrieve a document status summary for a given practice (no of docs waiting/delivered from a specified date and time) The API does not permit: Any document to be modified once posted to EDT Hub. To replace a document before it is collected by a practice, change the status to DeletedBySender and resubmit a replacement document. Retrieval or viewing of a document that already exists in EDT Hub.

11 11 EDT_AddDocumentXML This method is used to add a document to EDT Hub. The document within the XML may be clear text (html formatted, rich text or plain text) OR any file in binary (Base 64) encoded form. Prerequisites In order to add a document, you must know the NACS code of the receiving practice and that it is active in EDT Hub. You can determine if a practice is available (both present and active) on the EDT Hub using EDT_GetPracticeList (the inactive element will be 0 in the returned xml). Documents that do not contain an active GP practice will be rejected. You will also need to specify the document source type. The document source type is an id within EDT Hub that allows documents to be categorised, usually by department. The administrator of the system is then able to switch documents types on/off without effect the entire system. Generally each sending system will use its own document source type. In order to obtain a list of active document source types, use the EDT_GetSourceTypes method. Documents that do not contain an active document source type will be rejected. For further information, please see the Guidance for Implementation section later in this document for further information about using EDT_AddDocumentXML. Passed in: Access Key (string) A unique key provided by PCTI in order to prevent unauthorised use of the API XML (string) XML string containing a message conforming to the standard as defined in the PCTI EDT Message Specification. This message contains the document metadata and the physical document. Document Extension (string) File type specified by the file extension of the embedded document in the CDDATA text block of the XML. Embedded documents fall into 2 categories, text and binary. Text file categories HTM TXT RTF Binary file categories Anything other than above e.g. DOC, PDF Text files are extracted and identified using the Document Extension specified.

12 12 Binary file categories extracted, un-encoded and saved using the Document Extension specified. Encoding must be Base 64. Passed Back: Returns: Document Status (integer) The status of the document once added. Values are: 4001 On Hold (not yet available for collection) 4002 Waiting (available for immediate collection) Document ID (string) The ID of the newly created EDT document. This ID can be used to query/set the status of a document - see EDT_GetStatus and EDT_SetDocStatus Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_AddDocumentXMLResponse xmlns="edtwebns"> <EDT_AddDocumentXMLResult>boolean</EDT_AddDocumentXMLResult> <rsnewdocid>string</rsnewdocid> <rserr>string</rserr> </EDT_AddDocumentXMLResponse> </soap:body> </soap:envelope>

13 13 EDT_SetDocStatus Updates the current document status for a specified EDT document ID. Applies to documents with a current status of OnHold, Waiting or Rejected Only. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Document ID (string) The EDT Document ID returned from a successful call to EDT_AddDocumentXML Document Status (integer) Valid values are: 4001 On Hold (not yet available for collection) 4002 Waiting (available for immediate collection) 4006 DeletedBySender (added in error by sender) Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_SetDocStatusResponse xmlns="edtwebns"> <EDT_SetDocStatusResult>boolean</EDT_SetDocStatusResult> <rserr>string</rserr> </EDT_SetDocStatusResponse> </soap:body> </soap:envelope>

14 14 EDT_GetDocStatus Retrieves the current document status for a specified EDT document ID. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Document ID (string) The EDT Document ID returned from a successful call to EDT_AddDocumentXML Document Status (integer) Values are: 4001 On Hold (not yet available for collection) 4002 Waiting (available for immediate collection) 4003 Delivered 4004 Processed 4005 Rejected 4006 DeletedBySender (replaced with newer version) 4007 ConversionPending (auto-set to waiting once tiff ed) Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response POST /edtwebservice.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "EDTwebns/EDT_GetDocStatusExt" <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetDocStatusResponse xmlns="edtwebns"> <EDT_GetDocStatusResult>boolean</EDT_GetDocStatusResult> <restatus>int</restatus> <rserr>string</rserr> </EDT_GetDocStatusResponse> </soap:body> </soap:envelope>

15 15 EDT_GetDocStatusExt Extended version of EDT_GetDocStatus(). Retrieves the current document status for a specified EDT document ID. Additionally returns reason and type of rejection if the current document status is flagged as Rejected. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Document ID (string) The EDT Document ID returned from a successful call to EDT_AddDocumentXML Document Status (integer) Values are: 4001 On Hold (not yet available for collection) 4002 Waiting (available for immediate collection) 4003 Delivered 4004 Processed 4005 Rejected 4006 DeletedBySender (replaced with newer version) 4007 ConversionPending (auto-set to waiting once tiff ed) Rejection Type (integer) Values are: 0 N/A (default value if status is not 4005) 1 User rejection (eg Patient not registered at practice) 2 System rejection (eg document failed during collection) Rejection Reason (string) A description of the rejection reason if one exists Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False

16 16 Soap 1.1 Response POST /edtwebservice.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "EDTwebns/EDT_GetDocStatusExt" <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetDocStatusExt xmlns="edtwebns"> <rskey>string</rskey> <rldocid>int</rldocid> <restatus>int</restatus> <rserr>string</rserr> <retype>int</retype> <rereason>string</rereason> </EDT_GetDocStatusExt> </soap:body> </soap:envelope> EDT_GetDocStatusList Method to retrieve a list of documents matching the required criteria. The list is return as a well formed XML string detailed below. Passed in: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Document Status (integer) The document status of the documents to be retrieved Values are: 4001 On Hold (not yet available for collection) 4002 Waiting (available for immediate collection) 4003 Delivered 4004 Processed 4005 Rejected 4006 DeletedBySender (replaced with newer version) 4007 ConversionPending (auto-set to waiting once tiff ed) Document Source ID (integer) The document source id of the documents to be retrieved. This can be passed as 0 to get all the documents. Start Date (DateTime) The start date of the date filter of the documents to be checked.

17 17 End Date (DateTime) The end date of the date filter of the documents to be retrieved. NACS Code (string) Supply the NACS code of the endpoint if you want to filter the results for that specific endpoint. User Rejections only (boolean) When querying for rejected documents, passing a value of true will set the filter to only return results for user rejections. Otherwise all rejections are returned. Passed Back: Document List XML (string) The resulting list is returned as an XML list for simple parsing. The EDT Hub document id is returned in the document attribute of DocID and the original document reference is shown in the Document_ref element. Notes: When querying rejected documents the returned XML element <Rejection_Reason> has a type attribute, this will be a value of USER document rejected by the receiving user SYSTEM document rejected by the system, EDT or the receiving system The EndPoint element has an attribute of NACS which holds the value of the NACS code to the end point described in the element. The DocumentSource element has an attribute of ID which holds the numerical id of the document source type from the Hub. This ID can be used in later calls to the method to retrieve document statuses for a specific document source.

18 18 Example returned XML showing user rejections ( from code examples above ) Returns: Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False depending on success or failure Soap Example POST /edtwebservice/edtwebservice.asmx HTTP/1.1 Host: Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "EDTwebns/EDT_GetDocStatustList" <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetDocStatustList xmlns="edtwebns"> <rskey>string</rskey> <rlstatus>int</rlstatus> <rldocsourceid>int</rldocsourceid> <rostartdate>datetime</rostartdate> <roenddate>datetime</roenddate> <rsnacs>string</rsnacs> <rsxml>string</rsxml> <rbuserrejonly>boolean</rbuserrejonly> <rserr>string</rserr>

19 19 </EDT_GetDocStatustList> </soap:body> </soap:envelope>

20 20 EDT_GetDocIDfromSourceID Used to retrieve the EDT document ID from a supplied source systems internal ref/id. This would be used to lookup the EDT ID prior to checking a documents status where the Document ID was not retained following the call to EDT_AddDocumentXML. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Source Type (integer) The ID of the document source system (See meta data table for SOURCETYPE) Source Document ID (string) The source systems unique document ID or reference Document ID (integer) The EDT Document ID returned from a successful call to EDT_AddDocumentXML Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetDocIDfromSourceIDResponse xmlns="edtwebns"> <EDT_GetDocIDfromSourceIDResult>boolean</EDT_GetDocIDfromSourceIDResul t> <rldocid>int</rldocid> <rserr>string</rserr> </EDT_GetDocIDfromSourceIDResponse> </soap:body> </soap:envelope>

21 21 EDT_GetEndPointList Used to retrieve a full list End Points and (if configured) as list of associated GP s. It may also be used to retrieve the GP list for a specific end point. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API NACS Code (string) NACS code configured in EDT Hub Leave blank or supply wildcard(*) to retrieve ALL end points Logical Address (string) Logical Address configured in EDT Hub Leave blank or supply wildcard(*) to retrieve ALL end points End Point List (XML String) End Point and associated GP's list Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetEndPointListResponse xmlns="edtwebns"> <EDT_GetEndPointListResult>boolean</EDT_GetEndPointListResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetEndPointListResponse> </soap:body> </soap:envelope>

22 22 EDT_GetEndPointList "rsxmlout" Example Contents

23 23 EDT_GetEndPointStatus Returns a document summary from a given date. Please note that the values refer to documents sent to all document source types. Passed in: Passed Back: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API NACS Code (string) NACS code configured in EDT Hub Leave blank or supply wildcard(*) to retrieve ALL end points Logical Address (string) Logical Address configured in EDT Hub Leave blank or supply wildcard(*) to retrieve ALL end points Start Date (string) Start date from which base the statistics Use wildcard (*) on start date to return all available information Summary (XML string) An xml summary showing no of waiting (non-collected), no on hold, no delivered, no rejected since ever or start date Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API Returns: True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetEndPointStatusResponse xmlns="edtwebns"> <EDT_GetEndPointStatusResult>boolean</EDT_GetEndPointStatusResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetEndPointStatusResponse> </soap:body> </soap:envelope>

24 24 EDT_GetEndPointStatus "rsxmlout" Example Contents

25 25 EDT_GetPracticeCodefromGPCode Return the NACS code of the GP practice for a specified GP code. Passed in: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API GP Code (string) Any GP code configured in EDT Hub Passed Back: Returns: Practice Code (string) NACS code for the practice the GP belongs to Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetPracticeCodeFromGPCodeResponse xmlns="edtwebns"> <EDT_GetPracticeCodeFromGPCodeResult>boolean</EDT_GetPracticeCodeFromG PCodeResult> <rsnacs>string</rsnacs> <rserr>string</rserr> </EDT_GetPracticeCodeFromGPCodeResponse> </soap:body> </soap:envelope>

26 26 EDT_GetPracticeList Used to retrieve a full list Practices and (if configured) as list of associated GP s. It may also be used to retrieve the GP list for a specific practice. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Practice Code (string) Pass in a NACS code in order to obtain a list of GP s for a specific practice Leave blank or supply wildcard character * to retrieve all practices. Practice and GP List (XML string) XML string containing a list of practices and associated GP s Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetPracticeListResponse xmlns="edtwebns"> <EDT_GetPracticeListResult>boolean</EDT_GetPracticeListResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetPracticeListResponse> </soap:body> </soap:envelope>

27 27 EDT_GetPracticeList rsxmlout Example Contents

28 28 EDT_GetSourceTypes Used to retrieve a list of active document sources configured in EDT Hub. Document source types that are marked as inactive are not returned. Passed in: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Passed Back: Returns: Source Type List (XML string) XML string containing a list of document sources Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetSourceTypesResponse xmlns="edtwebns"> <EDT_GetSourceTypesResult>boolean</EDT_GetSourceTypesResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetSourceTypesResponse> </soap:body> </soap:envelope>

29 29 EDT_GetSourceTypes rsxmlout Example Contents

30 30 EDT_GetPracticeStatus Returns a document summary from a given date. Please note that the values refer to documents sent to all document source types. Passed in: Passed Back: Returns: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Practice Code (string) The NACS code relating to the enquiry. Start Date (string) Start date from which base the statistics Use wildcard (*) on start date to return all available information Summary (XML string) An xml summary showing no of waiting (non-collected), no on hold, no delivered, no rejected since ever or start date Error Description (string) Error message describing reason for method failure For a list of error descriptions, see section Handling Errors returned by the API True/False Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetPracticeStatusResponse xmlns="edtwebns"> <EDT_GetPracticeStatusResult>boolean</EDT_GetPracticeStatusResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetPracticeStatusResponse> </soap:body> </soap:envelope>

31 31 EDT_GetPracticeStatus rsxmlout Example Contents

32 32 Guidance for Implementation This section provides guidance for the developer on how to integrate with the API. Before you begin, you should download the reference material identified at the start of this document (message specification, DTD, sample xml and test harness). Use the test harness to connect to the Test Web Service First of all, let s ensure that you are able to see the test web service and post a sample message to it. Copy the.net test harness application locally and run EDTH_TestHarness.exe. 1) Ensure that the webservice URL to points to PCTI test instance of the EDT Web Service: 2) Click Test If the test connection is successful, you will see the following dialog If not, please check that you have typed the url correctly (suggest cutting and pasting from this doc). If you still have problems, please contact PCTI to check on the availability of the test machine in case it is offline for maintenance. 3) Now enter the supplier access key that has been allocated to you in the Access Key text box. If you have not been allocated one, you may use the pilot key which is PI Please note that this key cannot be used in a production environment as some meta data is removed to make it unusable for a real practice.

33 33 4) Using the Add Document tab, set the Document Status to Waiting 5) Click on the... button to the right of the XML File text box and browse to the test.xml file. Select the file and then click on the Open button. Note: By default, you will be viewing a folder containing a test xml file. You can browse to another folder and use a file of your own if you wish. 6) Tick the Replace ReportID checkbox so that the document is updated with a unique reference number.

34 34 7) You can get the Test Harness to run an XML DTD check to verify your xml is correct by clicking in the Apply DTD Checks check box. This is optional and can be omitted. 8) Click Invoke. If you have selected the Apply DTD Checks option and there are differences in the xml you will see the following information message: This message indicates that the document has been added to the EDT Hub web service but there were errors detected in the xml contained in the test.xml file. Click OK to clear this message. You will see the Add Document tab displayed again.

35 35 If you wish to examine the test log in more detail, click on the View Test Log button. This will display the test log in its own window as shown below. To view the most recent entry scroll to the bottom of the log: Create your own message You should now create your own message using xml that conforms to the supplied DTDs. The PCTI EDT Message Specification provides details of the required meta data. As mentioned in the introduction, this is based on the Kettering structure and is therefore easily producible by most existing healthcare systems. The message must conform to the DTD and must be referenced in DOCTYPE within the message. The EDT_AddDocumentXML method will validate against this DTD on receipt and will reject should it fail validation. In order to create the message, you will require the following bits of information that relate to the specific EDT Hub you are posting to namely: An active GP practice NACS code An active Document Source Type Both of these can be extracted using the available methods (EDT_GetPracticeList and EDT_GetSourceTypes) or by exporting the xml list via the test harness.

36 36 1. Click on the Practice List You can either: List all the practices on the EDT Hub or you can List just one Practice by specifying the NACS code in the field provided. 2. Click on the Invoke button to populate the Practice List. The practice list is displayed: You can either view or save this list by using the buttons on the bottom left of the Practice Lists tab.

37 37 To View a Practice List If you wish to view the list click on the View XML button on the bottom left of the Practice tab. The list will open in a window as shown below. To Save a Practice List If you wish to save the list you can use the Save button at the bottom left of the Practice List tab. The windows Save dialogue box will open. This will allow you to navigate to your desired save location and specify a name for your file. Click the Save button to save your Practice List to a location of your choice. You will see a confirmation message displayed on your screen when the save is complete.

38 38 Your practice list has now been saved, click the OK button to close the message box. If you navigate to the folder containing your practice list file and double click on your saved file, it will open in your web browser: Test Harness Feature List You can use the test harness in a number of different ways, which are described in this section of the document. Add Document This feature allows you to add a document to the EDT Hub you are connected to. Use of this feature is described in the section titled Use the Test Harness to connect to the Test Web Service on Page 32 of this document. Set Document Status This feature changes the status of a document. To use this feature you will need to know the Document ID. For example, if a document is On Hold you can change it to Waiting or Deleted by Sender.

39 39 Get Document Status This feature allows you to find out the status of a document. You will need to know the document ID to use this feature. Get Document ID from Source ID This feature allows you to list a document from a particular source in order to obtain the Document ID. Enter the document source id and the unique document reference to obtain the documents id. Practice Code from GP Code This feature allows you to obtain the Practice bode by entering the GP code. This is for where you know the GP details but not the practice details. Practice List This feature will list all the practices (or a specified practice) configured on the EDT Hub you are connected to. Use of this feature is described in the section titled Create your own message on page 35 of this document. Get Source Types This feature provides you with a list of Document sources and other details including their status and whether the EDT Hub is set to convert documents upon receipt. Get Practice Status This feature allows you to list the status information for all practices (or a specified practice) on the EDT Hub you are connected to. To specify an individual practice you will need to enter the Practice Code (NACS Code). GetDocStatusEXT This feature retrieves the Document Status Extended Information. This is a method for finding out if a document has been rejected and the reason for rejection. You will need the Document ID to run this feature. Get End Point List This feature allows you to list all the End Points (or just one End Point) configured on the EDT Hub you are connected to. If you want to look at a specific End Point you can add either the End Point Code (NACS Code) or the Logical address.

40 40 Get End Point Status This feature lists the status of End Points (or an individual End Point) configured on the EDT Hub you are connected to. To list an individual End Point you will need to provide an End Point Code or Logical Address. You are also able to request an End Point status list based on a date (document posted date). The End Point Status list provides you with information relating to the numbers of documents in the system broken down by status. Soak Test You can use this feature to send a test document to the web service at specific intervals. Set the interval and then click start and leave the test harness running. Alternatively, you can send the test document immediately by using 'Post Now'. Send/Download This feature allows you to send a collection of test documents to the web service and have them automatically download. You can select the Source and End Point from drop Down lists on the tab (you will need to click Get endpoints/sources to populate the drop down lists. Recommended approach to adding a document 1) First check that GP practice is configured and active on the EDT Hub using: EDT_GetPracticeStatus 2) Next, check that the document source type is still active on the EDT Hub using: EDT_GetSourceTypes 3) Post document to the EDT Hub using: EDT_AddDocumentXML Note: if you are ready to make the document available to practices immediately, set the status to Waiting (4002). If not, set it to OnHold (4001) and then update it later using EDT_SetDocStatus. 4) Store the returned document ID It is not recommended that you call EDT_AddDocumentXML first and then deal with failures (inactive/invalid practice or inactive/invalid source type) by exception. Doing this will result in the EDT_AddDocumentXML method reporting these as failures to the error log. The system administrator and all recipients of error reports will be notified of these errors (which will be unnecessarily high during rollout) which therefore make genuine error monitoring much more difficult.

41 41 Supplying an updated version of a document that has already been added to EDT Hub Should you need to replace a document that has already been added to EDT but has not yet been collected by a practice? 1) Check on the document s status using: EDT_GetDocStatus 2) If the document has not yet been collected by the receiving practice (ie its status is still set to Waiting), you can prevent it being collected by changing its status to DeletedBySender using: EDT_SetDocStatus 3) And then re-supplying the document using the same document ID (known as the original document id in the message specification) using: EDT_AddDocumentXML If a document has already been collected, you must supply a new document ID. If the document has the same event date and description the practice will be informed that a similar document exists and be given the opportunity to file the new one as a replacement. Handling Errors returned by the API Each method returns an rserr XML error string when a call to it fails and the error is trapped. If the error cannot be trapped, an unhandled exception will be raised containing full details of the error. This is reported to the event log on the web service machine. During the implementation phase, please report these errors to PCTI for investigation. Below is a list of possible errors for each method and where appropriate, the reasons behind them. EDT_AddDocumentXML Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?>

42 42 <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_AddDocumentXMLResponse xmlns="edtwebns"> <EDT_AddDocumentXMLResult>boolean</EDT_AddDocumentXMLResult> <rsnewdocid>string</rsnewdocid> <rserr>string</rserr> </EDT_AddDocumentXMLResponse> </soap:body> </soap:envelope> The EDT_AddDocumentXML method will normally return a Document ID which is > 0 for each new document added. If a blank or Zero Document ID is returned, your application must handle the error which is described in the rserr return value/soap element. Returned Error Descriptions Failed to authenticate Access Key An invalid or blank access key was supplied An Originator ID has not been defined The EDT Hub has not been configured with a unique originator ID A default organisation has not be defined You are attempting to add a document without specifying an organisation name (which is acceptable). However the EDT Hub has not been configured with a default name and is therefore unable to complete the organisation name when passing the document to the receiving practice. Element Name: <Party AgentId="2"><OrgName> Invalid Document Source ID supplied The document source ID supplied does not exist on the EDT Hub. To get a list of valid document source ID s, use EDT_GetSourceTypes Element Name: <ClinicalReport><ReportSourceType> The supplied Document Source Type is marked as inactive The document source ID is currently marked as inactive. The EDT Hub administrator will have marked the source type as inactive. Element Name: <ClinicalReport><ReportSourceType> Invalid or inactive Practice ID The practice nacs supplied is either not present or inactive on the EDT Hub. To get a list of valid practices, use EDT_GetPracticeList and leave the Practice code parameter blank. Element Name: <Party AgentId="1"><OrgCode IdType="Practice">

43 43 Document XML string is blank A blank xml message string was passed in. Element Name: <ClinicalReport><TextItem><TextBlock> A document with matching source reference number and source type already exists A document has already been added to EDT Hub that contains this ID for this document source type. If this is a replacement document (and the existing document not already been collected by the practice), set the existing documents status to DeletedBySender and post it again. Element Name: <ClinicalReport><ReportID> Missing Source Document ID or Reference Every document added to EDT Hub must have its own unique reference for tracking purposes. Element Name: <ClinicalReport><ReportID> No Addressee Name provided and unable to find it within GP List using Addressee Code If the document source has been configured as requiring a GP code (this is an option) and the addressee name is left blank (the intended GP recipient at the practice), then EDT Hub attempts to retrieve the name using the GP code. In order to do this, the GP code must exist against the list of GP s at the recipient practice. Element Name: <Party AgentId="1"><OrgCode IdType="GP"> If you do not wish to validate GPs (and most trust implementations do not), change the setting against the document source type using the EDT Web Admin web site. Inactive Addressee Code (GP) specified If the document source has been configured as requiring a GP code (this is an option), then EDT Hub checks that the GP code has been added against the receiving practice. Element Name: <Party AgentId="1"><OrgCode IdType="GP"> If you do not wish to validate GPs (most trust implementations do not), change the setting against the document source type using the EDT Web Admin web site. Addressee Code (GP) does not belong to an active Practice If the document source has been configured as requiring a GP code (this is an option), then EDT Hub checks that the GP code has been added against the receiving practice and the practice is active. Element Name: <Party AgentId="1"><OrgCode IdType="GP"> If you do not wish to validate GPs (most trust implementations do not), change the setting against the document source type using the EDT Web Admin web site. Maximum file size exceeded - Upper limit is 16mb In order to prevent excessively large files to be sent to EDT Hub, the maximum size of the document is set. In real terms, individual documents should be no more than 50K per page for an encoded binary document and 10K for a text based document. File size is 0k You have attempted to post a zero length document

44 44 Missing or Invalid Metadata Errors The following errors occur when missing or invalid metadata is supplied. In most cases missing data will be trapped by dtd validation however they are present in EDT Hub as an extra precaution. Missing mandatory field value: Practice Identifier Element Name: <Party AgentId="1"><OrgCode IdType="Practice"> Missing mandatory field value: Patient Identifier (NHS) Applies to practices outside of Scotland (see message specification for further details) Element Name: <PatientMatchingInfo><PatientId><Id><IdValue> Missing mandatory field value: Patient Identifier (CHINO) Applies to practices within Scotland Only Element Name: <PatientMatchingInfo><PatientId><Id><IdValue> Missing mandatory field value: Patient Surname Element Name:<PatientMatchingInfo><StructPersonName><FamilyName> Missing mandatory field value: Patient Forename Element Name:<PatientMatchingInfo><StructPersonName><GivenName> Missing mandatory field value: Document Description Element Name: <ClinicalReport><ReportType> Missing mandatory field value: Document Source Type Element Name: <ClinicalReport><ReportCode> Invalid document status supplied The document status value can be one of the defined list. However, not all operations allow all status values to be used (eg. Cant set a document to DeletedBySender if it has already been collected by the practice) Field Sizing Errors Each metadata item is checked against the allowable length specified in the EDT Document Specification. If any fails this check, the following error is reported: Value supplied for field 'Field Element Name' exceeds the maximum field length of Length Remote Routing Errors With the introduction of the EDT Hub sending a document to another EDT Hub is now possible, these are the following errors that may be reported from this process:

45 45 Unable to locate the remote URL for the EDT Web Service The remote URL has been previously used but can no longer be located, i.e. this is missing from the data, please contact the EDT Hub Administrator. Unable to remotely add this document, as this hub is operating in Uni-Directional Mode The EDT Hub is currently working in Uni-Directional mode and can only send documents within its own hub. To send documents to remote EDT Hubs with active agreements in place, the hub needs to operate in Bi-Directional mode. Document Source is not configured to allow external routing The original document source type specified in the XML does not allow remote routing to other hubs. This has been set by the EDT Hub Administrator. Failed to add document, please try again The document has not been added to the database, this is possibly due to a network or web service issue, please try to re-add the document. Invalid NACS Code Invalid NACS Code supplied, no matching NACS can be found locally or on any remote EDT Hub that have active sharing agreements in place. Invalid Logical Address Invalid Logical Address supplied, no matching Logical Address can be found locally or on any remote EDT Hub that have active sharing agreements in place. Unable to connect to remote server The remote EDT Hub web service us currently unavailable, this could be down to network or security issues. NACS code unknown locally and Document Source is not configured to allow remote routing The supplied NACS code could not be found locally so is assumed to be remote but the associated document source does not allow remote routing so is unable to check. Remote web service unavailable Before any attempt to post to a remote web service, a check is made to ensure it is available. This could be down to network or security issues. Unable to add this document as the receiving EDT Hub no longer has an active sharing agreement. The remote EDT Hub sharing agreement has been stopped or is yet to accept the sharing agreement.

46 46 Invalid document source ID supplied The document source passed in the meta data does not exist on the Hub. A default organisation has not been defined The default organisation needs to be set in the web admin console system settings page.

47 47 EDT_SetDocStatus Soap 1.1 Response HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_AddDocumentXMLResponse xmlns="edtwebns"> <EDT_AddDocumentXMLResult>boolean</EDT_AddDocumentXMLResult> <rsnewdocid>string</rsnewdocid> <rserr>string</rserr> </EDT_AddDocumentXMLResponse> </soap:body> </soap:envelope> Returned Error Descriptions You may only update the status of non delivered documents You have attempted to change the status of a document to a status that is not allowed (eg attempting to change from Delivered to OnHold) Unable to locate document ID The document id supplied is not present on the EDT Hub. Note that this is the internal EDT Document ID, not the original document id or reference Invalid document status specified You have attempted to change the status of a document to a status that is not defined in EDT Hub Invalid document ID You have supplied a document id <=0. Note that this is the internal EDT Document ID, not the original document id or reference Invalid credentials An invalid or blank access key was supplied