Resolving Differences in Location Names

To display MicroStrategy data using a map visualization, the location names used by ESRI must uniquely match the location (geo attribute) names used by MicroStrategy. However, the names used for geographic locations are not always unique or the same as the ones that ESRI uses.

• Different locations may have the same primary location name and need a secondary location name to make them unique. For example, many counties in the US have the name "Washington". This county name is unique within a state, but not outside the state because the primary location name exists in multiple states. To uniquely identify such a county, you need to qualify it with the state name. When you do this, Washington AL becomes uniquely different from Washington GA or Washington PA.

• ESRI sometimes uses location names that are different from the names used by MicroStrategy. For example, ESRI refers to the country of Russia as 'Russian Federation', while MicroStrategy refers to it as 'Russia'.

To resolve differences in location names, MicroStrategy uses a configuration file, called mapNameConversions.xml. In this configuration file, you can define rules that allow you to map MicroStrategy location names to the location names used by mapping vendors when there are mismatches, and add secondary location names to the match when needed. You can restrict the application of the rule to specific mapping vendors (map shape servers), to maps with a specific kind of boundary, and to maps that use a specific geo attribute for mapping.

The out-of-the-box mapNameConversions.xml file is shown below. It has one rule, represented by an <elem> node.

<?xml version="1.0" encoding="UTF-8"?>       
<nameConversions>     
<!-- 
  Scope for ESRI - 1 
  Scope for MSTR - 2 
  Scope for Mapbox - 4
-->     
<elem id="1" n="Russia" scope="1">Russian Federation</elem>      
</nameConversions> 

To override rules set in the out-of-the-box name conversion configuration file and add new rules, create a custom mapNameConversions.xml file and add it to your plug-in, as described below.

1. Create a mapNameConversions.xml file with the content shown below and paste it under WEB-INF/xml/config in your plug-in folder.

   Copy

   <?xml version="1.0" encoding="UTF-8"?>   
   <nameConversions>   
   <!--     
     Scope for ESRI - 1       
     Scope for MSTR - 2  
     Scope for Mapbox - 4     
   -->       
   <!--     
   ... add <elem> nodes to define new rules or override existing rules ...       
   -->         
   </nameConversions> 

3. Add your own rules to the file. Each rule will be a separate <elem> element, which contains attributes that define the rule. For help in creating the <elem> elements, refer to Rule definition and Rule resolution. Rule definition describes the attributes you can use to define a rule, and Rule resolution explains how the rules are applied.

4. Save your changes.

Rule definition

Each rule is represented by an <elem> element, which contains attributes that define the rule, as described in the table below:

Rule resolution

Rules in the plug-in are merged with rules in the out-of-the-box configuration file before the ESRI Map visualization is run. If the same rule exists in both places, the rule in the plug-in overwrites the rule in the out-of-the-box configuration file; otherwise, the new rules in the plug-in are added to the out-of-the-box rules.

The sfv and ShapeId attributes are supported in Flash maps, but not DHTML.

1. Once the rules have been merged, the visualization first looks for a scope attribute in any of the rules. If it finds a scope attribute in a rule, the visualization checks for a match on scope. For example, a match would exist if scope = 1 and the ESRI Map visualization is being viewed in MicroStrategy desktop or MicroStrategy Web, with ESRI as the map shape server. A match would also exist if scope = 2 and the ESRI Map visualization is being viewed on a mobile device. If there is no scope attribute for a rule, the rule applies to any map shape server. If there is a mismatch between the scope and the environment where the visualization is being viewed,the rule is ignored. The visualization filters the rules to include only those that have a match on scope or no scope attribute.

2. The visualization then looks at each row of data, checking to see if there is a match on the primary location name in the MicroStrategy data (the value of the n attribute) in any of the rules (<elem> nodes). If it does not find a match, it moves to the next row of data and checks again for a rule match on the primary location name. If it does find a match, it filters the rules to include only those that have a match on the primary location name in the current row of data.

3. If there is only one matching name conversion rule, the visualization applies it. It substitutes the location name provided as the value of the <elem> node for the primary location name in the MicroStrategy data (value of the n attribute). If there are multiple rules, the map visualization tries to apply the most restrictive rule first. Attributes used to restrict the application of rules are listed below in order of decreasing restriction.

• shapeID
• role
• sfv

If it finds a rule with a match on the shapeID attribute, the visualization immediately applies it; otherwise, it looks for a rule with role attribute. It continues down the list of attributes until it finds a match. It applies the rule and moves to the next row of data.

Sample rules

Sample rules are shown below:

<elem id="1" n="Russia">Democratic Russia</elem>

