Adding a Custom Geographic Role


The GEO configuration editor in the WebFOCUS Server provides a tool for editing or adding properties for geographic roles.

On the WebFOCUS start page, from the Management Center, click Server Workspaces to access the WebFOCUS Reporting Server Workspace area. Alternatively, from the WebFOCUS Home Page, click the Settings menu and click WebFOCUS Server. When the WebFOCUS Reporting Server browser interface opens, open the Tools menu and click Workspace. The Workspace area opens.

In the Reporting Server Workspace area click Settings, point to Geo Services, then click Edit Configuration. The GEO configuration editor opens displaying the configured geographic roles, as shown in the following image.

Reference: Editing the List of Geographic Roles

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.

Note: Some users may not be able to run maps with custom geographic roles when the default reporting server security configuration is in place.  To allow a user to run content with custom geographic roles, on the Access Control page of the WebFOCUS Server Console, right-click the role that the user privileges are based on and click Directory/File Privileges, then enable both the Execute and List privileges for geo_services_user.xml.

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.

Example: Adding the WebFOCUS Regions Geographic Role

The following properties add the WebFOCUS Regions role to the configuration.

Note: The parameter name corresponds to the field name in the FeatureLayer referenced in the following URL:

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

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.

The following request uses the WebFOCUS Regions geographic role in a map request.

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

The output is shown in the following image.

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 backwards.
  • .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.