Map an arriving JSON record or dataset onto a website post type, the marked fields of a Page Template, or your own target field list—with direct key mappings, text templates, fixed values, and reviewable AI suggestions.
Where: Flowgen → Add → Website → Field Mapper.
Before you start
- Connect a record-producing node to What arrived. A single JSON record and a dataset of rows are both supported.
- Choose what the mapper is filling: a post type, a Page Template, or a custom field list.
- For a post type, connect the relevant Website and choose its collection. For a template, connect a Page Template whose fields have already been found and accepted.
Key ideas
- One target table, three sources of fields: A post type reads the selected website collection schema; a page template reads its accepted marked parts; My own list turns comma-separated names into stable field ids. The mapping table changes to match the selected target.
- Each target chooses one mapping mode: From copies one arriving key, Text evaluates a template such as {{First}} {{Last}}, and Fixed writes the same literal on every row. Leaving a target unmapped leaves it available for downstream automatic name matching instead of overwriting it.
- Page metadata is always available: The reserved targets _title, _slug, _status, and _menu appear in every target mode, so the same mapped row can control page identity, address, draft/published state, and menu inclusion.
- Automatic and AI mapping are different: Map what I can is a free deterministic name-and-type pass. Ask the AI makes one model call and returns suggestions only; no proposed row is applied until you choose Use or Use all.
- Single records and datasets keep their shape: record_out emits one mapped record as JSON text. When a table arrives, rows_out emits one mapped row per input row as a dataset, preserving row order for List Iterator or another data step.
Steps
- Add Field Mapper from Add → Website and connect the producer to What arrived. The card reports whether it received one record or a dataset and lists the discovered keys.
- Under Filling in, choose A post type, A page template, or My own list.
- For A post type, connect a Website to Website and select the collection. For A page template, connect Page Template to Page template. For My own list, enter comma-separated target names such as Title, Body, Cover image.
- Review the target rows. Use From to choose one source key, Text to combine values with placeholders such as {{First}} {{Last}}, or Fixed for a value shared by every row.
- Map _title and _slug when the destination needs explicit page identity. Set _status to draft or published and _menu when those values should travel with the record.
- Choose Map what I can for a deterministic first pass. Review every filled row and correct any match that is technically similar but semantically wrong.
- When the names are ambiguous, choose Ask the AI. Inspect confidence and the proposed source/template on each row, then choose Use for individual suggestions, Use all, or Discard.
- Run the node. Connect record_out to a single-record consumer such as a post socket, Save a Page, or Page Template; connect rows_out when the downstream step expects a dataset.
- For repeated publishing, feed rows_out into a supported List Iterator workflow. Do not create a deprecated Group Repeater or legacy Batch frame.
- After changing an upstream schema, template fields, or custom target list, revisit the table before running so mappings do not point to removed keys or fields.
Inputs and outputs
- What arrived (record_in): one JSON object, text that resolves to a record, or a dataset of rows.
- Website (doc_in): supplies website identity and post-type schemas for the post-type lane.
- Page template (template_in): supplies accepted template field ids for the template lane.
- The record (record_out): the last mapped record serialized as JSON text.
- Every row (rows_out): a typed dataset containing every mapped input row.
How mapping rows are represented
- From stores a quoted path such as ["Headline"], which safely addresses source keys containing spaces.
- Text stores a template such as {{first}} {{last}} and can combine multiple arriving keys.
- Fixed stores a literal value and repeats it for every mapped row.
- A target row uses exactly one of From, Text, or Fixed. Selecting the active mode again clears that mapping.
- Missing source values use skip behavior so an absent key does not write null over a value another downstream rule can still supply.
Custom targets
- Type target names as one comma-separated line. Flowgen lowercases each name and joins word runs with underscores to create its id.
- Duplicate ids collapse to the first field. Empty names are ignored.
- Names that suggest image or date content receive an image/date hint; all other custom targets default to text.
MCP and Flowgen AI
Create a mapper node, set mapperTargetSource and mapperMappings with set_props, and use propose_mapping when a model should suggest pairs. propose_mapping never applies its answer automatically: review the returned pairs and write only the approved mappings. New repeated work uses create_list_iteration and run_list_iteration, not Group Repeater or legacy Batch tools.
Tips
- Prefer the free automatic pass when names are already close; reserve AI proposals for ambiguous schemas.
- Use explicit _slug mappings when source titles can change, so published addresses remain stable.
- Name custom targets the way the destination names them. That makes the mapping reusable if you later replace the custom lane with a real post type.
Limitations and important notes
- Ask the AI requires both a resolved target field list and discovered source keys; it will report what is missing rather than invent a schema.
- AI results are suggestions, not applied configuration, until accepted on the card or explicitly written by an MCP host.
- Changing the connected post type or template can invalidate mappings to fields that no longer exist; review before the next run.
- Field Mapper reshapes records. It does not publish pages by itself and does not replace the supported List Iterator for repeated execution.
Troubleshooting
The mapping table is empty.
Choose a Filling in mode and provide its target: bind a website collection, connect a parsed Page Template, or type a custom field list.
Map what I can and Ask the AI are disabled.
Connect a record or dataset so source keys are discovered, and make sure the selected target lane resolves to at least one field.
A Page Template is connected but no fields appear.
Run Find the fields on the Page Template and accept its proposed marked parts first.
An AI suggestion did not change the mapping.
Suggestions are review-only. Choose Use on that row, Use all, or write the approved mapperMappings explicitly.
Only one result appears after mapping a dataset.
Use Every row (rows_out) rather than The record (record_out), then connect it to a dataset-aware node or a List Iterator.
FAQ
Does Field Mapper cost Sparks?
Map what I can is deterministic and does not use a model. Ask the AI performs one model round and may use Sparks according to the selected/default model.
Can it combine two source columns?
Yes. Use Text and reference both keys in one template, for example {{first}} {{last}}.
Should I put the mapper inside a Group Repeater?
No. Group Repeater is deprecated. Map the dataset, then use a source Items List and Results List through List Iterator for repeated downstream work.