Adding Mappings to a Messaging Relationship

You can add a custom mapping that contains a unique target field and condition, or for child relationship mappings, a unique target field, condition, and target child type. If a managed mapping exists with the same information, the custom mapping overrides it.

Note:

We recommend that you do not create mappings for fields that are specified as an identifier reference on the target:

  • To view the identifier reference on a declarative relationship, click Manage Relationship.
  • To view the identifier reference on a custom child relationship mapping, click next to the relevant relationship mapping and click Edit.

To add mappings to a relationship:

  1. On the Message Types tab, click the name of the message type that contains the relationship you want to customize. The message type is displayed.
  2. In the Relationship & Mapping Details section, click Manage Relationship and select the publication and subscription that make up the relationship.
  3. Complete one of the following steps:
    • Add a top-level mapping, click Add Mapping.
    • Add a mapping to an existing child relationship, click in the child relationship row and click Add Child Mapping.
  4. Specify the key that identifies the data you want to send. Keys are unique within their section of the mapping hierarchy. If a key already exists with the same name, a number is appended to the new key when you save, for example, (1).
  5. Select a source type to define the type of data being published and complete the relevant steps.

    This option enables you to create a mapping from a field on the source object or a related object.

    Select the source field path.

    Tip:

    The following target types are compatible with this source type:

    • Field
    • Transformed Data
    • Advanced Lookup for lookups that require additional input

    This option enables you to create a mapping where a fixed piece of data is sent.

    Specify a description of the fixed data you want to send for this key and provide the exact data you want to send.

    Tip:

    The following target types are compatible with this source type:

    • Field
    • Transformed Data

    This option enables you to create a mapping from a related object on the source to a related object on the target. You can then add individual mappings to this relationship.

    Specify the child object that will provide data for child source records.

    Tip:

    The compatible target type for this source type is Child Relationship.

    This option enables you to create a mapping from the parent source object to a related object on the target. You can then add individual mappings to this relationship.

    Tip:

    The compatible target type for this source type is Child Relationship.

    This option enables you to select a field from any of the parent objects defined in the message type to provide data to a target field on your child relationship.

    Specify the field from a parent object in the mapping hierarchy. The parent object is listed next to the field. If a key for this field doesn't already exist on the message type, it is created automatically when you save the mapping.

    Tip:

    The following target types are compatible with this source type:

    • Field
    • Transformed Data
    • Advanced Lookup for lookups that require additional input
  6. [Optional and Not Available for Child Relationship Target Types] Specify a condition field to apply a mapping to the target in specific circumstances. If specified, the message value for the condition field must evaluate to true for the mapping to be applied to the target.
    You can select any checkbox or formula field of type checkbox that exists on the source object.
    Leave this field blank to always apply the mapping to the target.
    Data Type Examples

    Data Type

    Example

    CheckboxSelected
    Formula of type checkboxSelected
  7. Select an appropriate target type based on the source type you selected.

    This option enables you to create a mapping from a field on the source object or a related object.

    Select the field in which to store the data from the message.

    This option enables you to create a mapping from a field on the source object or a related object and apply a data transformation table to transform the target value.

    Select the field in which to store the data from the message and select a data transformation table to apply to the mapping. If you selected a data transformation table that requires input from two sources, specify an additional transformation source field.

    For more information, see Data Transformation Tables.

    This option enables you to create a mapping to a lookup where record names are not unique:

    1. Enter the field that provides the additional identifier for the source object. If a key doesn't already exist for this field, Foundations creates it automatically.
    2. Enter the additional identifier for the target record.

    For more information about advanced lookup mappings, see Creating Mappings to Lookups with Common Record Names.

    This option enables you to create a mapping between a related object on the source to a related object on the target:

    1. Specify the child object that will receive data and create child source records.
    2. [Optional] To conditionally create child records based on specific information in the message, select a child filter field. You can select any checkbox or formula field that exists on the source child relationship object. A new key is created to represent the child filter field.
      Leave this field blank to always create records for this child relationship.

      The filter field determines whether child records are created or updated. For records to be created or updated, the value in the message must evaluate to true. For example, if you select a filter field that relates to an Active checkbox on the source record, the target record will only be created or updated if the checkbox is selected.

      Data Type Examples

      Data Type

      Example

      CheckboxSelected
      Formula of type checkboxSelected
    3. Select the action to take for child records:
      • Always Add - Adds new records for all the information in the message. Any existing records are unchanged. Duplicate records might be created.
      • Update Matching * - Updates existing child records that match the records in the message. Existing records that do not match are not updated.
      • Update Matching and Delete * - Updates existing child records that match the records in the message. Existing records that do not match are deleted.
      • Replace All - Deletes all existing child records and creates new child records specified in the message.

        • * If you select an Update option, you must also specify values for the Unique Identifier on Source and the Identifier Reference on Target fields.

        These fields enable you to specify the link between source and target records and determine whether a record in the message matches an existing one in the target.

        • The unique identifier field on source determines the field on the source that contains unique data that identifies the record, for example, the record ID or name.
        • The identifier reference on target determines the field on the target that saves that information to be compared by future messages.

        When you save the mapping, an additional mapping is created for this key on the publication. The name of the key matches the name of the source field provided. Foundations will not automatically create a duplicate key at the same level in the hierarchy. If a key already exists with the same name, a number is appended to the new key, for example, (1).

        You can optionally map this information to another field. However, we recommend that you do not create a mapping to the field that you specified as the identifier reference on the target.

    Note:

    You can only select targets that you have permission to edit.

  8. [For Child Mappings Only] Select a target child type or enter the name of a new target child type. If blank, the mapping is assigned the Default target child type. For more information about target child types, see Splitting Source Data into Multiple Target Records.
  9. Click Save to save the mapping or Save & New to save the mapping and create a new mapping.
Tip:

If fields or objects with duplicate labels exist, API names are also displayed for clarity.

Additional Actions

You can now decide whether you want to enable return data for the messaging relationship to send confirmation data back to the source record. For more information, see Return Data Overview.

You can also add filters to your subscriptions so that they only receive information when specific criteria is met. For more information, see Adding Filters to Subscriptions.

Next Steps

When you have completed the optional steps above, you must specify when to send messages for the relationship. For more information, see Activating a Messaging Relationship.