Custom Lists

A Custom List is a user-defined, free-form child collection that can live on any entity. It lets you extend the common model to represent a structured relationship the standard model doesn't already declare — without changing the base entity.

Its children are ChildCustomEntity items shaped by a child Data Model that you choose. You name the list, and that name becomes the list's identity on the entity.

Preview

Custom Lists are in Preview and are rolling out across environments. Your Central environment may not run them yet — availability may lag the configuration UI until the full release completes.

Custom Lists vs. declared lists

Most list mappings target a list property the Data Model already declares — an Order's Lines, an Item's Prices. A Custom List is different: you attach it to an entity even though its Data Model does not declare a matching list property. Both are populated the same way (via a Looping List); the only difference is whether the destination is a declared property or a Custom List you named.

What a Custom List is

Aspect	Detail
Where it lives	On any entity — the parent Data Model does not need to declare a matching list property.
What its children are	ChildCustomEntity items, each shaped by a child Data Model you choose.
Its identity	The name you give it. Certifications, Inspections, Compliance Records — the name is how the list is addressed on the entity.
Child sub-type requirement	The child Data Model must have an Entity Sub Type. This is required — the platform raises an error (fails loud) if the child model has no sub type, rather than silently producing untyped children.

The child model must be sub-typed

A Custom List's child Data Model must have an Entity Sub Type set. If it doesn't, the platform raises an error rather than emitting untyped children. Set the child model's sub type before you save the map. See Data Models for defining Entity Sub Types.

When to use one

Reach for a Custom List when the standard model doesn't already declare the child relationship you need, and you don't want to alter the base entity to add it. You get a first-class, keyed child collection that syncs downstream — without a model change rippling through every consumer of that entity.

Some generic scenarios:

Parent entity	Custom List	Child sub-type	Represents
Contact (Person)	Certifications	Certification	Professional certifications a contact holds.
Location	Inspections	Inspection	Inspection records tied to a site.
Product	Compliance Records	Compliance Record	Regulatory / compliance documents for an item.

In each case the base model (Person, Location, Product) never declared the child list — the Custom List adds the relationship on top of it.

How to set one up

1. Define or choose the child Data Model, and set its Entity Sub Type. This is the shape of a single child (e.g. a Certification model with a name/key and any attributes). The sub type is mandatory — see the warning above.

2. Add a Looping List to the map where you want the list populated. Configure it as you would any Looping List (see Action Mapping for adding one to a route).

3. Set the Central List to your Custom List. Instead of picking a declared list property, you name the list here — that name becomes its identity on the entity (Certifications).

4. Choose the Looping Method for how the source turns into children — Loop All, Group by Field, or Split by Separator. See Looping Lists for the depth on each.

5. Wire the child's fields. At minimum, map the child's primary key. Add any other child properties the sub-type carries.

The UI terms you'll be working with:

Term	Meaning
Central List	The destination list — for a Custom List, the name you give it.
Looping Method	How the loop turns the source into children (Loop All / Group by Field / Split by Separator).
Group By Property	The field to group items by, when using Group by Field.
Child sub-type / Entity Sub Type	The mandatory sub type on the child Data Model.

Populating them

The three Looping Methods populate a Custom List exactly the same way they populate a declared list. For the full mechanics of each method — including Group by Field hierarchies and nested Looping Lists — see Looping Lists.

A worked Split by Separator example: a connector hands you a single delimited value and you fan it out to one keyed child each.

Source — a contact record with a delimited custom field:

{
  "id": "contact-1001",
  "firstName": "Jordan",
  "properties": {
    "property_certifications": "CPA;PMP;CFA"
  }
}

Configure a Looping List whose:

• Central List = a Custom List named Certifications
• Looping Method = Split by Separator, separator = ;
• Child sub-type = Certification
• Child primary-key map = the split token

The model then gets a Certifications Custom List with three ChildCustomEntity children, keyed by each token:

{
  "id": "contact-1001",
  "firstName": "Jordan",
  "customLists": {
    "Certifications": [
      { "subType": "Certification", "primaryKey": "CPA" },
      { "subType": "Certification", "primaryKey": "PMP" },
      { "subType": "Certification", "primaryKey": "CFA" }
    ]
  }
}

(Illustrative shape — the exact envelope differs, but the important part is: one delimited value became three keyed children.)

How they behave

Custom List children are stored flat and keyed, and each child's lifecycle is tracked independently:

• Scoped per parent. The same key can exist under multiple parents independently — CPA under contact-1001 is a distinct child from CPA under another contact.
• Own sync lifecycle. Each child syncs downstream with its own create / update / delete operation, based on its key state.
• Re-adding creates a new record. If a child is removed and later re-added, a new active record is created alongside the historical (soft-deleted) one — the platform does not resurrect the old row.

Keys are scoped per parent

Because keys are per parent, you never have to worry about a child key colliding across parents. Each parent owns its own set of keyed children.

Publishing / save side

On a save action, a Custom List does the reverse of a read: it emits its children back out, one output element per child, each carrying its own operation (create / update / delete):

Protocol	Output shape
JSON	An array named by the connector property.
XML	A repeating element.
File (delimited)	One row per child, with parent columns repeated.

Which operations are actually written is governed by the Looping List's Supported Operations, and deletes are never assumed. See Filtering Looping List Items by Operation for the full rules and the _destroy recipe.

See Also

• Looping Lists — The three looping methods (Loop All, Group by Field, Split by Separator) in depth
• Action Mapping — Adding Looping Lists to a route, filters, and delete handling
• Data Models — Defining child models and Entity Sub Types
• Data Adaptation — Transform and adapt values inside a child map
• Code View — View the underlying map-group configuration