---
name: spreadsheet-records-sync
description: Loads an uploaded spreadsheet into a record type of the workspace with the bulk sync tool, previewing the changes before writing. Use for master data imports, periodic refreshes of a table, or migrating a list from Excel into records.
license: Apache-2.0
metadata:
  adlass.categories: "data-tables/export-sync, data-tables/migration"
  adlass.industries: ""
  adlass.tags: "records,spreadsheet,import,sync,upsert,master-data"
  adlass.adaptation: "mapping"
  adlass.source: "original"
  adlass.version: "1"
---

# Sync a spreadsheet into a record type

## Purpose

Bring the rows of an uploaded Excel or CSV file into one record type of the workspace without typing a single record by hand. The run reads the sheet as a table, maps its columns to the field keys of the target type, previews what would change and then writes the rows through the sync tool so that a second run with the same file changes nothing.

## Scope

The work covers one worksheet and one target record type. It handles new rows (created), rows whose key already exists with different values (updated), rows that are identical (left untouched) and, in sync mode, records whose key no longer appears in the sheet (deleted). Column names may differ from the field keys; the query aliases them.

**Excluded:** changing the schema of the record type, linking records to other records or documents, and sheets whose rows have no reliable unique key.

## Data basis

- The uploaded spreadsheet, available through list_tables and describe_table with column names, types and sample rows.
- The target record type in scope, described by describe_record_type with field keys, types, required rules and select options.
- The key field named in the adaptation notes, which must be unique and non-empty in every row.

## Result

Records of the target type that mirror the spreadsheet, plus a short memo with the counters returned by the sync tool (created, updated, deleted, unchanged), the query that was used and every row that could not be loaded with its reason.

## Quality criteria

- The dry run was inspected before any record was written, and its counters match the expectation for the file.
- Every selected column is aliased to an existing field key; the tool rejects unknown columns.
- The key column has no empty and no duplicate values in the query result.
- Rows with conversion errors are listed in the memo instead of being silently skipped or guessed.

## Instructions

Start with list_tables and describe_table to learn the exact table key, the column names and the types the parser detected. Then call describe_record_type for the target type and write a SELECT statement that returns one column per field you want to fill, each aliased to the field key, for example `SELECT codigo AS codigo, nombre AS nombre FROM cuentas`. Trim, cast or filter inside the SQL when the sheet contains header repeats, totals or empty rows. Run sync_records_from_query with dryRun set to true, check the counters and the sample rows, and only then run it for real. Use mode upsert unless the adaptation notes say the sheet is the complete population; then use mode sync so that removed rows disappear from the records as well. Never rewrite a value that the sheet leaves empty; keep the query so that such cells stay NULL. If the tool reports errors, fix the query or report the rows, do not retry blindly.

## Adapt before use

- Put the target record type into the skill scope and name its key field in the skill body.
- State which worksheet and which columns feed which fields when names differ.
- Decide whether the sheet is the complete population (mode sync) or an addition (mode upsert).