36C10G20R0014-012.docx

VA OI&T Data Access Services (DAS) Core Phase II Data Routing Service

Version 1.6.5

Interface Control Document

November 2017

VLER BTS

Revision History

(CPS) to Data Routing Service (DRS) with support for Synchronous interactions Randhir Manhas

· DAS Data Exposure for asynchronous data retrieval.

· DAS Data Storage to specific patient identification location in DocumentReference.

· Appendix D updated with sample including a contained Patient reference.

Moroni Pickering

· Removed sample configuration file from the end of section 2.1

· Appendix E updated with additional OperationOutcome Samples

· Added additional DocumentReference sample to Appendix D

· Removed Data Exposure Design Flow broken PDF embedded link Moroni Pickering

Updated the Sequence diagrams for section 2.2.1.4.

Randhir Manhas

Table of Contents

Introduction This document is the Interface Control Document (ICD) for the interface between Partners and the Data Routing Service (DRS). The DAS Client Gateway (CGW) acts as a proxy between Partner application and DRS.

In this ICD, “Partners” is the role name assigned to VA systems, Community Care Network Contractors (CCNC) or external vendor systems which send requests to DAS and expect back a Synchronous or Asynchronous response from the receiver system indicating the success or failure of the request.

Purpose The ICD serves as a specification of the interface between Partner applications, and the Data Access Services’ (DAS) generic DRS. It will be used by:

Developers of the DRS, Developers of Partner applications (Optional).

Scope This ICD describes the operations, data transfers, and communication methods of the service interface supported by DRS.

Upon formal approval by each Partner application, this ICD shall be incorporated into the requirements baseline for the DAS and all interfacing applications.

System Identification Data Routing Service The Data Routing Service (DRS) serves as a processes execution service between Partner systems. Since DRS is a generic service, it supports various partner/recipient systems as a common design pattern. Refer to Appendix B for Supported integrations by DRS. Table 11 provides identifier specifics for the Data Routing Service.

Table 11 – Data Routing Service Identifiers

Operational Agreement This ICD is maintained by the DAS PMO. Requested changes to the interfaces described in this document, are to be submitted to that group for consideration.

All Partners interacting with the DRS are required to either use or support this interface.

Standards and References This ICD makes use of the following standards and references:

1. [HTTP] - RFC 2616 Hypertext Transfer Protocol – HTTP/1.1, June, 1999 http://tools.ietf.org/html/rfc2616

2. FHIR Resource “DocumentReference” to post http data – http://hl7.org/fhir/DSTU2/documentreference.html

3. FHIR Resource “OperationOutcome” to post http data – http://hl7.org/fhir/DSTU2/operationoutcome.html

4. FHIR Resource “Binary” to exchange binary data – http://hl7.org/fhir/DSTU2/binary.html

5. [XML] - Extensible Markup Language (XML) 1.0 (Fifth Edition), November, 2008 http://www.w3.org/TR/REC-xml/

6. [DCGADD] - ADD010 - DAS Client Gateway http://vaww.oed.portal.va.gov/products/das/Implementation/Application%20Design%20Documents%20(ADDs)/ADD010%20-%20DAS%20Client%20Gateway.docx

7. [CPSADD] - ADD025 – Data Routing Service http://vaww.oed.portal.va.gov/products/das/Implementation/Application%20Design%20Documents%20(ADDs)/ADD025%20-%20Data%20Routing%20Service.docx

Interface Definition This ICD specifies the interface between Partner systems and the DRS. In a given HTTP request one Partner is the sender of the request and one or more partners are the receivers of the request.

The interface is designed to process every request DAS receives from a sender and returns a success or failure response from the receivers synchronously or asynchronously.

System Overview The generic DRS establishes data exchange between Partner Systems Synchronously or asynchronously as shown in the context diagrams below. Partners initiate all requests to DAS CGW that routes these requests to the DRS which carries out each transaction to complete the request. All requests must be FHIR based message.

DRS runs and processes the FHIR (Fast Healthcare Interoperability Resources) message payload based on the RESTful URL and request method (POST) identified in the request. The Content-Type of the request to DAS must be of type “application/json+fhir”.

For Synchronous exchanges between Partner systems, a response from the receiver system is returned to DRS to identify the success or failure of the request that was processed and is then communicated by DRS to the sender system via CGW in a synchronous fashion (Refer to Figure 2-1). The sequence of this data flow is:

The Sender sends a Restful HTTP POST to DRS. the CGW receives the message and passes it synchronously to DRS.

DRS synchronously sends the Restful HTTP POST to one or more Receivers via Outbound Gateway (OGW).

The Receiver synchronously returns an HTTP response to DRS via OGW.

DRS synchronously returns an HTTP response to the Sender via CGW.

For Asynchronous exchanges between Partner systems, an immediate response would be returned to the sender by DRS via Client Gateway upon receiving the request, whereas, the success or failure response from the receiver system is returned asynchronously by DAS to the sender system via OGW (Refer to Figure 2-2). The sequence of this data flow is:

