Importing and Syncing Records

When records come from another system — a recreation booking system, an agenda manager, a property feed, a spreadsheet export — send them through the upsert: it creates each record the first time and updates the same record every time after. Each record is identified by the system it came from and that system’s own ID, so sending the same data again never makes a duplicate.

When to use it

A one-off import that an AI assistant runs through the connector (postruntime_upsert_post, one record per call).
A scheduled sync from a system with an API, using FlowMint Workflows’ Post Runtime: Upsert Records step.
For records you create by hand, use the WordPress admin or postruntime_create_post instead.

There is no CSV upload screen. To import a spreadsheet, ask an assistant to read it and upsert each row through the connector.

How matching works

A record’s identity is three things:

the record type (post_type),
source — a short key you choose for the other system, such as recdesk or civicclerk (lowercase letters, numbers and underscores),
external_id — that system’s ID for the record. Numbers are stored as text.

The first upsert with a given identity creates the record (published, unless you send a status). Every later upsert with the same identity updates that record.

What an update changes

Only the keys you send are written. title is required every time; content, excerpt, status, fields, taxonomies and the featured image change only when present. A field you do not send keeps its value, so edits made on the site to other fields survive the next sync.
Unchanged records are skipped. If everything sent is identical to the last sync, nothing is written — no revision, no new modified date — and the response’s action is unchanged. Otherwise it is created or updated.
fields maps post-field keys to values, with the same rules as the record edit screen. Send dates as described in Events and calendar feeds.
taxonomies maps a taxonomy to term names, slugs or IDs, and replaces that taxonomy’s terms on the record. Missing terms are created; the taxonomy must already be attached to the type.

Images from a feed

Send the feed’s photo address as featured_image_url. The image is downloaded into the media library, set as the featured image, and given the record’s title as alt text. The media library remembers where each image came from, so the same address is downloaded only once however often the feed is synced. An address that cannot be fetched or is not an image is reported in the response’s warnings; the record is still written. When featured_image_id is also sent, it wins.

Scheduled syncs with FlowMint

FlowMint’s Post Runtime: Upsert Records step takes the list a previous step fetched, maps each item onto a record with a template ({{ item.* }} for the current item), and upserts them one by one. It fails the run, rather than quietly emptying the site, when fewer records arrive than expect_min_records or more than max_failure_ratio of them cannot be written. Records the other system stops sending are kept by default, or set to draft with missing_upstream: "draft"; they are never deleted.

Limits and common problems

title is required. Every upsert needs a title, including updates.
A duplicate appeared. The source or external_id differs from the earlier import — for example RecDesk against recdesk is the same after cleaning, but recdesk against rec_desk is not.
A field value is refused. The value breaks that field’s rules, such as a badge value that is not one of its options. On a new record, the record is not created; on an existing one, the other changes are kept.
Seeing what came from where. The connector’s postruntime_list_posts shows each record’s source and external ID.