Overview

Integration Filters allow you to either allow or drop events based on a set of criteria you configure within the transformation. Common use cases utilizing filters include:

Sending events only when they meet a specific event name. E.g. send all events except page events.
Only send events that contain a userId, limiting event tracking to only logged-in users.
Excluding traffic from known bots

Filters can also be created and applied via the Transformation Library available within the MetaRouter CLI. Utilizing this tooling, you can apply filters at the pipeline level to reduce the number of playbook filters that you need to manage.

How To Use Integration Filters

Integration Filters can be accessed with the first drop-down available in each section of your integration playbook. When opened, the filter section can be populated with YAML code using the below filter actions and conditions. You can only save valid YAML; invalid YAML code will be rejected.

Filters can be specified inside the Global, Event Specific, or Default sections of the playbook.

💡
When filters are applied within a section of a playbook, you will see an orange dot next to that section indicating that a filter is active.

Filter Actions

The most important concept to understand relating to Filters are Filter Actions. They determine whether events are dropped if they meet the filter criteria, or if an event can only be sent if it meets the filter criteria.

There are two Filter Actions:

allow: If the filter condition is true, allow the event to be sent to the destination. If the condition is not true, then the event will be dropped.
deny: If the filter condition is true, drop the event to prevent it from reaching the destination. If the condition is not true, the event will be sent to the destination.

It is very important to understand Filter Actions. If these are set incorrectly, they may allow data that should be filtered out of the stream to reach a destination, or they may result in data not reaching a destination when it should.

ByEventNames

Filtering using the ByEventNames methodology will allow you to filter events based on the name of the event.

filters:
    # Drops events if their event name is equal to "ssn_sent" or "credit_report_sent". Otherwise, allows the event.
  - byEventNames:
      action: deny
      events:
        - ssn_sent
        - credit_report_sent
    # Allows events if their event name is equal to "page" or "screen". Otherwise, drops the event.
  - byEventNames:
      action: allow
      events:
        - page
        - screen

{
  "filters": [
    {
      // Drops events if their event name is equal to "ssn_sent" or "credit_report_sent". Otherwise, allows the event.
      "byEventNames": {
        "action": "deny",
        "events": [
          "ssn_sent",
          "credit_report_sent"
        ]
      }
    },
    {
      // Allows events if their event name is equal to "page" or "screen". Otherwise, drops the event.
      "byEventNames": {
        "action": "allow",
        "events": [
          "page",
          "screen"
        ]
      }
    }
  ]
}

ByConditions

Filtering using the byConditions methodology will allow you filter events based on the parameters that are located within events. These are the available byConditions filters:

Drop events when consent.C0004 is true

filters:
  - byConditions:
      action: deny
      when:
        booleanEqual:
          inputPath: context.consent.C0004
          value: true

{
  "filters": [
    {
      "byConditions": {
        "action": "deny",
        "when": {
          "booleanEqual": {
            "inputPath": "context.consent.C0004",
            "value": true
          }
        }
      }
    }
  ]
}

Drop events when consent.C0004 is true, "true", "True", "TRUE", etc

filters:
  - byConditions:
      action: deny
      when:
        matchesAny:
          conditions:
            - booleanEqual:
                inputPath: context.consent.optOut.C0004
                value: true
            - stringEqual:
                ignoreCase: true
                inputPath: context.consent.optOut.C0004
                value: "true"

{
  "filters": [
    {
      "byConditions": {
        "action": "deny",
        "when": {
          "matchesAny": {
            "conditions": [
              {
                "booleanEqual": {
                  "inputPath": "context.consent.optOut.C0004",
                  "value": true
                }
              },
              {
                "stringEqual": {
                  "ignoreCase": true,
                  "inputPath": "context.consent.optOut.C0004",
                  "value": "true"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

Allow events that have at least one product in the properties.products array (drop the rest)

filters:
  - byConditions:
      action: allow
      when:
        inputPathIsObject:
          inputPath: properties.products.0

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathIsObject": {
            "inputPath": "properties.products.0"
          }
        }
      }
    }
  ]
}

Is inputPath a specific boolean value?

filters:
  - byConditions:
      action: allow
      when:
        booleanEqual:
          inputPath: context.consents.C0004
          value: true

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "booleanEqual": {
            "inputPath": "context.consents.C0004",
            "value": true
          }
        }
      }
    }
  ]
}

Is inputPath present?

filters:
  - byConditions:
      action: allow
      when:
        inputPathExists:
          inputPath: properties.products.0

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathExists": {
            "inputPath": "properties.products.0"
          }
        }
      }
    }
  ]
}

Is inputPath an array?

filters:
  - byConditions:
      action: allow
      when:
        inputPathIsArray:
          inputPath: properties.products

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathIsArray": {
            "inputPath": "properties.products"
          }
        }
      }
    }
  ]
}

Is inputPath a boolean?

filters:
  - byConditions:
      action: allow
      when:
        inputPathIsBoolean:
          inputPath: context.active

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathIsBoolean": {
            "inputPath": "context.active"
          }
        }
      }
    }
  ]
}

Is inputPath a number?

