Creating Custom Filters

You can create a custom filter by creating a named filter or a filter class. A named filter is useful for simple filters while a filter class should be used for complex filters (for example, when the returned results must be modified).

For more information about predefined REST filters, see the discussion about filters in Subscriber Management (SubMan) API.

Named Filters

Use named filters to remove fields from the response. Named filters are defined in the ${MTX_DIR}/conf/rsgateway.yaml file. To view a list of all named filters, query the RS Gateway with the URL: http://address:port/data/json/filters.

For details about the MATRIXX Digital Commerce environment variables, see the discussion about installation directories, navigation shortcuts, and environment variables in Installation and Configuration.

Filter Classes

You can create Java classes to customize the response. For example:
  • Conditional exclude or include fields. For example, include if a parameter is above a specific value.
  • Change field values. For example, remove microseconds from a time field.
  • Add fields.
The definition includes the Java class and parameters sent to the Java code. For example:
filter:
  BalanceArraySeconds: |
    fieldPaths:
      - BalanceArray/StartTime
      - BalanceArray/EndTime
    filterClasses:
      - UsecFilter

When you create a filter class you build the file using Maven. Each filter is a separate JAR file with an identifiable name. You add the filter definition to the rsgateway.yaml file and copy the JAR file to the RS Gateway classpath and then restart RS Gateway. You can add multiple filter definitions in the same classpath.

Named Filter Example

In the discussion about creating a named filter, the example describes how to create a filter that can be used when creating a subscriber. The custom filter excludes _resultCode, _resultText, and _resultType and returns the following:
  • ObjectId
  • Result
  • ResultText
  • RouteId

Filter Class Example

In the discussion about creating a filter class, the example describes how to create a filter that can be used to filter purchasable product offers. The custom filter excludes product offers with balances that are outside of the following parameters:
  • maxValue
  • minValue

Per-service Filter Specification

You can define per-service implementations of a filter name. For example:

my_filter={}
service_create_device_for_subscriber_and_add_offer:my_filter={}
service_create_device_and_subscription:my_filter={}

When you call a URL with ?filterName=my_filter, RS Gateway uses the first one, unless the service being called is service_create_device_for_subscriber_and_add_offer, in which case its the second filter, and if you call the service service_create_device_and_subscription then the third filter is used.

In this way, you can implement a single named filter differently depending on which REST call is executed. This is useful when implementing a filter where the operations required of the filter are different depending on which URL is called. For a pricing query, it might filter things out based on metadata; for a subscription query it might filter things from the purchased offer array and from the balance array.