Skip to content

Advanced Import Features

Import Synchronization

When you import content from a file or remote server, MapsAlive examines the data being imported and determines what existing hotspots should be updated or deleted and what new hotspots should be created.

Creating and updating hotspots

When the hotspot Id in the data you are importing matches the hotspot Id of an existing hotspot in the tour, MapsAlive updates the existing hotspot from the imported data. If there is no matching hotspot Id in the tour, MapsAlive creates a new hotspot from the imported data. As such, you can use import to initially populate a tour with hotspots and then use it again whenever you want to update those hotspots.

Deleting hotspots

You can use import to delete hotspots from a tour by including the delete property in your data and setting its value to True (delete is not a property of a hotspot, but we call it that anyway for import purposes).

Data Formats

The content that you import into MapsAlive, whether imported from a file or remote server must be in a format that MapsAlive understands. MapsAlive understands two formats:

  • Spreadsheet (Excel or CSV)
  • Tour XML

The spreadsheet formats store data in rows and columns. The first row contains header names to describe the kind of data that is in the columns. Excel and CSV are record-oriented spreadsheet formats. Tour XML is a MapsAlive-defined format that represents the hierarchical structure of a tour as shown in Figure 1.

Figure 1 – Tour Hierarchy

Choosing an import format

The format you choose depends on how you will create and manage your data. If you will be managing your data by hand, an Excel spreadsheet may be the best choice. You can use Excel to work with both Excel files (.xls and .xlsx) and CSV files.

Because of the verbose nature of XML, you should only use it if the XML will be generated from your data automatically by another program. Internally, the MapsAlive importer logic works with Tour XML so when you import spreadsheet data it will be converted to Tour XML as shown in Figure 2 below.

Figure 2 – MapsAlive import processing

Each of these formats has distinct advantages. Excel spreadsheets are easy for humans to work with. CSV is a format that thousands of programs can export. XML is a more flexible and structured format to use when data is being generated from a database by a computer program.

Spreadsheet formats

The two spreadsheet formats (Excel and CSV) have one thing in common: they are row and column-oriented. The first row contains headings to indicate what kind of data is in each column and the remaining rows contain data. You only need to provide columns for hotspot content properties that you want to import. Any properties that don’t have columns will not be affected by the import.

Tour XML

The Tour XML format contains an element for each hotspot or map that you want to import. Each hotspot element contains property elements for the properties that you want to import. If a property element is not present, its corresponding hotspot content property is not affected by the import.

The Tour XML is processed only once regardless of how many maps are in the tour that the data is being imported into. Which data is imported into which map is controlled by an element’s position in the XML hierarchy. For example, a hotspot whose parent element is map 1 is imported into map 1.

Hotspot Properties

Hotspot properties are the attributes of a hotspot that you can set by importing data. The Hotspot Property Table below describes each property and specifies its allowed values.

Important notes:

  • The following properties are required: TourId, MapId, HotspotId, Title.
  • Property names cannot contain spaces.
  • The property names in the table show the letter casing that is required only if you are importing Tour XML. The first letter is always lower case and the other letters are as shown.
  • If you are not importing Tour XML, casing does not matter. For example, you could use categories or Categories or CATEGORIES.
  • The casing of property value keywords does not matter. For example, you can use true or True or TRUE.
  • To prevent MapsAlive from changing a hotspot’s existing property value, leave the cell empty. If you are importing Tour XML, do not include that property’s element in the XML.
  • If the hotspot has a value and you want to erase it, type [blank] as the value. If using templates, you can prevent a template value from setting a property by typing [protect] as the value.
  • When the allowed value is HTML, you can specify text which includes HTML characters for example This is <b>bold</b> text. When it says "plain text", no HTML is allowed.

Hotspot Property Table