<elem id="2" n="Russia" scope="1">Russian Federation</elem>

<elem id="3" n="Russia" scope="1" shapeId="400">Democratic Russia</elem>

<elem id="4" n="Russia" scope="1" shapeId="400" role="3">Russian Federation</elem>

<elem id="5" n="Fairfax" sfv="Virginia" role="9">Fairfax County</elem>

<elem id="6" n="Fairfax" sfv="Virginia" shapeId="600">Fairfax County</elem>

<elem id="7" n="Fairfax" sfv="VA" shapeId="600">Fairfax County</elem>

<elem id="8" n="St. Thomas" sfv="USA" role="3">St. Thomas, Virgin Island</elem>

<elem id="9" n="Saint Thomas" sfv="USA" role="3">St. Thomas, Virgin Island</elem>

<elem id="10" n="Delhi" sfv="India">New Delhi</elem>

An explanation of each sample rule is provided below:

Rule 1:<elem id="1" n="Russia">Democratic Russia</elem>

Meaning: Whenever any map visualization sees the name 'Russia' (in the MicroStrategy data), it should use the name 'Democratic Russia' to get data from the shape server.

This is called a universal rule, because it applies to any map visualization, regardless of the shape server. There is no scope attribute.

Rule 2:<elem id="2" n="Russia" scope="1">Russian Federation</elem>

Meaning: Whenever an ESRI Map visualization sees the name 'Russia' (in the MicroStrategy data), it should use the name 'Russian Federation' to get data from the ESRI shape server.

This rule has a scope attribute that restricts the application of the rule to a map visualization with ESRI as the shape server.

Rule 3: <elem id="3" n="Russia" scope="1" shapeId="400">Democratic Russia</elem>

Meaning: Whenever an ESRI Map visualization with boundaries for countries of the world sees the name 'Russia' (in the MicroStrategy data), it should use the name 'Democratic Russia' to get data from the ESRI shape server.

This rule has two attributes—scope and shapeId—that restrict the application of the rule. The scope attribute restricts the rule to a map visualization with ESRI as the shape server, and the shapeId attribute restricts the rule to maps with world country boundaries.

Rule 4: <elem id="4" n="Russia" scope="1" shapeId="400" role="3">Russian Federation</elem>

Meaning: Whenever an ESRI Map visualization with boundaries for countries of the world and Country as the primary geo attribute sees the name 'Russia' (in the MicroStrategy data), it should use the name 'Russian Federation' to get data from the ESRI shape server.

This rule has three attributes—scope, shapeId, and role—that restrict the application of the rule. The scope attribute restricts the rule to a map visualization with ESRI as the shape server, the shapeId attribute restricts the rule to maps with world country boundaries, and the role attribute restricts the rule to maps with Country as the primary geo attribute.

Rule 5: <elem id="4" n="Fairfax" sfv="Virginia" role="9">Fairfax County</elem>

Meaning: Whenever any map visualization with County as the primary geo attribute sees the name 'Fairfax' as the County value and 'Virginia' as the state value (in the MicroStrategy data), it should use the name 'Fairfax County' instead of 'Fairfax' to get data from the shape server.

This rule has two attributes—sfv and role—that restrict the application of the rule. The sfv attribute restricts the rule to data from the state of Virginia, and the role attribute restricts the rule to maps with County as the primary geo attribute. It can get data from any shape server since it has no scope attribute.

Rule 6:<elem id="5" n="Fairfax" sfv="Virginia" shapeId="600">Fairfax County</elem>

Meaning: Whenever any map visualization with US zip codes as boundaries sees the name 'Fairfax' as the county and 'Virginia' as the state (in the MicroStrategy data), it should use the name 'Fairfax County' instead of 'Fairfax' to get data from the shape server.

This rule has two attributes—sfv and shapeId—that restrict the application of the rule. The sfv attribute restricts the rule to data from the state of Virginia, and the shapeId attribute restricts the rule to maps with US county boundaries.

Rule 7:<elem id="6" n="Fairfax" sfv="VA" shapeId="600">Fairfax County</elem>

Meaning: Whenever any map visualization with US counties as boundaries sees the name 'Fairfax' as the county and 'VA' as the state (in the MicroStrategy data), it should use the name 'Fairfax County' instead of 'Fairfax' to get data from the shape server.

This rule has two attributes—sfv and shapeId—that restrict the application of the rule. The sfv attribute restricts the rule to data from the state with the abbreviation VA (Virginia), and the shapeId attribute restricts the rule to maps with US county boundaries.

Rule 8:<elem id="7" n="St. Thomas" sfv="USA" role="3">St. Thomas, Virgin Island</elem>

Meaning: Whenever any map visualization with Country as the primary geo attribute sees the name 'St. Thomas' as the city and 'USA' as the country (in the MicroStrategy data), it should use the name 'St. Thomas, Virgin Islands' instead of St. Thomas' to get data from the shape server.

This rule has two attributes—sfv and role—that restrict the application of the rule. The sfv attribute restricts the rule to the country USA, and the role attribute restricts the rule to maps with Country as the primary geo attribute.

Rule 9:<elem id="8" n="Saint Thomas" sfv="USA" role="3">St. Thomas, Virgin Island</elem>

Meaning: Whenever any map visualization with Country as the primary geo attribute sees the name 'Saint Thomas' as the city and 'USA' as the country (in the MicroStrategy data), it should use the name 'St. Thomas, Virgin Islands' instead of St. Thomas' to get data from the shape server.

This rule has two attributes—sfv and role—that restrict the application of the rule. The sfv attribute restricts the rule to the country USA, and the role attribute restricts the rule to maps with Country as the primary geo attribute.

Rule 10:<elem id="9" n="Delhi" sfv="India">New Delhi</elem>

Meaning: Whenever any map visualization sees the string 'Delhi' as the city and 'India' as the country (in the MicroStrategy data), it should use the string 'New Delhi' instead of 'Delhi' to get data from the shape server.

This rule has an sfv attribute that restricts the application of the rule to the country of India.

Examples of rule resolution

There are multiple rules for the location name 'Russia': Rules 1, 2, 3, and 4.

• Rule 1 is a universal rule that applies to the primary location name 'Russia' with no other restrictions.

• Rule 2 applies to the location name 'Russia', but restricts the application of the rule to visualizations with ESRI as the map shape server (scope = "1").

• Rule 3 applies to the location name 'Russia', but is even more restrictive. It restricts application of the rule to visualizations with ESRI as the map shape server (scope = "1"), but it also restricts application to data rendered with US state name boundaries (shapeId = "400").

• Rule 4 applies to the location name 'Russia', but is the most restrictive. It restricts application of the rule to visualizations with ESRI as the shape server (scope = "1") and data rendered with US state name boundaries (shapeId= "400"), but it also restricts application to visualizations with Country as the primary geo attribute (role = "3")

Below are examples of rule resolution for the name 'Russia' using the sample rules described above:

• If only Rule 1 is included in the plug-in, it will be used to overwrite Rule 1 in the out-of-the-box name conversion configuration file. Rule1 from the plug-in will be applied to any row of data with Russia as the location name because it is a universal rule that applies to any map visualization.

• If both Rule 1 and Rule 2 are included in the plug-in, the visualization will first try to apply Rule 2 because it is more restrictive than Rule 1. Rule 2 has a scope attribute, and a rule with scope always takes precedence over a universal rule. If ESRI is the shape server for the map visualization (there is a match on scope), Rule 2 will be applied to any row of data with 'Russia' as the location name; otherwise, Rule 1 from the plug-in will be applied.

• If Rule 1, Rule 2, and Rule 3 are included in the plug-in, the visualization will first try to apply Rule 3 because it is more restrictive than Rule 2. It has a shape attribute which is more restrictive than a simple scope restriction. If ESRI is the shape server for the map visualization (there is a match on scope) and the current shape file is "Countries of the world" (shapeId="400"), Rule 3 will be applied to any row of data with 'Russia' as the location name; otherwise, it will try to apply Rule 2. If Rule 2 fails, it will apply Rule 1 from the plug-in.

• If only Rule 3 is included in the plug-in, the visualization will first try to apply Rule 3 because it is more restrictive than Rule 1 in the out-of-the-box name conversion configuration file. Rule 3 has a shapeId attribute which is more restrictive than a simple scope restriction. If ESRI is the shape server for the map visualization (there is a match on scope) and the current shape file is "Countries of the world" (shapeId="400"), Rule 3 will be applied to any row of data with 'Russia' as the location name; otherwise, it will apply Rule 1 from the out-of-the-box name conversion configuration file.

• If Rule 1, Rule 2, Rule 3, and Rule 4 are all included in the plug-in, the visualization will first try to apply Rule 4 because it is the most restrictive. It has a role attribute which is more restrictive than a shape attribute. If ESRI is the shape server for the map visualization (there is a match on scope) and the geo attribute is "County" (role="3"), Rule 4 will be applied to any row of data with 'Russia' as the location name (value of the primary geo attribute); otherwise, it will try to apply Rule 3. If Rule 3 fails, it will try to apply Rule 2, and if Rule 2 fails, it will apply Rule 1 from the plug-in.