The Sender sends a Restful HTTP POST to DRS. The CGW receives the message and passes it synchronously to DRS.

DRS sends a synchronous http response to the sender system.

DRS asynchronously sends the Restful HTTP POST to one or more Receivers via OGW.

The Receiver synchronously returns an HTTP response to DAS via OGW.

DRS asynchronously returns an HTTP response received from the receiver system to the Sender via OGW.

This ICD describes the interface needed to support the execution of a message-passing process from its start through to its completion, and ultimately to the return of a status which describes the success or failure of the request which was sent to the DRS.

Figure 21: Data Routing Service Context Diagram A – Sync HTTP

Figure 2 – Data Routing Service Context Diagram B – Async HTTP

Figure 3 – Data Routing Service Context Diagram C – Async JMS

As part of performing a business process, DRS may need to send requests to other systems as part of the processing (according to their ICDs). This ICD does not cover those interactions.

Requests to/Responses from the DRS are covered by this ICD as shown in the above diagrams.

The purpose of DRS is to be Generic Routing Service; the DRS can be configured based on partner system requirements. The list below are some examples of what can be configured.

To determine

· if DRS requires a Sync or ASync communication end to end.

· if DRS needs to send data to one or more destination systems.

· if DRS needs to publish same data to all destination systems.

· corresponding number of Redis channels that would need to be configured if the same data needs to be routed to multiple destinations. This configuration applies to Async cases only.

· how the target system is going to communicate with DRS (HTTP/JMS etc.).

· if there is a file attachment from external vendor, if yes, it needs to have configuration for the AV Scanning.

· if a JSON/XML schema validation (Future capability) is required based on the content-type received i.e. application/json or application/xml in the FHIR message payload.

Interface Overview This ICD describes the interface to DRS. Other interfaces may be made available at a later date.

The interface to DRS will have:

1. One input RESTful request indicating the messages to be processed.

2. One output response message indicating state of the messages that was processed.

