User Filter Validations

To be notified on the parent page whenever a user filter is applied or reset, and to handle validation errors returned by applyUserFilter. The USER_FILTER_CHANGE event reports the current filter state to your code; the applyUserFilter Promise reports any validation failure.

Function Call

// Listen for filter changes
ObjName.addEventListener(ZACustomEvent.USER_FILTER_CHANGE, callback);
// Handle a validation error
ObjName.applyUserFilter('Sales', 'abc').catch(function (err) { /* ... */ });

Parameters – Event Callback Payload

The callback receives a single eventData object.

FieldDescription
appliedUserFilters

Array<Object>

The user filters currently applied. Fires on every apply, including RESET (a reset entry reflects the cleared state).

appliedUserFilters[]

Object

Each entry describes one filter

  • columnName - the filter's label
  • displayCriteria - the readable user filter value currently applied (e.g. East, Q1 2025 – empty when reset)
  • dataType (e.g. CATEGORICAL_SINGLE_SELECT, NUMERIC_MULTI_SELECT, TIMELINE)
  • exclude (e.g. true for NOT‑IN or Exclude mode)

Use this event to keep your own filter UI in sync with the embedded view – for example, when a user changes a filter from inside the embed, the callback lets you update the matching control on the parent page.

Parameters – Error Object

When applyUserFilter rejects, the catch handler receives an error object. Read the message from err.errorDesc (fall back to err.errorMsg / err.message).

Most validation errors follow a standard format:

Invalid criteria for filter "<filterName>": <reason>

The filter name is always included. Two errors are raised before type validation and do not use this wrapper:

CaseMessage
Missing filter namecolumnLabel is missing, set a proper user filter columnLabel
Unknown filterNo User Filter found with the name <filterName>

Standard (wrapped) validation messages by type:

CaseReason (inside the wrapper)
Numeric - not a number"abc" is not a valid number
Numeric slider - bad formatexpected "from:to" numeric range or {from, to} object, got "abc:200"
Date range - bad formatexpected date range as "from to to" or {from, to} object, got "random-text"
Duration - bad formatexpected a duration like "0 days 00:17:05" or seconds, got "not-a-duration"
Categorical - empty valuevalue cannot be empty
Multi‑select - empty arrayexpected at least one value for multi-select
Date actual - invalid valueinvalid value "gibberish" for DATE_ACTUAL_YEARS
Seasonal - invalid valueinvalid value "Q5" for DATE_SEASONAL_QUARTERS
Relative date - invalid phraseexpected a relative date like "Last 6 Hours" or "This Week", got "Foo Bar Baz"
Timeline - unrecognised valueunrecognised timeline filter value: "<submitted value>"

Tip: invalid multi‑select items are quoted individually – e.g. applying ['2023', 'abc'] names "abc" specifically, so you can report exactly which value failed.