> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# User custom fields
> Define org-wide custom attributes on people, populated from your IdP and surfaced on every user profile
Every organization gets a built-in **Users** database, holding one row per person in Serval. Turning on user custom fields lets you add your own typed fields to it: cost center, employee type, badge ID, start date, or anything else your IdP knows about people that Serval doesn't model natively.
Once defined, those fields appear as **Custom attributes** on each person's profile, and become available as criteria in access profiles, routing rules, SLA attachment, queue filters, and ticket list filters.
**"User custom fields" and "custom attributes" are the same thing.** User custom fields is the capability you turn on and the schema you define. Custom attributes is the section those fields render in on a person's profile.
## Turn on the capability
The toggle is in a team's **Settings → Capabilities**.
1. Enable **Databases** first. Custom fields are defined on the Users database, so the User custom fields toggle stays locked until Databases is on.
2. Enable **User custom fields**.
On enable, Serval creates the organization's Users schema and immediately kicks a sync sweep, so values populate right away instead of waiting for the next scheduled user sync.
**The setting is org-wide, even though it lives in a team's settings.** The team that turns it on becomes the owner and ingests users for the whole organization. Every other team's toggle locks with a note naming the owner. To hand ownership to a different team, turn it off on the owning team first.
**Choose IT as the owner in most cases.** The owning team is the one whose connected apps populate these fields, and IT typically administers the identity and directory apps that carry the attributes you want: Okta, Google Workspace, Slack, and similar. Putting ownership anywhere else means the team that manages those app connections isn't the team that owns the schema they feed.
The dependency also runs backwards. While user custom fields are on, that team's Databases toggle stays locked, so turn custom fields off before disabling Databases.
## Define the fields
The Users table appears in the owning team's Databases alongside your other tables. Add fields to it exactly as you would any other item type, and every field type is available. See [Schema design](/sections/documentation/databases/schema-design#fields) for the field types and for how renames, retypes, and deletions behave.
The Users table's key field holds Serval's internal user ID rather than a user-facing attribute, so it's excluded everywhere fields are listed or picked.
The Users table behaves differently from a table you create:
* There's no **Add item** button. Rows are created by user ingestion, or on the first manual save against a person who doesn't have one yet.
* It can't be deleted.
* User search backs the browse experience rather than the standard item list, so the archived-items toggle doesn't apply.
## Populate the fields
### From a connected app
Values come from your connected IdP's user payloads. Map them on the Users table's **Sources** tab, using the same multi-source mapping UI as any other database. Several sources can contribute to the same table, and you pick the source of truth per field. See [Ingestion](/sections/documentation/databases/ingestion).
### By hand on a profile
Open a person's profile, go to the **Attributes** tab, and click any value under **Custom attributes** to edit it in place.
### Pinning
A manual edit pins the value by default, which stops sync from overwriting it. Release the pin to let connected apps update the field again, or pin an unpinned value to freeze what's currently there.
Every write is recorded. Expand a row to see its history: previous values, whether each was pinned, the user or connected app that set it, and when.
## Where user custom fields can be used
| Surface | Available fields |
| :--------------------------------- | :------------------------------- |
| Access profile membership criteria | Text, Unique, Enum, Multi-select |
| Routing rule requester conditions | Text, Unique, Enum, Multi-select |
| SLA attachment criteria | Text, Unique, Enum, Multi-select |
| Queue filters | All field types |
| Ticket list filters | All field types |
The split isn't arbitrary. Access profiles, routing rules, and SLA criteria match on value labels, so they only offer the types that can produce a populated value picker. Offering the others would let you build a rule that matches nobody. Queue and ticket filters use typed predicates instead, so they can express Number, Boolean, Timestamp, and User reference comparisons too.
Surfaces that author criteria against these fields hide the option entirely until the org has opted in and defined at least one usable field.
## Permissions
| Action | Required permission |
| :---------------------------- | :-------------------------------------------- |
| Turn the capability on or off | Update settings, on that team |
| View custom attributes | View items, on a team that can see the schema |
| Edit custom attributes | Update items, on the **schema-owning** team |
**Editing custom attributes isn't gated the same way as the default attributes on the same tab.** Default attributes (name, timezone, language, manager) are editable by the person themselves or any org admin. Custom attributes are entity writes, authorized against the team that owns the Users schema. An org admin who lacks item-edit permission on the owning team sees custom attributes as read-only while the default fields stay editable.
Both sections are read-only on a deactivated user's profile. System users show no default attributes at all, and their custom attributes are read-only.
## What's next
Field types, key fields, and how to change a schema after data is in place.
Connect an IdP and map its user payload onto your fields.
Build profile membership criteria from user attributes.
Control who can view and edit items, and trace every field change.