Define and manage filters

A filter either blocks or conditionally sends events in async subscriptions (i.e., notifications you receive). You can apply, or link, filters to subscriptions that rely on either Redox data models or Redox FHIR®. Learn more about filters.

• All environment users can view filters. However, a user must be assigned to an engineer or support role to create or edit filters. Learn about 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.

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.

   
4. All existing filters in the environment display.

Follow these instructions to create a filter.

1. Log in to the dashboard.
2. From the navigation menu, click the Connections page.
3. All of your connections appear. Select the connection with the subscription you want to filter.
4. By default, the Subscriptions page opens. Find the subscription you want to filter, then click the Settings link.

   Why can’t I see a subscription’s settings?

   If you don’t see the Settings option:

   1. Remember you can only filter event notifications you RECEIVE. If you don’t see a Settings option for a subscription, you might be looking at a subscription for sync traffic or event notifications you SEND.
   2. You may not have the correct Redox data model or FHIR® notification included in the given subscription. Check with your Technical Account Manager.

5. The Settings page opens. Click the Define filter button.

   
6. Proceed to the relevant Step 2 option based on the type of filter you want to create.

It might be useful to block traffic for a particular subscription during the implementation phase.

1. From the Filter mode drop-down, select the Block all option.
2. Click the Save Filter button.

   
3. Your new filter is saved and 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.

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 Filter mode drop-down, select the Send if option.
2. A set of three fields appears. Click the Select Field Path drop-down to view a list of fields.
3. Select the field you want to filter.

   Array field paths

   If the field path is an array, the filter applies if any value within the array meets the conditions specified by the rule(s). Learn more about filtering arrays.

4. A modal opens for testing the field path and value. You can change your selection by clicking the Field Path drop-down again to view a list of fields.

   
5. Once you have the correct path, use the validation tools to test your choice. Or, if you don’t want to test, you can skip and proceed to the next step.
   1. Find a log payload for the subscription you want to filter. Learn more about searching for logs.

      
   2. Copy and paste the log payload into the Test Message section.

      
   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.
6. 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.
7. Click the Select Path button on the bottom right of the modal.
8. The modal closes. In the next 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.
9. 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.

   
10. To add a rule for another field, click the plus (+) icon. Populate the fields for the new rule.
11. Once you’ve finished defining all the necessary rules, click the Save Filter 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.

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 Template Mode link to enter advanced editing mode. In this mode, the Field Path becomes editable so you can directly edit the field path or enter one that doesn’t appear in the drop-down list. You can also click the JSON Path Expressions link to open help text definitions.

We don’t recommend advanced editing for FHIR® beginners.

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.

There are three ways you can edit a filter.

1. Follow the instructions to view existing filters.
2. From the list of existing filters, click on the filter with links you want to review or manage.
3. The Settings page opens. Under the Links section, an existing link will display or you can add a link.

   Only one filter link allowed

   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 Delete icon to the right of the subscription. A modal opens to confirm that you want to proceed. Click the Delete button to continue or the Cancel button to discard the changes.
   3. To add a new link, select a connection from the Connection drop-down.
      1. Next, click the Select subscription link.
      2. A modal opens with the available subscriptions for the selected connection. Use the Search field or the Connection drop-down to narrow down the available options. If needed, use the page options at the bottom of the modal to navigate through the pages. Then select the radio button of the subscription you want to link the config modifier to.
      3. Click the Select Subscription button.

After testing in staging, you can promote a filter to production. Learn about promoting assets.

1. Log in to the Redox dashboard.
2. From the Environments drop-down, select the Staging environment.

   
3. From the side nav menu, click the Operations drop-down.
4. The Operations options expand. Click the Filters option.

   
5. All existing filters in the environment display. Click on the filter you want to promote.
6. The Settings page opens. Click the Promote button.
7. 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.

   
8. The Settings page in the production environment opens. Add a filter link to a subscription to apply the filter in your production environment.

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 may have been introduced or to resolve an error by using a version that worked previously.

1. Follow the instructions for viewing existing filters.
2. From the list of existing filters, click on the filter you want to update.
3. The Settings 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. However, you can’t restore a version that’s already in use.

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.

   
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.