Filters control which records are retrieved from a database object when a Process runs. When you configure a Process Input, you assign a Filter to it — the Filter determines exactly which records are loaded into the Process Logic workbook. Without a Filter, a Process Input would retrieve every record in the object, which is rarely what you want and often a significant performance problem.

Filters are defined using XML, stored centrally in the platform, and are reusable. The same Filter can be applied to multiple Process Inputs across different Processes. Many common filters are pre-installed in every instance, covering date-based and parameter-driven selection patterns.

Where filters are used

Filters are used when configuring Process Inputs. They can also be applied to screens to control what data is displayed by default — see Applying Default Filters to Screens. This article focuses on filter usage in the context of Processes.

Create a filter

Before creating a new Filter, check whether an existing one already meets your requirements. Navigate to Process Configuration \> Filters and review what is available. Copying and modifying an existing Filter is usually faster than writing one from scratch.

To create a new Filter:

Open the Configuration application and navigate to Process Configuration \> Filters.
Click Edit.
Enter the number of Filters to create and click Add.
For each new Filter, enter a Filter Name that clearly identifies its purpose. Use consistent naming conventions so other configurators can understand what a Filter does without reading its XML.
In the Filter field, enter the XML definition. You can paste from an existing Filter and modify it, or write one from scratch using the structure described below.
Enter a Description explaining what the Filter does and when to use it.
Enter an Audit Comment and click Save and Refresh.

XML structure

Every Filter is defined as an XML fragment. The opening element must declare the platform namespace.

<xml-fragment xmlns:es="http://energysys.com/schema/energysys">
  ...
</xml-fragment>

A Filter is built from expressions. Each expression defines one condition: an attribute to evaluate, an operator, and a value to compare against.

<es:Expression>
  <es:Attribute>STATUS</es:Attribute>
  <es:Operator>eq</es:Operator>
  <es:Value>Active</es:Value>
</es:Expression>

This returns only records where STATUS equals Active.

Operators

Operator	Meaning
`eq`	Equals
`neq`	Not equal to
`lt`	Less than
`lte`	Less than or equal to
`gt`	Greater than
`gte`	Greater than or equal to
`like`	Matches a text pattern (use `%` as wildcard)
`nlike`	Does not match a text pattern
`empty`	Attribute has no value
`nempty`	Attribute has a value

Combining conditions

Use <es:And> to require all conditions to be true, or <es:Or> to require any one condition to be true. Wrap each expression in an <es:Filter> element within the logical group.

<xml-fragment xmlns:es="http://energysys.com/schema/energysys">
  <es:And>
    <es:Filter>
      <es:Expression>
        <es:Attribute>REGION</es:Attribute>
        <es:Operator>eq</es:Operator>
        <es:Value>North</es:Value>
      </es:Expression>
    </es:Filter>
    <es:Filter>
      <es:Expression>
        <es:Attribute>STATUS</es:Attribute>
        <es:Operator>eq</es:Operator>
        <es:Value>Active</es:Value>
      </es:Expression>
    </es:Filter>
  </es:And>
</xml-fragment>

Using Process Parameters in filters

Filter values can reference Process Parameters using the syntax $P{Parameter Name}. When the Process runs, the platform substitutes the parameter value into the Filter before executing the query. This is how Filters are made dynamic — for example, retrieving records only for the date the user supplied at runtime.

<es:Expression>
  <es:Attribute>TRANSACTION_DATE</es:Attribute>
  <es:Operator>eq</es:Operator>
  <es:Value>$P{Transaction Date}</es:Value>
</es:Expression>

Parameter names in Filters must match the Parameter names configured on the Process exactly, including capitalisation. This is why using consistent parameter names across all Processes in an application matters — it allows Filters to be reused without modification.

Functions

Optional functions can be applied to an attribute value before the comparison is evaluated.

Function	Effect
`extract year`	Extracts the year from a date
`extract month`	Extracts the month from a date
`lower`	Converts text to lowercase
`upper`	Converts text to uppercase
`trim`	Removes leading and trailing spaces
`length`	Returns the character count
`round`	Rounds a numeric value
`floor`	Truncates decimal places
`ceiling`	Rounds up to the nearest whole number

Date range filters

A common pattern is to retrieve all records within a given month. This uses SQL date functions in the filter value:

<xml-fragment xmlns:es="http://energysys.com/schema/energysys">
  <es:And>
    <es:Filter>
      <es:Expression>
        <es:Attribute>TRANSACTION_DATE</es:Attribute>
        <es:Operator>gte</es:Operator>
        <es:Value>trunc($P{Period}, 'MONTH')</es:Value>
      </es:Expression>
    </es:Filter>
    <es:Filter>
      <es:Expression>
        <es:Attribute>TRANSACTION_DATE</es:Attribute>
        <es:Operator>lte</es:Operator>
        <es:Value>last_day($P{Period})</es:Value>
      </es:Expression>
    </es:Filter>
  </es:And>
</xml-fragment>

This retrieves records where TRANSACTION_DATE falls anywhere within the month of the supplied Period parameter.

Concatenating parameters in filter values

When a foreign key in a child object is made up of multiple components from a parent object's unique key, you can construct the filter value by concatenating parameters with a wildcard:

<es:Expression>
  <es:Attribute>CONTRACT_REF</es:Attribute>
  <es:Operator>like</es:Operator>
  <es:Value>%$P{Category}::$P{Type}%</es:Value>
</es:Expression>

This returns records where CONTRACT_REF contains both the Category and Type parameter values.

Filtering by creation or modification date

By default, objects do not expose creation and modification timestamps. To filter records by when they were created or last modified, you must first enable the feature on the object, then include those attributes in the Process Input.

Enable modification date filtering on the object:

Navigate to Objects \> Objects and select the object.
Click Edit.
Set Filter on Modification Dates to True.
Enter an Audit Comment and click Save and Refresh.

Once enabled, the system makes two hidden attributes available for that object: EU_CREATED_AT and EU_MODIFIED_AT (both DateTime). These do not appear in the object's attribute list but are available to Processes and OData queries.

Include them in a Process Input:

When configuring the Process Input, set Include Modification Dates to True. The EU_CREATED_AT and EU_MODIFIED_AT values will be appended to the end of each record loaded into the workbook.

You can then reference these attributes in a Filter:

<es:Expression>
  <es:Attribute>EU_MODIFIED_AT</es:Attribute>
  <es:Operator>gt</es:Operator>
  <es:Value>$P{Last Run Date}</es:Value>
</es:Expression>

This retrieves only records modified after the date supplied as a parameter — useful for incremental processing patterns where you only want to process records that have changed since the previous run.

If using modification date filtering on a Virtual Object, set the Main Object field on the Virtual Object to indicate which of its source objects provides the timestamps.