---
title: FileAttributesFilter
description: Retrieves and exposes a record from a delimiter-separated file. Lookup of the record is performed using a specified key, whose value is derived from an expression. The resulting record is exposed in an object whose location is specified by the target expression. If a matching record cannot be found, then the resulting object is empty.
component: pinggateway
version: 7.2
page_id: pinggateway:reference:FileAttributesFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/FileAttributesFilter.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: 2025-06-02T16:30:54Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/FileAttributesFilter.html
section_ids:
  FileAttributesFilter-usage: Usage
  FileAttributesFilter-properties: Properties
  FileAttributesFilter-moreinfo: More information
---

# FileAttributesFilter

Retrieves and exposes a record from a delimiter-separated file. Lookup of the record is performed using a specified `key`, whose `value` is derived from an expression. The resulting record is exposed in an object whose location is specified by the `target` expression. If a matching record cannot be found, then the resulting object is empty.

The retrieval of the record is performed lazily; it does not occur until the first attempt to access a value in the `target`. This defers the overhead of file operations and text processing until a value is first required. This also means that the value expression is not evaluated until the object is first accessed.

## 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,
         "key": configuration expression<string>,
         "value": runtime expression<string>
     }
}
```

For an example see [Log in with credentials from a file](../gateway-guide/credentials-datasource.html#tutorial-credentials-from-file).

## 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` is not set, the keys are assigned automatically by the column numbers of the file.

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

  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 a `username` field and a `password` field mentioned in the fields list, Then you can access the user name as `${attributes.file.username}` and the password as `${attributes.file.password}`.

  See also [Expressions](Expressions.html#Expressions).

* `"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 be looked-up in the file.

  See also [Expressions](Expressions.html#Expressions).

## More information

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