# summary

Restore or migrate profiling definitions into a Salesforce org from portable CSV files, with simulation to validate the result before any records are written.

# description

Profiling definitions capture the scoping decisions that tell Cuneiform what to analyze. When those decisions need to move between environments — sandbox to production, old scratch org to new, or restored after a refresh — this command imports them from CSV files produced by `definition export`.

The command reads a source directory containing `pnova__Profiling_Definition__c.csv`, generates a temporary import configuration, and executes the import. Partial failures are surfaced explicitly — if some definitions fail validation while others import successfully, the output identifies which objects failed and why.

OPERATION MODES:

- **Insert** (default) — Creates new records only. Fails on duplicate Name. Use for clean restores into empty orgs.
- **Upsert** — Creates new records OR updates existing records matched by the Name external ID. Use when some definitions may already exist in the target org (e.g., incremental deployment to production).

WHEN TO USE:

- After a sandbox refresh — restore definitions from backup in under a minute
- For production deployment — import validated definitions from sandbox with simulation as the approval artifact
- For template provisioning — import a standard definition set into each new engagement org
- To test safely — simulate first with --simulation to validate the entire pipeline before committing

COMMAND SEQUENCE: `definition export` (save definitions to files) → `definition import --simulation` (validate against target) → `definition import` (execute) → `profile` (run profiling with restored definitions)

# flags.target-org.summary

Salesforce org to import definitions into. The command validates Cuneiform installation before executing the import.

# flags.source.summary

Directory containing the CSV files to import. Point this at a previous `definition export` output directory or any directory with a `pnova__Profiling_Definition__c.csv` file (e.g., --source ./backup/definitions).

# flags.operation.summary

How to handle existing definitions: Insert (default) creates new records and fails on duplicate Names; Upsert creates new records and updates existing records matched by Name. Use Insert for clean restores into empty orgs. Use Upsert when some definitions may already exist from earlier iterations.

# flags.simulation.summary

Validate the import without modifying data. Runs the full import pipeline — parsing, validation, duplicate checking — but skips all writes. Use before production imports to verify the operation would succeed. The simulation output serves as a change approval artifact.

# examples

- Restore definitions after a sandbox refresh:

  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions

- Validate the import before committing (simulation runs the full pipeline without writing):

  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions --simulation

- Deploy validated definitions to production with Upsert to handle mixed scenarios:

  <%= config.bin %> <%= command.id %> --target-org prodOrg --source ./release/definitions --operation Upsert

- Provision a new engagement org from a standard definition template:

  <%= config.bin %> <%= command.id %> --target-org newClientOrg --source ./templates/standard-definitions

- Output as JSON for scripted verification in CI pipelines:

  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions --json

# warnings.title

Warnings