> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/reference/user-search-configuration.md).

# User search configuration

Every column name and optional-criterion value the four user-search properties accept, with their shipped defaults and the vocabularies each search widget validates against.

## What this is, and when you need it

The four properties that decide which columns a user-search grid shows, and the property that decides which optional criteria are pre-expanded on a search form. All five are on **Administration → System Configuration** — two in the `System` category and three in `DirectoryLookup`, which is the tab to check when a key is not where you expect it. Scan the tables here, then set the values on [Find a user](/administration-guide/identities/find-a-user.md).

Every one of these properties is a comma-separated list. OpenIAM splits on `,` and nothing else, so **whitespace is not trimmed** — a value entered as `email` matches no column and renders blank.

## The four result-column properties

All four accept the same column vocabulary and use the same parser. They differ only in which screen they drive.

| Property                                                       | Label                                   | Shipped default                                                                                                                                                |
| -------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.openiam.ui.user.search.result.columns`                    | Columns Shown in User Search Results    | `name,phone,email,userStatus,accountStatus`                                                                                                                    |
| `org.openiam.ui.user.dir.lookup.search.result.columns`         | Directory Lookup Search Result Columns  | `name,title,department,phone,email,location`                                                                                                                   |
| `org.openiam.ui.user.view.user.search.result.columns`          | Directory Reports Search Result Columns | `name,phone,email,organization,department`                                                                                                                     |
| `org.openiam.ui.dir.lookup.subordinates.search.result.columns` | Subordinate Search Result Columns       | `firstName,lastName,userStatus,accountStatus,nickname,birthdateAsStr,maidenName,suffix,gender,middleInit,jobCodeId,title,locationCd,classification,costCenter` |

`org.openiam.ui.user.search.result.columns` has held its shipped value unchanged since 4.0.0.0.

## Column names

| Group         | Values                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity      | `name`, `firstName`, `lastName`, `middleInit`, `nickname`, `maidenName`, `prefix`, `prefixLastName`, `partnerName`, `suffix`, `principal`, `employeeId` |
| Contact       | `phone`, `email`                                                                                                                                        |
| Status        | `userStatus`, `accountStatus`                                                                                                                           |
| Structure     | `organization`, `department`, `division`, `title`, `location`, `locationCd`, `costCenter`, `classification`                                             |
| Employment    | `employeeTypeId`, `employeeTypeName`, `jobCodeId`, `startDate`, `userTypeInd`, `accountTypeName`                                                        |
| Personal      | `birthdateAsStr`, `gender`, `sex`                                                                                                                       |
| Relationships | `supervisorMdTypeName`, `supervisorsNameList`, `relationship`, `hasRelatedAccounts`, `applicationNames`                                                 |

Two column names behave differently from the rest.

**`name` is composed, not stored.** `org.openiam.ui.user.fullname.compose.rule` ships `firstName,lastName` and decides how the name column is assembled. Change that property and the `name` column changes on all four screens at once.

**`principal` has a side effect.** Naming `principal` in a column property makes OpenIAM load each user's default identity for the result grid. Omit it and the identity is not fetched at all, which is why a `principal` column added anywhere other than the property renders blank.

A column key that is not in the table above is not rejected — the grid falls back to a title-cased version of whatever you typed for the header and shows an empty column under it. A blank column with a plausible-looking header is almost always a typo.

## Optional search criteria

`org.openiam.ui.user.search.form.additional.criteria`, label **Additional User Search Criteria**, type `MultiSelect`. It **ships empty**, and empty is valid: out of the box no optional criterion is pre-expanded when a search form loads. Since 4.2.2.0 its type is a multi-value select, which is why the System Configuration screen renders it as a multi-select rather than a text box.

The property does not decide which criteria *exist*. It names the ones already expanded when the form loads. The readback is the form itself: load a search screen and see which optional criteria are open rather than folded away.

### The vocabularies are not the same on every screen

More than one search widget consumes this property, and each validates it against its own set of keys. A value outside a widget's set is dropped with no error, so the same property can work on one screen and appear to do nothing on another.

| Widget                              | Accepted keys                                                                                                                                                                            |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Advanced user search                | `lastName`, `email`, `principal`, `employeeId`, `userStatus`, `accountStatus`, `employeeType`, `jobCode`, `maidenName`, `roleId`, `groupId`, `organizationId`, `resourceId`, `attribute` |
| Directory lookup user-search widget | `userStatus`, `accountStatus`, `employeeType`, `userType`, `jobCode`, `attribute`, `resourceId`, `organizationIds`, `roleIds`, `groupIds`, `firstName`, `maidenName`, `nickName`         |
| SelfService request user picker     | `userStatus`, `accountStatus`, `attributeName`, `application`, `roleId`, `groupId`, `employeeType`, `maidenName`, `jobCode`, `firstName`, `nickname`, `userType`                         |

Note the near-misses between the second and third rows: `attribute` against `attributeName`, `resourceId` against `application`, `roleIds` against `roleId`, `nickName` against `nickname`. These are different keys, not spelling variants, and each is only honoured by the widget that declares it.

**The safe set.** Seven keys are accepted by both of the first two widgets:

{% code overflow="wrap" %}

```
userStatus,accountStatus,employeeType,jobCode,maidenName,attribute,resourceId
```

{% endcode %}

Five are accepted by all three: `userStatus`, `accountStatus`, `employeeType`, `jobCode` and `maidenName`. Stay inside the seven unless you have tested the specific screen you care about, and inside the five if the value must behave identically everywhere.

### The Organization criterion is special

The Organization criterion is hidden exactly when organization scoping is already restricting the search — it would have narrowed nothing, so OpenIAM leaves it off the form. Naming it in the property does not bring it back. If it never appears for one operator and does for another, the difference is whether scoping applies to them, not the property. See [Scope a delegated administrator](/administration-guide/identities/delegated-administration.md).

## Reading the effective configuration

Both properties are read back from the search screen itself: the grid headers are the result columns in their configured order, and the optional criteria that load already expanded are the ones the second property names. There is no separate view of the effective configuration.

Both are cached. The property cache refreshes on the sweep interval — five minutes on shipped configuration — so a search screen that disagrees with the System Configuration screen is usually a change that has not swept yet, not a change that failed. Wait out one sweep before changing anything else.

## Related

* [Find a user](/administration-guide/identities/find-a-user.md) — the task these properties configure
* [System properties](/administration-guide/reference/system-properties.md) — every property named here, in the full catalogue
* [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) — when the columns are right and the user is still missing

*Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/reference/user-search-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.