Set up external entities to provide tailored details to marketing contacts

 

Updated: November 1, 2016

Applies To: Dynamics Marketing

System_CAPS_importantImportant

Microsoft Dynamics Marketing is scheduled to be retired on May 15, 2018. After that date the service will no longer be available. Please plan accordingly. For details, see the blog post Microsoft Dynamics Marketing service will be discontinued, and learn what’s coming next.

External entities are custom data records that you create and maintain using the Microsoft Dynamics Marketing SDK. The feature lets you associate an external entity with specific contacts by using custom contact fields. You might use this to send email marketing messages that include details personalized for each recipient, such as the store nearest to them, coupon codes they can use, or the orders they’ve placed recently. The advantage of this technique is that it provides a single data source (your external entity) that is shared with many contacts; you can therefore update details for several contacts at once by editing the values of a single external entity record. This reduces redundancy and improves maintainability.

For example, you might want to associate each contact with their nearest store location, and include details like store name, phone number, and address. Though you could achieve this with standard custom fields, adding an external entity will make it easier to maintain the contact records.

You must use the Microsoft Dynamics Marketing SDK to create and edit your external entities (More information: Provide customized data to your users), but once they are set up you can assign external entity records to your contacts using the standard Dynamics Marketing UI, as described in this topic.

To use external data in email marketing messages:

  • Use the Dynamics Marketing SDK to add external entities of the required type(s).

  • Map external entity types to custom contact fields for the site/client company that will use them.

  • Map each marketing contact to the relevant external entity record.

  • Insert the external entity record details in your email marketing message designs as needed.

When one or more external entities have been added to your site (using the SDK), you can see them by going to Settings > Business Administration > External Entities. Each entity listed here represents a single data record; usually you will have several entities of each type, providing users with several records to choose from when assigning entity values to each marketing contact. The External Entities list page provides the usual controls for sorting, filtering, and searching the list (More information: Learn how to work and get around in Microsoft Dynamics Marketing). Click a name in the list to open its maintenance page, which provides a few more details about your selected item. The maintenance page provides the controls and information described in the following table.

Setting or control

Description

Name

A name for the entity (read-only). This is the value that users choose when assigning an external entity record to a contact.

Entity Type

A classification of the entity (read-only). When users want to assign a custom contact entity to a contact, they can choose from among all external entities that share the same type. All external entities of a given type should contain the same set of data fields using the same XML schema.

External ID

A unique ID that identifies the entity (required to update it from the SDK) (read-only).

Status

The active/inactive status of the entity. Only active entities can be used.

Download button
Download

Click this button to download the data stored in the entity. The data is in human-readable XML format.

Contacts

This tab lists all of the contacts that currently assigned this entity, and provides controls similar to those from the standard Contacts list page (More information: Manage contacts).

System_CAPS_noteNote

Each external entity is an XML file that contains a single data record. You can think of the collection of all external entities having the same type as comprising a single data table named after the shared type value. For example, if you have 6 retail stores in 6 major cities, then you might have 6 external entities of type "Retail Outlets"—one for each store, with each providing name, address and phone details. Later, when assigning a nearest store value for contacts, you will be able to select from among these 6 stores based on what city your contact lives in.

To make external entity records available for use with your contacts, you must set up a custom contact field for the client/site company that owns the relevant contacts. To do this:

  1. Do one of the following:

    • To add the field to marketing contacts that belong to the site company, go to Settings > My Company > Company Settings.

    • To add the field to marketing contacts that belong to a client company, go to Marketing Execution > Clients > Client Companies and use the sort, search, and filter controls to find and open the relevant client company.

  2. Open the Custom Contact Fields related-information tab for your selected company.

  3. Click the Create button New button to add a new custom contact field.

  4. A new row is added to the table. Set it up as follows:

    • Field Type: Set to "External Entity".

    • Name: Choose the type (not name) of the external entities that you want to be able to select from for this field. Usually, you will have several external entities of each type.

    • Title: Enter a name for the field as it will appear on the Contact maintenance page in Dynamics Marketing.

  5. Click Save or Submit. The new custom field is now available on the Details tab, under the External Entities Fields heading, for all marketing contacts that belong to your chosen company. This new field provides a drop-down list for selecting records from the external entity and applying them to your various contacts.

For more information about how to work with custom contact fields, see Create custom contact fields for market segmentation.

After you have mapped a custom contact field to an external entity type, you can select an external entity record for each contact as needed.

  1. Go to Marketing Execution > Marketing Database > Marketing Contacts and use the sort, search, and filter controls to find and open a relevant contact.

  2. Open the Details related-information tab for your selected contact.

  3. In the External Entity Fields section of the Details tab, you’ll see the custom contact field that you added and configured to map to an external entity type.

  4. Start typing the name of the external entity record that you want to assign to the current contact (or enter "%%" as a wildcard). A list of matching entities opens; use it to select the name of the entity you want to assign.

    Nearest Store UDF on Contact form

  5. Click Save or Submit to save your setting.

For more information about how to work with contact records, see Manage contacts.

Usually, the main purpose of setting up external entities is to use their data in your marketing emails. For example, to send customized details about the store location assigned to each contact on your mailing list, add a code snippet to your mail design, and then edit it to insert the name and address of the store that you've mapped with the contact (recipient of the email).

  1. Go to Marketing Execution >Email Marketing > Email Marketing Messages and open or create a new email message for the company you added an external entity to (More information: Create or view email marketing messages).

  2. Go to your message design and place your cursor at the position where you want to use the external entity data

  3. From the Insert Plug-In menu, choose @ExternalContent.Get(“<ExternalEntityType>”,) (where <ExternalEntityType> matches the type of entity you want to use). A string of code that matches your selection is entered into your message (for example, @ExternalContent.Get("NearestStore", )).

    System_CAPS_noteNote

    You don't have to use the Insert Plug-In menu to add the code—just use the correct syntax. You could instead type the code directly or copy/paste from an expression you added previously, which is an easy way to insert several fields from the same external entity.

  4. To finish setting up the expression, add a second parameter to the inserted code that specifies the XPATH to a value you want to fetch from the external entity.

    For example, if your external entity is formatted as shown in the XML sample below, then you could use the following two expressions to include the store name and street address: @ExternalContent.Get(“nearestStore”, “/properties/storeName”) and @ExternalContent.Get(“nearestStore”, “/properties/address/street”).

    <ExternalEntity Type="nearestStore" Name="HolmdelStore">
       <properties>
          <storeName>Holmdel Store</storeName>
             <address>
                <street>2113 Ely Road</street>
                <city>Holmdel</city>
                <state>New Jersey</state>
                <zip>07733</zip>
             </address>
          <phone>555-1212</phone>
       </properties>
    </ExternalEntity>
    

Show: