Filters

Filters are an additional channel for determining if an Event should be processed by ContextMod. They differ from Rules in several key ways:

Runs, Checks, Rules, and Actions can all have Filters
Filters test against the current state of the Activity (or its Author) being processed, rather than looking at history/context/etc…
Filter test results only determine if the Run, Check, Rule, or Action should run – rather than triggering it
- When the filter test passes the thing being tested continues to process as usual
- When the filter test fails the thing being tested fails.

A Filter has these properties:

include – An optional list of Filter Criteria. If any passes the filter passes.
exclude – An optional list of Filter Criteria. All must NOT pass for the filter to pass. Ignored if include is present.
excludeCondition – A condition that determines how the list of Filter Criteria are tested together

Criteria

A criteria is some property of a thing (Activity or Author) can be tested, and what the expected outcome is EX:

age: '> 2 months' => Author is older than 2 months

Filter Criteria is one of more criteria combined together to form a set of conditions that must all be true together for the Filter Criteria to be true EX

age: '> 2 months'
verified: true

The above Filter Criteria is true if:

the Author’s account is older than 2 months AND
they have a verified email

Filter Shapes

Generically, a “full” Filter looks like this:

include: #optional
  - name: AFilterCriteria
    criteria:
      #...
  #...one or more Filter Criteria

exclude: #optional
  #...one or more Filter Criteria

excludeCondition: OR or AND

But for convenience a Filter’s shape can be simplified with a few assumptions:

Simple Object

When a Filter is an object, the object is assumed to be a Filter Criteria which is used in include

itemIs:
  approved: false

Simple List

When a Filter is a list, the list is assumed to be a list of Filter Criteria and used in include

itemIs:
  - approved: false
    filtered: false
  - is_self: true

Filter Types

There are two types of Filter. Both types have the same “shape” in the configuration with the differences between them being:

what they are testing on
what criteria are available to test

Author Filter

Test the Author of an Activity. See Schema documentation for all possible Author Criteria

Mod Actions/Notes Filter

See Mod Actions/Notes documentation.

Toolbox UserNotes Filter

See UserNotes documentation

Item Filter

Test for properties of an Activity:

Subreddit Filter

Test for properties of the Subreddit an Activity belongs to. See Schema documentation

Named Filters

Named Filters work the same as Named Rules and Named Actions:

Filter Criteria may be given a name. A named Filter Criteria can re-used anywhere in the configuration regardless of location. This is done by:

specifying a name on a Filter Criteria once EX: name: MyFilterCriteria
using the Filter Criteria name in place of a Filter Criteria object

runs:
  - name: MyFirstRun
    checks:
      - name: MyFirstCheck
        kind: submission
        itemIs:
          - MyFilterCriteria
        rules:
          #...
        actions:
          #...
      - name: MySecondCheck
        kind: submission
        itemIs:
          include:
            - name: MyFilterCriteria
              criteria:
                approved: false
        rules:
          #...
        actions:
          #...

Examples

General Usage

Below are examples of where filters can be used

Usage in a Run

runs:
  # this run will only be processed if author is a contributor
  - name: MyRun
    authorIs:
      - isContributor: true
    checks:
     # - ...

Usage in a Check

runs:
  - name: MyRun
    checks:
      # check will only be processed if author is a contributor
      - name: MyCheck
        kind: submission
        authorIs:
          - isContributor: true
        rules:
          # ...
        actions:
          # ...

Usage in a Rule

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        rules:
          # rule will only run if author is a contributor
          - name: MyFirstRule
            kind: recentActivity
            authorIs:
              - isContributor: true
            thresholds:
              # ...
        actions:
          # ...

Usage in an Action

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        rules:
          - name: MyFirstRule
            # ...
        actions:
          # action will only run if author is a contributor
          - kind: approve
            authorIs:
              - isContributor: true

Using Author and Item Filter

runs:
  - name: MyRun
    checks:
      # Check will only process if author is a contributor AND submission is not approved
      - name: MyCheck
        kind: submission
        authorIs:
          - isContributor: true
        itemIs:
          - approved: false
        rules:
          # ...
        actions:
          # ...

Filter Shapes Usage

Below are examples of how filters can be structured using filter shapes

Using a Simple Object

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        # check is only processed if submission is not approved AND not marked as nsfw
        itemIs:
          approved: false
          over_18: false
        rules:
          # ...
        actions:
          # ...

Using a Simple List

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        # check is only processed if submission is EITHER:
        # -> not approved AND not marked as nsfw
        # -> not approved AND marked as nsfw AND has flair text 'Mildly NSFW;
        itemIs:
          # each '-' denotes a NEW set of criteria
          - approved: false
            over_18: false
            
          - link_flair_text: Mildly NSFW
            over_18: true
            approved: false
        rules:
          # ...
        actions:
          # ...

Using a Full Anonymous Filter

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        # check is only processed if submission is EITHER:
        # -> not approved AND not marked as nsfw
        # -> not approved AND marked as nsfw AND has flair text 'Mildly NSFW;
        itemIs:
          include:
            - approved: false
              over_18: false
              
            - link_flair_text: Mildly NSFW
              over_18: true
              approved: false
        rules:
          # ...
        actions:
          # ...

Using a Full Anonymous Filter with Exclude

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        # check is only processed if submission is NOT approved
        itemIs:
          exclude:
            - approved: true
        rules:
          # ...
        actions:
          # ...

Using a Full Named Filter

runs:
  - name: MyRun
    checks:
      - name: MyCheck
        kind: submission
        # check is only processed if submission is:
        # -> not approved AND not marked as nsfw
        itemIs:
          include:
            - name: sfwNotApproved
              criteria:
                - approved: false
                  over_18: false
        rules:
        # ...
        actions:
        # ...

Author Filter Examples

New User

# author's account is less than 30 days old AND has less than 30 comment karma
authorIs:
  include:
    - name: newUser
      criteria:
        age: < 30 days
        commentKarma: < 30

New User with pattern in Name

# author's account is less than 30 days old AND has less than 30 comment karma AND has 'nsfw' in their account name
authorIs:
  include:
    - name: newUser
      criteria:
        age: < 30 days
        commentKarma: < 30
        name: '/nsfw/i'

User has pattern in their profile description

authorIs:
  include:
    - description:
        - '/Add Me On Snapchat/i'
        - '/Add my snapchat/i'
        - '/Dm me for content/i'
        - '/Will Verify/i'

Exclude moderators AND users by name

Useful when CM should not run if the author is from a list of users or a moderator

authorIs:
  excludeCondition: AND
  exclude:
    # will not run if user is a mod or is automoderator
    - isMod: true

    # will not run if the user is in the list below
    - name:
        - User1
        - User2
        - User3

Item Filter Examples

Unmoderated comment by non-op

itemIs:
  - removed: false
    approved: false
    op: false

Submission is self post with no flair

itemIs:
  - is_self: true
    link_flair_text: false

Table of Contents