Requests from Partners must be transmitted according to the RESTful Web Service protocol (For protocol details, please refer to the DAS Client Gateway ADD, section 1.5, #5). This protocol guarantees:

1. The delivery of a request from Partner system via CGW to the DRS.

2. And finally the delivery of a response back to a Partner system for every request it makes to DRS via CGW.

DRS Interface URL DRS is invoked by DAS Client Gateway component. DAS Client Gateway acts as a proxy between VA, CCNC or external vendor systems and the systems would need to use the restful http URL to exchange data with DAS via DAS Client Gateway. Example of this URL is given below:

https://{host}:{port}/drs/v1/{sender-system} Note: Refer to Appendix B for supported Integrations and the corresponding URLs based on directional flow of data exchange between the systems.

DRS URLs invoked by Client Gateway (internal to DAS):

http://{host}:{port}/drs/v1/{sender-system} where:

1. “http” indicates protocol to be used for the communication

2. {host} is the DNS name or the IP address of the web server hosting the service.

3. {port} is the TCP port accepting the HTTP requests. Note: the user-system will receive the {host} and {port} upon onboarding with DAS.

4. “drs” is the application name.

5. “v1” is the version of the interface.

6. {sender-system} is an abbreviated or short name of the sender system where the data originates from.

The details of the operations are explained in the following subsections.

Table 2-1: Data Routing Service Community Care URLs

DRS

Sender System

{operation-name} (Sender System)

Intended Restful operation to be executed for Community Care Network Contractor, External Vendor, or VA System destinations.

CCN Contractors, External Vendors, VA Systems

Community Care Network Contractor System This section describes the http post URL used by the CCNC/external vendor system for FHIR DocumentReference resource data exchange with a VA system. The section also has details on required header parameters, http request payload, http response and the capabilities invoked in DRS depending upon the data flow between the systems and specific requirements as outlined in DAS User stories.

DRS URL: POST

http://{host}:{port}/drs/v1/tpa

Required HTTP Headers:

Content-Type: application/json+fhir X-ConversationID:{Conversation Id} X-RoutingSenderID:{Sender} X-RoutingReceiverIDs:{Receiver} X-TransactionID: {Transaction Id}

{Conversation Id} - the conversation Identifier in the request http header of RESTFul message from the sending system that the receiving system would echo back in the asynchronous response message in the X-ConversationID element of the http header.

{Sender} – Sender is the Sender Identifier, {Receiver} - Receiver is the Receiver Identifier. If the message needs to be delivered to multiple recipients, then the Receiver would contain corresponding number of Receiver Identifiers separated by commas. Refer to Appendix F below for values of identifiers and sample.

{Transaction Id} – the unique identifier for an individual transaction across systems. A conversation consists of multiple transactions.

Description:

The URL accepts a FHIR message from a sender that has the content-type as application/json+fhir and DRS then pushes the message to a Redis channel. If the message contains an attachment (such as xml, doc, txt, jpeg etc.), the file attachment content needs to be binary data. The actual payload content data format needs to be mutually agreed upon by the sender and the receiver.

If publishing to Redis is successful, an HTTP response message is returned to the sender that contains a status code equal to “201” Else, if any error is incurred, an HTTP error response is returned that contains a relevant status code as outlined in the Appendix A.

Parameters:

None Message Body:

The message body contains a FHIR formatted standard message that contains the data payload as the binary data that a sender system would send to DAS to deliver it to the target system. Contact the source and/or the target systems that produce and/or consume this data for actual samples. A FHIR http post sample has been provided below in Appendix C to establish a common understanding of FHIR Resource that can be used to transmit system’s actual payload data in a FHIR format.

Validations: DRS can be configured to support Schema Validation.

Note: DAS does not have requirements to perform schema validations for CC projects.

Virus Scanning: External Vendor systems that have attachments to be transmitted to a VA system, the DRS has a configuration file that the code can use to have hooks for AV Scanning. The DRS service will extract the attachment(s) from the FHIR data and invoke the DAS AV Scanning client to scan the attachments before the FHIR data containing attachments is transmitted to the target system.

Response:

See Appendix A for all http codes and corresponding messages returned from DAS for synchronous HTTP responses.

VA System This section describes the http post URL used by the VA system for FHIR DocumentReference resource data exchange with a CCNC or external vendor system. The section also has details on required header parameters, http request payload, http response and the capabilities invoked in DRS depending upon the data flow between the systems and specific requirements as outlined in DAS User stories.

DRS URL: POST

http://{host}:{port}/drs/v1/{vasystem}

Required HTTP Headers:

Content-Type: application/json+fhir X-ConversationID:{Conversation Id} X-RoutingSenderID:{Sender} X-RoutingReceiverIDs:{Receiver} X-TransactionID: {Transaction Id}

{Transaction Id} – See section 2.2.1.1 {Transaction Id}

{Conversation Id} - See section 2.2.1.1 {Conversation Id}

{Sender} – Sender is the Sending System Identifier.

{Receiver} - Receiver is the Receiver Identifier. If the message needs to be delivered to multiple recipients, then the Receiver would contain corresponding number of Receiver Identifiers separated by commas. Refer to Appendix F below for values of identifiers and sample.

Description:

The URL accepts a FHIR message that has the content-type as application/json+fhir and DRS then pushes the message to a Redis channel. If the message contains an attachment (such as xml, doc, txt, jpeg etc.), the file attachment content needs to be binary data. The actual payload content data format needs to be mutually agreed upon by the sender and the receiver.

If publishing to Redis is successful, an HTTP response message is returned that contains a status code equal to “201” Else, if any error is incurred, an HTTP error response is returned that contains a relevant status code as outlined in the Appendix A.

Parameters:

None Message Body:

The message body contains a FHIR formatted standard message that contains the data payload as the binary data that a sender system would send to DAS to deliver it to the target system. Contact the source and/or the target systems that produce and/or consume this data for actual samples. A FHIR http post sample has been provided below in Appendix C to establish a common understanding of FHIR Resource that can be used to transmit system’s actual payload data in a FHIR format.

Validations: DAS does not have requirements to perform schema validations for CC projects but if required, the DRS has a configuration file that the code can use to have hooks for Schema Validation.

Virus Scanning: External Vendor systems that have attachments to be transmitted to a VA system, the DRS has a configuration file that the code can use to have hooks for AV Scanning. The DRS service will extract the attachment(s) from the FHIR data and invoke the DAS AV Scanning client to scan the attachments before the FHIR data containing attachments is transmitted to the target system.

Response:

See Appendix A for all http codes and corresponding messages returned from DAS for synchronous HTTP responses.

Pharmacy This section describes the http post URL used by the external vendor system (i.e. third party pharmacy data) for data exchange with a VA system “Inbound eRx”. The section also has details on required header parameters, http request payload, http response and the capabilities invoked in DRS depending upon the data flow between the systems and specific requirements as outlined in DAS User stories.

DRS URL: POST

http://{host}:{port}/drs/v1/pharmacy

Required HTTP Headers:

Content-Type: application/xml

Description:

The URL accepts a XML message and pushes the message to a Redis channel. If successful a HTTP 200 response status which contains a NCPDP compliant XML response message is returned that contains a status code equal to “000” Else, if any error is incurred an HTTP error response is returned with NCPDP compliant XML response message that contains a status code equal to “600” within the HTTP Reason Phrase.

Parameters:

None Message Body:

Should contain the XML request structure with the following:

Validations:

Response:

The response body is a NCPDP compliant XML formatted string that contains a header and body structure.

HTTP 200 OK

Successful

<?xml version="1.0"?> <Message version="010" release="006" xmlns="http://www.changehealthcare.com"> <Header> <To Qualifier="D">6208890924002</To> [n1] <From Qualifier="P">3323778</From> [n2] <MessageID>ae58e3d87e414985949361728cfc9385</MessageID> [n3] <RelatesToMessageID>4016216120.20160226204656</RelatesToMessageID> [n4] <SentTime>2016-02-26T20:46:57.7Z</SentTime> </Header> <Body> <Status> <Code>000</Code> [n5] </Status> </Body> </Message>

<?xml version="1.0"?> <Message version="010" release="006" xmlns="http://www.changehealthcare.com"> <Header> <To Qualifier="D">6208890924002</To> [n1] <From Qualifier="P">3323778</From> [n2] <MessageID>ae58e3d87e414985949361728cfc9385</MessageID> [n3] <RelatesToMessageID>4016216120.20160226204656</RelatesToMessageID> [n4] <SentTime>2016-02-26T20:46:57.7Z</SentTime> </Header> <Body> <Error> <Code>600</Code> [n5] </Error> </Body> </Message>

HTTP 415 Unsupported Media Type

Content-type found in request body is not valid XML message, or request body is empty.

<Header> <To Qualifier="D">6208890924002</To> [n1] <From Qualifier="P">3323778</From> [n2] <MessageID>ae58e3d87e414985949361728cfc9385</MessageID> [n3] <RelatesToMessageID>4016216120.20160226204656</RelatesToMessageID> [n4] <SentTime>2016-02-26T20:46:57.7Z</SentTime> </Header> <Body> <Error> <Code>600</Code> [n5] </Error> </Body> </Message>

HTTP 500 <Reason Phrase>

Authentication Failed (or) Any other exception/error Error Message captured in HTTP Reason Phrase

<Header> <To Qualifier="D">6208890924002</To> [n1] <From Qualifier="P">3323778</From> [n2] <MessageID>ae58e3d87e414985949361728cfc9385</MessageID> [n3] <RelatesToMessageID>4016216120.20160226204656</RelatesToMessageID> [n4] <SentTime>2016-02-26T20:46:57.7Z</SentTime> </Header> <Body> <Error> <Code>600</Code> [n5] </Error> </Body> </Message>

[n1] = element value gotten from Request message “From Qualifier”.

[n2] = element value gotten from Request message “To Qualifier”.

[n3] = generate unique UUID, alpha numeric characters supported and max 35 length limit [n4] = element value gotten from Request messageID.

[n5] = static value Success=”000” and Failure=”600”.

DAS Data Passthrough For data exchanges between VA and external vendor systems, if the sender system wants DAS to act as a pass-through of its data and does not want DAS to store this data, shall use FHIR resource “DocumentReference” for data exchange with all required metadata elements in a restful http post request to DRS.

Since the data /attachments from a sender system to be shared with a receiver system can be significantly large in size, the sender and receiver systems will need to support data streaming for which it will need to follow the following design pattern:

1. The sender system shall populate the content.attachment.url element of the DocumentReference resource pointing to the eventual location of the document stored in the sender system rather than embedding binary data within the DocumentReference resource’s content.attachment.data element.

The URL in the content.attachment.url element should have the following FHIR format:

{relative-path}/Binary/[documentURN]?transactionID={unique ID}&requestor={ES|PPMS|CUI etc.}&purposeOfUse=Treatment&dataSource={ES|PPMS|CUI etc.} Where, relative-path is the URL path used by the system’s service, documentURN is a unique document identifier, transactionID is a Unique Identifier for a request, requestor is the information about the system requesting data and should not be service account information, purposeOfUse is used to define the purpose of this request and may vary depending upon the type of data being requested/shared, and dataSource is used to define the source of the requested data

2. DRS will deliver the DocumentReference resource to the receiver system.

3. The receiver system shall extract the URL from the content.attachment.url element of DocumentReference resource and invoke DRS using a relative URL path that will include the query from the url element to retrieve the binary data from the sender system. Example given below:

https://{host}:{port}/drs/v1/Binary/[query-from-the-url-element]

Where, query-from-the-url-element is the url path sent in the DocumentReference to retrieve Binary data from the sender system as shown in step 1above.

Example given below:

https://{host}:{port}/drs/v1/Binary/{relative-path}/Binary/[documentURN] ?transactionID={unique ID}&requestor={ES|PPMS|CUI etc.}&purposeOfUse=Treatment&dataSource={ES|PPMS|CUI etc.}

4. DRS will strip off the /drs/v1 context from the URL and use the remaining URL to invoke the sender system to retrieve the binary data in the response via data streaming. See step 1 for this URL.

Note:

· The Sender system always need to ensure they correctly populate the http headers X-RoutingSenderID and X-RoutingReceiverIDs for DRS to route the request/data correctly to the receiver system.

· The mime-type is required for the associated Binary data. The Sender system shall use the AcceptType header to populate a corresponding mime type for the Binary data stream. For example if the binary data is for a jpeg file, the Sender system shall use image/jpeg in the AcceptType header.

5. If DRS retrieves this data from external vendor system outside VA firewall, then DRS will scan this data for any virus infections before streaming the binary data to the receiver system. If response to Binary data delivery is a failure, then DAS will only log the failure for reporting purposes and the target system is assumed to retry the GET query after configured number of retries in DAS (default is 7 hrs.).

A sample template and a sample metadata for “DocumentReference” resource has been provided in Appendix C and D. Refer to the sequence diagrams below for data flow steps.

The outcome of a FHIR message delivery to a target system shall be communicated to the sender system via a FHIR resource “OperationOutcome”. A template and sample is given in Appendix E below. The issue.details.text element has been customized to include http status code, error text and date time stamp using the following format:

[httpstatuscode]:[error text] # [datetimestamp]

Note: The OperationOutcome FHIR resource may also be used by the receiver system as a resource to communicate Application Acknowledgements asynchronously for cases where upon receiving data from a sender system, the receiver system wants to communicate the processing results of the original message from the sender. A sample for this case is provided in Appendix E (OperationOutcome Example 3) that contains DocumentReference as a contained FHIR resource. The sequence of data flow steps for this communication will remain the same as shown in the pdf diagram above with an understanding that instead of passing DocumentReference FHIR resource, the OperationOutcome FHIR resource will be used with a contained DocumentReference FHIR resource.

DAS Data Storage VA or external vendor systems that require DAS to store data in its datastore shall use FHIR resource “DocumentReference” for data exchange with all required metadata elements in a restful http post request to DAS. Since the data /attachments from a sender system can be significantly large in size, the sender system will need to support data streaming for which it will need to follow the following design pattern:

1. The sender system shall populate the content.attachment.url element of the DocumentReference resource pointing to the eventual location of the document stored in the sender system rather than embedding binary data within the DocumentReference resource’s content.attachment.data element.

The URL in the content.attachment.url element should have the following FHIR format:

{relative-path}/Binary/[documentURN]/?transactionID={unique ID}&requestor={ES|PPMS|CUI etc.}&purposeOfUse=Treatment&dataSource={ES|PPMS|CUI etc.} Where, relative-path is the URL path used by the system’s service, documentURN is a unique document identifier, transactionID is a Unique Identifier for a request, requestor is the information about the system requesting data and should not be service account information, purposeOfUse is used to define the purpose of this request and may vary depending upon the type of data being requested/shared, and dataSource is used to define the source of the requested data

2. DRS will store the DocumentReference resource in a Mongo DB collection.

3. DocumentReference must contain patient identification information for patient documents stored in DAS. Expected location of the identifier is DocumentReference.subject.identifier. For example values reference section 2.2.1.6 DAS Data Exposure.

4. DRS shall extract the URL from the content.attachment.url element of DocumentReference resource and query the sender system using this URL to retrieve the binary data from the sender system in the response .

5. DRS will receive the binary data in the response via data streaming.

Note:

· The Sender system always need to ensure they correctly populate the http headers X-RoutingSenderID and X-RoutingReceiverIDs for DRS to route the request/data correctly.

· The mime-type is required for the associated Binary data. The Sender system shall use the AcceptType header to populate a corresponding mime type for the Binary data stream. For example if the binary data is for a jpeg file, the Sender system shall use image/jpeg in the AcceptType header.

6. If DRS retrieves this data from external vendor system outside VA firewall, then DRS will scan this data for any virus infections before storing this data in DAS gridfs datastore and update the stored Mongo DB collection for DocumentReference resource’s URL element with gridfs Id.

7. DRS will generate a notification to the sender system that will be sent via http post to the sender system. This notification will contain DocumentReference resource with content.attachment.url element pointing to the eventual location of the stored binary data in DAS Mongo gridfs datastore. Example given below:

/drs/v1/Binary/[gridfsId]?transactionID={unique ID}&requestor={system}& purposeOfUse=Treatment&dataSource=CUI

8. The sender system shall use this URL to query for the Binary data that DAS will supply in the response via data streaming.

A sample template and a sample metadata for “DocumentReference” resource has been provided in Appendix C and D. Refer to the sequence diagrams below for data flow steps.

DAS Data Exposure DAS will expose data stored in the eHealth Exchange, Direct Secure Messaging (DSM), and Clinician User Interface (CUI) collections to VA Viewer VIX in a two-step query process.

First-Pass VA Viewer VIX shall query DAS for a patient’s Healthdata using ICN as Patient Identifier via rest http GET call. An example of the query is shown below:

https://{host}:{port}/drs/v1/cc/DocumentReference?subject.identifier={2.16.840.1.113883.3.42.10001.100001.12 for DoD or 2.16.840.1.113883.4.349 for VA}|{EDIPI/ICN}&requestor={system}&transactionId={unique ID}&purposeOfUse=Treatment&dataSource=CC

REST GET http query with sample values:

http://{HOST}:{PORT}/drs/v1/cc/DocumentReference?subject.identifier=2.16.840.1.113883.3.42.10001.100001.12|1060970991&transactionId=3892472398742937&purposeOfUse=Treatment&requestor=CVIX&dataSource=CC

DAS would Correlate the ICN with MVI using getCorrespondingIDs() call and once the patient is validated, it shall search the CUI, DSM and eHx collections for documents using the correlated patient identifier and build a bundle of DocumentReference resources (including date, short description, MIME type, URL, size, etc.) for a patient. Each DocumentReference resource’s content element holds one attachment data type (for contentType, url, etc.). This bundle of DocumentReference resources would be returned as a first pass metadata response to the CVIX query. Sample of DocumentReference resource is provided in Appendix C and D.

Note: If DAS does not find data pertaining to a Patient’s ICN in any of the collections, then an empty bundle will be sent in the response to the requestor. Sample shown below:

"resourceType":"Bundle", "id":"ca6b625f-aaa3-45e8-9865-ed8d851c8bbb", "meta":{ "lastUpdated":"2017-06-05T19:06:02.275Z" "type":"searchset", "total":0, "link":[ "relation":"self", "url":" /drs/v1/cc/DocumentReference?subject.identifier=2.16.840.1.113883.3.42.10001.100001.12|1060970991&transactionId=3892472398742937&purposeOfUse=Treatment&requestor=CVIX&dataSource=CC "

Second-Pass VA Viewer VIX shall query DAS using the document URN (an eventual location of a document) provided in the content.attachment.url element of the DocumentReference resource in the first-pass query response. The binary data pertaining to the stored document in DAS will be exchanged with the requesting system via data streaming mechanism as a response to the query.

The second pass is asynchronous:

1) http GET /Binary request

2) DRS return acknowledgement for acceptance of the GET request

3) DRS pulls the Binary from the source system (if external it also scans for malicious code)

