CareSystemFieldMapping Metadata Type in SFDX

Architectural Overview#

In enterprise healthcare implementations, patient demographics and clinical encounters often originate across multiple Electronic Health Record (EHR) platforms such as Epic, Cerner, or Meditech. The CareSystemFieldMapping metadata type provides a declarative mapping layer within Salesforce Health Cloud that links external source system identifiers and fields directly to target Salesforce objects (targetObject) and fields (targetField).

Rather than hardcoding field transformations in middleware or Apex integration handlers, architects use CareSystemFieldMapping to maintain source-to-target schema definitions in version control. When Health Cloud ingests clinical payloads, it evaluates active mappings by source system and role to populate patient accounts, contacts, or clinical data model records accurately.

Directory Location and File Suffix#

In Salesforce DX (SFDX) source format and Metadata API projects, CareSystemFieldMapping components are stored in the careSystemFieldMappings directory.

Key Metadata Fields#

The following table details the core XML elements available on CareSystemFieldMapping as of API version 68.0 (Winter ’27):

Declarative Metadata Example#

The following example configures a CareSystemFieldMapping record that maps an external Epic medical record number (MRN) to the Medical_Record_Number__c external ID field on the Account (Person Account) object for patient records.

<?xml version="1.0" encoding="UTF-8"?>
<CareSystemFieldMapping xmlns="http://soap.sforce.com/2006/04/metadata">
    <externalIdField>Medical_Record_Number__c</externalIdField>
    <isActive>true</isActive>
    <isProtected>false</isProtected>
    <masterLabel>Epic Patient MRN Mapping</masterLabel>
    <role>Patient</role>
    <sourceSystem>Epic_EHR_Prod</sourceSystem>
    <sourceSystemId>EPIC-FAC-001</sourceSystemId>
    <targetField>Medical_Record_Number__c</targetField>
    <targetObject>Account</targetObject>
</CareSystemFieldMapping>

Package Manifest (package.xml)#

Include CareSystemFieldMapping in your manifest to retrieve or deploy mappings across Health Cloud environments:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Epic_Patient_MRN_Mapping</members>
        <name>CareSystemFieldMapping</name>
    </types>
    <version>68.0</version>
</Package>

SOQL Queries and SFDX CLI Commands#

You can query CareSystemFieldMapping records directly in SOQL to audit active EHR field mappings in an org, or retrieve them using the Salesforce CLI (sf).

SELECT DeveloperName, MasterLabel, SourceSystem, SourceSystemId,
       Role, TargetObject, TargetField, ExternalIdField, IsActive
FROM CareSystemFieldMapping
WHERE IsActive = true
ORDER BY SourceSystem ASC, TargetObject ASC

Use the sf CLI to retrieve and deploy mappings during CI/CD runs:

# Retrieve all CareSystemFieldMapping components from the target org
sf project retrieve start --metadata CareSystemFieldMapping

# Deploy a specific CareSystemFieldMapping component
sf project deploy start --metadata CareSystemFieldMapping:Epic_Patient_MRN_Mapping

Architect Best Practices and Gotchas#

• Bundle Schema Dependencies: Always deploy custom fields on CustomObject alongside or prior to CareSystemFieldMapping in CI/CD pipelines.
• Standardize Source System Naming: Use consistent naming conventions for sourceSystem and sourceSystemId across sandboxes and production. Avoid embedding environment-specific URLs in sourceSystemId so that the same metadata file deploys cleanly across QA, UAT, and Production.
• Deactivate Instead of Deleting: When retiring an legacy EHR feed, set <isActive>false</isActive> and deploy the update before executing destructive changes, ensuring in-flight integration jobs fail gracefully.

Frequently asked questions

What is the purpose of CareSystemFieldMapping in Health Cloud?

It defines declarative mappings between external EHR source system fields and target Salesforce objects and fields, allowing Health Cloud integrations to route inbound clinical attributes without hardcoded Apex transformation logic.

Which license or feature is required to deploy CareSystemFieldMapping?

The target org must have the Health Cloud license provisioned and Health Cloud settings enabled. Deploying to a standard Sales or Service Cloud org without Health Cloud fails with an unknown metadata type error.

How does CareSystemFieldMapping link to a specific external clinical system?

It uses the sourceSystem and sourceSystemId properties alongside role and targetObject to match incoming HL7 or FHIR payloads from a specific EHR instance to the right Salesforce record.

Can CareSystemFieldMapping target custom objects as well as standard objects?

Yes, the targetObject and targetField properties can reference standard objects such as Account or Contact as well as custom objects and Health Cloud clinical objects.