Respond to the Carequality Interoperability Framework

Talk to a Redoxer first

We typically offer to be your responder to the Carequality Interoperability Framework. But if you would prefer to be your own responder, talk to a Redoxer first to make sure that you're eligible per Carequality's requirements.

Typically, we offer digital record retrieval to enable your access to the Framework. If you choose (and are eligible) to be your own responder, read through this guide to understand the background and set up for your system.

Background

Event types

When using Redox as your responder, you would use the PatientPush or VisitPush event types of the ClinicalSummary data model to prepare Redox to respond to requests from Carequality participants.

As your own responder, you rely on these event types of ClinicalSummary instead:

  • DocumentQuery
  • DocumentGet
  • DocumentQueryResponse
  • DocumentGetResponse

Document types

The most common and valuable document type for Carequality participants is the Continuity of Care Document (CCD), which has a LOINC code of 34133-9. We recommend making CCDs available to respond to document requests.

You can respond with an alternative document type, but talk to a Redoxer about alternatives you're thinking about first.

Setting up your system

  1. Submit a connection request to Redox to create a connection directly with Carequality.
  2. Go through the steps outlined in getting started with digital record retrieval, but skip the steps for pushing clinical summary documents.
  3. Create and verify an endpoint in your system so that you can receive synchronous requests from the Framework.

    Learn more

    Learn about synchronous requests for background context to complete this step.

  4. Create and authenticate an API key in your system so that you can send synchronous responses to the Framework, or plan to use an existing API key.
  5. Make sure that you can support these fields for receiving and processing DocumentQuery: (a) the Patient.Identifiers array; (b) all of the Visit fields; and (c) the Document.Types array. The patient identifier and identifier type should persist to your system as you push patient demographics. The rest of the fields are optional for you to implement as you choose for your system.
  6. Make sure that you can support these fields for responding with DocumentQueryResponse: (a) the Documents[].ID string. The requester uses the network document ID for the DocumentGet query so be sure to persist and cache document IDs in your system. If you choose to dynamically generate documents, be sure to persist and cache the document ID for a reasonable amount of time (e.g., 24 hours) so that you don't have to rebuild the document if the requestor asks for the document multiple times within a short amount of time. The network document ID must be globally unique, so please use a UUID or your [documentOID].[documentID] (e.g., 2.16.840.1.113883.3.6147.458...^1234).
  7. Plan for how to respond with DocumentGetResponse (see step 9 or 10 depending on document type).
  8. If you plan to respond with non-CCD documents, you must be able to populate these fields for DocumentGetResponse: (a) Meta.DataModel and Meta.EventType; (b) Document.ID; (c) FileType; and (d) Data. The rest of the fields are optional for you to implement as you choose for your system.
  9. If you plan to respond with CCDs, you can choose to respond either in the traditional format (i.e., XML) or in an alternative format. For the traditional format, you must be able to populate the same fields noted in step 9. For the alternative format, you can use the DocumentGetResponse required Meta fields and include the body fields from either VisitPush or PatientPush event types instead.

Reference docs

Check out our reference docs for more details about the required and optional fields for these event types:

Generating documents

You must decide how you want to manage and provide documents when Carequality participants request them. You can generate documents in your database either:

  1. (Recommended) Dynamically, at the time of the query. For this option, you must generate the document in a performant manner. We also recommend caching the document for a reasonable amount of time for your system (e.g., 24 hours). That way, if the requestor asks for it again within a short amount of time, you don't have to rebuild it. The benefit of generating documents dynamically is that the requestor doesn't have to locate one document in a large list; instead, the specific document they want is generated when they want it.
  2. Immediately, upon completing a patient visit and retaining the document indefinitely. Immediately doesn't have to be real-time; for example, you could choose to generate documents as part of a nightly batch job.

Redox document IDs

Whenever you generate documents (whether dynamically or immediately), a local document ID is created within your system. The local ID is assigned by your system and it may or may not be unique.

We also create a network document ID for the same document. The network ID is a unique identifier assigned by Redox to identify the document within the Framework.

Validating your system

  1. Talk to a Redoxer to get the Postman collection and staging environment so that you can send test requests to validate your system. When you test, you're essentially acting as an external Carequality participant querying yourself. You're free to validate in production too, but it's not required since you already have the data.
  2. Send a ClinicalSummary.DocumentQuery with the network patient ID for a test patient to the Redox gateway: 2.16.840.1.113883.3.6147.458.2.
  3. We resolve it to your local patient ID and forward the request to your configured endpoint.
  4. After receiving a DocumentQuery, perform steps 5 through 8 with a Redoxer to validate that you respond successfully. For each of the responses, you include the local document ID, which Redox translates to the network document ID.
  5. First, confirm that you can respond with a list of all documents that you have available for the patient with no specific search parameters.
  6. Next, confirm that you can respond with a list of documents filtered down to a specific document type.
  7. Then, confirm that you can respond with a list of documents filtered down to a specific visit date range. Make sure that you can support both start/end dates, only start date, and only end date.
  8. Lastly, test whether you can respond for a patient that has no related documents. This helps you define how to handle the interim state between locating a patient and preparing a document.
  9. Once you successfully complete steps 5 through 8, you have successfully validated DocumentQueryResponse.
  10. Now, you must validate DocumentGet. Send a ClinicalSummary.DocumentGet with the network document ID to the Redox gateway: 2.16.840.1.113883.3.6147.458.2.
  11. Redox resolves it to the local document ID and forward the request to your configured endpoint.
  12. After receiving the DocumentGet, perform steps 13 through 14 with a Redoxer to validate that you respond successfully.
  13. Confirm that you can find a document and return it in the right format–and that you receive it back in response to your initiating request.
  14. Confirm that you can handle responding with the appropriate error code when you fail to locate a document.