Synchronize an ACF relationship between two WordPress entries

Identify the direction that no longer works

A Venue entry may display workshops taking place there, and a Workshop entry the venues where it is offered. When you add the workshop “Gravure” to the “Salle Nord” entry, you expect to find “Salle Nord” after reopening “Gravure.” This return depends on updating a second field. First check both edit screens and their saved values. If fields agree but the public list remains incomplete, the next check concerns the template or query displaying the list.

Define the expected direction before changing fields. Some teams manage relationships only from venues, with workshops serving as a read view. Others want to add or remove a link from either screen. Record the current rule, affected content types, and ACF version loaded on the site. The native configuration interface has existed since ACF 6.2 for supported types. An older site may have a legacy filter writing the inverse value. Another may generate a list through an inverse query without storing a second value.

On an authorized copy, prepare four synthetic entries: two Venues and two Workshops. Use “Salle Nord” and “Gravure” for the first addition, “Salle Sud” to check that one workshop can receive two venues, and “Poterie” as a control outside the pair. If you need a preexisting link to preserve, establish “Salle Nord → Poterie” and verify its reverse link before testing Gravure. Give recognizable names and record IDs. In multisite or with translations, specify which site, language, and objects you are testing.

Record both fields and the active definition

With the account maintaining definitions, open ACF > Field Groups. On each side, record the group, field type, technical name, field key, and location rule. Labels such as “Related venues” and “Related workshops” help editors, while keys distinguish two fields with the same label. Check which group actually appears on each entry. If Local JSON or a PHP file is authoritative, also record its version. Prepare the test with that definition's maintainer so the same setting remains loaded after the editor reloads.

For the example, choose two top-level Relationship fields. The venue field accepts Workshops and the workshop field accepts Venues. Both store multiple selections if the organization allows several links. In field settings, record allowed types and other filters governing the choice list. A workshop excluded by a filter before selection presents a different problem from a selected workshop whose entry receives no reverse value.

Before testing, save relevant settings and reference-entry values in a dated record. Draw each link as “Salle Nord → Gravure” and add the expected reverse value. If a relationship already exists with another entry, keep it as a counterexample. This control will tell you whether the test simply added a link or replaced the complete list. Read values that should remain empty in the same way.

Approach 1. Configure targets in one or both directions

In the group displayed on Venues, open the Relationship field selecting Workshops. In the Advanced tab, enable the bidirectional setting and choose as its target the field selecting Venues on Workshops. Save the definition through your site's maintained workflow. This configuration tells ACF where to write the ID of the Venue being saved on the selected Workshop. This configuration alone does not automatically configure propagation in the opposite direction when editing the Workshop field.

If editors must work from either entry, open the field in the Workshops group, enable its bidirectional setting too, and select the Venues Relationship field as target. Check both selections after reloading the groups. If the same field is actually used on entries of one type, the option targeting that field itself permits a reciprocal relationship within that type. Use it only when each side represents the same role, such as two related resources. Two distinct roles may call for two fields even if entries share a content type.

ACF updates the specified target fields for that save. Propagation from A to B does not trigger a chain updating C through B. If you use several targets, check each one's purpose and test every destination separately. Start with one pair. An old function maintaining the same values may continue acting in parallel. Identify it before enabling the native setting and have replacement tested on the copy. Compare additions and removals, because a duplicate or excessive deletion may remain invisible during only the first addition.

Check type, limits, and write permissions

The native feature applies to Relationship, Post Object, User, and Taxonomy fields. The target field must be top-level and its value type must match the object whose ID will be written. For example, a field on a user profile may target a User field on a post because the propagated value identifies a user. A Post Object field expects a post ID. Screens that do not provide a post, term, or user identity, such as an options page, require another design. Moving the field to obtain the option changes data organization and deserves a separate test.

Also check cardinality. If two venues can choose the same workshop, the inverse field must represent two venues. ACF documents that bidirectional updating may save multiple values even when the target field presents a limit or single-value setting. In the latter case, formatting may return only one value. Therefore test two concurrent links and compare the raw value with what the screen and template can show. To enforce a genuinely unique relationship, have that rule applied during authorized changes in both directions and also test replacing an existing link.

In recent versions, ACF checks certain target-update permissions during interface saves. The version 6.8.11 changelog states, among other things, that adding a reference to a target post requires the account to be able to edit that post. Test with the role performing actual input after an initial administrator test. A script-triggered save may run in a different trust context. Keep the same accounts and flow to reproduce a permissions problem. Preserve access checks when the relationship connects entries belonging to different owners or teams.

Add and remove from each side

Open Salle Nord, select Gravure, and save. Reopen Salle Nord and Gravure from their lists. Check that Gravure appears in Salle Nord and Salle Nord appears in Gravure. Also reopen Poterie. If it was linked to Salle Nord before testing, the link must remain on both sides. If both directions are configured and the workshop accepts multiple venues, open Gravure, add Salle Sud, and save. After reloading, Salle Sud should point to Gravure and Gravure should still contain Salle Nord. If editing is restricted to the Venue side, make this second addition in Salle Sud and only observe the result on the Workshop side.

