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're overwhelmed by the jet of water coming in your direction. Basically, it's too much water and 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.
Let's say you're only interested in a subset of patients from a healthcare organization, like the cardiology unit. You could create a filter that would accept all incoming payloads for patients seen only in the cardiology unit and block the rest. But without the filter, you'd receive all the data payloads from every unit, leaving you to decide which to keep after processing them yourself.
Before you get too excited, though, one filter can't apply universally to every data model, FHIR® resource, or 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), you must 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 one data model, resource, and 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.
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.
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.
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 wouldn't receive this data payload because (walrus) appears in this payload.
Block all restricts any requests with this data model or resource until the filter is removed. Blocking is helpful when preparing for a new integration that's not ready for go-live just yet.
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.