1. Implementing Payroll for the United States
  2. Manage Geography Info for the US

Manage Geography Info for the US

Vertex provides jurisdiction codes that help determine tax info for your state, county, city, and so on. Periodically, these codes require updating, such as when two cities merge, and Vertex publishes a geocodes file reflecting that change.

To make sure the payroll process has the latest info, do the following.

What you want to do

This involves

Update your US geography info

  1. Installing the geography data files

  2. Loading the geographies

  3. Resolving upload errors

  4. Reviewing the Load Geographies log file

Manage the geographies

  • Verifying geographies

  • Viewing geocodes for a geography

  • Restoring geographies

  • Configuring state display properties

  • Configuring city display properties

For further info, see the following sections.

How You Install the Geography Data Files

Vertex publishes monthly updated files that contain geography data changes (ORAMAST.txt file).

Oracle Cloud Operations installs these files for you. You automatically receive a notification when the file is available for installation, you can select a link in the notification to get the latest Vertex Payroll Tax Calculation Guide for the United States.

Note: Pennsylvania political subdivision codes, school districts, and townships are stored in a data table that's not accessible through the Geographies task. You load this data only through the Load Payroll Tax Information for US process. You can't otherwise change the values.

How You Load the Geographies

After the geography data files are installed, use the Load Geographies flow to incorporate the new data into your installation.
Note: Consider configuring a schedule to run this flow after your monthly Vertex update.

  1. From My Client Groups, click Payroll.

  2. Click Submit a Flow.

  3. Select your US legislative data group (LDG).

  4. Search for and select Load Geographies.

  5. Set the required values under Parameters.

    Field name

    What you enter

    Data Source

    Vertex is the default and only option.

    File Location

    Enter the path to the geography file if you have stored it in a location other than the default.

    File Name

    Name of the geography file.

    Enable Inactive Geographies

    Indicate if you want to enable inactive geographies.

    If you disabled a Vertex-delivered geography, use this field to reactivate it.

    Note: This doesn't apply to geographies you configured yourself. If you removed a user-defined geography, you must redefine it.

  6. Click Submit.

How to Resolve Upload Errors

If you receive errors when you run the Load Geographies task, you can use these diagnostic tests from the Diagnostic Dashboard to help identify what went wrong.

  • US HR and Payroll Geography Loader Details Test

  • US HR and Payroll Geography Diagnostics Details

  • US HR and Payroll Geography Setup and Health Check Report

  • US HR and Payroll Geography Type Validity

For further info, see Diagnostic Tests for the US in the Help Center.

If you're unable to resolve the issue, log a service request with Oracle Support.

How to Review the Load Geographies Log File

The log file for the Load Geographies task contains important and helpful info, such as error messages, informational messages, and your geocode file version number. Check the log if you experience any problems with the upload process.

To view the log:

  1. From the Navigator, select Tools and then Scheduled Processes.

  2. Search for and select the these processes.

    • Load US Postal Code Geographies

    • Load US Geography Identifiers

    • Load US Master Geographies

  3. Click View Log for each, and check them for useful info.

How to Verify the Geographies You Loaded

To verify the geographies delivered by Vertex:

  1. Start the Geographies task from your implementation project.

  2. Select US, and click Search.

    The predefined entry for United States displays.

  3. Select the green check for each type of geography data you want to verify.

    Definition data

    What it does

    Geocoding Defined

    This is the location's latitude and longitude coordinates.

    Address Cleansing Defined

    Not used by Oracle Fusion Human Capital Management.

    For further info, see Address Cleansing Configurations in the Help Center.

    Structure Defined

    The hierarchical grouping of geography types for the US.

    Hierarchy Defined

    This displays the primary and alternate names for all US geographies.

    Selecting a state's link displays its primary and alternate names and codes. Ensure you have marked the proper name as primary.

    When you load the state geographies, they include both 2-character state abbreviations and full state names.

    For info about configuring your state display properties, see Configure State Style Formats in the Help Center.

    Validation Defined

    This is the geography mapping and validation for a country's address styles, as well as its overall geography validation control.

    For further info, see Address Style Format Mapping for the US in the Help Center.

  4. To fix a missing locale, such as a city or county:

    • If no local taxes are associated with the missing locale, you can create an entry for it in the geography table.

    • If there is a local tax associated for the missing locale, you must ensure that you have the correct geocode from Vertex. Otherwise you must wait for a Vertex update to populate the missing locale.

    For further info, see Manually Add a Geography for the US in the Help Center.

How to View a Geography's Geocode

A geocode is a 9-digit code that identifies the legal jurisdiction. The first two digits represent the state, the next three represent the county, and the last four represent the city. There are no leading zeroes. The Load Geographies task creates this data.

To view a geography's geocode:

  1. Start the Geographies task from your implementation project.

  2. Search for and select United States.

  3. Select Manage Geography Hierarchy from the Actions menu.

  4. Double-click the appropriate geography name to view its tax geography code.

How You Restore Geographies

When you manually remove a Vertex geography, the data remains in the geography table but is marked as disabled.

To restore a disabled geography:

  1. From My Client Groups, click Payroll.

  2. Click Submit a Flow.

  3. Select your US LDG, and search for and select Load Geographies.

  4. Enter a payroll flow name.

  5. For Enable Inactive Geographies, select Yes. This restores all disabled geographies.

  6. Click Submit and then OK.

This doesn't apply to user-defined geographies. You must manually redefine these geographies.

How You Can Configure State Display Properties

Use the Load Geographies task to determine if addresses use full state names, state abbreviations, or both. For further info, see Configure State Style Formats in the Help Center.

How You Can Configure City Display Properties

Use the Load Geographies task to update the names for a US city. For further info, see Configure City Display Properties in the Help Center.

Related Topics