Customizing the List of Geographic Roles

Reference:

Geographic Role Definitions
Adding the WebFOCUS Retail Regions Geographic Role

Customers with Enterprise Data often have map layers that represent their territories, events, or logistical information. These are published as Map Services to either a subscription based in the Esri Cloud (ArcGIS.com) or on an internal portal. This portal is available with ArcGIS Server 10.3 installations. More information can be found at

http://server.arcgis.com/en/portal/.

InfoAssist comes with a configuration file (geo_services.xml) that contains elements that describe all of the geographic roles, geographic hierarchies, URLs to the map services, and base maps available to InfoAssist. This file is located in the catalog directory under the server home directory:

_edahome/catalog/

Note: Optionally, on the WebFOCUS® Reporting Server, you can show this directory on the application tree by clicking Show edahome, edaconf, edaprfu, scaroot, edatemp, edalog and foccache for all users on the Filter menu of the Reporting Server Console Applications page. Then, you can edit the geo_services.xml file directly in the Reporting Server Console.

The geographic role selections that you can make in InfoAssist are built dynamically using this configuration file. Each role definition in the configuration file, when selected in InfoAssist, generates metadata and a request that is sent to Esri in order to download the appropriate map and place the markers or polygons on the map.

A geographic role can be part of a hierarchy. For example, the World geographic role is at the top of a hierarchy that contains continents, countries, states, and cities. These hierarchies are also described in the geo_services.xml file.

To add a custom geographic role, you must add the necessary parameters for the geography to this file.

You can also customize the geographic roles available by deleting geographic role definitions from the <GEO_ROLES> object. To configure Esri On Premise, you should remove any geographic role definition that references a URL that points to a location outside of your locally hosted Esri server.

