XML Format for Contact Imports

This topic describes how to import contact and profile attribute data with an XML file.

For general information about XML, see  http://de.wikipedia.org/wiki/XML .

Related Topics​

• ​Quick Reference: Contact Import XML​

• ​Attributes​

• ​Automate Contact File Import​

• ​Import Contacts​

Basic File Structure ​

To format your XML file, use the following guidelines.

Hint:

Replace the encoding of the code examples with an encoding that matches the characters in your input file. Select the correct character encoding on the interface when you import the file

Element and attribute names are normally case-sensitive in XML files. Mapp Engage performs a case-insensitive comparison of attribute names in the XML file to the existing attributes in your system during import. This comparison prevents the creation of that new attributes with different capitalisation.

The following sample shows the correct nesting for all elements in a contact import file. The sample contains values for new custom attributes that are defined during import. The sample also specifies values for all standard attributes, member attributes, read mode, and message limitation.

Sample XML

 
	<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 offers several standard attributes to store contact profile data. These attributes are offered by default in every system.

For more information about data formats for the standard attributes, see ​Quick Reference: Contact Import XML​.

Custom Attributes​

Custom attributes store data about a contact. This type of attribute is created specifically for your system. Custom attributes are specific to your system, and do not come standard with Mapp Engage. You can create custom attributes to the store the data about your contacts that is relevant to your digital marketing needs and strategies.

In the XML file, custom attributes use the namedattr element, which contains an XML attribute to specify the name of the custom attribute. Enter the value that you want to store in the contact profile between the start tag and end tag.

<namedattr name="x">value</namedattr>

• Replace X with the name of the attribute. You can view the name of the profile attributes in your system in the ​Administration​ area.

• If a custom attribute with that name exists, Mapp Engage adds the values to the existing attribute.

• If a custom attribute with that name does not exist, Mapp Engage creates an attribute to store the data. We strongly recommend that you specify the data type and enumeration during import. For more information, see​ New Custom Attributes​.

Hint:

In the following example, the custom attribute LastPurchase exists in the system, and is not defined in the XML file

Example

Contact Jane Miller is imported with her email address, mobile number, and first name. Mapp Engage records the date of their last purchase in a custom attribute named LastPurchase.

 
<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 custom attributes when you import a file. You can specify the data type, and whether the attribute is enumerated.

You can import new custom attributes in the same file that you use for contact data import. You do not need a separate XML file.

WARNING!

You can only specify the data type and enumeration of new custom attributes that do not exist in Mapp Engage. If the import file specifies the data type for a custom attribute that exists, an error occurs. Mapp Engage cannot process the import file

In the XML file, new custom attributes use the namedattr-definition element. The XML attributes define the enumeration, data type, and name.

Example

This example defines three new custom attributes.

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

Member Attributes​

Member attributes let you save different information for the same contact in different groups.

You can only create member attributes with import of an XML or CSV file. You cannot create member attributes manually on the Mapp Engage interface. Member attributes always use the string data type.

In the XML file, member attributes use the memberattr element, which contains an XML attribute to specify the name of the member attribute. Enter the value that you want to store in the contact profile between the start tag and end tag.

<memberattr name="x">value</memberattr>

• Replace X with the name of the attribute.

• If a member attribute with that name exists in the group, Mapp Engage adds the values to the existing attribute.

• If a member attribute with that name does not exist in the group, Mapp Engage creates an attribute for the data.

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>

Group Attributes​

A group attribute stores one value for all members of a group. The value is identical for all group members.

Hint:

It is not possible to import group attributes in an XML file that is used for contact data import. Group attributes must be imported in a separate XML file. For additional information, see ​XML Format for Group Attribute Imports

Read Mode​

The read mode stores information about how contacts want to receive messages.

Mapp Engage uses the read mode to decide which channel to use when it sends messages to your contacts. The read mode controls the following channels: email, SMS, and mobile push.

Read mode preferences apply to group messages only. Read mode preferences do not apply to system messages.

Hint:

By default, read mode preferences are only valid within a specific group. These settings do not apply for messages that the contact receives from other Mapp Engage groups.

During import, you can choose to apply the read mode preferences system-wide. This option means that the read mode settings for each contact are overwritten for all groups this contact is a member of. This option is found in the ​Advanced Options​ area of the ​Import Contacts​ window.

You can edit the read mode setting for a single contact in the Mapp Engage interface. The preferences that you enter in Mapp Engage manually overwrite any read mode preferences that have been imported in an XML or CSV file

In the XML file, read mode uses the channel element.

Example

The following file specifies that Jane Miller has three preferences. Jane prefers messages via email, prefers HTML messages (rather than text messages) and allows SMS messages.

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

The following table shows you how to set up the XML file to specify read mode.

Message Limitation​

You can use an XML import file to specify the maximum number of messages you send to a contact. This message limitation is specific to a single contact. You can also set message limitation on a system level. For more information, see ​Message Limitation​

Message limitations apply to all Mapp Engage messaging channels (email, SMS, and mobile push). Message limitations do not apply to system messages or single messages.

In the XML file, message limitation uses the maxmessages element.

Example

The following file specifies that Jane Miller receives no more than two messages in seven days.

<?xml version="1.0" encoding="ISO-8859-1"?> 
	<userdata xmlns="http://webservices.ecircle-ag.com/ecm"> 
		<user> 
			<Email>Jane.Miller@email.com</Email> 
			<maxmessages number="2" period="7"/> 
		</user> 
	</userdata>