Field Mapping
Now that you’ve told Feed Me where your data comes from, it’s time to define how individual items in the feed map to new or existing elements in Craft.
While the specifics will vary widely depending on your content model (and the structure of the incoming data), the same pattern applies to most map configuration:
- Find the target field in the Field column;
- Choose a source for that field’s data from the menu in its row’s Feed Element column;
- Customize options for the type of data being imported;
- (Optional) Set a static or dynamic default value;
Native Fields
The native fields you have available to map against depend on the element type you’ve selected as the target for the import—for example, entries support a Title, Slug, Parent, Post Date, Expiry Date, Status, and Author in addition to the custom fields attached via its field layout.
TIP
Native fields have similar options to custom fields, so we’ll only cover the novel ones, in this section.
Element IDs
You can map data in your feed to the element ID, which is useful if you are certain which element you want a given feed item to update. This can be when updating for content in other locales, or bulk-updating existing items.
DANGER
Do not use this when importing “new” data! Content from another system (ExpressionEngine, WordPress, etc.) will not have the same IDs as their corresponding elements in Craft, by virtue of how records are created in the database. If you specify the wrong element ID (deliberately or coincidentally), you run the risk of updating completely unrelated content (i.e. an asset when you meant to update an entry).
There are only two situations in which setting IDs is recommended:
- When re-importing data that was exported from Craft, then modified;
- Importing or synchronizing data from external systems that already track Craft element IDs;
In most cases, incoming data should be matched based on a different unique identifier.
Custom Fields
Like native fields, each custom field type’s configuration options depend on what kind of data it stores.
Scalar Data
Text, numbers, booleans, and other basic data types require no additional configuration. Color, dropdown, email, lightswitch, money, radio, and URL fields all use “scalar” values.
Dates
Feed Me can parse most date formats, but to handle cases where it may be ambiguous (i.e. 01-02-2023), you can lock the mapping to a specific pattern.
Relational Fields
When setting up related content through an assets, categories, entries, tags, or users field, you will be asked how Feed Me should locate the referenced element(s).
For example, if you were importing a list of AKC winners that contained a breed property with values like Dachshund or Greyhound, you might tell Feed Me to look up existing Breed entries by their Title, and to Create entries if they do not exist. The same holds true for other element types and their corresponding relational field types.
Nested Fields
When importing relational data, you have an opportunity to map values onto those elements’ fields, as well. Enable Element fields (x) to expand controls for those nested fields.
WARNING
Keep in mind that nested field values will be applied uniformly to all relations.
Matrix
See the Importing into Matrix guide to learn more about this special field type.
Plugin Fields
Feed Me comes with support for the following plugin-provided field types:
| Field Type | Developer |
|---|---|
| Calendar Events | Solspace |
| Commerce Products | Pixel & Tonic |
| Commerce Variants | Pixel & Tonic |
| Entries Subset | Nathaniel Hammond |
| Google Maps | Double Secret Agency |
| Linkit | Pressed Digital |
| Simplemap | Ether Creative |
| Super Table | Verbb |
| Typed Link | Sebastian Lenz |
TIP
Other fields that store simple text values (like Redactor) will work automatically.
Default Values
When the source for a native or custom field is set to “Use default value,” you may provide a value in the third column that will supersede any default value defined by the field itself. If parseTwig is enabled in your Configuration, textual fields are treated as Twig “object templates,” and have access to other fields on the element you're importing:
{title} was last imported on {{ now | date }}Unique Identifiers
It's important to select a unique identifier for your feed to assist with the Import Strategy you’ve chosen. When comparing against existing entries, it will compare the fields you select here with the data in your feed. In addition to the element’s native fields (like title, slug, status, or ID), you may use custom field values for matching.
WARNING
There are some limitations to the matching engine, though—it will not work for content stored in Matrix and other nested, Matrix-like fields such as Super Table and Neo which can’t be easily or reliably serialized.
DANGER
If data that is used as part of a unique identifier is altered between imports by a user (or any other means—including a different import), Feed Me may not be able to match it again! When combined with the Delete missing elements import strategy, this can result in inadvertent data loss.