filters:
  - byConditions:
      action: allow
      when:
        inputPathIsNumber:
          inputPath: context.app.build

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathIsNumber": {
            "inputPath": "context.app.build"
          }
        }
      }
    }
  ]
}

Is inputPath an object?

filters:
  - byConditions:
      action: allow
      when:
        inputPathIsObject:
          inputPath: properties.products.0

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathIsObject": {
            "inputPath": "properties.products.0"
          }
        }
      }
    }
  ]
}

Is inputPath a string?

filters:
  - byConditions:
      action: allow
      when:
        inputPathIsString:
          inputPath: properties.products.0.sku

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "inputPathIsString": {
            "inputPath": "properties.products.0.sku"
          }
        }
      }
    }
  ]
}

Is inputPath a specific string value?

filters:
  - byConditions:
      action: allow
      when:
        stringEqual:
          inputPath: context.ip
          value: 127.0.0.1

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "stringEqual": {
            "inputPath": "context.ip",
            "value": "127.0.0.1"
          }
        }
      }
    }
  ]
}

Is inputPath a specific number value?

filters:
  - byConditions:
      action: allow
      when:
        numberEqual:
          inputPath: properties.total
          value: 1000

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "numberEqual": {
            "inputPath": "properties.total",
            "value": 1000
          }
        }
      }
    }
  ]
}

Is inputPath not a specific number value?

filters:
  - byConditions:
      action: allow
      when:
        numberNotEqual:
          inputPath: properties.total
          value: 1000

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "numberNotEqual": {
            "inputPath": "properties.total",
            "value": 1000
          }
        }
      }
    }
  ]
}

Is inputPath greater than a specific number value?

filters:
  - byConditions:
      action: allow
      when:
        numberGreaterThan:
          inputPath: properties.total
          value: 1000

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "numberGreaterThan": {
            "inputPath": "properties.total",
            "value": 1000
          }
        }
      }
    }
  ]
}

Is inputPath greater than or equal to a specific number value?

filters:
  - byConditions:
      action: allow
      when:
        numberGreaterThanEqual:
          inputPath: properties.total
          value: 1000

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "numberGreaterThanEqual": {
            "inputPath": "properties.total",
            "value": 1000
          }
        }
      }
    }
  ]
}

Is inputPath less than a specific number value?

filters:
  - byConditions:
      action: allow
      when:
        numberLessThan:
          inputPath: properties.total
          value: 1000

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "numberLessThan": {
            "inputPath": "properties.total",
            "value": 1000
          }
        }
      }
    }
  ]
}

Is inputPath less than or equal to a specific number value?

filters:
  - byConditions:
      action: allow
      when:
        numberLessThanEqual:
          inputPath: properties.total
          value: 1000

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "numberLessThanEqual": {
            "inputPath": "properties.total",
            "value": 1000
          }
        }
      }
    }
  ]
}

Does inputPath contain a specific string value?

filters:
  - byConditions:
      action: allow
      when:
        stringContains:
          ignoreCase: true
          inputPath: context.userAgent
          value: mozilla

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "stringContains": {
            "ignoreCase": true,
            "inputPath": "context.userAgent",
            "value": "mozilla"
          }
        }
      }
    }
  ]
}

Is inputPath a specific string value? (case independent)

filters:
  - byConditions:
      action: allow
      when:
        stringEqual:
          ignoreCase: true
          inputPath: context.properties.category
          value: games

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "stringEqual": {
            "ignoreCase": true,
            "inputPath": "context.properties.category",
            "value": "games"
          }
        }
      }
    }
  ]
}

Is inputPath not a specific string value? (case independent)

filters:
  - byConditions:
      action: allow
      when:
        stringEqual:
          ignoreCase: true
          inputPath: context.properties.category
          value: games

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "stringEqual": {
            "ignoreCase": true,
            "inputPath": "context.properties.category",
            "value": "games"
          }
        }
      }
    }
  ]
}

Does inputPath start with a specific string value?

filters:
  - byConditions:
      action: allow
      when:
        stringHasPrefix:
          ignoreCase: true
          inputPath: context.userAgent
          prefix: mozilla

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "stringHasPrefix": {
            "ignoreCase": true,
            "inputPath": "context.userAgent",
            "prefix": "mozilla"
          }
        }
      }
    }
  ]
}

Does inputPath end with a specific string value?

filters:
  - byConditions:
      action: allow
      when:
        stringHasSuffix:
          inputPath: writeKey
          suffix: test

{
  "filters": [
    {
      "byConditions": {
        "action": "allow",
        "when": {
          "stringHasSuffix": {
            "inputPath": "writeKey",
            "suffix": "test"
          }
        }
      }
    }
  ]
}

Clearing a Filter

If you do not want to add a filter, type filter: [] into the YAML box. This will ensure that no filters are applied to the playbook section you have open.

Overview

How To Use Integration Filters

💡When filters are applied within a section of a playbook, you will see an orange dot next to that section indicating that a filter is active.

Filter Actions

ByEventNames

ByConditions

Clearing a Filter

💡
When filters are applied within a section of a playbook, you will see an orange dot next to that section indicating that a filter is active.