How do I avoid duplicate records when I import the same CSV again?

What is a useful business key?

A key represents the business operation rather than its position in a file. For customer creation, an email address may work if the destination treats it as unique. For invoice creation, prefer an external invoice reference. For a monthly report, include the account and period so October and November are different operations.

Row numbers, timestamps generated at each run and CSV filenames change when you reorder or re-export data. They cannot reliably identify the same operation. Choose and normalize identifiers before the batch starts, preserving any leading zeros that carry meaning.

How do I separate accounts and destinations?

Deduplication uses the workflow name, items.scope and business key. Set scope from the destination, account and operation. A back-office URL alone is insufficient if two accounts use that same URL. The input filename must not be the scope.

"items": {
  "from": "{{param.input}}",
  "key": "{{item.InvoiceReference}}",
  "scope": "{{param.base}}|{{param.account}}|create-invoice"
}

This fragment illustrates an invoice workflow; its parameters and destination checks must also be defined. An empty scope shares keys across the workflow’s scopes and can make legitimate rows skip in another account. Treat the empty-scope warning as something to fix before a real batch.

What about the row created while I recorded the task?

That record already exists before replay begins. After saving the workflow, use run_adopt with the exact full input row and an evidence note. Adoption runs the confirmation steps and journals the submitted row so a later batch can skip it. Do not send the demonstration row again while adoption or its outcome remains unresolved.

For an API or MCP demonstration, plan a fresh read to verify the existing record. The original write response cannot serve as an independent recheck. The 0.2.0 Git candidate requires a destination lookup or actual verification after the skipped commit; npm 0.1.1 does not include that new adoption guard.

Test the procedure on a small authorized batch. Check the business key, scope, irreversible commit and row-specific expect before processing the rest.

What happens when I rerun or change the file?

• A confirmed key with the same row data is normally skipped.
• Different data under a completed key is blocked; the create procedure does not silently become an update.
• Duplicate keys inside one input file are rejected before processing.
• An uncertain key remains held, including during an explicit repeat.

repeat: true, or CLI --repeat, intentionally reruns completed items. Use it only when a repeated effect is intended. Changing workflow names or deleting the journal can also remove the context that prevented a repeat.

For a remote HTTP API that documents idempotency-key support, Ritoko can send a stable Idempotency-Key. The header helps only when the receiving service honors its contract. Independent imports, manual entry and another installation remain outside this journal. See the workflow contract.