This chapter covers the following topics:
Geography Hierarchy is a data model that lets you establish conceptual parent-child relationships between geographies. A geography, such as Tokyo or Peru, describes a boundary on the surface of the earth. Applications can extrapolate information based on this network of hierarchical geographical relationships.
For example, in Geography Hierarchy, the state of California is defined as the parent of San Mateo county, which is the parent of Redwood City, which is the parent of the postal code 94065. If you enter just 94065, the application can determine that the postal code is in California, or that the corresponding city is Redwood City.
Oracle Trading Community Architecture (TCA) and other Oracle E-Business Suite applications can leverage Geography Hierarchy for various uses related to locations, such as real-time address validation and tax calculation. The geography information is centrally located in TCA and shared among all the applications.
Note: TCA does not provide seeded geography information, but the data model and features to set up and store that information.
The top level of Geography Hierarchy is Country, so the hierarchy essentially contains countries and their child geographies. Other aspects of Geography Hierarchy include:
Geography Type: A divisional grouping of geographies, either geopolitical (for example, City, Province, and District) or physical (for example, Island, Mountain, and Continent).
Geography: A physical space with boundaries that is a defined instance of a geography type. For example, San Jose is a geography of the City geography type.
Country Structure: A hierarchical grouping of geography types for a country. For example, the structure for United States is: State, County, City, then Postal Code.
Geography Usage: A classification of a set of geography types to indicate the purpose and usage of that data, for example for taxation. For example, the State, County, and City geography types can be used for calculating US sales tax.
Master Reference Geography Hierarchy: The Geography Hierarchy data considered as the single source of truth. It is all the data, including geography types and geographies, that you define and maintain in TCA Geography Hierarchy administration.
The geography usage for the entire hierarchy is Master Reference, and defined geography types and geographies are considered master reference geography types and geographies. For example, Country is a universally recognized geography type, and United States is considered a master geography.
Master Reference Geography Hierarchy data is used as the source for validating addresses, and for creating user-defined geography hierarchies, which include boundaries, or zones, for business-specific uses. So while the Master Reference Geography Hierarchy is the source of truth for geography data, for example with all the US states defined, user-defined geography hierarchies contain entities with arbitrary boundaries, namely, tax zones that encompass various US states in each zone.
User-Defined Geography Hierarchy: A classification of geographical data, created from master reference data or manually entered, for tax purposes. A user-defined geography hierarchy can have:
Zones: User-defined geographical boundaries for the specific geography usage, based on Master Reference Geography Hierarchy data. For example, a Tax geography usage can have the San Jose Tax zone, and a Sales geography usage the Southwest Sales Region zone. The boundaries of the Southwest Sales Region zone would enclose various master reference states, for example California, Arizona, Nevada, Utah, and New Mexico.
Zone Type: A layer or grouping of zones, for example, Income Tax and Sales Regions zone types. The Sales Regions zone type would contain zones such as Southwest Sales Region, Midwest Sales Region, and so on.
Geography Name Referencing is the process of validating and mapping address elements of existing location table records against master reference geographies. For example, for a specific address record, the CA value in the STATE column of the HZ_LOCATIONS table is mapped to the master reference geography of CA.
Related Topics
Administering Geography Hierarchy
Set up and maintain the Master Reference Geography Hierarchy, which can:
Be used across the Oracle E-Business Suite for various purposes and tasks related to locations, for example address validation.
Provide the underlying structure from which administrators create tax zones for user-defined geography hierarchies.
Note: You perform setup tasks for user-defined geography hierarchies outside of Geography Hierarchy administration. To create and update tax zones and zone types, you use Oracle E-Business Tax.
See: Geography Hierarchy Overview.
From the Geography Hierarchy: Countries page, you can access the various features for administering each country in the Master Reference Geography Hierarchy. The original list of available countries comes from the FND_TERRITORIES table. After you initially define the hierarchy for a country, you can continue to maintain it using the same administration functionality.
Optionally use Receivables lookups to add and manage the code types and data providers available for defining geographies. This table shows the lookup types.
| Geography Attribute | Lookup Type | Lookup Meaning |
|---|---|---|
| Code Type (for geography codes, such as FIPS Code or ISO Country Code) | HZ_GEO_IDENTIFIER_SUBTYPE | Geography Identifier Subtype |
| Data Provider (source of geography information) | HZ_GEO_DATA_PROVIDER | Geo Data Provider |
See: Defining Receivables Lookups, Oracle Receivables Implementation Guide.
Structure:
Define country structures of geography types to establish how geographies within the country are hierarchically related.
Create geography types as needed.
See: Defining Country Structures.
Important: You must define the country structure before you can define specific geographies for a geography type within that structure. You should define a complete and accurate country structure the first time around, because you cannot insert new levels between existing levels after geographies are defined. You can add new levels below the lowest level in a structure.
For example, you want to use Geography Hierarchy for United States address validation. For the US country structure, you define the geography type Country as the parent of State, State as parent of County, County as parent of City, and City as parent of Postal Code.
View Details:
View and define the list of geographies for a specific geography type in the country structure. See: Viewing and Defining Geographies.
For example, for the United States, you first define all the states for the State geography type, then the counties in each state, the cities in each county, and the postal codes in each city.
For each geography in the list, you can also click Update to enter additional details.
Tip: Access to View Details (for the list of geographies) and the corresponding Update (for information specific to a geography) is available in a hierarchical manner, based on your country structure. On each View Details page, you can access the list of geographies for the geography type one level down.
For example, when you click View Details for United States in the Geography Hierarchy: Countries page, you get a list of states within the US. For each state, you can click View Details to get the list of counties within that state, or click Update for that state. So, if you want to update information for Redwood City, the navigation path is: View Details for United States > View Details for California > View Details for San Mateo > Update for Redwood City.
Update: Maintain information specific to a geography. See: Updating Geographies.
For example, while you define a specific state in the US, you can enter alternative names or codes for that state.
Manage Validations: Specify geography validation level and address styles at the country level, and map geography types in country structures to location table attributes for address or tax validation purposes. See: Managing Validations.
Run the Geography Name Referencing process to map addresses in location tables to master reference geographies. This mapping is used for tax calculation. See: Geography Name Referencing Process.
Tip: Set these related profile options:
HZ: Batch Size for committing records in Geography Name Referencing process
HZ: Number of workers for a given Geography Name Referencing request
See: Profile Options and Profile Option Categories.
Important: If you are also using Flexible Address Formatting and have an address style assigned to the country that you are administering, then make sure that your Geography Hierarchy setup is consistent.
See: Address Formatting, Oracle Trading Community Architecture User Guide.
For the selected country, define the hierarchical structure of geography types to establish:
How geographies can be related.
The types of geographies you can define for that country.
The geography types available for geography or tax validation.
With the Country geography type implicitly at the top of the structure, the subsequent levels are numbered with 1 as the next level after Country.
Caution: After you first define a country structure, you cannot later insert levels. You can only add geography types below the current lowest level, and delete geography types without defined geographies. This setup is usually a one-time procedure, so make sure that you define a complete and accurate country structure the first time.
You must add a geography type as a level in the country structure before you can define a geography for that geography type in a country. For example, before defining the state of California, the State geography type must be added to the United States country structure.
Prerequisites
Procedure
This table describes some terms in the pages used for this procedure.
| Term | Description |
|---|---|
| Geography Exists at Level | Indicates if at least one geography is defined for the geography type at this level. For example, if the geography type is State, and California is already added as a geography for State, then a geography exists at this level. At this point, you cannot make changes to this level, including deletion. |
If the country structure is completely undefined, then optionally copy the structure from another country.
The application provides you with a set of available master reference geography types. If needed, you can create a unique geography type before adding it to this or any other country structure.
Important: To ensure that Oracle E-Business Suite applications leveraging Geography Hierarchy can allow users to enter or search a range of postal code values, use the seeded Postal Code geography type. Do not create a new type, for example called Zip Code.
Add geography types as needed. Each geography type is added right below the current lowest level.
You can delete geography types only if geographies do not exist at that level. If the geography type is not the lowest level in the country structure, then you delete not only that level but all levels below it.
Note: If you delete a geography type, then all associated validation mappings and usage for this level are also deleted. See: Managing Validations.
Related Topics
Administering Geography Hierarchy
View the list of geographies for a specific geography type in the selected country, and add geographies as needed. For example, for the State geography type in the United States, you would define the list of US states.
Prerequisites
Procedure
Add geographies that are not already on the list. The entered name and code are, by default, the primary name and code for that geography. Primary names and codes are displayed to users.
Note: Specify a code type, if known, and leave User Entered as the data provider, as you are manually entering in the geographies.
If you currently have no geographies to enter for this geography type, but do have geographies for any lower level in the country structure, then select Geographies Unknown for This Level and go to Step 4.
Update specific geographies to provide more information, for example to enter additional names or code, or select another as primary. See: Updating Geographies.
As needed, delete geographies to inactivate them, only if the geography does not have active geographies in the subsequent level of the country structure.
Note: All child geographies of the geography that you are inactivating are no longer valid. You cannot view or update those geographies. For example, inactivating a county invalidates all its cities and postal codes, as well as any user-defined zones within that county.
If there is a subsequent level in the country structure, click View Details to view and define geographies for the next geography type. For example, State is a parent of County in the United States country structure, and you are currently viewing the list of states. You can click View Details for California for the list of counties within that state.
Related Topics
Geography Name Referencing Process
Administering Geography Hierarchy
Update a specific geography, for example the city San Francisco or the country United States, and specify details such as the geography's date range, primary and alternate names and codes, and parent geographies.
Prerequisites
Procedure
This table describes some terms in the pages used for this procedure.
| Term | Description |
|---|---|
| Data Provider | The source of the geography name or code. The data provider is User Entered if the name or code was manually added to the list of geographies. See: Defining Geographies. |
| Time Zone | The time zone that the geography is in. |
Update general information for the geography.
Update primary and alternate names and codes. Names must be unique, and codes unique within a code type.
An example of primary and alternate name usage is in real-time address validation. For example, the primary name is CA and alternate names are Cal and Calif. If the user enters Cal or Calif, then the application considers that valid and saves the value to the HZ_LOCATIONS table as CA.
You cannot delete a primary name or code until another name or code is selected as primary.
If you select a different name or code as primary, that change is reflected when you revisit the View Details page.
Add geographies, from one level above in the country structure, that are parents of the geography you are updating. When this geography was first defined, a parent-child relationship was already established.
For example, when defining Humboldt county, you added Gilmore City as a city, so Humboldt is the parent of Gilmore City. Gilmore City, however, is also in Pocahontas county, so when you update Gilmore City, you add Pocahontas as a parent. When you define or view details for Pocahontas county, Gilmore City would already be displayed as a city within that county. See: Defining Geographies.
Related Topics
Geography Name Referencing Process
Administering Geography Hierarchy
Geography Hierarchy information can be used for geography validation, which ensures that addresses have valid geographic information, such as the correct combination of city, state, and postal code. Because street level data is not included, however, this validation does not ensure that addresses pass postal validation and can have postal deliveries to those locations.
The real-time address validation in Oracle Trading Community Architecture and other Oracle E-Business Suite applications leverage geography validation based on the information set up in Geography Hierarchy. See: Real-Time Address Validation, Oracle Trading Community Architecture User Guide. Oracle E-Business Tax validation and calculation also leverages Geography Hierarchy.
Use the Manage Validations page to perform tasks that are part of the address or tax validation setup. See: Setting Up Real-Time Address Validation.
For address validation, specify the validation level for the country. If the level is not No Validation, then map the country structure to HZ_LOCATIONS source table attributes, and mark the mapping with Geography Validation usage. If you also use Flexible Address Formatting for this country, then do the mapping using the address style assigned to the country as a guide.
Prerequisites
Procedure
This table describes some terms in the pages used for this procedure.
| Term | Description |
|---|---|
| Address Style | The address style element from Flexible Address Formatting or HR address formatting. |
| Geography Validation Level for Country |
|
| Maps to Attribute | Column from the source table. |
| Source Table | The table that addresses are stored in, either HZ_LOCATIONS or HR_LOCATIONS_ALL. |
Enter the source table first, as that determines the available address styles.
The first time you set up for either the HZ_LOCATIONS or HR_LOCATIONS_ALL source table, you select a source table but not an address style because you must first set up a default address mapping.
Note: No Style represents the default validation mapping, which is used if:
A country is not associated with an address style.
An application is not set up with Flexible Address Formatting.
The FAF or HR address style used in a particular situation is not set up here with a dedicated validation mapping.
As long as you set up validation mapping for No Style, you ensure that geography or tax validation can be performed for any address in this country, based on your setup. After No Style is set up for the respective source table, you can define additional mapping for specific address styles:
If you do use Flexible Address Formatting for this country, select HZ_LOCATIONS and the FAF address style assigned to this country.
For HR_LOCATIONS_ALL, you can select from any HR address style.
Tip: Set up geography mapping and validation for only HR address styles that are potentially used for this country.
Note: Additional mapping after No Style for either source table is optional, even if you do use FAF for this country.
For address styles other than No Style, then select the source table and address style combination to display the address style mapping. Use the style information to help you map the address for validation purposes, in the next step.
Map geography types from the country structure to attributes from the source table. You can map different types to the same attribute for different address styles, but not for the same style.
Tip: Map only geography types that you want to use for geography or tax validation purposes. For example, the mapping determines which address elements are part of the address validation process.
Only mapped elements are processed when the Geography Name Referencing runs. See: Geography Name Referencing Process.
For any mapped geography type and attribute combination, optionally select at least one validation usage, tax or geography. The address elements corresponding to the geography types must be correct for the address to be considered valid for the selected usage.
Note: If an address element is mapped to a geography type, but not selected for geography validation usage, then suggested values can be provided for that address element during address entry, but that element is not validated.
Geography validation applies only to the HZ_LOCATIONS table.
Geography Validation: For example, for the United States, you specified the North America address style for HZ_LOCATIONS addresses. Then for that combination, you map the US country structure to HZ_LOCATIONS attributes, and specify that Country, State, and Postal Code values are used for geography validation. When the user enters a US address using this address style, the address must have the correct country, state, and postal code combination, based on Geography Hierarchy data, to be considered geographically valid.
Use the Geography Validation check box to specify which address elements are mandatory during address entry, based on the geography validation level for country selected. The Geography Validation Level for Country can be:
Error
Warning
Mandatory Fields Only
No Validation
Note: The Geography Validation usage determines which address elements are mandatory during address entry, based on the geography validation level selected. For example, if the validation level is Mandatory Fields Only, then users must enter address elements that have Geography Validation usage, but the address can still be saved if values are invalid.
Tax Validation: For example, for the United States, you had specified the North America address style for HR_LOCATIONS_ALL. Then for that combination, you map the US country structure to HR_LOCATIONS_ALL attributes, and specify that County, State, and City are used for tax validation. When a sales transaction involves an address with the North America address style, the address must have the correct county, state, and city combination, based on Geography Hierarchy data, to be considered valid for tax calculation.
Important: For either usage, do not skip more than one consecutive level unless you are certain that the selected geography types can uniquely identify geographies.
For example, the country structure is: State, County, City, and Postal Code, and you want to select just State and Postal Code for geography or tax validation. However, for the combination of California and 94065, the city can be either Redwood Shores or Redwood City. In this case, you should also select at least City for geography or tax validation.
(Geography validation only) Specify the validation level for this country, if at least one mapping is selected for geography validation usage.
Note: If you select Mandatory Fields Only, Geography Validation will change to Mandatory in the Geography Mapping and Validations section.
Related Topics
Geography Name Referencing Process
Administering Geography Hierarchy
Run the Geography Name Referencing process to validate address elements in location tables, such as HZ_LOCATIONS and HR_LOCATIONS_ALL, against geographies in the Master Reference Geography Hierarchy. For each address, or location record, the program identifies which master reference geography an address element maps to, if any. Oracle E-Business Tax uses this mapping information for business-specific purposes such as tax calculation.
Geography Name Referencing is based on Geography Hierarchy validations data and setup. See: Managing Validations.
This table describes the validation mapping of the United States country structure to the HZ_LOCATIONS table, for the North America address style.
| Geography Type | Maps to Attribute | Tax Validation | Geography Validation |
|---|---|---|---|
| Country | COUNTRY | Yes | Yes |
| State | STATE | Yes | Yes |
| County | COUNTY | Yes | No |
| City | CITY | Yes | Yes |
| Postal Code | POSTAL_CODE | No | Yes |
An address in HZ_LOCATIONS has address elements as shown in this table.
| HZ_LOCATIONS Column | Address Element Value |
|---|---|
| ADDRESS1 | 500 Oracle Parkway |
| CITY | Redwood City |
| COUNTY | Santa Clara |
| STATE | |
| POSTAL_CODE | 94065 |
| COUNTRY | United States |
The Geography Name Referencing process runs on the HZ_LOCATIONS table and processes this address. The program:
Checks for the address style associated with this address, for this example, the North America address style. The program can use the corresponding validation mapping setup from Geography Hierarchy for the next step.
Compares each address element, or HZ_LOCATIONS attribute, that is mapped to a geography type in the US country structure, against the corresponding master reference geography defined in Geography Hierarchy. This table describes the results of this comparison for each element in the above address.
| Geography Type | HZ_LOCATIONS Column | Address Element Value | Master Reference Geography | Result |
|---|---|---|---|---|
| Country | COUNTRY | US | United States | Address element is validated and mapped to the master reference geography, because the address value is a defined code or alternate name. |
| State | STATE | CA | Based on the other entered address elements, the program can extrapolate and map to CA as the state if CA is the only possible value. For example, there are no other states with the San Mateo county and Redwood City combination. | |
| County | COUNTY | Santa Clara | San Mateo | Address element is not valid and therefore not mapped to the master reference geography. Mapping status is Error. However, if the program can find a unique correct value, as with the state, then the address element is corrected and mapped accordingly. |
| City | CITY | Redwood City | Redwood City | Address element is validated and mapped to the master reference geography. |
| Postal Code | POSTAL_CODE | 94065 | The master reference geography value is not available, so the mapping status is Error. |
The concurrent program log provides a summary of the results of the processed addresses.
As indicated in the Geography Hierarchy validation mapping, the Country, State, County, and City geography types are used for tax validation. For any address, tax is calculated based on the master reference geographies that each address element is mapped to, as a result of Geography Name Referencing. For the address in this example, if the State and County address elements cannot be mapped, then tax validation and calculation cannot occur for State and County tax, but can for Country and City tax because those address elements are validated and mapped.
For the countries that you run Geography Name Referencing for:
Define the Geography Hierarchy country structure. See: Defining Country Structures.
Define geographies for each geography type in the country structure. See: Viewing and Defining Geographies and Updating Geographies.
Map geography types in the country structure to location table attributes, and specify geography usage. See: Managing Validations.
Set these profile options:
HZ: Batch Size for committing records in Geography Name Referencing process
HZ: Number of workers for a given Geography Name Referencing request
Tip: If performance of the Geography Name Referencing process seems low, check with your database administrator about increasing the number of workers.
See: Profile Options and Profile Option Categories.
Location Table Name: Select the table with the address records that you want to process, either HZ_LOCATIONS or HR_LOCATIONS.
Run Type: Specify to process all records, only records that previously resulted in error, or only new records that this program has never processed.
Address Usage: Specify to run the program for either the tax or geography validation usage, or both. The program provides results that correspond to address elements and geography types with the selected usage.
Country: Enter the country to process addresses for.
Location ID From and Location ID To: Enter a range of location IDs to identify the addresses to process.
Start Date and End Date: Enter a date range to process only addresses that are active within this range.
Related Topics