Mapping Configuration Tutorial

There are a number of steps involved in configuring mapping:

Step 1 - Create a List of Field IDs and Geographical Value Set IDs

The first step is to obtain the IDs of the fields and value sets that you want to display in Map View. You can obtain these from SuperADMIN using the following command:

CODE

cat <dataset_id> <field>

Where:

<dataset_id> is the ID of the SXV4 with the geographical field.
<field> is the name of the geographical field.

For example, in the following dataset (ID: RoadSafetyData) there is a field called Accident Location that contains details of the geographical location of a road traffic accident:

TEXT

> cat RoadSafetyData "Accident Location"
[ XTAB Field : 'Accident Location' ]
    [ ID : 'SXV4__RoadSafetyData__F_Accidents__Local_Authority_(District)_FLD' ]
    [ Value Set : 'SXV4__RoadSafetyData__C_Country' ]
        [ Value Set : 'SXV4__RoadSafetyData__C_Regions' ]
            [ Value Set : 'SXV4__RoadSafetyData__C_LocalArea' ]
                [ Value Set : 'SXV4__RoadSafetyData__C_Location' ]

As shown here, this field is a hierarchy containing four nested geographical value sets.

Field ID

The format of the field ID returned in SuperADMIN is:

TEXT

<type>__<dataset>__<fact_table>__<field_id>__FLD

To configure mapping, you need the <field_id> part, which in this case is Local_Authority_(District).

In some cases, you can use the field name (in this case Accident Location, although this does not work for multilingual datasets).

Value Set ID

The format of the value set name returned in SuperADMIN is:

TEXT

<type>__<dataset>__<valueset_id>

To configure mapping, you need the <valueset_id> part.

In this example the value set IDs you need are therefore: C_Country, C_Regions, C_LocalArea and C_Location.

Step 2 - Create Geographic Layers in your Third Party Mapping Service

Use your third party mapping tools to create the geographical layers on the external mapping service for each of the fields you want to map.

Currently, SuperWEB2 supports ArcGIS Server 10.0 only.

Where possible, make sure that the data on the ArcGIS server covers all of the geographical field items in the SXV4. If there are field items in the SXV4 that do not match up with any layers on the mapping service, then Map View may not be able to generate a map when those items appear in the table.

If you have field items in your geographical fields that are genuinely non-geographical (such as "Other" or "Unknown") then you may want to use SuperWEB2's dump codes feature to prevent users from accessing Map View when non mappable items appear in a table.

Step 3 - Configure the Thematic Mapping Layers in SuperADMIN

The next step is to configure a thematic mapping layer for every mappable field. This is done in SuperADMIN. You need to define:

Some default settings. These will apply to all layers unless specifically overridden.
A definition for each individual layer. This will define:
- The layer bindings. These are the links between an SXV4 value set containing mappable items and the corresponding field in the mapping server that has the geographical shape data.
- Any default properties you want to override for this layer. Any properties you do not specifically set for a given layer will use the default value.

The easiest way to set up the thematic mapping layers is to define the settings in a text file and then import this into SuperADMIN. The following is an example that you can use as a basis for constructing your own mapping defaults. Copy this to a text file and then edit accordingly for your deployment:

Sample Mapping Layer Configuration

JAVA

