Mapping is a special Apex class that gives Adapters and Filters info about the mappings a user has defined for the Link.

Mappings can be found as a property inside a LinkContext.

The Mapping class is pretty straightforward, the only thing that is a little special is the configuration property. It is contextually-sensitive, so for example if you are inspecting the Mappings from inside your custom Filter, if there’s a value inside configuration it is because a user has specifically set a configuration for YOUR Filter on THIS Link, so go ahead and use it.

For more information about mapping configurations, check out ConfigurablePerMappingFilter.


Data Type Class Property Description
String name A unique name for this mapping, comes from the DeveloperName field of the corresponding cMDT record.
Field Path sourceFieldPath Reference to the specific Field that is being queried from; different from a property path.
List<String> sourcePropertyPath A representation of which data values to read from the original record properties.
Field Path targetFieldPath Reference to the specific Field that is being written to; different from a property path.
List<String> targetPropertyPath A representation of where to write to within the active record properties.
configuration Configuration information, if any has been specified for this mapping in this context.  

Field Path vs Property Path

Field Path and Property Path are similar concepts and the distinction between the two is best explained with some examples.

When we are thinking about a schema shape, it’s an abstract tree of which fields might be present on a hypothetical record. A FieldPath represents a Field’s position in this tree.

However, when we have an actual, concrete record that we are working with, we want to be more specific when it comes to nested lists. That’s where PropertyPath comes in.

Here’s an example Mapping:

{'fieldPath': ['contacts','firstname'], 'propertyPath' : ['"contacts"', '*', '"firstname"']}

Here’s another Mapping with the same field path, but a different property path:

{‘fieldPath’: [‘contacts’,’firstname’], ‘propertyPath’ : [‘“contacts”’, ‘0,1’, ‘“firstname”’]}


Typically you will be working with property paths in most use cases; field paths are more specialized for certain scenarios where it is useful to think in terms of the fields separate to some degree from the records (for example when a source adapter is deciding which fields to query for).

Test Coverage

There are methods for creating Mapping instances for test purposes in ValenceTestUtil:

global static Mapping createTestMapping(String name, String conciseSourcePropertyPath, String conciseTargetPropertyPath, String configuration);

global static Mapping createTestMapping(String name, List<String> normalizedSourcePropertyPath, List<String> normalizedTargetPropertyPath, String configuration);

You can set up Mapping instances to use in your test classes as follows.

// inside your test class

Map<String, valence.Mapping> mappings = new Map<String, valence.Mapping>();
mappings.put('first', ValenceTestUtil.createTestMapping('first', 'ParentAccount.AccountName', 'MyParentAccountName', null));

// set up a new, empty instance of LinkContext
valence.LinkContext context = new valence.LinkContext();

// set properties that you need, for example testing a source Adapter
context.linkSourceName = 'SomeSourceTable';
context.batchSizeLimit = 200;
context.mappings = mappings;

// etc