Enhancement: Map Google People API 'fileAs' to vCard 'FN' (Formatted Name) in GoogleContactsAPIService

[akurpanek]

Describe the feature you'd like to request

When importing contacts from Google using the Google Integration app (integration_google), Nextcloud fetches contact details via the Google People API. Currently, the sync process extracts structured name components (names) but completely ignores the fileAs field (documented in Google People API Reference).

My Use Case

I have a large number of contacts sharing identical first and last names. To distinguish between them, I utilize Google's fileAs field to add crucial context or custom nicknames without cluttering the structural First/Last name fields.

For example, I have multiple entries for "Alex Schmidt":

First Name	Last Name	Google fileAs / Intended UI Display Name
Alex	Schmidt	Alex Schmidt (climbing)
Alex	Schmidt	Alex Schmidt (surfing)

When syncing via the integration app, the unique fileAs value is dropped. As a result, they all show up identically as "Alex Schmidt" in Nextcloud Contacts, creating massive ambiguity in the address book.

Describe the solution you'd like

I would like GoogleContactsAPIService.php to check for the presence of the fileAs field in the Google API payload. If fileAs is set and not empty, it should be used to overwrite or fill the $displayName / vCard FN (Formatted Name) property, while leaving the structured N property intact.

Proposed Code Solution

In lib/Service/GoogleContactsAPIService.php, the current code blocks populate $displayName solely from $n['displayName']:

\$displayName = '';
// we just take first name
if (isset(\$c['names']) && is_array(\$c['names'])) {
    /** @var array{displayName?: string, familyName?: string, givenName?: string, middleName?: string, honorificPrefix?: string, honorificSuffix?: string } \$n */
    foreach (\$c['names'] as \$n) {
        \$displayName = \$n['displayName'] ?? '';
        \$familyName = \$n['familyName'] ?? '';
        \$firstName = \$n['givenName'] ?? '';
        \$additionalName = \$n['middleName'] ?? '';
        \$prefix = \$n['honorificPrefix'] ?? '';
        \$suffix = \$n['honorificSuffix'] ?? '';
        if (\$familyName || \$firstName || \$additionalName || \$prefix || \$suffix) {
            \$prop = \$vCard->createProperty('N', [0 => \$familyName, 1 => \$firstName, 2 => \$additionalName, 3 => \$prefix, 4 => \$suffix]);
            \$vCard->add(\$prop);
        }
        break;
    }
}

// PROPOSED ADDITION:
// Check for the Google People API 'fileAs' field to preserve custom display contexts
if (isset(\$c['fileAs']) && is_array(\$c['fileAs'])) {
    foreach (\$c['fileAs'] as \$f) {
        if (!empty(\$f['value'])) {
            \$displayName = \$f['value'];
            break;
        }
    }
}

This logic ensures that if a user has explicitly defined a "File As" format in Google, Nextcloud respects this as the primary display string (FN property) in the address book, avoiding duplicated visual names.

Describe alternatives you've considered

1. Manual Editing: Manually editing hundreds of contacts inside Nextcloud after the initial sync to append the bracketed context to the display names. This is extremely time-consuming and inefficient.
2. Polluting Structural Fields: Appending the context (e.g., (climbing)) directly into the "First Name" or "Last Name" fields inside Google Contacts before importing. However, this breaks standard name structures, messes up formal alphabetical sorting, and pollutes the clean name data.
3. Custom Scripting: Writing a standalone python/php script to intercept Google VCF exports and batch-rename properties via regex before importing them to Nextcloud. While functional for a one-time migration, this does not help users who rely on the automated integration_google application for continuous syncing.

[lukasdotcom]

Hi @akurpanek,

I'm not sure where the fileAs is stored as your proposed addition would not work as the fileAs field does not exist in the $c object. Also not sure if displayName should be overridden when it is already defined. It would be better to use fileAs in the contacts also for Nextcloud.