{
    "defaults":{
        "joinFieldType":"STRING",
        "maxRanges":5,
        "selectionColours":{
            "noData":{
                "fillColour":"#FF0000"
            },
            "selection":{
                "fillColour":"#969696"
            }
        },
        "opacity":200,
        "defaultClassificationAlgorithm":"EqualDistribution",
        "spatialReference":"4326",
        "selectionLimit":1000,
        "defaultRanges":5
    },
    "layers":[
        {
            "arcgisServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer/13",
            "bindings":[
                {
                    "field":"Local_Authority_(District)",
                    "databases":[
                        "RoadSafetyData"
                    ],
                    "valueSet":"C_Country"
                }
            ],
            "nameField":"CTRY_NAME",
            "name":"Countries",
            "featureLayerId":13,
            "dynamicImageServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer",
            "dynamicImageLayerIds":[
                13
            ],
            "joinField":"CTRY_CODE"
        },
        {
            "chunkSizes":{
                "client":5,
                "server":5
            },
            "arcgisServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer/14",
            "bindings":[
                {
                    "field":"Local_Authority_(District)",
                    "databases":[
                        "RoadSafetyData"
                    ],
                    "valueSet":"C_Regions"
                }
            ],
            "nameField":"R_NAME",
            "name":"Regions",
            "featureLayerId":14,
            "dynamicImageServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer",
            "dynamicImageLayerIds":[
                14
            ],
            "joinField":"R_CODE"
        },
        {
            "chunkSizes":{
                "client":10,
                "server":10
            },
            "arcgisServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer/25",
            "bindings":[
                {
                    "field":"Local_Authority_(District)",
                    "databases":[
                        "RoadSafetyData"
                    ],
                    "valueSet":"C_LocalArea"
                }
            ],
            "nameField":"LA_NAME",
            "name":"Local Authorities",
            "featureLayerId":25,
            "dynamicImageServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer",
            "dynamicImageLayerIds":[
                25
            ],
            "joinField":"LA_CODE"
        },
        {
            "chunkSizes":{
                "client":30,
                "server":30
            },
            "arcgisServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer/11",
            "bindings":[
                {
                    "field":"Local_Authority_(District)",
                    "databases":[
                        "RoadSafetyData"
                    ],
                    "valueSet":"C_Location"
                }
            ],
            "nameField":"LOC_CODE",
            "name":"Location",
            "featureLayerId":11,
            "dynamicImageServiceURL":"http://arcgis10.myserver.com/arcgis/rest/services/db/MapServer",
            "dynamicImageLayerIds":[
                11
            ],
            "joinField":"LOC_CODE"
        }
    ]
}

See Mapping Property Reference for full details on each of these settings. The important ones that you will need to change based on your ArcGIS mapping service are:

spatialReference	The spatial reference ID. In most cases this should be set to 4326.
bindings	In each layer you need to specify the SXV4 value set it applies to. If you have multiple fields that contain the same geographical data (for example you have multiple datasets with an Area field that contains information relevant to Australian states and suburbs) then you can bind a single layer definition to multiple SXV4 value sets and datasets.
arcgisServiceURL	In each layer you need to specify the URL of the REST endpoint for the ArcGIS mapping server that will provide the geometry layer.
joinField	In each layer you need to specify which field on the ArcGIS server it maps to.
joinFieldType	You need to specify whether the `joinField` is a `STRING` or `NUMBER` type field. In the example here, all layers are mapping to fields of the type `STRING`, so this is defined in the `defaults` rather than being defined in every layer.
nameField	In each layer you need to specify which field on the ArcGIS server contains the names associated with the shapes for this layer. The names are displayed in Map View if a user clicks on the region. Please note that as these names come from the ArcGIS server, they will be displayed in whatever language they were configured to use in ArcGIS, regardless of the dataset or user interface language that is currently selected in SuperWEB2.
featureLayerId	In each layer you need to specify the ID of the layer on the ArcGIS server that contains the geometric data for this value set.
dynamicImageServiceURL	The URL of the REST endpoint for the ArcGIS mapping server that will provide the outline/boundary images (this is the background layer image that shows the areas that can be selected; it is a transparent image that only shows boundary outlines and labels).
dynamicImageLayerIds	In each layer you need to specify an array of IDs of the layers on the ArcGIS server that contain the outline/boundary images.

You will also need to add and remove layers as appropriate depending on how many mappable fields you have. Each layer needs to be enclosed in curly brackets and separated by commas.

The example here contains four layers for the four levels in the hierarchy of the sample Retail Banking Area field.

Import the Settings

Once you have finished editing the mapping settings in your text file, use the following command in SuperADMIN to import your new settings and replace the current mapping layer definitions:

CODE

cfg global superweb2.mapping.thematic load <filename>

For example:

CODE

cfg global superweb2.mapping.thematic load E:\Configuration Files\Mapping Settings.json

Next Steps

You may also need to complete these configuration steps: