---
title: FileAttributesFilter
description: Retrieves and exposes a record from a delimiter-separated file. PingGateway looks up the record with the keys specified in the fields setting.
component: pinggateway
version: 2026
page_id: pinggateway:reference:FileAttributesFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/FileAttributesFilter.html
revdate: 2025-06-02T18:01:47Z
section_ids:
  FileAttributesFilter-usage: Usage
  FileAttributesFilter-properties: Properties
  FileAttributesFilter-moreinfo: More information
---

# FileAttributesFilter

Retrieves and exposes a record from a delimiter-separated file. PingGateway looks up the record with the keys specified in the `fields` setting.

PingGateway populates the [FileAttributesContext](FileAttributesContext.html) and the optional `target` (deprecated) with key-value pairs from the record. If no matching record is found, the context and optional `target` are empty.

When the deprecated `target` setting is configured, PingGateway lazy loads the record on the first attempt to access one of its values. This defers the overhead of file operations and text processing until a value is first required. PingGateway doesn't evaluate the `value` expression until the data is first accessed. PingGateway reads the file synchronously, potentially impacting performance.

When `target` isn't set, PingGateway reads the file asynchronously when calling this filter. In this case, place this filter immediately before the entity reading the data from the context.

## Usage

```json
{
     "name": string,
     "type": "FileAttributesFilter",
     "config": {
         "file": configuration expression<string>,
         "charset": configuration expression<string>,
         "separator": configuration expression<enumeration>,
         "header": configuration expression<boolean>,
         "fields": [ configuration expression<string>, ... ],
         "target": lvalue-expression, // deprecated
         "key": configuration expression<string>,
         "value": runtime expression<string>,
         "executorService": ScheduledExectutorService reference
     }
}
```

You can find an example in [Password replay from a file](../gateway-guide/credentials-file.html).

## Properties

* `"file"`: *configuration expression<[string](preface.html#definition-string)>, required*

  The file containing the record to be read.

* `"charset"`: *configuration expression<[string](preface.html#definition-string)>, optional*

  The character set in which the file is encoded.

  Default: `"UTF-8"`.

* `"separator"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional*

  The separator character, which is one of the following:

  * `COLON`

    Unix-style colon-separated values, with backslash as the escape character.

  * `COMMA`

    Comma-separated values, with support for quoted literal strings.

  * `TAB`

    Tab-separated values, with support for quoted literal strings.

  Default: `COMMA`

* `"header"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional*

  A flag to treat the first row of the file as a header row.

  When the first row of the file is treated as a header row, the data in that row is disregarded and cannot be returned by a lookup operation.

  Default: `true`.

* `"fields"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional*

  A list of keys in the order they appear in a record.

  If `fields` isn't set, the keys are assigned automatically by the column numbers of the file.

* `"target"`: *<[lvalue-expression](preface.html#definition-lvalue-expression)>, optional*

  |   |                                                                                                                                                                                                                                           |
  | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | This property is deprecated. Use the [FileAttributesContext](FileAttributesContext.html) instead. Learn more in the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. |

  Expression that yields the target object to contain the record.

  The target object is a `Map<String, String>`, where the fields are the keys. For example, if the target is `${attributes.file}` and the record has `username` and `password` fields mentioned in the `"fields"` list, access the username as `${attributes.file.username}` and the password as `${attributes.file.password}`.

  Learn more in [PingGateway expressions](Expressions.html).

* `"key"`: *configuration expression<[string](preface.html#definition-string)>, required*

  The key used for the lookup operation.

* `"value"`: *runtime expression<[string](preface.html#definition-string)>, required*

  The value to find in the file.

  Learn more in [PingGateway expressions](Expressions.html).

* `"executorService"`: *ScheduledExecutorService [reference](preface.html#definition-reference), optional*

  A [ScheduledExecutorService](ScheduledExecutorService.html) to read the file.

  Default: The default ScheduledExecutorService in the heap

## More information

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