Following standard XML syntax rules, each element is enclosed in element start and end tags (<elementname>, </elementname>), and attribute values are enclosed in double quotation marks (").

Reference: Geographic Role Definitions

A geographic role is stored as a geo_role element in the geo_roles object of the geo_services.xml file. A geographic role must be defined with:

An ID that will identify the role in the configuration file.
A format and length for the data to be returned.
A role name.
A display title for the role name (to appear as a selection in Map dialog box in InfoAssist).
An optional role format (if the role can have multiple formats, such as a name and an abbreviation).
A display title for the format.
A role type (geography for geographic objects such as country or state, geometry for geometry points, geometry areas, or geometry lines, or coordinate for longitude or latitude).
An optional vocabulary rule element containing vocabulary elements for associating the role with a field in the metadata.

The syntax is

<geo_role id="id" value_size="size" unified="false" role_name="rname"
        role_name_title="rname_title" role_format="rformat"
        role_format_title="rformat_title" geo_type="gtype"
        type="datatype" >
        <vocabulary_rules>
            <vocabulary>vrule</vocabulary>
         </vocabulary_rules>
      </geo_role>

where:

id="id"

Is an alphanumeric uppercase value, up to 50 characters, used to identify the geographic role.

type="datatype"

Is the data type for the ID. Can be one of the following.

"alpha" for alphanumeric data, formats An or In.
"integer" for integer numeric data, format In.
"numeric" for fractional numeric data, formats Pn.m, Dn.m, or Fn.m.
"text" for text data, format TXn.

value_size="size"

Is the optional number of characters in USAGE format length (any, if not set).

role_name="rname"

Is the name of the geographic role.

role_name_title="rname_title"

Is the title of the geographic role, to be displayed in the Map dialog box for selection.

role_format="rformat"

Is an optional format for the geographic role, useful when the role can be referenced using multiple formats, such as a name, an ISO code, and an abbreviation. Standard role titles include the following.

NAME. Specifies that the role defines the name of a geographic entity, such as Florida.
ABBR. Specifies that the role defines an abbreviation, such as FL.
ZIP3. Specifies that the role defines a 3-digit zip code.
ZIP5. Specifies that the role defines a 5-digit zip code.
FIPS. Specifies that the role defines a FIPS (Federal Information Processing Standard) code.
ISO2. Specifies that the role defines an ISO 3166-2 code published by the International Organization for Standardization (ISO).
ISO3. Specifies that the role defines an ISO 3166-3 code published by the International Organization for Standardization (ISO).
LINE. Specifies that the role defines one line of a role, just as an address line.
FULL. Specifies that the role defines a full geographic role, such as a full address.

role_format_title="rformat_title"

Is an optional title for the format of the geographic role. It will be shown in parentheses along with the role title in the Map dialog box, for example, State (Abbreviation).

geo_type="gtype"

Is one of the following predefined role types.

"geography" for geographic objects, such as country or state.
"geometry" for geometry objects, such as geometry point, geometry line, and geometry area.
"coordinate" for coordinates, such as latitude and longitude.

<vocabulary>vrule</vocabulary>

Is an element that consists of a group of vocabulary elements that explicitly describe column names for the geographic role. These rules will be used to select the best geographic data for the role.

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 place holder 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 the word must not be found in the column name.

Once you have added a geographic role definition, you can run the geo_srv_roles procedure on the WebFOCUS Reporting Server to see that the parameters were added correctly.

Example: Sample Geographic Role Definitions

The following defines the State Abbreviation geographic role. The role ID is USSTATE_ABBR. The role name is USSTATE with a role format of ABBR. The titles that show in the Map dialog box are US state (Abbreviation). The format is A2, and the vocabulary rules specify that the characters state must be present, but the characters iso, capital, and population must not be present. The geo type is geography, indicating that the returned data will be a geographic area.

<geo_role 
id="USSTATE_ABBR"
 value_size="2"
 type="alpha" 
role_name="USSTATE" 
role_name_title="US state" 
role_format="ABBR" 
role_format_title="Abbreviation"
 geo_type="geography">
<vocabulary_rules>
<vocabulary>+%state%-%iso%-%capital%-%population%</vocabulary>
</vocabulary_rules>
</geo_role>

The following is a role definition for latitude values. The role ID is LATITUDE. The role name is also LATITUDE. Its format is numeric. The title that displays in the Map dialog box is Latitude. The geo type is coordinate, indicating that the returned data will be points. The vocabulary rules specify that the characters latitude must be present.

<geo_role
 id="LATITUDE"
 type="numeric"
 role_name="LATITUDE" 
role_name_title="Latitude"
 geo_type="coordinate">
 <vocabulary_rules>
  <vocabulary>%latitude%</vocabulary>
 </vocabulary_rules>
</geo_role>

The following is the definition for the city role. The ID is CITY. The role name is also CITY. Its format is NAME. The title that displays in the Map dialog box is City (Name). The definition has a set of vocabulary elements. Only one of the elements in the list must be true. Therefore, the characters city, or town, or country plus capital, or state plus capital must be present.

<geo_role
 id="CITY" 
type="alpha" 
role_name="CITY" 
role_name_title="City" 
role_format="NAME" 
role_format_title="Name"
 geo_type="geography">
 <vocabulary_rules>
  <vocabulary>+%city%-%population%</vocabulary>
  <vocabulary>+%town%-%population%</vocabulary>
  <vocabulary>+%country%+%capital%-%population%</vocabulary>
  <vocabulary>+%state%+%capital%-%population%</vocabulary>
 </vocabulary_rules>
</geo_role>

Reference: Geographic Role URI Definitions

After adding a geographic role, you must add its URI to the <URIS> object in the geo_services.xml file. The syntax is.

<uri description="description">
   <returned_geometry>type </returned_geometry>
   <returned_georole>role</returned_georole>
   <url type="esri" authorization="auth" synonym="">
         "url_to_georole"
   <parameters>
    <parm order="number" parm_name="pname" parm_georole="parmrole"/>
   </parameters>
  </uri>

where:

"description"

Is a description for the geographic role to which the URI is pointing.

type

Is any supported geometry type, such as GEOMETRY AREA.

role

Is the name of the returned geographic role.

"auth"

Is the type of authentication needed to access this geographic role. Valid values are:

silent. Credentials for your ArcGIS application are provided in the connection string of the Adapter for Esri.
none. No authorization is needed.
named. User credentials are provided in the connection string of the Adapter for Esri.
on premise. User credentials for a locally hosted ArcGIS server are provided in the connection string of the Adapter for Esri.

"url_to_georole"

Is the URL for the geographic role.

parm order="number"

Is the number of a parameter needed to retrieve the correct geographic role.

parm_name="pname"

Is the name of the parameter associated with parm order.

parm_georole="parmrole"

Is the name of the geographic role associated with parm order.

Once you have added the URI, you can run the geo_srv_map_uris procedure on the Reporting Server to see that the parameters were added correctly.

Note: You must add the base URL to the list of proxy URLs in the esri_arcgis_rest.xml file. For example:

<ESRI_URL URL="//services7.arcgis.com/L95Wwv9OjRQ0tjAs/ArcGIS" DESCRIPTION="Custom Data" />

Reference: Adding the WebFOCUS Retail Regions Geographic Role

These steps describe how to add the WebFOCUS Retail Regions geographic role to the geo_services.xml file.

Open the geo_services.xml file. The default location is:
```
C:\ibi\WebFOCUSnn\srv\home\catalog\geo_services.xml
```
where nn is your release of TIBCO WebFOCUS. For example, 82 for release 8.2
Add the role to the end of the GEO_ROLES object:
```
<geo_role id="REGION" value_size="50" unified="false"
        role_name="WF_Region" role_name_title="WF_Region"
        role_format="NAME" role_format_title="NAME"
        geo_type="geography" type="alpha" >
        <vocabulary_rules>
            <vocabulary>+%region%</vocabulary>
         </vocabulary_rules>
      </geo_role>
```
The ID is REGION. The role name is WF_Region. Its format is NAME. The title that displays in the Map dialog box is WF_Region. The definition has a vocabulary rule. The characters region must be present.

Run the geo_srv_roles procedure on the Reporting Server to see that the role was added correctly. The output is shown in the following image.

Add the URI to the map server layer for this role at the end of the URIS object:

<uri description="WFRetail Regions" >
    <returned_geometry>GEOMETRY_AREA</returned_geometry>
    <returned_georole>REGION</returned_georole>
    <parameters_georoles>
       <parm position="1" parm_georole="REGION" />
    </parameters_georoles>
    <urls>
      <url type="esri" authorization="none" synonym=""
      value="//services7.arcgis.com/L95Wwv9OjRQ0tjAs/ArcGIS/rest/services/wfretail_sub_regions/FeatureServer/0"
      provider="Esri" >
          <keys key="default" />
          <parameters_names>
             <parm position="1" parm_name="SUB_REGION" />
          </parameters_names>
       </url>
    </urls>
</uri>

Note: You must add the base URL to the list of proxy URLs in the esri_arcgis_rest.xml file. For example:

<ESRI_URL URL="//services7.arcgis.com/L95Wwv9OjRQ0tjAs/ArcGIS" DESCRIPTION="Custom Data" />

Optionally, on the Reporting Server, run the geo_srv_map_uris procedure to see if the parameters were added correctly. The output is shown in the following image.

You will now be able to select this role from the Map As menu the next time you start WebFOCUS, as shown in the following image.

Example: Using the WebFOCUS Retail Regions Role in a Map Layer

This example configures a map layer using the WF_Region role.

In the Data pane, right-click a field that contains subregion data, for example. On the shortcut menu, select Map As and then select the WF_Region role, as previously illustrated. The output is shown in the following image: