---
title: "Managed fields"
manual: "Academic Profiles"
version: "main"
source: "Configuration/ManagedFields/Index.rst"
rendered: "2026-10-02T15:38:26+00:00"
---

# Managed fields {#configuration-managed-fields}

A synchronisation or an import fills some fields of a person record, and an
editor who changes such a value in the backend loses the change on the next
run. The `managedFields` map of
`Configuration/AcademicPersons/Settings.yaml` names those fields, and the
backend record form and the profile editor of [`fgtclb/academic-persons-edit`](https://packagist.org/packages/fgtclb/academic-persons-edit)
render them read-only, but only on the records the synchronisation wrote. A
record an editor or a profile owner added keeps every field editable.

The `readonly` flag of the [validations](../Validations/Index.html#configuration-validations)
is the other lock. It applies to every record of a table, so it also locks the
e-mail address an editor added by hand. Use `readonly` for a field no one
may change, and `managedFields` for a field the synchronisation owns.

## Which records are locked {#configuration-managed-fields-records}

A managed field is read-only on a record that

-   carries an import identifier, as every record written by the frontend
    user synchronisation does (see
    [The records of a list](../FrontendUserSync/Index.html#configuration-frontend-user-sync-records)), and every imported
    record that sets one,
-   is a record of the default language, and
-   belongs to a profile that is not excluded from the synchronisation with
    **Skip synchronisation**. A hidden profile is still synchronised,
    so its records stay locked.

The field shows a note below its label, after the description it already has:
**Maintained by the synchronisation (fe_users:12), so it is read-only
here.**

Every other record keeps the behaviour it had: a record without an import
identifier, every record of an excluded profile, and every translation. The
synchronisation writes the default language only, so a translated position or
title is text an editor maintains. Fields that are shared by all languages,
such as the names, are read-only on a translation already.

The lock applies to the backend form and the profile editor only. The
synchronisation, an import or a script keep writing the fields, and a value
that reaches the database some other way is not refused.

Two cases behave differently from what the rules above suggest:

-   A copy of a synchronised record keeps its import identifier, so the copy is
    locked as well. Copying a record is not a way to get an editable one.
-   In a workspace, the profile and the contract a record belongs to are read
    as they are live. Switching **Skip synchronisation** on unlocks the
    profile form at once, and its contracts and contact records once the
    profile is published.

## In the profile editor {#configuration-managed-fields-editor}

The profile editor of [`fgtclb/academic-persons-edit`](https://packagist.org/packages/fgtclb/academic-persons-edit) applies the same
map to the same records. A managed field is shown read-only with the marker
**Synchronised**, on the profile page and in the contract and contact
forms. A contract or contact with a managed field cannot be deleted, and it
offers no edit once every field the owner could edit is managed. Hiding and
sorting stay available, the synchronisation changes neither.

In a translated site language the editor edits the translation. A managed
field whose value all languages share, such as the website or the type of a
phone number, stays read-only there, as it does in the backend. A translated
field, such as the position of a contract, is text of the translation and
stays editable. A synchronised contract or contact still cannot be deleted
there.

## The keys {#configuration-managed-fields-keys}

The shipped lists are empty, so no field is managed until a package names one:

**EXT:academic_persons/Configuration/AcademicPersons/Settings.yaml**

```yaml
managedFields:
  profile: []
  contracts: []
  emailAddresses: []
  phoneNumbers: []
  physicalAddresses: []
```

Each list names fields the way the rest of the file does, by their key or by
the property they address, and only the list of the record's own type applies:

| Key | Names a field of |
| --- | --- |
| `profile` | `profile`, for instance `title` or `website` |
| `contracts` | `contracts.fields`, for instance `position` |
| `emailAddresses` | `contracts.contactSections.emailAddresses.fields`, for instance `emailAddress` or its property `email` |
| `phoneNumbers` | `contracts.contactSections.phoneNumbers.fields` |
| `physicalAddresses` | `contracts.contactSections.physicalAddresses.fields` |

`type` names the type of the list it is in: listed below
`phoneNumbers`, it locks the type of a phone number and nothing else.

A field the file does not configure cannot be managed. A name that matches no
field makes every person record form and the profile editor fail with the
exception `1790536034`, which names it, until the list is corrected. Flush
the TYPO3 caches after a change, as after every change of the file.

## Example: synchronised names and contacts {#configuration-managed-fields-example}

The three name fields ship locked for every profile, with `readonly` and
`disabled` (see [Fields that are locked by default](../Validations/Index.html#configuration-validations-defaults)). A site
package that wants them locked on synchronised profiles only replaces those
flags, and names the fields together with the contract position and the
e-mail address:

**EXT:my_sitepackage/Configuration/AcademicPersons/Settings.yaml**

```yaml
profile:
  firstName:
    validators:
      - required
      - frontendreadonly
  middleName:
    validators:
      - frontendreadonly
  lastName:
    validators:
      - required
      - frontendreadonly

managedFields:
  profile:
    - firstName
    - middleName
    - lastName
  contracts:
    - position
  emailAddresses:
    - emailAddress
```

Backend editors can now correct the names of a profile they created, and the
synchronised ones stay locked, in the backend and in the profile editor.
`frontendreadonly` keeps profile owners away from the names of every
profile, synchronised or not. Leave it out to let the owner of a profile no
synchronisation writes correct their own name. `required` keeps the
first and last name required in the backend, as the TCA of the profile table
declares them.