SfSkills Domains Docs GitHub

Home / data / deployment-data-dependencies

deployment-data-dependencies

Use this skill when managing data record dependencies during deployments: resolving org-specific record type IDs that differ between source and target orgs, remapping queue IDs and user IDs in data plans, seeding Custom Settings values post-deployment, and using external IDs or DeveloperName references instead of hardcoded org-specific IDs.

Open the skill folder on GitHub

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:

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 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:

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

SituationRecommended ApproachReason
RecordTypeId in CSV causing INVALID_CROSS_REFERENCE_KEYUse RecordType.DeveloperName in SFDMU mappingDeveloperName is portable across orgs; ID is not
Custom Settings not working after deploymentAdd post-deploy seeding scriptCustom Settings data does not deploy with metadata
Queue OwnerId in data plan failing in target orgQuery Group.Name in target org to get queue IDQueue IDs are org-specific
Apex DML hardcoding a record type IDReplace with getRecordTypeInfosByDeveloperName()Dynamic resolution always uses target org's ID
sf data import tree with cross-object referencesUse @sf_reference_id node attributeCreates relative references resolved at import time

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:

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

ArtifactDescription
ID audit reportList of data plan fields containing hardcoded org-specific IDs
Remapping configurationUpdated SFDMU or data plan config using DeveloperName references
Custom Settings seeding scriptApex or CLI script for post-deploy Custom Settings population

Package files