4) DRS http POST /stream to the original requesting system to an Endpoint provided by the system

An example of the second-pass REST GET http query is given below:

https://{host}:{port}/drs/v1/Binary/[documentURN]?transactionID={unique ID}&requestor={system}& purposeOfUse=Treatment&dataSource=CUI

Step 4, the POST will send the headers as specified in section 2.2.1.1

Interface Requirements The DRS interface for all VA or external vendor systems exchanging Community Care data with DAS require them to send “DocumentReference” FHIR resource in the http body via restful http post with required http headers as listed in sections 2.2.1.1 and 2.2.1.2.

Constraints All VA or external vendor systems must use http protocol response status codes to communicate the http call response statuses as shown in Appendix A below.

Interface Verification The interface will be verified by testing to this ICD.

Interface Control

TBD

Security Certificates Transfers between External Partner’s applications and the DRS must be protected by two-way SSL within the HTTPS application layer protocol. This protocol requires certificates which identify the host computers running:

1. The External Partner’s applications and

2. The Data Routing Service application.

Certificates must be public CA (Certificate Authority) signed certificates for this interface. External Partners are responsible for obtaining and keeping their certificates up to date based on the lifetime of each certificate.

The certificates for External Partner’s host computers and the DRS computers must be securely exchanged. See Table 21 for contact information. The DRS will need a copy of each External Partner’s certificate and any other certificates needed to establish a chain of trust to the signing CA. Similarly The each External Partner’s host computer will need a copy of the DRS computer certificate and other certificates needed to establish a chain of trust to the signing CA.

