MicroStrategy ONE

Using a Custom Shape in KML Format

Download the ESRI Map visualization plug-in provided for you and follow the steps below.

  1. Create or obtain a KML file that defines the custom shapes for your map

    You can use a KML file that you already have or you can create a new one. KML is a file format used to display geographic data in two-dimensional maps and three-dimensional Earth browsers. A code snippet from a sample KML file is shown below:

    Copy 
    <?xml version="1.0" encoding="UTF-8"?>
    <kml xmlns="http://www.opengis.net/kml/2.2">
        <Document>
            <Placemark>
                <name>attribute value</name>
                <ExtendedData>
                    <Data name="attribute key">
                        <DisplayName>attribute display value</DisplayName>
                        <Value>attribute value</Value>
                    </Data>
                </ExtendedData>
    ...
                <Polygon>
                    <outerBoundaryIs>
                        <LinearRing>
                            <coordinates>set of custom shape coordinates</coordinates>
                        </LinearRing>
                    </outerBoundaryIs>
                </Polygon>
            </Placemark>
    ...
        </Document>
    </kml>

    Each <Placemark> element contains the shape definition data for one of the custom shapes. It also contains the information needed to match each shape with its corresponding data.

    • By default, the <name> element is used to match the data with the shapes Its value must correspond to the MicroStrategy attribute element data used by the map. For example, if your custom shapes are states, the value of the <name> element might be "Maryland" or "California".

    • It is possible to override the default matching behavior by adding an <ExtendedData> element as a child of <Placemark>. This provides flexibility by allowing you to match your custom shapes with data identified in multiple ways. For example, you might do this if you want to match the shapes in your KML file with state data identified by the abbreviations of state name or object IDs, in addition to the state names.

    • The <coordinates> element (a child of <Polygon><outerBoundaryIs><LinearRing>)contains the definition of each custom shape. The definition is a set of points described by longitude, latitude, and optional altitude that determine the outline of the shape.

     

    Do the following:

    • Give the KML file that defines your custom shapes a meaningful name, such as CustomCountyShapesFile.kml, and save it in your ESRI Map visualization plug-in folder.
    • Save the KML file directly in your plug-in, or create a kml folder in the plug-in and save your custom shapes file under the kml folder.

  2. Modify the geo shape configuration file so the ESRI Map visualization can use your custom shapes

    Navigate to mstrGeoShapesConfig.xml, located under xml/config in your plug-in folder, and open it in a text editor. The file should include code like the sample shown below.

    Copy 
    <layers>
        <layer id="900" title="Custom County Map Layer" ml="CustomCountyShapesFile.kml">
            <shapeKeys>
                <shapeKey key="name" path="/ExtendedData/Data[@name='name']/value"/>
                <shapeKey key="abbr" path="/ExtendedData/Data[@name='abbreviatedName']/value"/>
                <shapeKey key="id" path="/ExtendedData/Data[@name='object_id']/value"/>
            </shapeKeys>
        </layer>
    </layers>
    <shapes>
        <shape id="901"
            custom="true"
            plugin="ConnectorForMap"
            desc="Custom Counties by Name"
            descWeb="mstrweb.7777n"
            descFlash="mstr.6666n"
            descDesktop="5555n"
            roleId="9"
            type="Polygon"
            default="false"
            shapeCat="1004"
            shapeKey="name"
            layerId="900"
            sf="name"
            sfr="2"
        />
        <shape id="902"
            custom="true"
            plugin="ConnectorForMap"
            desc="Custom Counties by Abbreviation"
            descWeb="mstrweb.7777a"
            descFlash="mstr.6666a"
            descDesktop="5555a"
            roleId="9"
            type="Polygon"
            default="false"
            shapeCat="1004"
            shapeKey="abbr"
            layerId="900"
            sf="name"
            sfr="2"
        />
        <shape id="903"
            custom="true"
            plugin="ConnectorForMap"
            desc="Custom Counties by ID"
            descWeb="mstrweb.7777i"
            descFlash="mstr.6666i"
            descDesktop="5555i"
            roleId="9"
            type="Polygon"
            default="false"
            shapeCat="1004"
            shapeKey="id"
            layerId="900"
            sf="name"
            sfr="2"
        />
    </shapes>

    Make the changes below to customize the geo shape configuration file for your environment.

    • For the child <layer> element under the parent <layers> element, do the following:

    • For the id attribute, replace "900" with a value that is unique (not one already used by MicroStrategy for a map layer). This value uniquely identifies this map layer that uses your custom shapes. It is referenced by the layerID attribute in the <shape> element.

      Multiple <shape> elements can use the same map layer (that is, the same KML file), but use different keys to match the shapes and data, such as name, abbreviation, or ID. The keys used to match are provided by the shapeKey attribute of the different <shape> elements. The match happens as follows for each custom shape:

      • The value of each shapeKey attribute is used to find a match with the key attribute in a <shapeKey> element.

      • The matching <shapeKey> element contains a path attribute, which points to a specific <Data> element in the KML file (identified by the value of the name attribute in the <Data> element).

      • The matching <Data> element has a child <Value> element, and its value is used to get the MicroStrategy data associated with this custom shape.

    • For the title attribute, replace "Custom County Map Layer" with a value that describes this map layer that uses your custom shapes.

    • For the ml attribute, replace "CustomCountyShapesFile.kml" with the name of your KML file, including the relative path, inside the plug-in folder. For example, use ml="CustomCountyShapesFile.kml" for a file saved directly under the plug-in folder, or use ml="kml/CustomCountyShapesFile.kml" for a file saved in a folder called kml under the plug-in folder.

    • For the child <shapeKey> elements under the parent <shapeKeys> element, do the following:

    • Remove any child <shapeKey> elements that you do not need for your environment. In the plug-in provided for you, there are three of these elements. One identifies the shapes by name, another by abbreviation, and the third by ID.

      • If you do not want to use one or more of these elements, delete the appropriate elements.

      • If you do want to use one or more of these elements, keep the appropriate elements.

      • If you want to identify your shapes by a different value, change the value of the key attribute in one of the <shapeKey> elements. For example, if you want to use a value called SMSA to identify your shapes, your code might look as follows:
        <shapeKey key="SMSA" path="/ExtendedData/Data[@name='SMSA']/value"/>

    • For each child <shapeKey> element that you need for your environment:

      • Set the key attribute to the value that will be used to identify the <shape> element associated with the custom shape file. This is the same value as the value of the shapeKey attribute in the corresponding <shape> element.

      • If you want the data field used to match the data with the shapes to be different from the value of the <name> element for each <Placemark> in the KML file, set the path attribute to the location of the data field you want to use, using the format /ExtendedData/Data[@name='>MyCustomShapes']/value .

        For example, assume that you want to use state abbreviations to match your custom shapes with your data and the code in your KML file looks like the code below:

        Copy 
        <?xml version="1.0" encoding="UTF-8"?>
        <kml xmlns="http://www.opengis.net/kml/2.2">
            <Document>
                <Placemark>
                    <name>custom shape name</name>
                    <ExtendedData>
                        <Data name="abbreviatedName">
                            <DisplayName>Pennsylvania</DisplayName>
                            <Value>PA</Value>
                        </Data>
                    </ExtendedData>
                    <Polygon>
                        <outerBoundaryIs>
                            <LinearRing>
                                <coordinates>set of custom shape coordinates</coordinates>
                            </LinearRing>
                        </outerBoundaryIs>
                    </Polygon>
                </Placemark>
        ...
            </Document>
        </kml>

        The code in your mstrGeoShapesConfig.xml file would look like this:

        Copy 
        <layers>
            <layer id="900" title="My Custom Map Layer" ml="MyCustomShapesFile.kml">
                <shapeKeys>
                    <shapeKey key="abbr" path="/ExtendedData/Data[@name='abbreviatedName']/value"/>
                </shapeKeys>
            </layer>
        </layers>

    • For the child <shape> elements under the parent <shapes> element, do the following:

      • Remove any child <shape> elements that you do not need for your environment. In the plug-in provided for you, there are three of these elements. One identifies the shapes by name, another by abbreviation, and the third by ID. These values are identified by the shapeKey attribute.

        • If you do not want to use one or more of these, delete the appropriate elements.

        • If you do want to use one or more of these, keep the appropriate elements.

        • If you want to identify your shapes by a different value, change the value of the shapeKey attribute in one of the <shape> elements. For example, if you want to use a value called SMSA to identify your shapes, your code might look as follows:

          Copy 
          <shape
          ...
              shapeKey="SMSA"
          ...
          />

      • For each child <shape> element that you need for your environment:

        • For the id attribute, replace the current value with one that is unique (not one already used by MicroStrategy for a shape). This value uniquely identifies this custom shape definition.

        • For the custom attribute, keep the current value of "true".

        • For the plugin attribute, if you are using the default plug-in provided for you, keep the current value of ConnectorForMap, or set it to a different name if you created a plug-in with another name.

        • For the desc attribute, change the current value to a meaningful description. This is the value that is displayed in the Boundaries drop-down on the Properties Panel for the ESRI Map visualization when you choose to display a map with areas. For example, if these are regions identified by SMSA, the value might be desc="Regions by SMSA". Or, if these are states identified by state abbreviations, the value might be desc="Custom States by Abbr". If you want to localize the description, you need to add values for the following additional attributes:

          • descWeb

          • descFlash

          • descDesktop

        • For the roleId attribute, change the current value to the geo role for your custom shapes using one of the values below:

          roleId description

          1

          		City

          2

          		State

          3

          		Country

          4

          		Location

          5

          		Latitude

          6

          		Longitude

          7

          		Other

          8

          		Zip Code

          9

          		County

          • For the type attribute, keep the current value of "Polygon".

          • For the default attribute, if you do not want this to be the default shape file, keep the current value of "false"; otherwise, set it to "true".

          • Use the shapeCat attribute if you need to have a more granular identification for a shape. The shape category is an integer, such as 1002 for countries, 1003 for US States, and 1004 for US Counties. For example, assume that you choose "7" (Other) as the value of the roleId attribute and you want to use SMSAs to define your shapes. You could set the shapeCat attribute to a value that is not used by MicroStrategy.

          • For the shapeKey attribute, set this to the value that will be used to match the shapes with the data. For example, in the code above, the values were name and id and desc. This is the value of the key attribute in the corresponding <shapeKey> element in the <layers> hierarchy.

          • For the layerid attribute, set it to the value of the id attribute you used for the <layer> element in the <layers> hierarchy that references the KML file associated with this map layer. For example, layerid="900".

    • Save your changes.

  3. Confirm that you can use the custom shapes.

    1. Restart MicroStrategy Web.

    2. Use the ESRI Map visualization in a VI dashboard and select Area Map as the Map Type on the Properties panel.

    3. Expand the Boundaries drop-down in the ESRI Properties panel. Make sure that it includes the description for your custom shapes as an option.

    4. Choose the option for your custom shapes. The Map visualization reads the KML file specified in the ml attribute of the <layer> node in mstrGeoShapesConfig.xml and renders the appropriate custom shapes.

    5. If you experience problems, check the troubleshooting tips below:

      • Make sure that the report grid you are applying the visualization to has attribute elements that match the value of the <name> element for the <Placemark> elements in the KML file.

      • Make sure that the values used in the KML and mstrGeoShapesConfig.xml files in your plug-in are the right case. All these values are case-sensitive.

      • Make sure that every element has an end tag.

      • By default, MicroStrategy Cloud customers cannot use custom cloud-based ESRI maps; they use ESRI public servers. If they want to use ESRI public servers, they must enable client authentication.