Handling queries and responses

Queries are two-way, synchronous requests for data where one system initiates a query (REQUEST) and the other responds with relevant data (RESPOND). The source system that requests data waits for a response from the destination system.

Think of a query like a phone call. When you ask a question, you stay on the line and wait for a direct response. This is different from an asynchronous notification, which is more like sending a text message—you send it and then continue with your day, waiting for a response to arrive later. Learn about handling notifications.

When handling queries, it’s important to understand two different response scenarios:

1. Response from Redox (after you REQUEST): This contains a two-part response with the delivery status and your query results.
2. Response to Redox (when you RESPOND): This is the answer you give with results to your connection’s query. Your response tells Redox whether you successfully processed the query.

When you initiate a query, you receive a response with two parts:

• HTTP status code from Redox
• query results from the destination system

There are three types of synchronous responses:

1. success response
2. partial error response
3. error response

Best case scenario: Redox successfully processes and delivers your query to the intended destination, and the destination successfully accepts the request and returns results.

If so, you receive a 200 OK status from Redox. The response body contains the requested data from the destination system. The fields and values present are specific to the data model or FHIR® resource you sent.

Keep in mind that not having query results doesn’t mean your query failed. You could receive a success response with no query results. You might need to modify the request if there aren’t any matching results.

Occasionally, Redox successfully processes and delivers your request, but an error occurs within the destination system, so it fails to accept the query.

If this happens, you still receive a 200 OK status from Redox, but the body of the response contains an array populated with error data:

1
{
2
   "Meta": {
3
     …
4
     "Errors": [
5
       {
6
         "Text": "Destination returned an error response.",
7
         "Module": "Destination Response",
8
         "DestinationStatusCode": 401,
9
         "Details": "Not authorized to access this patient."
10
       }
11
     ]
12
   }
13
 }

1
{
2
		"resourceType": "OperationOutcome",
3
		"issue": [
4
			{
5
				"severity": "error",
6
				"code": "invalid",
7
				"details": {
8
					"text": "Unknown search parameter name \"foobar\" for model \"Patient\"",
9
					"coding": [
10
						{
11
							"code": "MSG_PARAM_UNKNOWN",
12
							"system": "http://terminology.hl7.org/CodeSystem/operation-outcome",
13
							"display": "Parameter \"foobar\" not understood"
14
						}
15
					]
16
				},
17
				"diagnostics": "Failed to execute FHIR search"
18
			}
19
		]
20
	}

Sometimes your query fails within Redox, which means we fail to process and deliver it to the intended destination.

If the error occurs within Redox, you may receive a 4XX or 5XX HTTP status. Review HTTP errors.

When you receive a synchronous query from your connection, we wait for you to send back a response with the results of their request. Then, we return it to your connection in the format indicated in their request.

When you successfully receive a query from your connection, you should send back a 200 OK status with a response type that matches the query request.

Here’s an example: Your connection’s EHR system triggers an alert when a provider wants to order a new medication for a patient, but the provider wants to review the patient’s data before deciding on a specific medication. The EHR system sends a ClinicalDecisionsSupport request for more data. Your system successfully processes the request and aggregates results with the relevant data. You respond to Redox with a 200 OK status and the ClinicalDecisionsSupport.Response data model.

Keep in mind that not having query results doesn’t mean the query failed. You could return a success response with no query results. Your connection might need to modify the request if there aren’t any matching results.

There are two scenarios for failed deliveries to your system:

1. query times out
2. system error

If we don’t hear back from you after a couple of minutes, the query times out. We let the source system (i.e., your connection who initiated the query) know that their query wasn’t received. The source system can retry sending if they want.

If an error occurs and your system isn’t able to successfully receive the query, you should respond with a 4XX or 5XX HTTP status code and a response body with any relevant details:

We send the failed status code and the response with the errors back to your connection.