About This Release > Adapter Enhancements > GIS Adapters

GIS Adapters

Topics:

This section provides detailed descriptions of new features for GIS adapters.

Adapter for Esri ArcGIS

The Adapter for Esri ArcGIS provides access to the Esri cloud for the purposes of drawing maps and demographic layers, and also providing the following geometry functions that retrieve geometry data and geocode addresses:

  • GIS_DISTANCE. Calculates the distance between two geometry points.
  • GIS_DRIVE_ROUTE. Returns the driving route between two geometry points.
  • GIS_GEOCODE_ADDR. Returns the geometry point for a complete address.
  • GIS_GEOCODE_ADDR_CITY. Returns the geometry point for address, city, and state.
  • GIS_GEOCODE_ADDR_POSTAL. Returns the geometry point for address, postal_code.
  • GIS_GEOMETRY. Builds/converts a JSON geometry object given a geotype, WKID (Well-Known ID) spatial reference, and a initial JSON geometry.
  • GIS_IN_POLYGON. Given a geometry point and a polygon definition, returns the value 1 (TRUE), if the point is in the polygon or 0 (FALSE), if is not.
  • GIS_LINE. Given two geometry points or lines, GIS_LINE builds a JSON line defining a geometry line.
  • GIS_POINT. Given a WKID (Well-Known ID) spatial reference, longitude, and latitude, returns a JSON point defining a geometry object.
  • GIS_SERVICE_AREA. Calculates the geometry area with access boundaries within the given time or distance from the provided geometry point.
  • GIS_SERV_AREA_XY. Calculates the geometry area with access boundaries within the given time or distance from the provided coordinates and WKID spatial reference.

For detailed information about the geography functions, see BAD XREF HERE "Reporting Language Enhancements

Unified Definition for ArcGIS Server URLs and Geographic Roles

Topics:

The server comes with a file named geo_services.xml that configures all ArcGIS geographic services that are available out of the box when the server is installed.

In order to correctly retrieve and use location data in a request, the geographic roles for the fields that represent locations must be accurately defined in the request or the metadata. Geographic roles may be part of a hierarchy. For example, a city may be part of a state, and the state part of a country. The hierarchical relationships are needed in order to identify and retrieve the correct location data.

Hierarchy definitions also provide WebFOCUS with the information needed to perform AutoDrilling from a geographic role at a higher level of the geographic hierarchy to a geographic role at a lower level of the geographic hierarchy.

When you use the Web Console Data Assist tool to assign a geographic role to a field, the hierarchies display their member roles within the appropriate contexts. For example, the following image shows the hierarchies available by default, with the World hierarchy open to its first level of member roles.



Note that, by default, the available hierarchies are the EU hierarchy, the US hierarchy, and the World hierarchy.

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. In order for these customized geographic roles to be available through the server, they must be added to the geo_services.xml file.

Configuring Geographic Roles

Reference:

The geographic configuration file, geo_services.xml, is located in the catalog directory under the server home directory: 

_edahome/catalog/

The server builds the calls needed to retrieve geographic roles dynamically using this configuration file. Each role definition in the configuration file, when used in a WebFOCUS request, generates metadata and a request that is sent to Esri.

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.

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 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 the front-end tools).
  • 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 polygons or GEOMETRY for points).
  • An optional vocabulary rule element containing vocabulary elements for associating the role with a field in the metadata.

The following attributes define a geographic role.

id

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

type

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

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

role_name

Is the name of the geographic role.

role_name_title

Is the title of the geographic role, to be displayed in the tools for selection.

role_format

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.

role_format_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 tools, for example, State (Abbreviation).

geo_type

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 and geometry area.
  • "coordinate", for coordinates such as latitude and longitude.
vocabulary_rules

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

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 tools 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 tools is Latitude. The geo type is geometry, indicating that the returned data will be points or areas described using 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="geometry">
 <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 tools 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 Hierarchy Definitions

Some geographic roles exist as part of a hierarchy, and the data for the hierarchical roles are stored at the same map services endpoint (URL). Hierarchical role relationships are stored as hier elements in the geo_services.xml file.

Each hierarchy definition in geo_services.xml has the name of the hierarchy (attribute ID) and a group of LEV elements with the attributes level, geo_role, and, optionally, value. Not all defined roles can be used in hierarchies. The same role can be included in more than one hierarchy and may be on different hierarchical levels in each. However, the same role cannot be used more than once in the same hierarchy. Multiple geographic roles can be assigned to the same hierarchical level in a hierarchy.

Geographic hierarchies are defined with the following attributes:

id

Is a name of up to 50 alphanumeric characters used to identify the hierarchy.

level

Is a natural number (integer, starting with 1 for the top level) that specifies the level of the role within the hierarchy.

geo_role

Is the ID attribute of a geographic role (geo_role element).

value

Is an alphanumeric value, up to 50 characters, predefined for this geo role in this hierarchy.

Example: Sample Geographic Hierarchy Definition

The following element defines the world hierarchy. The top level is CONTINENT, both the Name role and the ISO code role. Level 2 has four COUNTRY geographic roles, corresponding to four different country formats. Level 3 contains three state formats, level 4 contains the city name, and level 5 contains two address formats and the postal code. 

<hier id="World">
   <lev level="1" geo_role="CONTINENT"/>
   <lev level="1" geo_role="CONTINENT_ISO2"/>
   <lev level="2" geo_role="COUNTRY"/>
   <lev level="2" geo_role="COUNTRY_FIPS"/>
   <lev level="2" geo_role="COUNTRY_ISO2"/>
   <lev level="2" geo_role="COUNTRY_ISO3"/>
   <lev level="3" geo_role="STATE"/>
   <lev level="3" geo_role="STATE_ISO_SUB"/>
   <lev level="3" geo_role="STATE_FIPS"/>
   <lev level="4" geo_role="CITY"/>
   <lev level="5" geo_role="ADDRESS_FULL"/>
   <lev level="5" geo_role="ADDRESS_LINE"/>
   <lev level="5" geo_role="POSTAL-CODE"/>
  </hier>

Reference: Adding the Federal Reserve Districts Geographic Role

These steps describe how to add the Federal Reserve Districts geographic role to the geo_services.xml file.

  1. Open the geo_services.xml file. The default location on Windows is:
    C:\ibi\srvnn\home\catalog\geo_services.xml

    where nn is your release of the server. For example, 77 for Release 7707.

  2. Add the role to the end of the GEO_ROLES object:.
    <geo_role id="FED-DIST" value_size="50" type="alpha" role_name="FED-DIST" role_name_title="FED District" role_format="FR_Distric" role_format_title="FED District Name" geo_type="geography">
   <vocabulary_rules>
    <vocabulary>+%FR_Distric%</vocabulary>
   </vocabulary_rules>
</geo_role>

    The ID is FED-DIST. The role name is also FED-DIST. Its format is FR_Distric. The title that displays in the tools is FED District. The definition has a vocabulary rule. The characters FR_Distric must be present.

  3. Add this role to the US Hierarchy:
    <hier id="US">
   <lev level="1" value="United States" geo_role="COUNTRY"/>
   <lev level="1" value="US" geo_role="COUNTRY_ISO2/>
   <lev level="1" value="USA" geo_role="COUNTRY_ISO3"/>
   <lev level="2" geo_role="USSTATE"/>
   <lev level="2" geo_role="USSTATE_ABBR"/>
   <lev level="2" geo_role="USSTATE_FIPS"/>
   <lev level="3" geo_role="USCOUNTY"/>
   <lev level="3" geo_role="USCOUNTY_FIPS"/>
   <lev level="4" geo_role="USCITY"/>
   <lev level="4" geo_role="USCITY_FIPS"/>
   <lev level="5" geo_role="ADDRESS_FULL"/>
   <lev level="5" geo_role="ADDRESS_LINE"/>
   <lev level="5" geo_role="ZIP3"/>
   <lev level="5" geo_role="ZIP5"/>
   <lev level="6" geo_role="FED-DIST"/>
  </hier>
  4. Add the URI to the map server layer for this role at the end of the URIS object:.
    <uri description="FedReserve Districts">
   <returned_geometry>GEOMETRY_AREA </returned_geometry>
   <returned_georole>FED-DIST</returned_georole>
   <url type="esri" authorization="none" synonym="">
http://services7.arcgis.com/L95Wwv9OjRQ0tjAs/arcgis/rest/services/FRDISTRICTS/FeatureServer/0</url>
   <parameters>
    <parm order="1" parm_name="FR_Distric" parm_georole="FED-DIST"/>
   </parameters>
  </uri>

This role will now be available to use in a request and will display in the tools.

WebFOCUS

Feedback