XML Format for Contact Imports

This page explains the XML format required to import contact data into Mapp Engage. It describes the file structure, available elements and attributes, and how to configure them correctly during import.

Basic File Structure

To format your XML file correctly, follow these rules:

• XML element and attribute names are case-sensitive.

• During import, Mapp Engage compares attribute names case-insensitively to avoid duplicates caused by capitalization.

• The first line of your file must include the XML declaration and character encoding. Make sure the encoding matches your input file, and select the same encoding during import.

Component Table

<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
	<list>
		<namedattr-definition enum="false" type="date" name="LastPurchase"/>
		<namedattr-definition enum="false" type="number" name="HouseholdSize"/>
		<namedattr-definition enum="false" type="string" name="Hobbies"/>
			<user>
				<email>joseph.example@emaildomain.com</email>
				<mobilenumber>498912345678</mobilenumber>
				<faxnumber>00000000</faxnumber>
				<identifier>11122233abc</identifier>
				<firstname>Joseph</firstname>
				<lastname>Example</lastname>
				<nickname>Joe</nickname>
				<dateofbirth>1983-06-23</dateofbirth>
				<title>1</title>
				<zipcode>12345</zipcode>
				<partnerid>12345</partnerid>
				<isolanguagecode>en</isolanguagecode>
				<isocountrycode>US</isocountrycode>
				<timezone>Europe/Berlin</timezone>
				<namedattr name="TotalPurchases">944.76</namedattr>
				<namedattr name="LastPurchase">15.03.2010</namedattr>
				<namedattr name="HouseholdSize">3</namedattr>
				<namedattr name="Hobbies">Dancing</namedattr>
				<memberattr name="LastPurchase">shoes</memberattr>
				<memberattr name="LocalStore">Manchester</memberattr>
				<channel type="email" mode="prefer" format="email-html"/>
				<channel type="mobile" mode="allow"/>
				<channel type="fax" mode="deny"/>
				<maxmessages number="2" period="7"/>
			</user>
	</list>
</userdata>

Standard Attributes

Mapp Engage provides several standard attributes for contact profile data. These are available by default in every system. For details on formats, see the Attribute Reference section below.

Custom Attributes

In an XML import, custom attributes are defined with the namedattr element. The name attribute specifies the attribute name, and the value is placed between the start and end tags.

<namedattr name="LastPurchase">15.03.2016</namedattr>

• If the attribute already exists, Mapp Engage adds the value.

• If it does not exist, Mapp Engage creates the attribute.

• Best practice: specify the data type and whether the attribute is enumerated during import.

Example

<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <list>
    <user>
      <email>Jane.Miller@email.com</Email>
      <mobilenumber>498912345678</MobileNumber>
      <firstname>Jane</FirstName>
      <namedattr name="LastPurchase">15.03.2016</namedattr>
    </user>
  </list>
</userdata>

New Custom Attributes

You can create new custom attributes when you import a file. Define the data type and whether the attribute is enumerated with the namedattr-definition element.

Example

<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <list>
    <namedattr-definition enum="false" type="date" name="LastPurchase"/>
    <namedattr-definition enum="true"  type="number" name="HouseholdSize"/>
    <namedattr-definition enum="false" type="string" name="Hobbies"/>
  </list>
</userdata>

Note

You can only define data types and enumerations for attributes that do not already exist in Mapp Engage. If you include these settings for an existing custom attribute, the import fails.

XML Attributes

Member Attributes

Member attributes let you store different values for the same contact across different groups.

You can only create member attributes by importing an XML or CSV file. They cannot be created manually in the Mapp Engage interface. Member attributes always use the string data type.

In the XML file, member attributes are defined with the memberattr element. The name attribute specifies the member attribute, and the value is placed between the start and end tags.

Example

<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <list>
    <user>
      <email>jose.example@email.com</Email>
      <memberattr name="LastPurchase">shoes</memberattr>
      <memberattr name="LocalStore">Manchester</memberattr>
    </user>
  </list>
</userdata>

• If the member attribute already exists in the group, the new value is added to it.

• If it does not exist, Mapp Engage creates the attribute and stores the value.

Group Attributes

Group attributes cannot be imported in the same XML file as contact data. They must be imported separately.

For details, see Import Group Attributes.

Read Mode

Read mode defines how a contact prefers to receive group messages (email, SMS, push). It does not apply to system messages or single messages.

In the XML file, read mode is set with the channel element.

Example

<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <user>
    <email>Jane.Miller@email.com</Email>
    <channel type="email" mode="prefer" format="email-html"/>
    <channel type="mobile" mode="allow"/>
    <channel type="fax" mode="deny"/>
  </user>
</userdata>

• Preferences apply only within the current group.

• You can extend them system-wide during import (Advanced Options in Import Contacts).

• Manual edits in Mapp Engage always overwrite imported values.

XML Attributes

Message Limitation

You can limit the number of messages a contact receives within a defined period. This applies to all Mapp Engage channels (email, SMS, push) but not to system or single messages.

In the XML file, message limitations are set with the maxmessages element.

Example

<userdata xmlns="http://webservices.ecircle-ag.com/ecm">
  <user>
    <email>Jane.Miller@email.com</Email>
    <maxmessages number="2" period="7"/>
  </user>
</userdata>

• In this example, the contact receives no more than two messages in seven days.

• After the limit is reached, no further messages are delivered until the period resets.

XML Attributes

Attribute Reference

The following tables provide a quick reference for the standard elements, date and time formatting, and the additional elements used in contact import XML files.

Standard Attributes

The following elements are nested inside the user element.

Date and Time Formatting

Mapp Engage uses ISO-8601 date formats.

Time zones must be entered using the following structure:

YYYY-MM-DDThh:mm:ss(+/-)GMT offset

Example:
US/Eastern - 2012-12-25T15:15:15-05:00

ISO-8601 formatting is recommended for all date and time values in the import file. Deprecated formats are not fully supported.

Additional Information

The following elements are also nested inside the <user> element.
The maximum number of characters per value is 2000.