Field mapping Extensions are a powerful feature that allow end users to extend the field-level mapping defined by Map components within the Process. Users can choose pairs of fields to be mapped in addition to the standard mapping. Depending on the application Connectors used in the Process, the user's own custom fields can be browsed dynamically and incorporated into the mapping. Note that custom objects cannot be dynamically browsed and mapped.
The mappings defined by the end user augment the mappings defined in the underlying Map component; they do not replace or override the predefined mapping. The user does not have the ability to "un-map" predefined mappings. Also, destination fields mapped from Map Functions in the underlying Map cannot be customized.
Object Definition and Data Map Extensions are used together to enable the custom mapping.
Field mapping Extensions are for Widgets only.
Field mapping Extensions are currently only available for XML Profiles. Maps that involve Flat File, Database, or EDI Profiles cannot be extended at this time.
Only simple field-to-field mappings can be defined. Advanced mapping logic including transformations, conditional scripting, and other function-type actions are not supported.
In this article:
Object Definitions
Object Definitions define a logical representation of an object type. The definition essentially merges the Profile elements from all the Operations for the given object type into a "super set" of fields. (The Object Type is listed within the Operation component.) For example, if your Process contained a Salesforce Account Query Operation and a Salesforce Account Upsert Operation, there would be separate Profiles for the Account Query response and the Account Upsert request. The Object Definition serves to create a generic Salesforce Account object type, whose fields the aggregate of both the Query and Upsert Profiles.
Looking ahead, when a Map component's source and destination Profiles are specified in Object Definitions, that Map can then be extended.
Creating Object Definitions
For all SDK application Connectors and the Salesforce Connector, the Object Definitions are generated automatically per Connection/Object. For non-SDK application Connectors and arbitrary XML Operations (e.g. XML over HTTP), the Object Definitions must be defined manually.
To create an Object Definition, click Add Object Definition, enter a Name (e.g. "QuickBooks Customer") and Object Type (e.g. "Customer), and check the box next to the relevant Profile(s) for the given object.
You can edit or delete a manually-created Object Definition using the Edit (
) and Delete (
) buttons, respectively.
Setting the Content Root
The Content Root represents the level at which the Profile elements should be merged.
To set the Content Root for a given Profile, click the View (
) button next to the Content Root, select the appropriate Profile element, and click OK.
The Content Root is used to "ignore" header elements not pertinent to the object's fields and to accommodate application Profiles that have different Profile structures for different operation. For example, the "Add Customer" and "Modify Customer" request Profiles for QuickBooks have different top level elements:
QuickBooks Add Customer Request:
<CustomerAddRq>
<CustomerAdd> << CONTENT ROOT
<Name>
<IsActive>
...
QuickBooks Mod Customer Request:
<CustomerModRq>
<CustomerMod> << CONTENT ROOT
<ListID>
<EditSequence>
<Name>
<IsActive>
...
In this example, the Content Root for each Profile should be set to CustomerAdd and CustomerMod, respectively.
You will typically not have to set the Content Root for automatically generated Object Definitions.
If no Content Root is selected, the XML root element is used.
Setting Aliases
Aliases allow you to provide user-friendly labels for Profile elements. Sometimes the raw XML Profiles have undistinguished, non-obvious, or downright cryptic element names that might not make sense to the end user. You can use aliases to provide a label that is more recognizable to the end user.
To set an alias, click the View () icon next to the Object Definition, check the box next to a field, and type a new alias value. Click OK when finished.
Data Maps
Data Map Extensions represent the generalized mapping between two Object Definitions. A list of the Map components that reference Profiles specified in the Object Definitions are grouped below each object pair. Within each group, you can choose to allow/disallow a specific Map from being extended. You can also lock fields on Source and/or Destination side. More on Locking Fields. The list of "Maps without Object Definitions" is simply for reference.
Locking Fields
You can lock certain fields so end users cannot customize the mapping from or to those fields. You should lock fields that are critical to the successful operation of your integration such an internal IDs or other key fields. You might also want to lock fields "system" fields or other fields not relevant to the integration to simply shorten the list presented to the end user. Locking an aggregate element will effectively lock all of its child element.
Destination fields mapped from Map Functions in the underlying Map are always locked.
You can lock fields at both the Data Map group level and the Object Definition level. To lock fields, click the Lock (
) button and check the box next to each field you want to lock, then click OK.
At the Data Map group level, you can lock fields on the Source and/or the Destination side of the Map. At the Object Definition level, you can lock fields per Profile. This gives you fine grained control over the fields that can be mapped for specific operations. For example, you want to users to be able to map to an "Account Number" field when the record is initially created but not during subsequent updates. You could lock the "Account Number" field on the "update" Profile only. The end user would still see "Account Number", however any customized mappings would simply be ignored when data goes through the "update" map.
See also:
This page
Other pages
Account