From Salle Nord, remove only Gravure. After reloading both entries, this pair should be gone while the Salle Nord–Poterie and Salle Sud–Gravure links, if included in the test, remain. Recreate the pair on the copy and try removal from Gravure if both directions are enabled. For each save, record the changed field, account used, and expected IDs. Check both values after reopening entries from their lists.

If the reverse update fails in only one direction, first reread the target of the field where you acted and check the save context. If failure concerns only certain entries, compare their types, status, location, and account permissions. Repeat the check on a simple control before considering reconciliation of the entire collection. If the field stores the correct result but a component displays it in an unexpected order, establish separately what defines the display order and whether it has business significance.

Approach 2. Compare raw values with WP-CLI

A maintainer who already has WP-CLI can read both fields on a copy. The third parameter of get_field() disables value formatting. Save the fragment outside the public tree, for example in /srv/diagnostics/relation-temoin.php. In each $temoins row, replace the ID with that of the entry carrying the field and the dummy key with that field's key. Check that WP-CLI points to the copy, then run wp --path=/srv/recette/wordpress --url=https://recette.example eval-file /srv/diagnostics/relation-temoin.php, replacing the path and URL. In multisite, the URL selects the subsite. The fragment contains no write instruction.

Keep a record before addition, after addition, and after removal. Depending on the saved value, an array may contain IDs as numeric strings. The raw result does not necessarily match what a template reads when requesting full objects or applying display restrictions. An empty or Boolean value requires checking the key and loaded field definition before concluding. The fragment reads data in WP-CLI's technical context. Testing with the editor remains necessary to observe what that account can see and save.

<?php
if (!defined('WP_CLI') || !WP_CLI) {
    return;
}

if (!function_exists('get_field')) {
    WP_CLI::error('ACF est indisponible sur le site ciblé.');
}

$temoins = [
    [314, 'field_EXEMPLE_ATELIERS'],
    [427, 'field_EXEMPLE_LIEUX'],
];

foreach ($temoins as [$id, $cle]) {
    $valeur = get_field($cle, $id, false);
    WP_CLI::line(sprintf('%d | %s | %s', $id, $cle, wp_json_encode($valeur)));
}

Approach 3. Reconcile historical relationships through validated pairs

Enabling the setting changes save behavior. Handle entries linked before the change separately. Create a record of links present on each side. Separate consistent pairs, links populated on only one side, and discrepancies whose intended direction still needs confirmation. If the Workshop entry retains a link no longer present on the Venue entry, ask which side represents the desired state. Automatically merging both lists could reintroduce a deliberately removed link.

On a copy, choose a small batch of approved pairs. For a pair present on only one side, save from the entry where the link is already populated, then reread both sides. In ACF 6.8.11 code, selected references are reconsidered during saving, including those already present. If the inverse value remains absent, confirm that the source field actually passed through ACF saving and the account can write to the target. If your version requires a selection change, test removal and re-addition on an approved staging pair, checking neighboring links after each save.

Avoid bulk resaving entries. If automation is necessary, give the maintainer the explicit pair list, starting values, and expected differences before any write. Creation through the ACF API must use the field key when the entry does not yet hold a value. Programmatic writes run in a different context from editorial input. Have their permissions and effects checked separately.

For a relationship confirmed in both screens, next open each entry's expected rendering. The public list may come from a template applying other filters or a cached version. Compare results on the same site, in the same language, and with the same visitor type. If the template displays private-entry or draft titles, have its display rules checked before reusing the list elsewhere.

Check both entries and return to a known state

Consider the test conclusive after verifying addition, removal, neighboring links, and an out-of-scope entry. If both directions are allowed, require the same checks from each screen. Repeat at least once with the usual role and an entry whose field allows multiple values. Check the result in administration after reloading, then in both expected public views. If targets are not intended to be public, check with accounts that can actually view them.

For rollback, distinguish field definitions from values already saved. First restore the previous settings or authoritative file version to suspend the added propagation. Disabling the bidirectional setting does not remove relationships written during testing. Then compare the starting record with the list of actual changes. On the copy, restore values only for affected pairs, accounting for approved changes made since. Check neighboring relationships after each correction. If an old filter still runs, the maintainer must account for its effect during restoration.

In the handoff, keep both fields' names and keys, affected types, active groups, permitted direction or directions, and ACF version used. Add control results and specify the selected historical-reconciliation method. Finally remove the technical fragment from the copy according to your procedure. The team can then reproduce an addition or removal without guessing which screen controls the relationship.

A target checklist before the first save

For the pair proposed in this guide, record the following settings in both groups. Use your installation's actual keys instead of the examples.

| Screen carrying the field | Selected field | Expected bidirectional target | | --- | --- | --- | | Venue | Related workshops | The Related venues field on the Workshop | | Workshop | Related venues | The Related workshops field on the Venue, if editing is permitted in both directions |

The content type allowed in the choice list and the target field are two different settings. Filtering the list to “Workshop” does not alone identify the field that should receive the venue. Reopen the Advanced tab after saving to confirm the selected target.

If the check works with the administrator but not the editor, compare the editor's ability to edit the target entry. Do not correct the symptom by removing all permission checks. The native setting documented since ACF 6.2 avoids a legacy custom filter for supported types; however, check the edition and version actually installed before replacing a historical mechanism. Success must cover addition and removal while preserving a second link. Disabling propagation stops future changes but does not undo relationships already saved.