#######
Mapping
#######

Mapping is a special Apex class that gives :ref:`extensions-adapters` and :ref:`extensions-filters` info about the mappings a user has defined for the :ref:`Link <overview-links>`.

Mappings can be found as a property inside a :doc:`link-context`.

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 :ref:`Filter <extensions-filters>`, 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 :doc:`/filter-interfaces/configurable-per-mapping-filter`.

**********
Properties
**********

.. csv-table::
    :header: "Data Type", "Class Property", "Description"

    String, name, "A unique name for this mapping, comes from the DeveloperName field of the corresponding cMDT record."
    :doc:`/classes/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."
    :doc:`/classes/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."
    String, configuration, "Configuration information, if any has been specified for this mapping in this context."

Field Path vs Property Path
===========================

:doc:`/classes/field-path` and :doc:`/extension-concepts/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:

.. code-block:: json

    {'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"']}

.. tip:: 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 :ref:`when a source adapter is deciding which fields to query for <building-your-query>`).

*************
Test Coverage
*************

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

.. code-block:: java

	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.

.. code-block:: java

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