On Boarding Each external host computer wishing to interface to the DRS (test or production environments) may have to have each connection approved by the VA ESCCB (Enterprise Security Change Control Board). This approval process takes 10 days minimum after all needed information is made available to the ESCCB. Contact DAS Operations for information on how to start this procedure. See Table 21 for contact information.

Once approval has been obtained, a change must be made to network equipment (an F5 router) to allow incoming connections from the host, identified by its IP address and certificate. Appropriate certificates must be made available at or before this time.

Appendix A – DRS HTTP Response Code Transformation The authoritative list of DRS HTTP response codes

"code": "201", "message": "SUCCESS:Request Processed: {x-conversation id}."

· Pharmacy - User defined Success Response XML. See section 2.2.1.3

Note: Applies only to accepting the message from the sender.

"code": "206", "message": "Partial Success, attempted message delivery failure:{ x-conversation id}, {receiver id}"

Bad Request – The request cannot be fulfilled due to missing parameters.

"code": "400", "message": " Bad Request:The request cannot be fulfilled due to missing/invalid parameters – {x-conversation id}, {receiver id(s)}."

OR

"code": "400", "message": " Bad Request:No Route detected – {x-conversation id}, {receiver id(s)}."

Requester is not authorized to submit requests to the given resource.

"code": "401", "message": " Unauthorized:Requester is not authorized to submit requests to the given resource – {x-conversation id}"

Request refused because the server does not support the content submitted by the client.

"code": "406", "message": " Not Acceptable: Request refused because the server does not support the content submitted by the client. Infection detected in {x-conversation id},{filename+index}."

Note: {filename+index} – filename+index is used in scenarios where DAS receives attachments from external systems that need to be scanned.

filename is the identifier from the message and index is derived from number of attachments included in the message.

Request refused because the server does not support the media type submitted by the client.

"code": "415", "message": " Unsupported Media Type:Request refused because the server does not support the media type submitted by the client – {x-conversation id}."

· Pharmacy – Currently, only application/xml is supported.

VA System - Yes

· VA System/TPA – Standard JSON HTTP Response message:

“The server encountered an unexpected condition which prevented it from fulfilling the request” "code": "500", "message": " Internal Server Error-The server encountered an unexpected condition which prevented it from fulfilling the request – {x-conversation id}."

· Pharmacy - User defined Failure Response XML. See section 2.2.1.3

Appendix B – Supported Integrations

VA System

https://{host}:{port}/drs/v1/ppms https://{host}:{port}/drs/v1/fbcs https://{host}:{port}/drs/v1/cui ES – Passthrough PPMS – Passthrough FBCS – Passthrough CUI – Storage/Retrieval *ES/CCNC use of custom formatted X-ConversationID for ES Seeding and OHI data exchanges:

Phase 1:

{Unique UUID+“Seeding”} (Originates from ES)

{Unique UUID+“OHI”} (Originates from CCNCs)

Phase 2:

{Unique UUID + “PRQ”} (Originates from CCNCs)

TPAs/Community Care Network Contractors

Appendix C – FHIR DocumentReference Template for CC The proposed FHIR HL7 resource for data communication is “DocumentReference” and the version of FHIR specifications to be used is DSTU2 . Below are just to be considered samples, please review FHIR HL7 documentation for details on elements and the structure. The elements need to be appropriately populated by each sending metadata and data payload in the “content” field.

"resourceType": "Bundle", "total": 2, "entry": [ { //1st Entry "resourceType": "DocumentReference", "masterIdentifier": { Identifier }, // Master Version Specific Identifier – VistA Imaging documentURN "identifier": [{ Identifier }], // Other identifiers for the document "subject": { Reference(Patient | Practitioner | Group | Device) }, // Who/what is the subject of the document ICN[&EDIPI] "type": { CodeableConcept }, // R! Kind of document (LOINC if available) "class": { CodeableConcept }, // Categorization of document // by specialty (-ology) "author": [{ Reference(Practitioner | Organization | Device | Patient | RelatedPerson) }], // Who and/or what authored the document "custodian": { Reference(Organization) }, // Organization which maintains the document – “VHA VistA Imaging” for now, "authenticator": { Reference(Practitioner | Organization) }, // Who/what authenticated the document "created": "<dateTime>", // Document creation date-time in JSON format (yyyy-MM-DDTHH:MI:SS+HH:MI) "indexed": "<instant>", // R! When this document reference created – date/time when the resource was “uploaded to FHIR” server "status": "<code>", // R! current | superseded | entered-in-error – hardcoded "docStatus": { CodeableConcept }, // preliminary | final | appended | amended | entered-in-error "relatesTo": [{ // Relationships to other documents – do we need this??? – was not used before at the VA!

"code": "<code>", // R! replaces | transforms | signs | appends "target": { Reference(DocumentReference) }], // R! Target of the relationship "description": "<string>", // Human-readable description – Title to display in listing (along with “created” & content type & size) "securityLabel": [{ CodeableConcept }], // Document security-tags – SecurityLabel tag values to be defined/agreed upon!!!

"content": [{ // R! Document referenced – always using one single document referenced in this array "attachment": { // R! in-line Attachment -- Where to access the document (only relevant Attachment tags listed here) "contentType": "<code>", // Mime type of the content, with charset etc.

“data”:”<base64Binary data>, // Binary Data inline Base64ed "url": "<uri>", // Uri where the data can be found "size": "<unsignedInt>", // Number of bytes of content (if url provided) – for listing display "hash": "<base64Binary>" // Hash of the data (sha-1, base64ed) – for HTTP GET verification ???

"format": [{ Coding }] // Format/content rules for the document

Following is the link for the “DocumentResource” resource that has details for all elements contained in the resource:

http://hl7.org/fhir/DSTU2/documentreference.html

Appendix D – FHIR DocumentReference Sample Metadata for CC Document Reference Sample1, returned within a Bundle, in response to a GET request:

"resourceType": "Bundle", "id": "0fbc5978-b8ec-45fc-9822-bd97ea4ba340", "meta": { "lastUpdated": "2017-02-14T10:21:33.437-05:00" "type": "searchset", "total": 1, "link": [ "relation": "self", "url": "http://172.20.124.53:8088/hapi-fhir-mock/baseDstu2/DocumentReference?created=%3E%3D2016-01-01&created=%3C%3D2017-02-20&subject.identifier=2.16.840.1.113883.3.42.10001.100001.12%7C1060970991&type=http%3A%2F%2Floinc.org%7C11488-4" "entry": [ "fullUrl": "http://172.20.124.53:8088/hapi-fhir-mock/baseDstu2/DocumentReference/2", "resource": { "resourceType": "DocumentReference", "id": "2", "meta": { "versionId": "1", "lastUpdated": "2017-02-14T09:47:14.002-05:00" "text": { "status": "generated", "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"> Random Document Associated with patient\t</div>" "identifier": [ "value": "123546548731" "contained": [ "resourceType" : "Patient", "id" : "patient1", "identifier" : [{ "system" : "urn:oid:2.16.840.1.113883.3.42.10001.100001.12",

"subject": { "reference": "#patient1" "type": { "coding": [ "system": "http://loinc.org", "code": "11488-4", "display": "Consult Note" "class": { "coding": [ "system": "http://ihe.net/xds/connectathon/classCodes", "code": "Consult Note", "display": "Consult Note" "author": [ "reference": "Practitioner/John Doe M.D."

"reference": "Organization/Portsmouth MTF" "custodian": { "reference": "Organization/VHA VistA Imaging" "created": "2017-02-01T10:00:00-00:00", "status": "current", "securityLabel": [ "coding": [ "system": "http://hl7.org/fhir/v3/Confidentiality", "code": "L", "display": "low" "content": [ "attachment": { "contentType": "image/gif", “data”:”base64 binary data”, "url": "/Binary/document URN", "size": 1597440, "hash": "31f81281b212b28993f92524c1170ac470ddb363", "title": "Patient something or other" "search": { "mode": "match"

Document Reference Sample2 (for a POST):

Note, the sample identifier is as EDIPI. CUI will be POSTing with ICN. Non-patient specific data will not include a contained Patient resource.

"resourceType": "DocumentReference", "id": "2", "meta": { "versionId": "1", "lastUpdated": "2017-02-14T09:47:14.002-05:00" "text": { "status": "generated", "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"> Random Document Associated with patient\t</div>" "identifier": [ "value": "123546548731" "contained": [ "resourceType" : "Patient", "id" : "patient1", "identifier" : [{ "system" : "urn:oid:2.16.840.1.113883.3.42.10001.100001.12", "value" : "1060970991" "subject": { "reference": "#patient1" "type": { "coding": [ "system": "http://loinc.org", "code": "11488-4", "display": "Consult Note" "class": { "coding": [ "system": "http://ihe.net/xds/connectathon/classCodes", "code": "Consult Note", "display": "Consult Note" "author": [ "reference": "Practitioner/John Doe M.D."

"reference": "Organization/Portsmouth MTF" "custodian": { "reference": "Organization/VHA VistA Imaging" "created": "2017-02-01T10:00:00-00:00", "status": "current", "securityLabel": [ "coding": [ "system": "http://hl7.org/fhir/v3/Confidentiality", "code": "L", "display": "low" "content": [ "attachment": { "contentType": "image/gif", “data”:”base64 binary data”, "url": "/Binary/document URN", "size": 1597440, "hash": "31f81281b212b28993f92524c1170ac470ddb363", "title": "Patient something or other"

Appendix B Notes:

· The additional meta data giving the clinicians name and the facility name. The clinicians name would be denoted by Practitioner and Facility denoted by Organization. Both would be contained in the author block. This could be considered non-standard but is still permissible. Also, acceptable would be adding a display element.

· "custodian"."reference" - Assume this will be static Text.

· The content.attachment.url must follow the format: /Binary/[documentURN]

Appendix E – DRS FHIR OperationOutcome Template Listed below is an “OperationOutcome” resource template that DRS will send to the source system or sender application as a FHIR JSON Acknowledgement message. The response type Acknowledgement will be based on a successful/failed delivery attempt to a target system or recipient application.

"resourceType" : "OperationOutcome", // from Resource: id, meta, implicitRules, and language // from DomainResource: text, contained, extension, and modifierExtension "issue" : [{ // R! A single issue associated with the action "severity" : "<code>", // R! fatal | error | warning | information "code" : "<code>", // R! Error or warning code "details" : { CodeableConcept }, // Additional details about the error "diagnostics" : "<string>", // Additional diagnostic information about the issue "location" : ["<string>"] // Path of element(s) related to issue OperationOutcome Example1:

An operation outcome that would be returned after a successful operation "resourceType": "OperationOutcome", "id": "allok", "text": { "status": "additional", "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n <p>All OK</p>\n </div>" "issue": [ "severity": "information", "code": "informational", "details": { "text": "201:All OK # datetimestamp”

OperationOutcome Example2:

An error that might be returned when an unexpected exception happens on a server "resourceType": "OperationOutcome", "id": "exception", "text": { "status": "additional", "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n <p>SQL Link Communication Error (dbx = 34234)</p>\n </div>" "issue": [ "severity": "error", "code": "exception", "details": { "text": "500:SQL Link Communication Error (dbx = 34234) # datetimestamp”

OperationOutcome Example3:

Final Processing Acknowledgement sent from TPAs with contained DocumentReference "resourceType": "OperationOutcome", "id": "OperationOutcome/31c54d42-174c-4f27-a7e7-9a45271b5613", "text": { "status": "generated", "div": "\n Error Processing CCN Records\n " "issue": [{ "severity": "error", "code": "processing", "details": { "text": "Error Processing CCN Record X" "contained": [{ "id": "DocumentReference/31c54d42-174c-4f27-a7e7-9a45271b5613",…