Metadata API Developer Guide

Introduction to Metadata API
Using Metadata API
Deploying and Retrieving Metadata
Deploying and Retrieving Metadata with the Zip File
Slow Deployments
Does a Retrieve Job Have a Status of Pending?
Sample package.xml Manifest Files
Running Tests in a Deployment
Running a Subset of Tests in a Deployment
Run Relevant Apex Tests in a Deployment (Beta)
Run the Same Tests in Sandbox and Production Deployments
Limit on Enqueued Deployments from Apex
Maintaining User References
CRUD-Based Metadata Development
REST Resources
Error Handling
Metadata API Context MCP Tool (Beta)
Reference
Appendices
PDF

Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Maintaining User References

User fields are preserved during a metadata deployment.

When a component in your deployment refers to a specific user, such as a recipient of a workflow email notification or a dashboard running user, then Salesforce attempts to locate a matching user in the destination organization by comparing usernames during the deployment.

For example, when you copy data to a sandbox, the fields containing usernames from the production organization are altered to include the sandbox name. In a sandbox named test, the username user@acme.com becomes user@acme.com.test. When you deploy the metadata in the sandbox to another organization, the test in the username is ignored.

For user references in deployments, Salesforce performs the following sequence:
  1. Salesforce compares usernames in the source environment to the destination environment and adapts the organization domain name.
  2. If two or more usernames match, Salesforce lists the matching names and requests one of the users in the source environment be renamed.
  3. If a username in the source environment doesn’t exist in the destination environment, Salesforce displays an error, and the deployment stops until the usernames are removed or resolved to users in the destination environment.