---
title: ScriptableFilter
description: Configure ScriptableFilter to process PingGateway requests and responses by executing a Groovy script that calls the next handler or returns a custom response
component: pinggateway
version: 2024.11
page_id: pinggateway:reference:ScriptableFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ScriptableFilter.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-06-02T09:47:34Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/ScriptableFilter.html
section_ids:
  ScriptableFilter-usage: Usage
  ScriptableFilter-properties: Properties
  ScriptableFilter-examples: Examples
  ScriptableFilter-moreinfo: More information
---

# ScriptableFilter

Processes requests and responses by executing a Groovy script. Executed scripts must return one of the following:

* [Promise\<Response, NeverThrowsException>](../_attachments/apidocs/org/forgerock/util/promise/Promise.html)

* [Response](../_attachments/apidocs/org/forgerock/http/protocol/Response.html)

To execute the next element in a chain (a filter or a handler), the script must call the expression `next.handle(context, request)`. If the script doesn't call `next.handle(context, request)`, the chain flow breaks and the script has to build and return its own response by calling one of the following expressions:

* `return myResponse`

* `return newResultPromise(myResponse)`

Actions on the response returned from the downstream flow must be performed in the Promise's callback methods.

You can find more information about script properties, available global objects, and automatically imported classes in [Scripts](Scripts.html). You can find more information about creating scriptable objects in Studio in [Scripts in Studio](../configure/extending.html#scripting-studio) and [Configure scriptable throttling](../gateway-guide/throttling.html#throttling-scriptable).

## Usage

```json
{
    "name": string,
    "type": "ScriptableFilter",
    "config": {
        "type": configuration expression<string>,
        "file": configuration expression<string>, // Use either "file"
        "source": [ string, ... ],                // or "source", but not both.
        "args": map,
        "clientHandler": Handler reference
    }
}
```

## Properties

You can find more information about properties for ScriptableFilter in [Scripts](Scripts.html).

## Examples

You can find an example scriptable filter that recovers policy advices from AM in the `failureHandler` property of [PolicyEnforcementFilter](PolicyEnforcementFilter.html).

## More information

[Scripts](Scripts.html)

[org.forgerock.openig.filter.ScriptableFilter](../_attachments/apidocs/org/forgerock/openig/filter/ScriptableFilter.html)