Configuring Geographic Information

The following standard unified geographic roles are configured by default and cannot be changed. These geographic roles create a hierarchy that can be used to drill down or up between levels of administration in maps, reports, or charts.

• CONTINENT.
• COUNTRY.
• STATE.
• COUNTY.
• CITY.
• POSTAL CODE.

To add a geographic role to the configuration, you can add a new Esri map or a shapefile hosted by the Server and associate a geographic role with the new map. You can also implement NUTS geographic roles support.

Configuring Properties of Geographic Roles

The following describes columns for geographic roles in the configuration editor.

name

Is the unique name of the geographic role. It cannot have spaces, but it can have underscores (_).

Next to the name is an indicator of whether the role is a standard role or a customized role.

title

Is the description of the geographic role that is displayed in reports and in drop-down lists in the WebFOCUS tools.

returned_geometry

Is the type of geographic data returned from the map service for rendering on the map.

Valid values include:

• GEOMETRY_AREA
• GEOMETRY_POINT
• GEOMETRY_LINE

When you have configured the properties, click OK to return to the Geo Configuration Editor.

The new role will display on the list of roles, Click Save to save it in the geographic configuration.

Adding a New Role for an Esri Map

To add an Esri geographic role, click Add ESRI map on the Geographic Configuration Editor.

The Create a new ESRI map role dialog box opens, as shown in the following image.

Configure the following map service properties.

name

Is a name for the geographic role.

title

Is a title to display in the WebFOCUS tools.

returned_geography

Select the type of geometry that is returned from the map service for this role. Valid values are:

• GEOMETRY_AREA. Returns JSON polygon definitions.
• GEOMETRY_LINE. Returns JSON line definitions.
• GEOMETRY_POINT. Returns a JSON point.

url

Is the URL to the map service that provides the geographic data.

Click Verify after entering the URL to verify that the map service is available by going to the specified URL.

Service Parameters

Add as parameters any additional geographic roles needed to identify the exact location of the new role. For example, a city name needs state and country parameters.

http://services7.arcgis.com/L95Wwv9OjRQ0tjAs/ArcGIS/rest/services/wfretail_sub_regions/FeatureServer/0

DEFINE FILE WF_RETAIL_LITE

REGION/A50 (GEOGRAPHIC_ROLE=REGION) = BUSINESS_SUB_REGION;
END
 
GRAPH FILE WF_RETAIL_LITE
SUM COGS_US
BY REGION
WHERE COUNTRY_NAME EQ 'United States'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH CHOROPLETH
ON GRAPH SET STYLE *
TYPE=REPORT, CHART-LOOK=com.esri.map, $
TYPE=DATA, COLUMN=N2, BUCKET=color, $
*GRAPH_JS_FINAL
"extensions": {
"com.esri.map": {
"overlayLayers":
[
{
"ibiDataLayer": {
"map-metadata": {
"map_by_field": "
REGION"
}
}
}
],
"baseMapInfo":
{
"customBaseMaps":
[
{
"ibiBaseLayer": "gray"
}
]
}
}
}
*END
ENDSTYLE
END

Adding a New Role for a Server-Hosted Map

A server-hosted map is based on a shapefile. You must upload the shapefile (.dbf) to an application folder accessible to the server. The server will transform it to ibijson format.

An ESRI shape file is actually a collection of at least four files:

• .dbf file. The .dbf file is a standard database file used to store attribute data and object IDs. A .dbf file is mandatory for shape files.
• .shp file. The .shp file is a mandatory Esri file that gives features their geometry. Every shapefile has its own .shp file that represents spatial vector data.
• .shx file. The .shx file is a mandatory Esri shape index position file. This type of file is used to search forward and backward.
• .prj file. The .prj file is an optional file that contains the metadata associated with the shapefiles coordinate and projection system.

All files must have exactly the same name and to be located in the same directory. If they are not, the shapefile conversion will fail.

When there are several possible keys associated with a geometry, a drop down list of detected key names will be displayed. Select any one of these fields. No selection required when there is a single geometry key.

The shapefile should only be in the GCS_WGS_1984 - World Geodetic System 1984 (decimal degrees) coordinate system.

