Hub API Specification

Transcription

1 Hub API Specification Version: 2.13 Published: Docman is the trading name of PCTI Solutions Ltd. Pioneer Court, Pioneer Way Whitwood, Castleford WF10 5QU 2013 PCTI Solutions Ltd. Docman is the trading name of PCTI Solutions Limited, a company registered in England, company number and registered address Pioneer Court, Pioneer Way, Castleford, WF10 5QU. VAT Registration No: T: F: E: docman@docman.com W:

2 Contents Document Information... 4 History... 4 Copyright... 4 Exclusion of liability... 4 Ownership... 4 Introduction... 5 Required Reference Material... 5 Test System... 5 Test Appliances... 5 Developer Testing... 5 Developer Support... 6 Overview... 6 The EDT Hub API (Inbound Web Service)... 8 Introduction... 8 Legacy Systems that do not support XML... 8 Functionality... 8 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 Depreciated 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 To View an end point list...34 To Save an end point list...34 Test Harness Feature List Copyright by PCTI Solutions Limited Page 2 of 52

3 Add Document...35 Set Document Status...35 Get Document Status...36 Get Document ID from Source ID...36 Practice Code from GP Code...36 Practice List ( Depreciated, please use GetEndPointList )...36 Get Source Types...36 Get Practice Status ( Depraciated, please use GetEndPointStatus )...36 GetDocStatusEXT...36 Get End Point List...36 Get End Point Status...36 Soak Test...37 Send/Download...37 Recommended approach to adding a document Supplying an updated version of a document that has already been added to EDT Hub. 37 Handling Errors returned by the API EDT_AddDocumentXML Unable to locate the remote URL for the EDT Web Service...41 Unable to remotely add this document, as this hub is operating in Uni-Directional Mode...41 Document Source is not configured to allow external routing...42 Failed to add document, please try again...42 Invalid NACS Code...42 Invalid Logical Address...42 Unable to connect to remote server...42 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 Copyright by PCTI Solutions Limited Page 3 of 52

4 Document Information History Author Stage Description Version 1 Date Michael Barrett Initial Draft First draft in new branding N/A Michael Barrett Revision Revision of document following feedback N/A Michelle Reviewed Updated N/A Burdett Michael Barrett Revision Replaced old demo Hub URLS with new /10/2015 Copyright ones. The copyright in this document is owned by PCTI Solutions Limited, including (without limitation) in all alpha-numeric text and code, images, schematics and illustrations. No part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of PCTI Solutions Limited. Exclusion of liability The information in this document is provided for information only and is subject to change without notice. While we make strenuous efforts to ensure that the content of this document is accurate and up to date when published, PCTI Solutions Limited gives no warranty on its accuracy and assumes no responsibility or liability for any errors or inaccuracies whatsoever (to the extent such exclusion is permitted by applicable law). Ownership For more information on the content or status of this document, please contact the person identified below: Michael Barrett Technical Author michaelbarrett@docman.com Tel: Docman Pioneer Court Pioneer Way Whitwood, Castleford, West Yorkshire, WF10 5QU Tel: Copyright by PCTI Solutions Limited Page 4 of 52

5 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 EDT Document Capture Interface (please see the separate documentation relating specific 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. Test Appliances For full end-to-end testing a VMWare Image of Docman (the GP side) is available to customers within the NHS who have an appropriate contract with PCTI Solutions Ltd. Please speak to your PCTI contact should you like to request either of these images. Developer Testing Copyright by PCTI Solutions Limited Page 5 of 52

6 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 resolutions@docman.com 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: 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 document 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 Document Capture). 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 (ITK2) allowing compliant messaging from an accredited ITK2.x web service host to EDT. (EDT ITK2.x) 9. An application adapter for the 111 messaging system allowing 111 compliant messages to be added. (EDT 111) 10. A desktop application to convert documents posted into the Hub into the tiff file format preferred by the Docman application. (EDT TIFF Converter) Copyright by PCTI Solutions Limited Page 6 of 52

7 Copyright by PCTI Solutions Limited Page 7 of 52

8 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 ITK2.x compliant and has been accredited for CDA document messaging. See EDT Hub is compliant with the NHS 111 standard. 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: 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 Document Capture utility to post any document to the EDT Hub Web Service via a simple dialog. This can also be used to check on sent documents and view any practice rejections. 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 Copyright by PCTI Solutions Limited Page 8 of 52

9 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. 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_GetEndPointList (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. Copyright by PCTI Solutions Limited Page 9 of 52

10 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. Binary file categories extracted, un-encoded and saved using the Document Extension specified. Encoding must be Base 64. 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) Passed Back: 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 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_AddDocumentXMLResponse xmlns="edtwebns"> <EDT_AddDocumentXMLResult>boolean</EDT_AddDocumentXMLResult> Copyright by PCTI Solutions Limited Page 10 of 52

11 <rsnewdocid>string</rsnewdocid> <rserr>string</rserr> </EDT_AddDocumentXMLResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 11 of 52

12 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: 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) Passed Back: 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_SetDocStatusResponse xmlns="edtwebns"> <EDT_SetDocStatusResult>boolean</EDT_SetDocStatusResult> <rserr>string</rserr> </EDT_SetDocStatusResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 12 of 52

13 EDT_GetDocStatus Retrieves the current document status for a specified EDT document ID. Passed in: 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 Passed Back: 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 Returns: 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> Copyright by PCTI Solutions Limited Page 13 of 52

14 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: 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 Passed Back: 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 Returns: True/False Copyright by PCTI Solutions Limited Page 14 of 52

15 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 Returns an XML string listing all documents which match the specified criteria. The document status and date range values are mandatory, the other parameters are optional filters Passed in: Access Key (string) A key provided by PCTI in order to prevent unauthorised use of the API Document Status ID (integer) The document status id to filter on 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) Pass the document source ID you wish to filter on ( optional ) Copyright by PCTI Solutions Limited Page 15 of 52

16 Start Date (DateTime) The start date of the filter range End Date (DateTime) The end date of the filter range NACS Code (string) Pass an endpoint NACS Code if you wish to filter ( optional ) User Rejection Only (boolean) If the document status passed is rejection, then set this to filter user rejections only Passed Back: XML results (string) A string containing the XML results from the search 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 POST /edtwebservice/edtwebservice.asmx HTTP/1.1 Host: Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "EDTwebns/EDT_GetDocStatusList" <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <EDT_GetDocStatusList 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> </EDT_GetDocStatusList> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 16 of 52

17 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: 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 Passed Back: 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 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_GetDocIDfromSourceIDResponse xmlns="edtwebns"> <EDT_GetDocIDfromSourceIDResult>boolean</EDT_GetDocIDfromSourceIDResult> <rldocid>int</rldocid> <rserr>string</rserr> </EDT_GetDocIDfromSourceIDResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 17 of 52

18 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: 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 Passed Back: 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 Returns: True/False Copyright by PCTI Solutions Limited Page 18 of 52

19 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> EDT_GetEndPointList "rsxmlout" Example Contents Copyright by PCTI Solutions Limited Page 19 of 52

20 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: 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 Passed Back: 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 Copyright by PCTI Solutions Limited Page 20 of 52

21 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> EDT_GetEndPointStatus "rsxmlout" Example Contents Copyright by PCTI Solutions Limited Page 21 of 52

22 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: 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 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_GetPracticeCodeFromGPCodeResponse xmlns="edtwebns"> <EDT_GetPracticeCodeFromGPCodeResult>boolean</EDT_GetPracticeCodeFromGPCode Result> <rsnacs>string</rsnacs> <rserr>string</rserr> </EDT_GetPracticeCodeFromGPCodeResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 22 of 52

23 EDT_GetPracticeList Depreciated 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. Note: This method is now depreciated in favour of the EDT_GetEndPointList Passed in: 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. Passed Back: 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 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_GetPracticeListResponse xmlns="edtwebns"> <EDT_GetPracticeListResult>boolean</EDT_GetPracticeListResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetPracticeListResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 23 of 52

24 EDT_GetPracticeList rsxmlout Example Contents Copyright by PCTI Solutions Limited Page 24 of 52

25 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: 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 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_GetSourceTypesResponse xmlns="edtwebns"> <EDT_GetSourceTypesResult>boolean</EDT_GetSourceTypesResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetSourceTypesResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 25 of 52

26 EDT_GetSourceTypes rsxmlout Example Contents Copyright by PCTI Solutions Limited Page 26 of 52

27 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: 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 Passed Back: 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_GetPracticeStatusResponse xmlns="edtwebns"> <EDT_GetPracticeStatusResult>boolean</EDT_GetPracticeStatusResult> <rsxmlout>string</rsxmlout> <rserr>string</rserr> </EDT_GetPracticeStatusResponse> </soap:body> </soap:envelope> Copyright by PCTI Solutions Limited Page 27 of 52

28 EDT_GetPracticeStatus rsxmlout Example Contents Copyright by PCTI Solutions Limited Page 28 of 52

29 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. Copyright by PCTI Solutions Limited Page 29 of 52

30 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. Copyright by PCTI Solutions Limited Page 30 of 52

31 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. Copyright by PCTI Solutions Limited Page 31 of 52

32 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. Copyright by PCTI Solutions Limited Page 32 of 52

33 1. Click on the Get End Point List You can either: List all the practices / end points 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 end point List. The end point list is displayed: 3. You can either view or save this list by using the buttons on the bottom left of the Get End Point List tab. Copyright by PCTI Solutions Limited Page 33 of 52

34 To View an end point list If you wish to view the list click on the View XML button on the bottom left of the Get End Point List tab. The list will open in a window as shown below. To Save an end point list If you wish to save the list you can use the Save button at the bottom left of the Get End Point 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. Copyright by PCTI Solutions Limited Page 34 of 52

35 Click the Save button to save your End Point List to a location of your choice. You will see a confirmation message displayed on your screen when the save is complete. Your end point list has now been saved, click the OK button to close the message box. If you navigate to the folder containing your end point 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 section 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. Copyright by PCTI Solutions Limited Page 35 of 52

36 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 ( Depreciated, please use GetEndPointList ) 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 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 ( Depraciated, please use GetEndPointStatus ) 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. 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. Copyright by PCTI Solutions Limited Page 36 of 52

37 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_GetEndPointStatus 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. 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: Copyright by PCTI Solutions Limited Page 37 of 52

38 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"?> <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. Copyright by PCTI Solutions Limited Page 38 of 52

39 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"> 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> Copyright by PCTI Solutions Limited Page 39 of 52

40 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 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"> Copyright by PCTI Solutions Limited Page 40 of 52

41 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: 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. Copyright by PCTI Solutions Limited Page 41 of 52