# Define and manage filters
A **filter** is a rule you define to conditionally allow or automatically stop certain asynchronous notifications from delivering to your destination(s) (i.e., notifications you receive). You should use filters to:
- Reduce noise: Prevent irrelevant data from reaching your system.
- Manage workflows: Only process notifications that meet specific criteria (e.g., only accept `PatientAdmin` messages for patients in the cardiology department).
There are two types of filters:
- **Send if**: Conditionally allow certain notifications based on one or more defined rules.
- **Block all**: Don’t allow any notifications for this subscription.
You can apply, or **link**, filters to subscriptions that rely on either Redox data models or Redox FHIR.
Filters are one of many operations that can be applied during log processing. [Learn about operations](/basics/data-exchange-with-redox/operations-for-data-processing).
## Prerequisites
- All environment users can view filters. However, a user must be assigned to an **engineer** or a **support** role to create or edit filters. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles).
> **Recommendation about PHI in filters**
>
> If you choose to filter fields with PHI, users assigned to an **observer** role might unintentionally access confidential data. Keep in mind that access to filter contents is managed by a different permission from the one managing access to log payloads.
- _Before creating a filter_, identify the specific field path (JSON or FHIR) you want to filter on.
- _To create a filter_, select a subscription with **async traffic** (an event notification that goes one way).
- _To edit a promoted filter_, first edit the staging version of the filter, then re-promote to production.
## View filters
Follow these instructions to review all the filters in your environment at once.
1. Log in to the Redox dashboard.
2. From the side nav menu, click the **Operations** drop-down.
3. The Operations options expand. Click the **Filters** option.
*Filters in the side nav*
4. All existing filters in the environment display.
> **Editing options**
>
> You can’t edit filters on this page. However, you can click the **Edit** button to open its settings and edit within the Connections page.
>
> If you’re viewing a promoted asset, though, you first have to edit in staging, then re-promote to production.
## View filtered logs
On the Logs page of the dashboard, any filtered logs have the Filtered icon.
*Filtered status*
Selecting the log opens the processing stages, which have a Filtered label and icon if a filter was applied. You can select the processing stage to view the log details, then click the filter label to see the specific filter details. These details include the status of the log and the outcome of each filter rule.
Filter details
For Block all rules, the filter details show that the message was blocked due to the defined filter rule.
*"Block all" outcome*
For Send if rules, the log details show an outcome for each rule.
If you have multiple Send if rules, the rules are evaluated in the order they’re defined. If a filter rule isn’t met, any subsequent rules aren’t evaluated.
*"Send if" outcomes*
| **Outcome** | **Notes** |
| --- | --- |
| Satisfied | The criteria for this filter rule was met. The next filter rule was evaluated. |
| Unsatisfied | The criteria for the filter rule wasn’t met. Any subsequent filter rules weren’t evaluated. |
| Skipped | A previous filter rule was unsatisfied, so this rule wasn’t checked at all. |
## Create a filter
1. Follow the steps to view filters.
2. Click the **New** button.
3. The create form opens. Enter a **human-friendly name** for the filter. This name appears on the Filters page.
4. In the Type field, select either **Block all** or **Send if**. Follow the instructions for the relevant type.
*Create a filter*
Option A: Block all filter rule
**Block all** restricts any notifications for the given subscription. Only deleting the filter will allow notifications to resume. Blocking is helpful when preparing for a new integration that’s not quite ready for go-live.
1. From the Type drop-down, select the **Block all** option**.**
2. Click the **Create** button.
*Create a block all filter rule*
3. Your new filter is saved. To apply it to your traffic, follow the instructions for linking a filter.
Option B: Send if filter rule
These conditional filters are the most common, since they allow you to moderate the event notifications you receive from one of your connections.
1. From the Type drop-down, select the **Send if** option**.**
2. From the Data model drop-down, select the expected **data model** in the subscription you want to link the filter to.
3. Under the Rules section, click the **Select field path** drop-down to view a list of fields and select the **field** you want to filter on.
4. A modal opens to test the field path and value. You can change your selection by clicking the Field Path drop-down again to view a list of fields.
> **Array field paths**
>
> Some fields are arrays, meaning there might be multiple values at one field path. You can tell if a field path is an array if it has brackets (`[]`) in the title. In this case, if _any_ value within the array meets the filter rule, then the filter applies.
*Select a field path*
5. (Optional) Once you have the correct path, use the validation tools to test your choice. Keep in mind that Redox doesn’t validate the filter like this. But it does give you an idea of whether you selected the right field path by using an existing log payload.
1. Find a log payload for the subscription you want to filter. [Learn how to search for logs](/how-to-use-redox/search-for-logs).
*Copy a log payload*
2. Copy and paste the **log payload** into the Test message section.
*Paste a log payload to test the field values*
3. On the right side of the modal, under Field values, the value that displays is the one found at the field path you selected.
4. Click the **Select** button on the bottom right of the modal.
6. The modal closes. In the second drop-down, select **is in** or **is not in**.
1. **is in**: The field path value must equal something in the defined value set. In other words, if the specified value(s) exist, the notification should be sent.
2. **is not in**: The field path value must not equal something in the defined value set. In other words, if these value(s) exist, the notification shouldn’t be sent.
7. Enter the relevant **comma-separated values**. You can also use **`null`** as a string value in the value set if you want to filter by whether the field path is populated.
> **Comma-delimited value sets**
>
> Trailing or leading spaces are ignored, unless you add them within quotation marks. If a value has a comma within it, you must use quotation marks to distinguish it from the other values. For example, you could specify an order code is in the value set `100,200,300`. But if one of the codes is `10,000`, you have to use quotation marks (e.g., `100,”10,000”,200,300`).
> **Case-sensitive values**
>
> Pay attention to case when you enter the value set. Value matching is case-sensitive for both “is in” and “is not in.” For example, `New` won’t match `new`.
*Create and save a filter*
8. To add a rule for another field, click the **Add rule** button. Populate the fields for the new rule. Or click the **delete** icon to remove a rule.
*Add or delete filter rules*
9. Once you’ve finished defining all the necessary rules, click the **Save** button. Alternatively, you can click the **Cancel** button to discard the filter.
> **Filter details in logs**
>
> The filtered status and details will appear in related logs. [Learn about filter statuses and outcomes](https://docs.redoxengine.com/permalink/Zn8kiEw3GdyBFaSwQNSAN/#view-filtered-logs).
> **Filters for data model event types**
>
> Remember that filters are for async event types. As an example, if you create a filter for the Redox `Notes` data model, the filter applies to the `Notes.New`, `Notes.Replace`, and `Notes.Delete` event types. But it doesn’t apply to `Notes.Query`. [Learn the difference between async and sync event types](/api-reference/redox-data-model-api/event-types-for-data-models).
>
> However, if you want to receive only one event type, you can create a is in filter on the `$.Meta.EventType` field. For example, if you only want to receive `Notes.New` event types, set the **field path** to `$.Meta.EventType` and the **value** to `New`. This filter ensures you won’t receive `Notes.Replace` or `Notes.Delete` event types.
#### Differences for FHIR field paths
If you’re creating a filter for a subscription that relies on Redox FHIR, the instructions are the same with a couple of minor differences when selecting the **FHIR field path**.
In the Select field path modal, you can click the **Switch to Advanced Mode** option to directly edit the field path or enter one that doesn’t appear in the drop-down list. _We don_’_t recommend advanced editing for FHIR beginners._
*Switch to template mode for FHIR field paths*
In advanced mode, you can click the **JSONPath Expressions** link to open help text definitions. Switch back to template mode anytime.
*JSONPath expressions help option*
When validating the FHIR field path, you have the additional option to toggle between **Field values** and **Output paths** to test that you have both correct. The value tells you what value would be filtered, and the path tells you the location in the FHIR payload.
*Toggle between field values and output paths*
## Edit a filter
1. Follow the steps to view filters.
2. Find the filter you want to edit and click anywhere it in its **row**.
3. Under Filter details, click the **Edit** button at the top right.
For promoted filters, follow the instructions below these.
4. The edit form opens. Edit any details or defined rules, or add new ones.
5. When you’re finished, click the **Save** button.
Edit a promoted filter
1. In a production environment, select the **promoted filter** you want to edit.
2. Under the Filter details, click the **Go to staging** button.
*Go to staging to edit*
3. A confirmation modal appears to acknowledge that you’re switching environments. Click the **Proceed** button to continue.
4. The filter opens in the **staging** environment. Click the **Edit** button and make any changes.
5. Click the **Save** button.
6. Once changes are successfully made, re-promote the filter to keep the assets in sync across environments.
> **Previous filter rule settings**
>
> Any edits to a filter rule are immediately applied to live traffic. However, when looking at past filtered logs, you’ll still see the old filter rules that were in effect at the time of that log.
## Link a filter
A filter can only be linked to one **subscription**. You have to create one for each subscription you want to filter.
1. Follow the steps to view filters.
2. Find the filter you want to edit and click anywhere it in its **row**.
3. The Details page opens. Fill out the fields under the Links section.
1. From the Connection drop-down, select the **connection** you want to link the filter to.
2. Click the Subscription drop-down. A modal opens with a list of the selected connection’s subscription(s). Click the **radio button** of the subscription you want, then click the **Select** button.
4. Click the **Link** button.
*Link a filter*
5. The filter automatically applies to the subscription’s traffic. For block all filters, all traffic for the selected subscription is restricted until the filter is removed.
> **Filter details in logs**
>
> The filtered status and details will appear in related logs. [Learn about filter statuses and outcomes](https://docs.redoxengine.com/permalink/Zn8kiEw3GdyBFaSwQNSAN/#view-filtered-logs).
## View and manage filter links
A filter can only be linked to one **subscription**. You have to create one for each subscription you want to filter.
Also, a subscription can only have one filter link. This means there’s a 1:1 relationship between filters and subscriptions. [Learn about subscriptions](https://docs.redoxengine.com/permalink/5k6U4ofmE0bKPBk4fhRcj5/#what-are-subscriptions).
> **Example scope**
>
> Let’s say you have two subscriptions for receiving `Order.New` notifications from two different healthcare organizations.
>
> - The first subscription is with Baylor Hospital. You create a Send if filter with a rule that looks for certain order type(s).
> - The second subscription is with UT-Southwestern. You want only the same order types as from Baylor, but you can’t link the Baylor filter to UT-Southwestern. This subscription needs its own filter, even if you want the same rule applied.
>
> However, you could add a rule to the Baylor filter if you only want to get orders from a specific facility within the health system. Then your filter would have two rules to conditionally allow new orders (of a specific type) from a specific facility.
>
> Remember that both of your subscriptions now have linked filters. This means you can’t create or link a new Block all filter to either of them.
1. Follow the steps to view filters.
2. Find the filter with the link you want to manage and click anywhere it in its **row**.
3. The Details page opens. A filter can only be linked to one subscription. To add a new link, you have to delete the existing filter link.
1. To view an existing link in context, click the **link** to open related logs.
2. To delete an existing link, click the **three-dots** icon to the right of the subscription, then the **Delete** option. A modal opens to confirm that you want to proceed. Click the **Delete** button to continue or the **Cancel** button to discard the changes.
*Delete a filter link*
3. To add a new link, you must first delete an existing link. Then, follow the steps to link a filter.
Alternatively, you can see the filter link information on the Details page of the linked subscription. You can click the **Manage** button to navigate back to the Filters page to edit or remove the link.
*Filter links on the subscription Details page*
## Promote a filter
During implementation, you can build and test a filter in a staging environment. Once you’re confident it works, you can promote it to production. Promoting an asset saves time and avoids introducing errors by rebuilding it in a different environment. [Learn about promoting assets](/implementation-guide/promote-assets-in-your-redox-organization).
1. Follow the steps to view filters.
2. From the Environments drop-down, make sure you’ve selected the **Staging** environment.
*Select the staging environment*
3. Find the filter you want to promote and click anywhere in its **row.**
4. The Details page opens. Click the **Promote** button.
5. A modal appears to let you know you’re exiting the staging environment and proceeding to the production environment. Click the **Proceed** button. Otherwise, click the **Cancel** button to discard the promotion.
*Promote a filter to production*
6. The Details page in the production environment opens. Add a **filter link** to a subscription to apply the filter in your production environment.
## Restore a filter version
Every time you edit a filter, you create a new version of the asset. You can restore a version of a filter that’s not currently in use. This may be helpful when troubleshooting to see where an error might have been introduced or to resolve an error by using a version that worked previously.
1. Follow the steps to view filters.
2. Find the filter with a version you want to restore and click anywhere in its **row.**
3. The Details page opens. Click the **Restore** button.
4. A modal appears to restore a version. From the drop-down, select a **version** to restore.
> **Restore notes**
>
> Restoring means activating a version that’s not in use. That means you can go backwards or forwards a version.
>
> Keep in mind you can’t restore a version that’s already in use or an asset that’s been deleted.
5. The diff view shows what’s different between the current and selected version. Review the differences. When finished, click the **Restore** button.
> **Versions after editing**
>
> If you edit an asset after restoring a previously used version, a new version is created.
>
> For example, let’s say you were on version 3 and you restore version 2. Then you make and save edits to version 2. This creates version 4 of the asset. At that point, you can still restore to version 3 at any time.
*Restore a filter version*
6. For promoted assets, restoring a version only applies to the current environment. If you restore a version in staging, you may need to re-promote the asset if you want to apply it to production as well.
*Unpushed changes*
*Out of sync versions*
> **Platform API endpoints**
>
> This article describes how to manage filters in the **Redox dashboard**. To manage destinations via **API**, use these **Redox Platform API** endpoints instead:
>
> - [Get environment filters](https://docs.redoxengine.com/permalink/d662015b-022e-57b9-9ba2-bf610511b7b2-get-env-filters)
> - [Get filter by ID](https://docs.redoxengine.com/permalink/79066a05-a025-5ff8-89f3-0242f6a7ccab-get-filter-by-id)
> - [Create filter](https://docs.redoxengine.com/permalink/468a2307-c05c-5c8f-8435-dcaf40321455-create-filter)
> - [Update filter](https://docs.redoxengine.com/permalink/45ab5582-31d1-592b-a541-a8713883581c-update-filter)
> - [Restore filter](https://docs.redoxengine.com/permalink/b527dbc1-f1a6-5072-bc4f-39580de4479a-restore-filter)
> - [Delete filter by ID](https://docs.redoxengine.com/permalink/799df785-1de7-5b0e-9791-df4d70163d50-delete-filter-by-id)
> - [Create link](https://docs.redoxengine.com/permalink/e2c6549b-6be3-5768-95bf-98beb2a45ee2-create-filter-link)
> - [Get link](https://docs.redoxengine.com/permalink/bfe7eee4-3273-5516-b8d1-34d2d0f0d42f-get-filter-link)
> - [Delete link](https://docs.redoxengine.com/permalink/e7756300-60db-5a9d-a985-58343687a57c-delete-filter-link)
> - [Promote asset](https://docs.redoxengine.com/permalink/00e540fd-52b8-5bcd-8b56-e392e9db575e-promote-asset)