To add a geographic role for a Server-hosted map, click Add WFRS map on the Geographic Configuration Editor.

The Add WFRS hosted map dialog box opens, as shown in the following image.

Configure the following properties.

role name

Is a name for the geographic role.

Geometry type

Select either POLYGON or POINT from the drop-down list.

Esri shape

Enter the name of the application directory where the shapefile resides, or click the ellipsis (...) to navigate to the application directory. Then select the .dbf file for the role.

Load to app

Enter the name of the application directory where you want to place the ibijson file, or click the ellipsis (...) to navigate to the application directory.

Quantization type

Quantization is the process of transforming a large set of input values to a smaller set of values. When transforming the shapefile, the server will quantize points that are too close together in order to optimize map rendering performance. Two methods are available for quantization, LINEAR or GRID. The default is LINEAR.

Quantization_X

Is the threshold value for the x-axis.

Quantization_Y

Is the threshold value for the y-axis.

If the map has multiple keys, a drop-down list displays so that you can select one.

Click OK when you have finished configuring the properties.

The new role is added to the configuration as a customized role, as shown in the following image.

Click Save to save this role to the configuration.

You can test the role by right-clicking the role in the configuration editor and clicking Test. A sample map will be generated, as shown in the following image.

Adding NUTS Support

Nomenclature of territorial units for statistics (NUTS) are geographic roles specific to the European Union.

To add NUTS geographic roles to the configuration, click Add NUTS support on the Geographic Configuration Editor.

The NUTS geographic roles are added, as shown in the following image.

Click Save to save these roles to the configuration.

Adding Support for Extended Postal Codes

Click Add extended postal codes to add support for Level 1 and Level 2 postal codes used in certain countries.

Customizing Vocabulary Rules

For each geographic role, a set of vocabulary rules define how to recognize when a field name should automatically be assigned to that role. If you right-click a role, you can click Customize vocabulary from the shortcut menu.

Elements in a rule are connected by the Boolean logic operation OR (only one needs to be satisfied). Each vocabulary element contains words enclosed with special characters. Words in the rule element are connected by the Boolean logic operation AND (all need to be satisfied).

A word may be prefixed and/or suffixed with the percent character (%), which is a placeholder for any sequence of characters. If an element contains more than one word, each word has to be prefixed by the character plus (+) or minus (-). Plus indicates that the word must be found in the column name. Minus indicates that word must not be found in the column name.

For example, the following are the vocabulary rules for the role COUNTRY.

To add another rule, click Add optional.

When you are finished, click OK.

Click Save to save these rules to the configuration.

You can edit an existing basemap definition or add a custom basemap.

Basemaps that are not vector maps are pre-rendered image tiles. Vector basemaps are delivered from ArcGIS Online as vector tiles that are rendered on the client based on a style file that is delivered with the vector tiles. This provides customization options not available with pre-rendered image tiles.

A default set of vector basemaps is configured in the GEO configuration editor in the Server. However, you can configure additional vector basemaps as needed. You can find the basemap URLs and Style URLs at http://www.arcgis.com.

Using Standard Basemaps

To add a new basemap or customize an existing basemap, select Basemap from the Object drop-down list.

The following image shows the GEO configuration editor with the Basemap object selected, showing the list of standard basemaps.

Configuring Basemap Properties

The following is a description of the properties used for basemap configuration.

name

Is the name of the basemap.

Next to the name is an indicator of whether the basemap is a standard basemap or a customized basemap.

icon

Is the name of the thumbnail for the basemap (for a standard basemap) or the URL to the thumbnail (for a customized basemap) that will appear on the Basemap drop-down list in the WebFOCUS tools or the Change Basemap map widget.

title

Is a title to display on the Basemap drop-down list in the WebFOCUS tools or the Change Basemap map widget.

url

Is the URL to the map service that provides the basemap, for a customized basemap. The map service URL can be copied from the URL field on the page showing a custom basemap. For a standard basemap, the URL is already stored in the server geographic configuration file and is not displayed.

type

Valid values are tiled and vector.

addon_json

