Upload a CSV file

An admin can load records into a source from a CSV file, with no code. Use it to load a system’s existing records before you connect it to the API, or to keep a system up to date by hand when nobody can connect it: export a complete list from time to time and upload it. The file goes through the same checks and the same matching as records sent to the API.

Prepare the file

• One row for each record, and a header row with the column names.
• Comma-separated or semicolon-separated: Samesake works out which.
• Saved as UTF-8, up to 50 MB. In Excel, choose CSV UTF-8 when you save. A file in another encoding fails with a message that says so. For more than 50 MB, split the file or send batches through the API.
• A column that holds your ID for each record, such as a customer ID. It’s the only column you have to have, and a row without an ID can’t be imported.

Samesake recognises the usual column names, including the column names in a Salesforce export, and suggests which column holds what. A file like this needs no changes:

Customer ID,Title,First Name,Last Name,Email,Date of Birth,Address Line 1,Address Line 2,Postcode,Mobile,Telephone
CRM-20001,Ms,Amara,Okafor,amara.okafor@example.com,1991-07-19,2 Birch Road,Salford,M5 3AB,07700 900211,0161 496 0211
CRM-20002,Mr,Daniel,Whitfield,daniel.whitfield@example.com,04/11/1975,51 Mill Lane,Bolton,BL1 4QT,07700 900212,
CRM-20003,Dr,Hannah,Price,hannah.price@example.com,,9 Orchard Close,Oldham,OL4 2JN,,0161 496 0213

The fields are the same as the API’s. Send a record lists what each accepts, including the date, phone number and postcode formats. A few things to check in an export:

• Dates are read day first. A file that writes 04/03/1986 for 3 April, month first, is read as 4 March, and 03/25/1986 isn’t read at all. Four-digit years and yyyy-mm-dd are safest.
• Phone numbers that a spreadsheet has stripped of the leading zero, such as 7700900211, are still read as UK numbers.
• A field can be empty. An empty field clears that detail on the record, as it does in the API.

Upload it

1. Sign in at app.samesake.co.uk as an admin and open Admin, then Sources.
2. On the source’s row, choose Upload CSV.
3. Choose a file. Samesake reads the header row.
4. Match the columns. Each detail has a menu of the file’s columns, already set to Samesake’s suggestion. Check them, and choose the column that holds the source record ID. You can map up to three columns to Phone. Samesake remembers your choices for this source, and uses them next time if the new file has the same columns.
5. Check the preview. It shows the first five rows as Samesake will read them, and says what’s wrong with any row it would skip.
6. Choose what the file means (below), then choose Import.

The file imports in the background, so you can leave the page and come back: the progress is there. A file is imported 1,000 rows at a time. Only one import runs for a source at a time, so a second upload has to wait for the first.

What the file means

Choice	What happens
Add and update these records	The default. Each row creates or updates a record. Nothing is ever deleted.
This file is the complete list	As above, and then every record of the source that isn’t in the file is deleted. It works like a snapshot.

Choose the complete list only if the file really holds every record the source should have. If it would delete more than 10% of the source’s records, the import stops before deleting anything, and waits for an admin: see A held import.

Read the result

The progress panel counts:

Count	Meaning
Rows read	Every line after the header, blank lines included, so it can be more than the other four added together.
Created	New records.
Updated	Records whose details changed.
Unchanged	Records that already had these details.
Skipped	Rows that couldn’t be imported.

The status is Waiting to start, Importing, Completed, Waiting for approval, Deletions not applied or Failed. Recent imports lists the last ten for the source.

Skipped rows

A row that can’t be imported is skipped, and the import carries on with the rest. The page lists each skipped row with its row number, counting the header as row 1, and the reason. It lists the first 100, and says how many more there were.

A row is skipped when:

• its source record ID is empty (the reason is “sourceRecordId is required.”), or
• a value breaks a limit: an ID of more than 100 characters, or any other field of more than 200. The reason is the same as the API’s, such as “email must be at most 200 characters.”

Fix those rows in your file, and upload it again. It’s safe to upload the same file twice: rows that haven’t changed are counted as unchanged.

Rows made up of nothing but separators, which Excel adds below the data, aren’t records, so they aren’t skipped or reported.

A held import

With complete list, a row that was skipped for a reason other than an empty ID doesn’t cause a deletion: its record counts as present, because the file did name it.

If the file would delete more than 10% of the source’s records, nothing is deleted and the status is Waiting for approval. An admin decides on Admin, then Matching, under Held snapshots: Delete the records, or Discard snapshot. If it’s discarded, the rows in the file were still imported, and only the deletions are skipped (the status is Deletions not applied).

If any row had no ID, Samesake can’t tell which record it was meant to keep, so any deletion at all, however few, waits for an admin.

A newer complete list for the source, from a file or from the API, replaces a held one, so an old decision can’t delete records that the newer list contains.

If an import fails

The page says why. The usual reasons:

• The file isn’t valid UTF-8. Save it again as UTF-8 (in Excel, CSV UTF-8) and upload it again.
• A column that you mapped isn’t in the file. Choose the columns again.
• The import stopped without finishing. Upload the file again.

Nothing from a failed import is lost or doubled: the rows that were saved stay saved, and uploading again leaves them unchanged.

What happens to the file

The file is deleted as soon as it’s imported. Anything left behind, such as a file you chose and never imported, is deleted within two days.