Module Script Filtering

MCP Filter — Scripting Reference

Overview

The search method on ModuleScripting accepts MCP-style filters — a human-readable filter format that uses display names and natural operator names instead of raw MongoDB queries.

Internally, filters are transformed through the McpFilterTransformer → QueryFilterProcessor pipeline into MongoDB queries.

# MCP filter (search) — uses display names + operators
Module('Customer').search({ "Status": "Active" })

# Raw MongoDB filter (findAll) — uses internal field paths
Module('Customer').findAll({ "$and": [{ "payload.f_abc123": "Active" }] })

Both approaches query the same data. Use search when you want readable, maintainable filters. Use findAll when you need raw MongoDB control.

---

API

search(filters, includes?, sort?, direction?, take?)

Returns a list of FETIASEntity matching the MCP filter.

Parameter	Type	Default	Description
filters	JObject	(required)	MCP-style filter object
includes	string[]	null	Fields to include (display names)
sort	string	null	Field display name to sort by
direction	QuerySortDirection	Ascending	Sort direction
take	int	0	Max results (0 = unlimited)

results = Module('Customer').search(
    { "Status": "Active", "Score": { "min": 80 } },
    sort="Score",
    direction=QuerySortDirection.Descending,
    take=10
)

---

Filter Format

Simple equality

Pass a plain value to match exactly:

{ "Priority": "High" }
{ "Score": 95 }
{ "state": "Open" }

Operator objects

Pass an object with operator keys for advanced matching:

{ "Title": { "contains": "report" } }
{ "Score": { "min": 80, "max": 100 } }
{ "DueDate": { "after": "2026-01-01" } }

Multiple fields (implicit AND)

Multiple fields in the same object are AND-ed together:

{
  "Priority": "High",
  "Status": "Active",
  "Score": { "min": 80 }
}

Explicit AND/OR grouping

Use and/or arrays for logical grouping. Nesting is unlimited.

{ "or": [{ "Status": "Active" }, { "Priority": "High" }] }

{
  "and": [
    { "state": "Open" },
    { "or": [
      { "Priority": "High" },
      { "Score": { "min": 90 } }
    ]}
  ]
}

---

Operator Reference

Text operators

Operator	Aliases	Description
is	equal, equals, eq	Exact match
not	isNot, ne, neq, notEqual, notEquals	Not equal
contains		Substring match (case-insensitive)
startsWith		Starts with value
endsWith		Ends with value
excludes	notContains, doesNotContain	Does not contain substring

{ "Title": { "contains": "report" } }
{ "Name": { "startsWith": "A" } }
{ "Status": { "not": "Cancelled" } }
{ "Notes": { "excludes": "draft" } }

Number operators

Operator	Aliases	Description
min	gte, minimum, atLeast, from, greaterThanEqual, greaterOrEqual	Greater than or equal (>=)
above	gt, moreThan, greaterThan	Greater than (>)
max	lte, maximum, atMost, to, lessThanEqual, lessOrEqual	Less than or equal (<=)
below	lt, under, lessThan	Less than (<)
between	range	Range — pass { "min": N, "max": N }

{ "Score": { "min": 80 } }
{ "Amount": { "below": 1000 } }
{ "Rating": { "between": { "min": 1, "max": 5 } } }

Combine min and max on the same field for a range:

{ "Amount": { "min": 1000, "max": 5000 } }

Date operators

Operator	Aliases	Description
after	since, from_date	On or after date (>=)
before	until, to_date	On or before date (<=)
within	around	Current time window (e.g. this week)
upcoming	in, next, coming	Next N time units from now
past	ago, previous, last	Previous N time units from now

Date range with ISO 8601 strings:

{ "DueDate": { "after": "2026-01-01", "before": "2026-12-31" } }

Relative date operators use { "duration": "day"|"week"|"month", "offset": N }:

{ "DueDate": { "upcoming": { "duration": "day", "offset": 7 } } }
{ "CreatedDate": { "past": { "duration": "month", "offset": 3 } } }
{ "UpdatedDate": { "within": { "duration": "week", "offset": 1 } } }

User operators

Pass "me" as a simple string value on any user field (standard or custom):

{ "assignee": "me" }
{ "createdBy": "me" }
{ "updatedBy": "me" }
{ "Reviewer": "me" }

The operator object form { "me": true } also works:

{ "Reviewer": { "me": true } }