Specifies additional JSON properties for rendering the map. For a custom vector basemap, enter the basemap map service URLs and Style URLs needed for rendering the map. The map can consist of an array of layers, each with a URL and its style URL. The style URL for each layer can be found by clicking View Style on the page showing the map layer. The map service URL for each layer can be copied from the URL field on the page showing the map layer. Enter the information in the following format.

  {"baseMapLayers":
   [
     {"url": "url_to_map_service", "styleUrl": "url_to_style"},
     {"url": "url_to_map_service", "styleUrl": "url_to_style"},
      ...
   ]
  }

Note: If the vector basemap has multiple layers, its page on ArcGIS online will have links to each layer.

Editing the Properties of a Standard Basemap

To customize the properties of an existing basemap, right-click the basemap line and click Customize BASEMAP.

The Customize Basemap dialog box opens, as shown in the following image.

Edit the properties you want to change. If you change the URL, you can click Verify to make sure the map service is valid and accessible.

When you are finished, click OK, then click Save on the GEO configuration editor Basemaps page.

Adding a Custom Basemap

To add a new basemap to the configuration, click Add.

The Create a BASEMAP dialog box opens, as shown in the following image.

Enter a name for the basemap, a URL to the thumbnail, a title to display, and the URL to the map service that provides the basemap, and click Verify.

When you have configured the properties, click OK, then click Save on the GEO configuration editor Basemap page.

{"baseMapLayers":[{"url": "https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer","styleUrl": "https://www.arcgis.com/sharing/rest/content/items/75f4dfdff19e445395653121a95a85db/resources/styles/root.json?f=pjson"}]}

TABLE FILE WF_RETAIL_LITE
PRINT
     ID_CUSTOMER
     COGS_US
	 QUANTITY_SOLD
     COMPUTE LONGITUDE/D12.2 =CUSTOMER_LONGITUDE;
     COMPUTE LATITUDE/D12.2 = CUSTOMER_LATITUDE;
BY  STATE_PROV_NAME
BY  ID_CUSTOMER NOPRINT
WHERE COUNTRY_NAME EQ 'United States';
ON TABLE NOTOTAL
ON TABLE PCHOLD FORMAT XML
END

To add a new context layer or customize an existing context layer, select ContextLayer from the Object drop-down list.

The following image shows the GEO configuration editor with the ContextLayer object selected.

Configuring Context Layer Properties

Following is a description of the properties used for context layer configuration.

name

Is the name of the context layer.

Next to the name is an indicator of whether the context layer is a standard context layer or a customized context layer.

authorization

Is the type of authentication needed to access this context layer. Valid values are:

• silent. Credentials for your ArcGIS application are provided in the connection string of the Adapter for Esri ArcGIS.

  Note: For instructions for configuring the Adapter for Esri ArcGIS, see the Adapter Administration manual.

• none. No authorization is needed.
• named. User credentials are provided in the connection string of the Adapter for Esri.
• on premises. User credentials for a locally hosted ArcGIS server are provided in the connection string of the Adapter for Esri.

layer type

Is the type of context layer. For a cached layer, the layer type is tile. For a layer that is rendered dynamically, the layer type is featurelayer.

title

Is a title to display on the demographic layer drop-down list in the WebFOCUS tools.

uri

Is the URL to the map service that provides the context layer.

addon_json

Specifies additional JSON properties needed for rendering the context layer. For example, smartMapping properties define the border styles within the context layer.

Customizing the Properties of an Existing Context Layer

To customize the properties of an existing context layer, click the down arrow next to a context layer name or right-click the context layer line and click Customize context layer.

The Customize CONTEXTLAYER dialog box opens, as shown in the following image.

Edit the properties you want to change. If you change the URI, you can click Verify to make sure the map service is valid and accessible.

When you are finished, click OK, then click Save on the GEO configuration editor Context Layers page.

Adding a New Context Layer

To add a new context layer to the configuration, click Add.

The Create a Customized CONTEXTLAYER dialog box opens, as shown in the following image.

Enter a name for the context layer, the authorization type, a layer type, a title to display, any additional JSON needed for rendering the context layer, and the URI to the map service that provides the context layer, and click Verify.

When you have configured the properties, click OK, then click Save on the GEO configuration editor Context Layer page.