DataLoader

<caos-data-loader>

compose a bulk insert, upsert, update or delete, map the columns, and read the per-row result

May be placed on a page inside an app.

Inputs

Name	Attribute	Description	Type	Default	Required
action	action, markup only	What the load does. upsert reveals the external-identifier choice; delete replaces the mapping section entirely, because a delete is driven by ids and an unused mapping section invites somebody to wonder what they got wrong.	text — one of insert, upsert, update, delete	insert	Optional
sizing	sizing, markup only	The bulk path or the synchronous one.	text — one of batch, standard	batch	Optional
object	object, markup only	Which object is being loaded onto. Changing it RE-PROPOSES the mapping — a different object has different fields, and keeping the old proposals would carry a mapping nobody chose.	objectRef	none declared	Optional
externalId	external-id, markup only	Which field identifies an existing record, for an upsert. Its options come from externalIds, which is empty until an object is chosen — and that emptiness is SHOWN.	fieldRef	none declared	Optional
objects	property only	The objects that can be loaded onto.	json	empty list	Optional
columns	property only	The file’s columns, in file order. Setting them re-proposes the mapping.	json	empty list	Optional
fields	property only	The fields of the chosen object, which the columns map onto.	json	empty list	Optional
externalIds	property only	The fields that can serve as an external identifier. EMPTY until an object is chosen, which the control says rather than hides.	json	empty list	Optional
mapping	property only	Column → field. A column mapped to the empty string is deliberately NOT loaded, which is a real answer with its own words in the control rather than a blank option.	json	none declared	Optional
results	property only	What each row did: { row, ok, id?, error? }[]. row is the row’s number IN THE FILE — the only thing connecting an error back to the file on somebody’s disk.	json	empty list	Optional
running	running, markup only	A load is in flight.	boolean	false	Optional
startLabel	start-label, markup only	What the start control is called.	text	Start load	Optional

Events

Name	When it fires	What it carries
caos-load-start	The start control is pressed, with the load described completely enough.	{ action, sizing, object, externalId?, mapping } — the mapping holds ONLY the columns going somewhere, so the caller does not re-apply a decision already recorded.
caos-load-change	Action, object or sizing changes.	{ action, sizing, object }.
caos-load-mapping	One column’s field changes.	{ column, field, mapping }.

Slots

Not documented yet — this piece has not said.

Styling hooks

Not documented yet — this piece has not said.

Methods

Not documented yet — this piece has not said.

Readable state

Name	Type	What it tells you
ready	boolean	Whether the load is described completely enough to ask for: an object, some columns, an external identifier for an upsert, and — for anything but a delete — at least one column actually going somewhere.
mapping	{ [column]: string }	The current mapping, skips included.
failures	CaosLoaderRowResult[]	The rows that failed, keeping their file row numbers.

Styling parts

Part	Which piece of it	When it is there
::part(loader)	The outer column.	Always
::part(settings)	The action / object / sizing row.	Always
::part(field)	One setting and its label.	Always
::part(mapping)	The column-to-field section.	Always
::part(mapping-row)	One column’s mapping row.	The action is not delete and there are columns.
::part(summary)	The mapped-column count, or the per-row outcome counts.	Always
::part(start)	The start control.	Always
::part(results)	The per-row result table.	Results have been supplied.

When to use it

When records are being written in bulk from a file and somebody has to describe the load first.

What to use instead

• FileField — a file is being attached to a record rather than loaded as records.
• ResultGrid — the rows are being READ rather than written — the loader’s own result table is about outcomes.

Accessibility

Every setting and every mapping control carries its own accessible name — “Field for the column Account Name” — so a screen of dropdowns is navigable rather than a row of unlabelled boxes. The waiting external-identifier control keeps full contrast and states what it is waiting for in its own prompt, so “not yet” and “not for you” are never confused. The summary is a role="status" live region. A skipped column says “Do not load this column” in words rather than being represented by a blank option.

