Org Loom
Canvas Docs Pricing

Walkthrough

Import CSV records onto the canvas

Turn rows from one or more CSV files into records you can review, edit, and connect on the canvas. The import can create new drafts, stage changes to existing Salesforce records, and build relationships between rows in different files.

Before you begin

Each CSV needs a unique, nonblank header row. You will choose one Salesforce object for each file, then decide which columns contain Salesforce field values and which columns are reference keys used only to connect rows.

A row without a Salesforce ID becomes a draft, which is a new record that exists only on the canvas until you upload it. A row whose ID matches a record in the connected org can load that record and stage the CSV values as edits.

  • Connect the Salesforce org that contains any existing records.
  • Make sure the files are in CSV format and no larger than 50 MB each.
  • Give related files distinct names so they are easy to identify in Relationships.
  • Decide whether the import should add to the current canvas or replace it.
  • In a Team workspace, ask a workspace admin for the Upload to Salesforce permission if you will upload the staged rows.

This flow does not write to Salesforce. It stages the rows on the canvas. Use Upload to Salesforce later when you are ready. For very large jobs that do not need a canvas review, use Salesforce Data Loader.

The process

  1. Open Import from CSV and add one or more files.
  2. Choose an object and map Salesforce field columns under Columns.
  3. Map Salesforce IDs or choose external-ID upsert when applicable.
  4. Designate reference-only columns and complete their Relationships.
  5. Add the records to the current canvas or replace the canvas.
  6. Review the resulting cards, then upload when ready.

Step 1: Add the CSV files

Open + Add records → Import from CSV. Drag files into the drop area or select the area to choose them from your device. Add related files together so Org Loom can build the links between their rows in one import.

Import from CSV with a drop area and Add to canvas and Replace canvas actions

Org Loom lists every accepted file separately. If a file is empty, unreadable, or not a CSV, the modal explains the problem and stays open so you can remove or replace that file.

Step 2: Choose the object and map columns

For each file, choose the Salesforce object represented by its rows. Org Loom may suggest an object from the filename, but you should confirm it before continuing.

Open Columns to review the mapping. The section starts closed so you can scan several files without a long list of fields. Headers that match a field label or API name may map automatically. A reference-style header ending in Key may also be suggested as a relationship column when Org Loom finds a confident match; always review the suggestion.

Each CSV column has three possible treatments:

  • Choose a Salesforce field when the CSV values should be stored in that field. A Salesforce field can receive values from only one column in the same file.
  • Choose Match to a related record in another CSV - not uploaded when the column is only a key for connecting records. You will finish that mapping under Relationships.
  • Choose Skip when the column should not be imported or used.

Lookup fields and relationship keys are different. A column mapped directly to a Salesforce lookup such as AccountId must contain blank values or 15- or 18-character Salesforce IDs. To connect by an account name, email, seed key, or another value, put that value in a separate CSV column such as AccountNameKey and mark it as a relationship column.

  • Map at least one Salesforce field in each file you want to import.
  • Salesforce-managed fields are not available as normal write targets.
  • If a mapped field is not writable for your Salesforce user, Org Loom warns you before the import and identifies values that will be left out.

Step 3: Choose how existing records are handled

To stage updates to records already in the connected org, map the CSV ID column to Salesforce ID (Id). Org Loom checks those IDs automatically; there is no separate “match and update” import mode.

  • A valid ID loads the current Salesforce record. CSV values are layered on top, and only values that differ are staged as edits.
  • A blank ID in the same file creates a new draft.
  • If an ID cannot be found in this org, Org Loom asks whether that row should become a new draft or be skipped. It is never silently inserted with the unresolved ID.
A checklist for CSV rows whose Salesforce IDs were not found, with options to import selected rows as drafts or cancel

If the file maps an eligible Salesforce External ID field, the Operation control appears and offers Insert new records or Upsert by external id. Upsert is not a general CSV import choice: it is available only after an eligible External ID field is mapped. Choose the key Salesforce should use when you later upload.

Step 4: Build relationships between CSV rows

Use a virtual relationship when a CSV has a name, email, seed key, or other stable value instead of the related record’s Salesforce ID. The key column helps Org Loom find another imported row; the key itself is not written to Salesforce.

For example, suppose you import these columns together:

  • Contact.csv.AccountNameKey contains the account name for each contact.
  • Account.csv.Name contains the unique account name for each account row.
  1. Under Contact.csv → Columns, set AccountNameKey to Match to a related record in another CSV - not uploaded.
  2. Open the relationship card headed Contact.csv.AccountNameKey. The header identifies the reference column being handled.
  3. Under Match against, choose Account.csv.Name. You can make this choice before choosing the lookup to populate.
  4. Under Populate, choose Account (Contact.AccountId). If Contact has more than one lookup to Account, use this control to choose the intended field.
  5. Confirm the compact status reports that every relationship value matched.

The completed rule reads left to right:
Contact.csv.AccountNameKey
Match against: Account.csv.Name → Populate: Account (Contact.AccountId)

The same approach supports hierarchies within one file. For example, Account.csv.ParentAccountNameKey can match against Account.csv.Name and populate Parent Account (Account.ParentId).

Relationship matching rules

  • Every nonblank relationship key must match exactly one target row. A missing match or duplicate target key makes the result uncertain, so Org Loom blocks the import instead of guessing.
  • A blank relationship key leaves that lookup unset for that row.
  • Only one virtual relationship column in a source file can populate the same Salesforce lookup.
  • You may mix existing Salesforce IDs and virtual keys for the same lookup across different rows. Map the real lookup ID column directly and configure the separate relationship-key column to populate that lookup.
  • Within one row, provide either the direct Salesforce ID or the virtual key for a lookup, not both. If both are present, edit the CSV so one is blank, then re-import.

If an imported virtual relationship would overwrite a lookup that is already connected on an existing canvas card, Org Loom preserves the current connection and reports that the link was skipped. Change the connection on the canvas if you intend to replace it.

Step 5: Add or replace the canvas

Choose Add to canvas to keep the current records and place the imported records alongside them. Choose Replace canvas to start a new unsaved canvas from the import. Org Loom confirms before replacing existing work.

Account and Contact draft cards on the canvas with their imported relationships connected

If a CSV ID matches a card already on the canvas, Org Loom does not create a duplicate. When the imported values differ, it opens Review imported changes so you can choose which values to copy onto the existing card. Closing that review without applying anything leaves the card unchanged.

Step 6: Review and upload

Inspect the imported cards before uploading. You can edit values, remove unwanted drafts, and add or correct relationships. Imported existing records show as modified only when the CSV staged a real change.

When the canvas is ready, choose Upload to Salesforce and review the preflight. Drafts will be created, modified existing records will be updated, and unchanged existing records will be skipped.

Import safety and limits

  • The canvas holds up to 500 records. An import that would exceed that limit is refused before any records are added or replaced.
  • Incomplete or uncertain relationship mappings block the import; Org Loom does not silently choose a target or import an unresolved link.
  • After a successful import, the confirmation toast briefly offers Undo. Undo restores the records, relationships, and object selection from before the import.
  • If you edit affected records after the import, the older Undo is refused instead of overwriting your newer work.
  • Canceling before the final import leaves the canvas unchanged.

See also