Tools: import and export field groups

CAFE → Tools moves field group definitions between sites: from local to staging to live, or into a new client site. Only the schema travels (groups, fields, settings, location rules), never content.

#Export

1. Go to CAFE → Tools → Export.
2. Tick the groups (search by title or key, or Select all). Each row shows the field count and where the group appears.
3. Click Export selected or Export all. The browser downloads cafe-field-groups-YYYY-MM-DD.json (or cafe-{group_key}.json for one group).

Groups in the trash are not listed. In PHP: cafe_export_field_groups().

#Import

1. Go to CAFE → Tools → Import.

2. Drop the file on the upload area, or paste the JSON (up to 2 MB).

3. Choose what to do:

   Mode	Name in the screen	Creates missing	Updates existing
   upsert	Add and update	✔	✔
   create	Only add new	✔	-
   update	Only update existing	-	✔

4. Click Check file. This is a dry run: nothing is written. You see:

   • New, Updated and Left as is counts for groups and fields;
   • each group with its fields, labelled with what happens: New, Update (with what changes: label, settings, position, …), Unchanged, Already exists (create mode), Not on this site (update mode);
   • Good to know (warnings) and problems (errors), each with its place in the file, e.g. groups[0].fields[2].

5. Click Import now and confirm. It's enabled only when the check found no errors and there is something to change.

In PHP: cafe_validate_field_group_import() (dry run) and cafe_import_field_groups().

#What an import never does

• It never deletes. Groups and fields that are not in the file stay as they are.
• It never changes values. A definition change that would make saved values unreadable is refused with an error. Examples are changing a text field with values into a number field, or moving a field with values into or out of a Collection.
• It never goes half-way. Every file is validated first; with any error, nothing is written. The writes run in one database transaction, so if a write fails, everything is rolled back.
• It never duplicates. Groups and fields are matched by their keys. Importing the same file again finds nothing to change and writes nothing.

#JSON format

{
    "format": "cafe",
    "format_version": "1.0",
    "export_type": "field_groups",
    "cafe_version": "0.6.0",
    "schema_hash": "6f1c…",
    "settings_pages": [ { "slug": "contact", "title": "Contact" } ],
    "groups": [
        {
            "key": "group_contact",
            "title": "Contact Settings",
            "description": "",
            "status": "active",
            "menu_order": 0,
            "settings": { "color": "#0d9488", "position": "normal" },
            "location_rules": [ [ { "rule": "settings_page", "operator": "==", "value": "contact" } ] ],
            "fields": [
                {
                    "key": "field_phone",
                    "name": "phone",
                    "label": "Phone",
                    "type": "text",
                    "required": true,
                    "settings": { "placeholder": "+31 20 …", "prepend": "Tel" },
                    "conditional_logic": null
                },
                {
                    "key": "field_socials",
                    "name": "socials",
                    "label": "Social profiles",
                    "type": "collection",
                    "required": false,
                    "settings": { "button_label": "Add Profile" },
                    "conditional_logic": null,
                    "fields": [
                        { "key": "field_url", "name": "url", "label": "URL", "type": "url", "required": false, "settings": {}, "conditional_logic": null }
                    ]
                }
            ],
            "hash": "a91e…"
        }
    ]
}

Stable keys. Groups and fields are identified by key (group_…, field_…), never by database IDs, so a file means the same thing on every site. Keys are matched exactly; name is what your theme uses (cafe_get_field( 'phone' )).

Deterministic. Groups are sorted by key, fields keep their order, and object keys are sorted. Exporting an unchanged schema twice gives byte-identical JSON, which is ideal for Git.

Schema hash. Both hashes use CAFE's canonical form: object keys sorted recursively, list order kept, then SHA-256. On import, CAFE:

• warns when schema_hash does not match the file's groups ("changed after export"). Hand-edited files are fine; they are still validated in full;
• compares each planned group with the saved group in the same canonical form. When the hashes match, nothing is written for that group.

Format versions. The importer reads format_version first. Files from a newer format are refused with "update CAFE on this site first". Older formats (none yet) are upgraded step by step before validation (Cybo\AdvancedFieldEngine\Tools\FormatMigrator).

#Settings Page links

A group placed on a Settings Page ("rule": "settings_page", "value": "contact") keeps that link after import. When the target site has no Settings Page with that slug, the check shows a warning. The group is still imported, and it appears as soon as a Settings Page with that slug is created (CAFE → Settings Pages, or cafe_add_settings_page()). Import never creates Settings Pages and never touches Settings Page values.

#Media

Image, Gallery, File and Video fields export their configuration (return format, allowed file types, preview size, limits). Media files never travel. Settings that point to one attachment, such as a Default Image, are exported empty because attachment IDs differ between sites. When a hand-made file contains one anyway, the import resets it (with a warning) for new fields and keeps this site's own choice for existing fields.

#Passwords and sensitive fields

A Password field's definition travels like any other field. Its saved values never do: export reads definitions only, and sensitive field types never export a default value.

#Custom field types

Import and export work with every registered field type, including your own (Custom field types). Settings are validated by each field type's own validate_settings(), and sub-field rules come from its accepts_child(). When a file uses a type that is not registered on the target site (the plugin providing it is not active), the check reports cafe_unknown_field_type for that field. The field is never turned into a text field.

#Warnings and errors

#REST API

GET /cafe/v1/tools/export and POST /cafe/v1/tools/import. See Admin REST API.