Examples

An upsert waiting for its object

The dependent choice: the external-identifier control is present and empty, with its prompt saying what it is waiting for — not hidden, and not disabled.

{
  "id": "example",
  "section": "An upsert waiting for its object",
  "columns": 1,
  "items": [
    {
      "id": "data_loader_1",
      "type": "component",
      "key": "data_loader",
      "inputs": {
        "action": "upsert",
        "objects": [
          "Account",
          "Contact",
          "Invoice__c"
        ],
        "columns": [
          "Account Name",
          "Industry",
          "Legacy Code",
          "Notes"
        ]
      }
    }
  ]
}

<caos-data-loader id="dataLoader1" action="upsert"></caos-data-loader>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const dataLoader1 = document.getElementById('dataLoader1');
dataLoader1.objects = [
  "Account",
  "Contact",
  "Invoice__c"
];
dataLoader1.columns = [
  "Account Name",
  "Industry",
  "Legacy Code",
  "Notes"
];

A mapping proposed and corrected

Three columns matched by name, one with no confident match proposed as “do not load” rather than guessed at — a wrong mapping nobody notices becomes their data.

{
  "id": "example",
  "section": "A mapping proposed and corrected",
  "columns": 1,
  "items": [
    {
      "id": "data_loader_1",
      "type": "component",
      "key": "data_loader",
      "inputs": {
        "action": "insert",
        "object": "Account",
        "objects": [
          "Account",
          "Contact"
        ],
        "fields": [
          "Name",
          "Industry",
          "AnnualRevenue",
          "Website"
        ],
        "columns": [
          "Name",
          "Industry",
          "Annual Revenue",
          "Internal Ref"
        ]
      }
    }
  ]
}

<caos-data-loader id="dataLoader1" action="insert" object="Account"></caos-data-loader>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const dataLoader1 = document.getElementById('dataLoader1');
dataLoader1.objects = [
  "Account",
  "Contact"
];
dataLoader1.fields = [
  "Name",
  "Industry",
  "AnnualRevenue",
  "Website"
];
dataLoader1.columns = [
  "Name",
  "Industry",
  "Annual Revenue",
  "Internal Ref"
];

What each row did

Failures first, each keeping its own row number — “row 412 failed” is what connects an error back to the file on somebody’s disk.

{
  "id": "example",
  "section": "What each row did",
  "columns": 1,
  "items": [
    {
      "id": "data_loader_1",
      "type": "component",
      "key": "data_loader",
      "inputs": {
        "action": "insert",
        "object": "Account",
        "objects": [
          "Account"
        ],
        "fields": [
          "Name"
        ],
        "columns": [
          "Name"
        ],
        "results": [
          {
            "row": 1,
            "ok": true,
            "id": "001x0001"
          },
          {
            "row": 2,
            "ok": true,
            "id": "001x0002"
          },
          {
            "row": 412,
            "ok": false,
            "error": "Required field missing: Industry"
          },
          {
            "row": 998,
            "ok": false,
            "error": "Duplicate value on a unique field"
          }
        ]
      }
    }
  ]
}

<caos-data-loader id="dataLoader1" action="insert" object="Account"></caos-data-loader>

// What an attribute cannot hold, set as a property — the same values the preview is drawn with.
const dataLoader1 = document.getElementById('dataLoader1');
dataLoader1.objects = [
  "Account"
];
dataLoader1.fields = [
  "Name"
];
dataLoader1.columns = [
  "Name"
];
dataLoader1.results = [
  {
    "row": 1,
    "ok": true,
    "id": "001x0001"
  },
  {
    "row": 2,
    "ok": true,
    "id": "001x0002"
  },
  {
    "row": 412,
    "ok": false,
    "error": "Required field missing: Industry"
  },
  {
    "row": 998,
    "ok": false,
    "error": "Duplicate value on a unique field"
  }
];