Deployment Data Dependencies

Deployment Data Dependencies

Use this skill when deploying data records (not metadata) across Salesforce orgs and the deployment fails because org-specific IDs — record type IDs, queue IDs, user IDs — differ between the source and target org. Also covers Custom Settings, which are org-specific data that do not deploy with metadata packages and must be seeded post-deployment.

Before Starting

Gather this context before working on anything in this domain:

• What data records are being deployed? CSV files, SFDMU data plan, Salesforce CLI data import tree, or a third-party tool like Prodly?
• Which fields contain org-specific IDs that will be different in the target org? Common culprits: RecordTypeId, QueueId (OwnerId pointing to a queue), OwnerId (pointing to a specific user).
• What Custom Settings objects does the application depend on? Custom Settings are org-specific data — they do not deploy with metadata and must be seeded separately.
• Are external IDs defined on the target objects to support upsert-based deployment?

Core Concepts

Record Type IDs Are Org-Specific

Record type IDs (18-character Salesforce IDs) are assigned when the record type is created in each org. The same record type "Customer Account" will have ID 0123000000000001 in Production but 0127000000000002 in a sandbox. They are never portable across orgs.

The canonical deployment data error is:

INVALID_CROSS_REFERENCE_KEY: Record Type ID

This error occurs when a CSV or data plan hardcodes a record type ID from the source org as a field value in a target org load.

The safe cross-org reference pattern:

1. In Apex: Schema.SObjectType.Account.getRecordTypeInfosByDeveloperName().get('Customer_Account').getRecordTypeId() — resolves the target org's ID dynamically at insert time.
2. In SFDMU / Bulk API jobs: Use RecordType.DeveloperName as an external ID reference in the relationship field mapping, not RecordTypeId as a literal ID column.
3. In sf data import tree (@sf_reference_id mechanism): Reference records by their @sf_reference_id node attribute — this creates relative references resolved at import time, not org-specific IDs.

Custom Settings Are Org-Specific Data — They Do Not Deploy

Custom Settings (both Hierarchy and List types) are org-specific data records, not metadata. When you deploy a metadata package or change set:

• The Custom Setting object definition (fields, API name) deploys as metadata
• The Custom Setting data records (the actual values) do NOT deploy

The only way to transfer Custom Settings data is:

1. A post-deploy Apex script that reads a configuration and inserts the Custom Setting records
2. A SandboxPostCopy implementation that seeds Custom Settings when the sandbox is refreshed
3. A data deploy step in the CI/CD pipeline (SFDMU, Copado Data Deploy, Prodly) that treats Custom Settings as deployable data objects

Failing to seed Custom Settings after deployment causes silent failures — features controlled by Custom Settings simply do not work without throwing a clear error.

Queue IDs and User IDs Are Also Org-Specific

Like record type IDs, Queue IDs (OwnerId values pointing to Group records of type Queue) and User IDs are org-specific. When loading records where OwnerId should be a queue, the approach is:

• Query the target org's Group object: SELECT Id, Name FROM Group WHERE Type = 'Queue' AND Name = 'Case Queue' — use the resulting ID in the import.
• In SFDMU, use the Group.Name or Group.DeveloperName as an external ID reference rather than the hardcoded Queue ID.

Common Patterns

Pattern: SFDMU External ID Mapping for RecordType

When to use: Deploying data records via SFDMU that include RecordTypeId as a lookup field.

How it works: In the SFDMU export.json configuration, use the relationship field pattern instead of RecordTypeId:

{
  "fields": ["Name", "RecordType.DeveloperName"],
  "externalId": "Name",
  "relationship": {
    "RecordType.DeveloperName": "RecordTypeId"
  }
}

SFDMU resolves RecordType.DeveloperName in the target org and maps the result to RecordTypeId at insert time — no hardcoded IDs required.

Why not hardcode IDs: Hardcoded IDs from source org cause INVALID_CROSS_REFERENCE_KEY on every target org where the record type ID differs.

Pattern: Post-Deploy Custom Settings Seeding Script

When to use: After every deployment that depends on Custom Settings values.

How it works:

1. Define the required Custom Settings values in a version-controlled JSON or YAML configuration file.
2. Write an Apex script (anonymous Apex or invocable) that reads this configuration and upserts Custom Setting records.
3. Execute this script as a post-deploy step in the CI/CD pipeline (e.g., sf apex run -f scripts/seed-custom-settings.apex).

Why not use change sets: Change sets deploy the metadata definition but not the data. Manual entry post-deploy is error-prone and untraceable. A script in version control is auditable.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Audit the data plan for org-specific IDs — Review all CSV files and data plan configs for hardcoded 15/18-character Salesforce IDs in lookup fields. Flag RecordTypeId, OwnerId, AssignedTo__c, or any field containing an ID.
2. Map record type DeveloperNames — For each hardcoded RecordTypeId, find the corresponding DeveloperName in the source org. Verify the same DeveloperName exists in the target org.
3. Update data plan to use DeveloperName references — Replace hardcoded RecordTypeId values with RecordType.DeveloperName lookups in SFDMU or equivalent tool configuration.
4. Identify Custom Settings dependencies — List all Custom Settings objects the application reads. Confirm that post-deploy seeding is in the deployment runbook.
5. Write or update seeding scripts — Create/update the post-deploy Custom Settings seeding script and add it to the CI/CD pipeline.
6. Test in target org — Execute the data deployment, confirm no INVALID_CROSS_REFERENCE_KEY errors, and verify Custom Settings values are present and correct.

Review Checklist

Run through these before marking work in this area complete:

• No hardcoded org-specific Salesforce IDs in data plan or CSV files
• RecordType references use DeveloperName, not hardcoded ID
• Queue references use Group.Name or DeveloperName lookup
• Custom Settings seeding script included in deployment runbook
• Apex code uses getRecordTypeInfosByDeveloperName(), not hardcoded IDs
• Post-deploy test confirms no INVALID_CROSS_REFERENCE_KEY errors

Salesforce-Specific Gotchas

1. INVALID_CROSS_REFERENCE_KEY is a data error, not a metadata error — This error looks like a deployment error but it is a data record DML error caused by hardcoded org-specific ID values in the data being loaded. It is not caught by metadata validation and only appears at data load time.

2. Custom Settings data is silently missing post-deployment — Features that read Custom Settings fail without throwing a clear error if Custom Settings are not seeded. The root cause is often only discovered in QA testing when expected behavior does not occur.

3. getRecordTypeInfosByDeveloperName() requires the DeveloperName, not the Label — Developers frequently use the record type Label (which may contain spaces) instead of the API DeveloperName. The method accepts only the DeveloperName (no spaces, underscore-separated).

4. sf data import tree @sf_reference_id does not resolve external IDs for lookup targets not in the same tree — If the referenced record is not in the same import tree (e.g., a lookup to a User record that already exists in the target org), @sf_reference_id does not work. Use an external ID field on the target object for cross-tree references.

Output Artifacts

Related Skills

• devops/deployment-strategies — Use for overall deployment sequencing and runbook design
• devops/environment-specific-value-injection — Use for Named Credential and Custom Metadata (CMT) config value management at deployment time
• data/sandbox-refresh-data-strategies — Use for post-sandbox-refresh data seeding which shares many of the same patterns
• devops/cpq-deployment-patterns — Use for CPQ-specific data deployment with complex relational data sets