Syntax	Aliases	Description
"me" (string)		Shorthand — works on any user field
{ "me": true }	myself, currentUser	Operator object form

Null checks

Operator	Aliases	Description
empty	none, null, isNull, isEmpty, blank, isBlank, isNone	Field is null or empty
exists	any, notNull, isNotNull, notEmpty, isNotEmpty, hasValue, isNotNone	Field has a value

{ "Notes": { "empty": true } }
{ "Assignee": { "exists": true } }

Boolean (YesNo) operators

Operator	Aliases	Description
yes	true, isTrue	Field is true
no	false, isFalse	Field is false

{ "Active": { "yes": true } }
{ "Archived": { "no": true } }

Table/List field operators

Filter rows within a Table or List field using the rows array. Each element is a sub-field condition using the same syntax as top-level filters.

{
  "Lines": {
    "rows": [
      { "Item": { "contains": "Widget" } },
      { "Quantity": { "min": 5 } }
    ]
  }
}

All sub-field conditions are AND-ed — matching rows must satisfy every condition.

Syntax	Description
{ "rows": [...] }	Match rows where all sub-conditions are true
{ "rows": [...], "operator": "excludes" }	Exclude entries where any row matches
{ "empty": true }	Table/list is empty
{ "exists": true }	Table/list has at least one row

---

Standard Fields

Standard fields can be used alongside custom module fields. They are automatically resolved to internal field IDs.

Field name	Maps to	Description
state	state	Entry state
documentId	documentId	Document ID
createdBy	createdBy	Creator username (supports "me")
assignee	assignTo	Assigned user (supports "me")
updatedBy	lastChangeBy	Last modifier username (supports "me")
createdDate	createdDate	Creation date
updatedDate	lastChangeDate	Last modification date
due	due	Due date
date	date	Entry date
search	documentId	Text search on document ID
createdAfter	createdDate	Alias for createdDate >=
createdBefore	createdDate	Alias for createdDate <=
updatedAfter	lastChangeDate	Alias for updatedDate >=
updatedBefore	lastChangeDate	Alias for updatedDate <=

{ "state": "Open", "assignee": "me" }
{ "createdBy": "me" }
{ "createdDate": { "after": "2026-01-01" } }

---

Examples

1. Simple equality

Module('Customer').search({ "Status": "Active" })

2. Text search with number range

Module('PurchaseOrder').search({
    "Vendor": { "contains": "Acme" },
    "Amount": { "min": 1000, "max": 5000 }
})

3. Date range on module field

Module('Leave').search({
    "Start Date": { "after": "2026-03-01", "before": "2026-03-31" }
})

4. Current user's tasks due soon

Module('Task').search({
    "assignee": "me",
    "due": { "upcoming": { "duration": "day", "offset": 7 } }
})

5. OR across states

Module('Leave').search({
    "or": [
        { "state": "Approved" },
        { "state": "Submitted" }
    ]
})

6. Nested AND/OR

Module('PurchaseOrder').search({
    "and": [
        { "state": "Open" },
        { "or": [
            { "Priority": "High" },
            { "Amount": { "min": 10000 } }
        ]}
    ]
})

7. Table row matching

Module('PurchaseOrder').search({
    "Lines": {
        "rows": [
            { "Item": { "contains": "Widget" } },
            { "Quantity": { "min": 5 } }
        ]
    }
})

8. Exclude rows + null check

Module('PurchaseOrder').search({
    "Lines": {
        "rows": [{ "Quantity": { "min": 10 } }],
        "operator": "excludes"
    },
    "Approval Note": { "empty": true }
})

9. Boolean + text exclusion

Module('PurchaseOrder').search({
    "Urgent": { "yes": true },
    "Category": { "not": "Internal" }
})

10. Entries updated in the past 3 months

Module('Customer').search({
    "updatedDate": { "past": { "duration": "month", "offset": 3 } }
})

11. With sort, direction, and limit

results = Module('Customer').search(
    { "Status": "Active" },
    sort="Score",
    direction=QuerySortDirection.Descending,
    take=20
)

---

Notes

• All operator names are case-insensitive. Use whichever alias feels most natural.

• Custom fields are referenced by display name (e.g. "Priority", "Start Date").

• Standard fields (e.g. "state", "assignee") are resolved automatically.

• The search method always returns List<FETIASEntity>.

• Use findAll / find / count / iterate for raw MongoDB filters when needed.