Property Description Allowed Values
categories Sets the categories for the hotspot. If the hotspot already has categories set, the categories will be reset using the values provided. To remove all categories for a hotspot, specify [blank]. Comma-separated list of Category Codes
clickAction Sets the click action for the hotspot’s marker. If you specify a value other than None, you must also provide a value for clickActionTarget. Also, see the openUrlInNewWindow property. URL, JavaScript, GoToPage, None
clickActionTarget Required when clickAction is set to URL, JavaScript, or GoToPage. Sets the value to be used as the target of the click action. For GoToPage, the target is the Map Id. Plain text
delete Permanently deletes the hotspot when the value is True. Be very careful when using Delete. True, False
dirPreviewImageUrl Sets the URL for the image to be displayed for the hotspot when its entry is moused over in the directory. A URL
dirPreviewText Sets the text to be displayed for the hotspot when its entry is moused over in the directory. Plain text or HTML
excludeFromDirectory Controls whether the hotspot appears in the directory. True, False
firstHotspot Makes this hotspot’s content display first when the map loads. You cannot unset this. If more than one hotspot has the firstHotspot property set to true in the import file, the last one found in the file will become the first hotspot. True
firstSlide Reserved for compatibility with MapsAlive V2. Changed to firstHotspot in V3.
hotspotId Required. Specifies the HotspotId for the hotspot. If the Id matches the HotspotId of an existing hotspot, the hotspot will be updated. If there is no existing hotspot with that Id, MapsAlive will create a new hotspot with that Id. The Id must not contain: & \ / : * ? " , < > | A HotspotId
hotspotOrder Sets the order in which the hotspot will display when a slide show is running. An integer
instructions Specifies an import template definition. Define Template, Use Template, End, #
isDisabled When True, the hotspot’s marker will not respond to mouseover, mouseout, or click events, and it will not change appearance when the mouse is over it. True, False
isHidden When True, the hotspot's marker will be hidden and will not respond to mouseover, mouseout, or click events. True, False
isLocked When True, the hotspot's marker will be locked on the Map screen in the Tour Builder. It has no effect on the published tour. True, False
isNotAnchored When True, the hotspot’s marker will not be anchored to a fixed location on the map. Instead, it will always appear in the same place when you pan or zoom the map. This feature is useful when you want to provide a hotspot that is always visible. True, False
isRoute When True, the hotspot’s id is used as a route container. For more information Routes. True, False
isStatic When True, the hotspot’s marker will not change appearance when the mouse is over it. It will however still respond to mouseover, mouseout, and click events by performing the action associated with those events. True, False
mapId Required. Specifies which map the hotspot can be imported into. Use * to mean the current map (the map that is selected in the Tour Navigator). Use ** to mean any map. The Id must not contain: & \ / : * ? " , < > | Note: For galleries use the Gallery Id as the MapId, and for data sheets use the Data Sheet Id as the MapId. A MapId, *, **
markerName Specifies the name of the marker to be used for the hotspot. Plain text
markerStyle Specifies the name of the marker style to be used for a marker that is bound to the hotspot. Has no effect for markers that are not bound. The markerStyle name is not case-sensitive, but its spelling and punctuation must be exactly as it appears in the Tour Builder. Plain text
markerZooms When True, this marker will change size when the map zooms in or out. When False it will always be the same size. To clear this setting and use the default setting for the map, specify [blank]. True, False
media Required when mediaType is set to Multimedia. Sets the embedded HTML for the multimedia. HTML
mediaType Sets the type of media for the hotspot’s content. If you specify Multimedia, you must provide a value for the media property. Photo, Multimedia
messengerFunction Required when the usesLiveData property is set to True. Sets the request function that the hotspot will call (messenger function is the legacy name for request function) JavaScript function call
mouseoutAction Sets the action that occurs when a user moves their mouse off the hotspot’s marker. If you specify JavaScript as the value, you must also provide mouseoutActionTarget. JavaScript, None
mouseoutActionTarget Required when mouseoutAction is set to JavaScript. Sets the JavaScript to be executed on mouse out. Plain text
mouseoverAction Sets the action that occurs when a user moves their mouse over the hotspot’s marker. If you specify JavaScript as the value, you must also provide mouseoverActionTarget. JavaScript, None
mouseoverActionTarget Required when mouseoverAction is set to JavaScript. Sets the JavaScript to be executed on mouseover. Plain text
newHotspotId Sets a new HotspotId for an existing hotspot. If the new Id is already in use by another hotspot, the property is ignored. Plain text
newSlideId Reserved for compatibility with MapsAlive V2. Changed to newHotspotId in V3.
note Sets the text that you want to attach to the hotspot as notes. MapsAlive does not use this property and you can use it for any purpose, for example recording a geocode (latitude and longitude). Plain text
openUrlInNewWindow Used when the clickAction property is set to URL. True indicates that the web page identified in the ClickActionTarget field should open in a new window. False means the web page replaces the current window. True, False
pageId Reserved for compatibility with MapsAlive V2. Changed to mapId in V3.
popupOverrideHeight Sets the height of this hotspot’s content, allowing you to override the min and max popup height specified for hotspots on this map. If you specify a height but no width, the size of the popup will correspond to the height specified and the width will automatically adjust to preserve the aspect ratio. This property has no effect if mediaType is set to Multimedia. Specify 0 to remove an existing height override. An integer
popupOverrideWidth Sets the width of this hotspot’s content, allowing you to override the min and max popup width specified for hotspots on this map. If you specify a width but no height, the size of the popup will correspond to the width specified and the height will automatically adjust to preserve the aspect ratio. This property has no effect if mediaType is set to Multimedia. Specify 0 to remove an existing width override. An integer
showContentWhen Specifies when a hotspot’s content will be displayed. Use Mouseover to show the hotspot’s content as soon as the mouse moves over the marker. Use Click if you want to show the hotspot’s content when the user clicks the marker. Use Never if you don’t want the content to display when the mouse moves over or clicks the marker. Mouseover, Click, Never
slideId Reserved for compatibility with MapsAlive V2. Changed to hotspotId in V3.
text Sets the text that appears in the text area of the hotspot’s content. Plain text or HTML
title Required. Sets the hotspot’s title. Plain text
tourId Required. Specifies which tour the hotspot can be imported into. Use * to mean any tour. A tour number, *
toolTip Set the text for the tooltip that displays when you mouse over the hotspot’s marker. Plain text
usesLiveData Controls whether the hotspot uses Automatic Live Data. When set to True. True, False
whenTouchExecuteClick Specifies what will happen when a hotspot is touched on a mobile device. When set to True, the hotspot’s click action will be executed if a click action is specified. When set to False, the hotspot’s mouseover action will be executed if a mouseover action is specified. True, False
zoomVisibility A value of zero means the marker is always visible. A negative value means the marker is visible when the zoom level is less than or equal to the value. A positive value means the marker is visible when the zoom level is greater than the value. A number between -100 and 100

Precautions

When you import data, you are importing it for the entire tour. You control which hotspots on which maps are affected by the import by setting the required MapId value for each hotspot. You can also restrict which tour the data can be imported into by specifying the required TourId value for each hotspot.

The TourId and MapId properties are required to ensure that you don’t accidentally import data into the wrong tour or map. For example, if you make tourist maps for different cities, you don’t want to accidentally import the San Francisco data into the San Diego tour. And if the San Diego tour has two maps, one for Downtown and one for North County, you don’t want to import the North County map data into the Downtown map.

Conversely, you might have hotspot data that you want to be able to import into more than one map in the same tour or into different tours. In that case, you can use wildcards for both the TourId and MapId values. A single asterisk * as the TourId value means any tour. A single asterisk * as the MapId value means the current map, that is, the map that’s selected in the Tour Navigator.

A double asterisk ** for the MapId means any map, so if you specify '**' for a tour with three maps, the hotspot will get imported into all three maps. This is handy when you have a hotspot that has a marker that you want to appear on every map such as an Order Now marker that goes to your shopping cart.

One map at a time

When you import data into a tour, MapsAlive selectively applies the data to each map of the tour. Using the MapId value as a guide, it decides which hotspots to import into which maps. You’ll learn later how you can use Import Templates to import the same hotspot data into different maps of different tours and even format the data differently depending on how it is being used.

If you only want to import data into one map, select that map in the Tour Navigator and make sure that the MapId in your import data is set to either '*' or to the map Id of the desired map.

Examples

This section provides examples of import data in the various formats supported by MapsAlive. The same data is shown as Excel, CSV, and Tour XML. The data imports two city hotspots and sets their title and text.

In the examples, the TourId value for each hotspot is set to * to mean that the data can be imported into any tour. If you want to ensure that the data can only be imported into a specific tour, you must provide a tour Id instead of using *. A tour’s Id is its tour number. You can find the tour number on the Tour Manager screen or at the bottom of the Tour Navigator.

The MapId value for each hotspot is set to * to mean that the data is only for the current map of the tour that the data is being imported into. The current map is the one that is selected in the Tour Navigator. To ensure that the data can only be used for a specific map, you must specify a map Id instead of using *. You can find and edit a map’s Id on the Advanced Map Options screen. By default, maps have Ids like map1, map2, and so on.

Excel

When using Excel, row 1 must be used as a header to specify which columns are used for which hotspot properties. If you import this spreadsheet, MapsAlive will create two hotspots and import the Title and Text content for each.

Figure 3 – Excel spreadsheet with a header and hotspot rows

CSV

The CSV data below is equivalent to the Excel spreadsheet shown in Figure 3. CSV files look very similar to Excel rows but become difficult to read when there is a lot of data. If you create CSV data by hand, be sure to properly escape embedded commas and quotes. We don’t recommend creating CSV by hand, but thousands of programs will generate it for you automatically from other data. 

TourId,MapId,HotspotId,Title,Text
*,*,s1,"Chicago, IL","Chicago is known as the ""windy city"""
*,*,s2,"New York, NY","New York is called the ""big apple"""

Tour XML

The Tour XML below shows the basic structure required for importing XML. The following elements are required:

<tour>,<maps>, <map>, <mapId>, <hotspots>, <hotspot>, <hotspotId>, and <title>

The structure below would be used for a tour with two maps, each having two hotspots. But, keep in mind that every hotspot property shown can be included in the Tour XML. The additional properties would be added to the <hotspot> elements to which they apply.

<tour>
  <maps>
    <map>
      <mapId></mapId>
      <hotspots>
        <hotspot>
          <hotspotId></hotspotId>
          <title></title>
          <text></text>
        </hotspot>
        <hotspot>
          <hotspotId></hotspotId>
          <title></title>
          <text></text>
        </hotspot>
      </hotspots>
    </map>
    <map>
      <mapId></mapId>
      <hotspots>
        <hotspot>
          <hotspotId></hotspotId>
          <title></title>
          <text></text>
        </hotspot>
        <hotspot>
          <hotspotId></hotspotId>
          <title></title>
          <text></text>
        </hotspot>
      </hotspots>
    </map>
  </maps>
</tour>

The Tour XML below represents the same tour content as the Excel spreadsheet shown in Figure 3 above. Use Tour XML when you will be generating your data from a program and you don’t need to use Import Templates.

<tour>
  <maps>
    <map>
      <mapId>*</mapId>
      <hotspots>
        <hotspot>
          <hotspotId>s1</hotspotId>
          <title>Chicago, IL</title>
          <text>Chicago is known as the "windy city"</text>
        </hotspot>
        <hotspot>
          <hotspotId>s2</hotspotId>
          <title>New York, NY</title>
          <text>New York is called the "big apple"</text>
        </hotspot>
      </hotspots>
    </map>
  </maps>
</tour>

To see what the Tour XML looks like for your tour, you can export your tour's hotspot content.

Import Macros

You can reference the content of one spreadsheet column in another column using Import Macros.

Figure 4 – Excel spreadsheet using Import Macros

Notice that column F in Figure 4 above has [Nickname] as its header. That’s not a hotspot property, but rather, a user-defined data column. MapsAlive knows it’s a data column because it is enclosed in square brackets. The text within the Text column uses macro syntax to reference the nickname data column and it also references data from the Title column which is a hotspot property.

Tip: If you have a user-defined data column that contains currency or formatted numbers, such as $63.98 or 1,000,000, these values are imported from Excel as straight numbers without any formatting characters like the , or $. So you would see 6398 or 1000000. To include the formatting characters when importing, set the cell format in Excel to Text and type the formatting characters explicitly in the text data.

