Filtering asynchronous messages

Filters are rules that you define to allow or block a subset of data payloads that you receive asynchronously from one of your connections. You can create filters for specific data models or FHIR® resources.  

Let’s explain this with an everyday analogy: you need only a sip of water to quench your thirst, but someone offers you a drink from a fire hydrant. The hydrant opens and you are overwhelmed by the jet of water coming in your direction. Basically, it's too much water and too high of pressure for what you need.  

Being connected to a massive healthcare organization with tens of thousands of incoming payloads per day might feel a bit like drinking from that fire hydrant. Our filters help to "turn down the pressure" to reduce that high-volume data stream to the specific dataset you need. For example, if you're only interested in a subset of patients from this particular healthcare organization—such as the cardiology unit—then you can create a filter that would accept all incoming payloads for patients seen in the cardiology unit and block the rest. Without a filter, you would receive all the data payloads from every unit, leaving you to decide which to keep after processing them yourself. 

If you do create a filter for this particular integration, however, this doesn't mean that you can apply it universally to every data model or FHIR® resource, nor every integration. Instead, you must define filters for each data model or FHIR® resource you want to filter for each integration.

For example, if you only want to receive orders with specific codes from Baylor Hospital (using the Order.New data model), then you would create a filter for those specific codes. But to filter orders from UT-Southwestern the same way, you must create a separate filter with those same codes.    

To recap, filters are specific to you, one data model or resource, and one integration. And filters can only be applied to asynchronous, one-way traffic. Because remember, you want to control the water coming out of that fire hydrant—not try to put that water back in.

FHIR resources

Currently, most of the FHIR® requests that we support are synchronous, which means you can't filter them. That said, filters work the same for either API, but they're mostly applicable if you're using the Redox Data Model API.

Filter rules

Now that you understand the why and how of a filter, let’s get into the details of what. A filter can have one of two rules: Send if or Block all

Send if… 

There are two subcategories to Send if rules: is in or is not in

  • is in means that the property value must be equal to a value in the valueset that you define.
  • is not in means that the property value must not be equal to a value in the valueset that you define. 

When you enter a valueset, you can do so in a comma-delimited format. Trailing or leading spaces are ignored, unless they are contained within quotation marks. If a value has a comma within it, you must use quotation marks to distinguish it from the other values. 

Using the order code example above, you could specify that the order code is in the valueset 100,200,300. But if one of the codes is 10,000, you would use quotation marks like this: 100,”10,000”,200,300.

Filters for null values

It's also possible to filter a specific field by whether it's populated or not. You can do this by treating null as a string value so the filter looks like this: is not in null. You can create this kind of filter so that you don't receive a specific field unless it's populated.

Pay attention...

Pay attention to case when you enter the valueset. Value matching is case-sensitive for both “is in” and “is not in.”

Filtering arrays

Some fields are arrays, meaning a request may have multiple values for that one field. These fields have brackets ([]) in the title. In this case, if any value within the array meets the filter rule, then the filter applies. 

Let’s say you create the following example filter: 

Send if Animal.Type[] is in (walrus). 

Then an incoming payload contains this: 

Animal.Type = [badger,rabbit,walrus,penguin].

Since (walrus) is one of the values in the array, you receive the data payload that has this field value. 

Now let’s say you have the same filter rule but you specify is not in instead. In this case, you would not receive this data payload because (walrus) appears in this payload. 

Block all

Block all restricts any requests using this data model or resource until the filter is removed. This is helpful when preparing for a new integration but it’s not ready for go-live just yet.

Successful filtered requests 

After you create a filter, it applies immediately to all your incoming traffic. A filtered request displays in your logs with a type of Receive and status of Filtered.

If we build custom filter logic for you, the Filtered status appears for those requests too.