Important: You must enclose the name of a user-defined data column in square brackets both in the column header and when you reference it. If you do not use the square brackets, MapsAlive does not know it is a user-defined data column and will ignore it.

You can insert the cell value from any column in the same row by simply enclosing it in square brackets. MapsAlive detects the macro and replaces it with the data referenced column.

Sometimes you’ll see the use of the [blank] macro. It does not refer to data in a column named [blank]. It is special syntax that means put nothing in this cell. Use it when you want to erase a hotspot’s property, for example, to set its Text property to blank. If you simply leave a cell empty, MapsAlive will interpret that to mean that you don’t want to change that property.

You can see the effect of the macros in Figure 4 by looking at the Tour XML that MapsAlive creates internally from the imported Excel data:

<hotspots>
  <hotspot>
    <hotspotId>s1</hotspotId>
    <title>Chicago</title>
    <text>Chicago is known as the "Windy City."</text>
  </hotspot>
  <hotspot>
    <hotspotId>s2</hotspotId>
    <title>New York</title>
    <text>New York is known at the "Big Apple."</text>
  </hotspot>
</hotspots>

Notice the typo in the second hotspot text element. It says known at instead of known as. This kind of human error often occurs when the same information is entered repeatedly. Duplicated information is referred to as redundant or denormalized data and should be avoided whenever possible. You can avoid redundant data (normalize your data) using Import Templates which are explained in the next section.

Macros cannot be used to provide values for the TourId or MapId columns.

Import Templates

Import Templates are a powerful feature of MapsAlive that allows you to pre-process data before it is imported. Preprocessing means that the data you enter is interpreted and processed into the actual data to be imported. Preprocessing allows you to separate data from the formatting and minimize how much data you have to specify.

Import templates are an advanced feature of MapsAlive, but they are worth making the effort to understand because they can save you a lot of time and they let you create formatted hotspot content that would otherwise be very difficult to make.

A simple example

Let’s start explaining Import Templates by continuing with the Import Macros example above. In that example, a typo was introduced in the second hotspot because the same text was typed twice. You can avoid that problem by moving shared information such as data and formatting into a template row.

In Figure 5 below, a template on row 2 tells MapsAlive to use * for the TourId and for the MapId, and to use [Title] is known as the [Nickname] as the Text property. The hotspots that follow on rows 3 and 4 will inherit their TourId, MapId, and Text column values from the template. The effect is the same as if you had used the Excel data from Figure 4, but without the typo.

Figure 5 – Excel spreadsheet using Import Template

Tip: To make it easier to work with your data in Excel you can put a line break in an Excel cell by pressing alt-Enter. That’s how we broke the text on Row 2 into two separate rows. You can also use word wrap on cells, but a line break allows you to force a break anywhere you want one, often making your import file more readable. Note that this does not affect the formatting of your hotspot data in your tour.

Macros cannot be used in the TourId, MapId, or HotspotId columns of a template. 

Template definitions

Figure 5 uses an unnamed template to provide values for the hotspot rows that immediately follow it. You can also define templates and refer to them by name. Defining templates allows you to use the same template in more than one place as shown on row 3 and row 6 in Figure 6 below.

Figure 6 – Excel spreadsheet with template definition

The example above defines a template named City on row 2. The template provides values for the TourId and Text columns. We want to use the template to import hotspots into two different maps in the tour, map East and map West.

You define a template with the keyword "Define" and use it with the keyword "Use". Notice that when you use a template, you can override any of its columns to tailor its use. In Figure 6, the two uses of the City template on rows 3 and 6 override the template’s MapId column instead of inheriting its empty MapId cell.

The effect of the example is that the hotspots on rows 4 and 5 will be imported into the map whose MapId is "East" and the hotspots on rows 7 and 8 will be imported into the map whose MapId "West". All four hotspots will inherit the Text property value from the template definitions in row 2 column F.

When you provide a MapId value other than * or ** your tour must contain a map with that MapId, otherwise, the hotspots with that Id will be ignored.

You can see the effect of the Excel in Figure 6 by looking at the Tour XML below that MapsAlive creates internally from the spreadsheet data:

<tour>
  <maps>
    <map>
      <mapId>East</mapId>
      <hotspots>
        <hotspot>
          <hotspotId>s1</hotspotId>
          <title>Chicago</title>
          <text>Chicago is known as the "Windy City."</text>
        </hotspot>
        <hotspot>
          <hotspotId>s2</hotspotId>
          <title>New York</title>
          <text>New York is known as the "Big Apple."</text>
        </hotspot>
      </hotspots>
    </map>
    <map>
      <mapId>West</mapId>
      <hotspots>
        <hotspot>
          <hotspotId>s1</hotspotId>
          <title>Denver</title>
          <text>Denver is known as the "Mile High City."</text>
        </hotspot>
        <hotspot>
          <hotspotId>s2</hotspotId>
          <title>Los Angeles</title>
          <text>Los Angeles is known as the "City of Angels."</text>
        </hotspot>
      </hotspots>
    </map>
  </maps>
</tour>

Data groups

When you use a template, whether named or unnamed, the template and the hotspots that it applies to form a data group. The spreadsheet in Figure 6 has two data groups, one for the eastern cities and one for the western cities. Each of the two groups starts with a single Use Template row. You can however create a multi-use data group by placing two or more Use Template rows above the hotspot rows. This causes MapsAlive to import the hotspot data differently depending on which tour and map you are importing into. An example of a multi-use data group is shown below in Figure 7.

The template definition on row 2 has a Tooltip column that sets the tooltip value to be the same as the hotspot’s title. The use of this template on row 3 is only for the map having MapId Plain and the use of the template on row 4 is only for the map having MapId Fancy.

On the Plain map, the hotspot text is simply copied from the nickname column, but on the Fancy map, the title and nickname are combined along with HTML tags to make the title bold and the nickname italic to produce an effect like Chicago is the Windy City.

Figure 7 – Excel spreadsheet using a multi-use data group

You can see the effect of the Excel in Figure 7 by looking at the Tour XML below that MapsAlive creates internally from the spreadsheet data. Note that the HTML characters like < have automatically been converted to entities like &lt; so that the XML parser won’t attempt to interpret them as XML. Note also that the two hotspots s1 and s2 appear in each of the two maps Plain and Fancy.

<map>
  <mapId>Plain</mapId>
  <hotspots>
    <hotspot>
      <hotspotId>s1</hotspotId>
      <title>Chicago</title>
      <text>Windy City</text>
      <tooltip>Chicago</tooltip>
    </hotspot>
    <hotspot>
      <hotspotId>s2</hotspotId>
      <title>New York</title>
      <text>Big Apple</text>
      <tooltip>New York</tooltip>
    </hotspot>
  </hotspots>
</map>
<map>
  <mapId>Fancy</mapId>
  <hotspots>
    <hotspot>
      <hotspotId>s1</hotspotId>
      <title>Chicago</title>
      <text>&lt;b&gt;Chicago&lt;/b&gt; is the &lt;i&gt;Windy City&lt;/i&gt;</text>
      <tooltip>Chicago</tooltip>
    </hotspot>
    <hotspot>
      <hotspotId>s2</hotspotId>
      <title>New York</title>
      <text>&lt;b&gt;New York&lt;/b&gt; is the &lt;i&gt;Big Apple&lt;/i&gt;</text>
      <tooltip>New York</tooltip>
    </hotspot>
  </hotspots>
</map>

Import Template rules

The examples above have shown how you can use Import Templates. Here are a few rules to help you understand them better.

  • Template definitions can appear anywhere in the spreadsheet, but they must appear before they are used.
  • The Instructions column can be used to specify a template definition or use. It can also be used to indicate a comment by typing # as the first character. Any row that starts with # in the Instructions column is ignored by MapsAlive, but it is useful for adding explanatory information within your spreadsheet.
  • A data group is typically one or more template uses followed by one or more hotspots. The data group ends when the next data group starts, but you can explicitly end a data group with a row that contains End in the Instructions column.
  • A data group does not have to begin with a template use. You can have a data group that just contains hotspot rows.
  • As MapsAlive does import processing for each map in the tour, it examines each data group once for each map. If no template use can be applied for a map, the hotspot rows in that group will be ignored.