Address details are the defining criteria for employee and employer taxation in the United States. It is important to use appropriate address details for correct tax deductions. Payroll administrators manually validate address details of employees to identify the taxation city for the address. If the taxation city is different from the city associated with the mailing address, then the payroll administrator adds the taxation address. In addition, the calculation of school district tax is determined by the school district code available in the employee county or city tax record.
Oracle US Payroll integrates with Vertex to optionally automate address validation using the Vertex address validation web service and to determine the correct taxation address. When an address is validated using Vertex Web Services, the Vertex response also includes school district details applicable to an address. This feature helps payroll administrators with employee records that are associated with states that have school district taxes such as Kentucky, Ohio and Pennsylvania.
For information on how to enable address validation using Vertex Web Services, see: Enabling Address Validation Using Vertex Web Services
When the Vertex Web Services address validation feature is enabled, Oracle US Payroll validates:
The person's primary address details available in the:
Address window (People)
Address window (FastPath)
Enter Employees window (Maintain Using Templates)
Maintain Employees window (Maintain Using Templates)
Main Address region, Personal Information page (Employee Self-Service responsibility)
The location address available in the Location window.
Note: Address changes in any other Oracle HRMS windows or self-service pages are not validated.
Important: The Vertex Web Services address validation feature is initiated if the address details such as Address Line, City, County, State or Zip Code are changed. If the Telephone or Mobile Number is updated, then the address validation is not initiated.
In the following description, the term user indicates a payroll administrator for Oracle US Payroll and an employee for self-service.
Oracle US Payroll compares user entered address details and taxation address details with the details returned by the Vertex Web Service. If there is a difference between these two addresses, then the application alerts the user.
The application gives the user the option to choose between the address returned by the Vertex Web Service and the existing address. If the user chooses to use the address returned by the Vertex Web Service, then Address Details and Taxation Address will be populated with the Vertex returned information. Otherwise, the application retains the user entered address details.
It is possible that some addresses may differ in "Address" details and some may differ in "Taxation Address". When the address details are validated, the application first displays the recommendation for the "Address" details. Next, the recommendation for "Taxation Address" is displayed. The user can chose or ignore the Vertex recommendation for Address and Taxation Address separately. When Multiple Taxation Addresses are returned by Vertex for an address, even if the entered taxation address matches one of the recommended addresses, both are displayed to the user so that they are aware of the scenario that multiple taxation addresses are returned for the current address.
If Vertex returns an error for the existing address details, then the application displays the error details so that the user can further review the address details.
If address validation does not occur due to incomplete or incorrect setup, then the application displays a warning so that the user can review the setup to ensure successful validation. Users can still continue to save their address even if the validation is unsuccessful.
The application saves the status of the address validation. Address details are validated if the payroll administrator enters a new address or updates an existing address. When address details are updated, the application determines whether the actual address details or other information such as a telephone number are being updated. Address validation is performed only if there is actual address change. If an address was not validated earlier, then it will be validated by the Vertex web service.
Payroll administrators can run the Validate US Addresses using Vertex Web Services concurrent process to validate addresses in bulk. See: Running the Validate US Addresses using Vertex Web Services Program
If an approval or notification mechanism is set up for self-service updates, then the payroll administrator or manager receives a notification on the address change.
In the event Vertex Web Services goes down or if the setup is incorrect or corrupted, Oracle US Payroll will be unable to validate address details using Vertex web services. Payroll Professional users will be given a warning about the situation. However, no such warning is given to employees who use self-service to update their address details. Instead a notification will be sent to the employee's designated HR/Payroll Representative about the unavailability of Vertex Web Services along with any error details. If Vertex Web Services become available once more, that is, Vertex web services are restored and the details entered by the employee are validated successfully, then another notification will be sent to same designated HR/Payroll representative indicating Vertex web services availability.
The following sections explain how person address and location address validation occurs in Oracle HRMS and Oracle SSHR.
The US-specific Address window has the provision to capture the taxation address if the details specified in the Address region are different from the taxation locality. Only the primary address is validated by Vertex Web Services as this is critical for tax calculation. See: Entering People's Addresses at Sites with Oracle Payroll , Oracle HRMS Workforce Sourcing, Deployment, and Talent Management Guide (US)
Add or Update Person Primary Address: When a new primary address is added or an existing primary address is updated, the address details will be validated. If there is an address update, then before validating the address, the application determines the type of address change. For example, has an address line, city, county, state or zip code changed or has other information changed, such as telephone number? Validation will be occur only if there is a change to the actual address details.
Validation of Existing Address: It is possible that some existing addresses have incorrect details or incorrect taxation address details. To ensure that existing addresses in the system are also validated, validation occurs when they are accessed using the Person Address window. The application displays a message about Vertex address validation.
The following sections explain the different scenarios during address validation:
Setup errors: During address validation, the application displays the following errors messages if it detects any incorrect or incomplete setup:
Vertex credentials are incorrect: The application displays a Login Error message if the login to Vertex Web Services is unsuccessful due to incorrect or missing user ID and / or password.
Vertex credentials are incorrect: The application displays a Login Error message if the login to Vertex Web Services is unsuccessful due to incorrect or missing user ID and / or password.
Proxy details are not set: The application displays a Connection Error message that proxy related profile options must be set correctly.
Vertex returns an error for the entered address: Vertex may display an error for the user entered address indicating that the entered Street Address or Postal Code is not valid. In such scenarios, the application displays the error returned by the Vertex Web Service so that the user can correct their address. If a user feels that the address details provided by them are correct, then they can ignore the Vertex response.
Vertex returns an address different from the user entered one: If Vertex returns an address different from the user entered one, then the user will be informed about the difference and provided with an option to choose between the Vertex returned value and the user entered value.
Address details entered without the Taxation Address, when required: When only address details are entered and no taxation address is present, the application displays a Vertex recommended Address message with an option to save the Vertex
Address details entered with the Taxation Address: When address details are entered along with taxation address, the application displays a Vertex recommended Address message if Vertex returns a different taxation address. The user can choose to save the recommended address or click No to retain the user entered Taxation Address.
Address for which multiple taxation addresses are returned: When Multiple Taxation Addresses are returned by Vertex for an address, even if the entered taxation address matches one of the recommended addresses, both are displayed to the user so that they are aware of the scenario that multiple taxation addresses are returned for the current address.
Feedback for address validation: When address validation occurs for primary address details in the person Address window, the application displays the following feedback for those addresses not previously validated by Vertex web services:
a. Feedback for address validation: When address validation occurs for primary address details in the person Address window, the application displays the following feedback for those addresses not previously validated by Vertex web services:
b. In the case of address details entered with the Taxation Address and if Vertex returns the same address, then the application displays a confirmation message that the address validation is complete and that the Vertex recommended address matches the entered Taxation Address.
Payroll administrators can add or update person addresses using People Management Templates. Address validation using Vertex Web Services will be performed when the person address is created or updated using the Enter Employees or Maintain Employees templates and the user will be provided with any Vertex recommended address. For more information, see: Features of Address Validation Using Vertex Web Services. Note that during address validation, recommendation for Taxation Address will be displayed only in the person Address window. The People Management templates will display only the recommendations for the "Address". When an address which was saved in the People Management template is opened in the person Address window, then this address will be validated and taxation address recommendations are displayed.
Employees can update their address details using the Main Address region in the Personal Information self-service page. When an employee updates the address details, Vertex Web Services validates address details and displays a warning to the user if a correction is required. The application presents an option to either Ignore the recommended address or Replace the address with the recommended address. If Replace is selected, then the existing address will be replaced with the Vertex recommended address. If Ignore is selected, then the existing address is saved and Vertex recommendation is ignored. If Vertex cannot locate the address entered, then the application displays a message that the entered address could not be located.
The self-service page does not have fields to capture the "Taxation Address". The recommendation provided by Vertex on Taxation Address is not displayed to the Self-Service user as they might not be aware of the taxation requirements of their jurisdiction. For such address changes, the payroll administrator can run the Validate US Addresses using Vertex Web Services concurrent program to validate all the addresses modified through self-service. They can also validate the addresses using Person Address window, if the number of addresses updated are one or two, instead of running the concurrent program.
When address details entered in Oracle HRMS and Oracle SSHR are passed to Vertex Web Services, Vertex Web Services provides necessary corrections to street address details along with the taxation details. Users can choose to utilize the Vertex recommended Street Address or continue to save the details that they entered.
The Location Address window for the US localization has a provision to record the taxation details of the address. For more information on how the location address validation feature works, see: Features of Address Validation Using Vertex Web Services.
When address details are validated using Vertex Web Services, then along with taxation details, the applicable School District is returned. When Vertex returns "School District" information for an address, then the School District code will be added to the City tax record automatically. The School District code will be added only if there is no School District already entered for the Employee tax records. For Pennsylvania, School District code will be added even if the School District code is already present for some other City in that state.
See "Address Validation Using Vertex Web Services" for an overview of the feature.
Profile Options Summary
The following table lists the profile options that you can define when enabling the Address Validation Using Vertex Web Services feature.
| Profile | Configurable Level | Values (default value in boldface) |
|---|---|---|
| Use Vertex Web Services for US Address Validation | Site, Application, and Responsibility | Yes, No |
| HR: Vertex Web Service Host | Site | payroll.online.vertexinc.com |
| HR: Vertex Web Service Port | Site | 443 |
| HR: Implementation Date for US Address Validation (DDMMYYYY) | Site, Application, Responsibility, and User | 01010001 |
The following sections discuss the profile options.
Determines whether US address details must be validated using Vertex Web Services.
If the profile option is not set or set to No, then address validation using Vertex Web Services is not performed.
If the profile option is set to Yes, then address details will be validated if there is any change in the address details or a new address is added. If there are any differences between the user entered address details and Vertex recommended details or any errors are encountered in accessing Vertex Web Services, then the application notifies the user. In such a scenario, the user can save the changes.
Determines the effective date that the application must consider when you run the Validate US Addresses Using Vertex Web Services concurrent program. This date is applicable to the Update Method parameter option and the application uses this date as the basis for either updating or inserting Vertex recommended addresses. See "Running the Validate US Addresses using Vertex Web Services Program " for more information.
Stores the Vertex Web Services host details.
Stores the Vertex Web Services port details.
See "Address Validation Using Vertex Web Services" for an overview of the feature.
To enable the Address Validation Using Vertex Web Services feature, complete the following steps:
Prerequisites
To enable address validation using Vertex Web Services
Set Up Login Credentials
When you purchase the license from Vertex to access Vertex Web Services, Vertex provides the login credentials corresponding to Vertex Web Services.
Set up the login credentials. The PAY_US_ADDRESS_VALIDATE.SET_VERTEX_CREDENTIALS procedure is created to help users set up the login credentials for each business group by calling the procedure as in the following command:
EXEC pay_us_address_validate.set_vertex_credentials
(p_business_group_id => <Business Group ID>,
p_username => <Username>, />
p_password => <Password>);Set Up Vertex Web Service Host and Port Details
Define the following profile options to set up the Vertex Web Services host details and login credentials:
HR: Vertex Web Service Host
HR: Vertex Web Service Port
Caution: The HR: Vertex Web Service Host and HR: Vertex Web Service Port profile options are delivered with default values of payroll.online.vertexinc.com and 443 respectively. In future, if the host and port are relocated, then you must update these profiles as required.
See: Address Validation Using Vertex Web Services Profile Options
Set Up Proxy Server Details, if Required
To access Vertex Web Services, you must have internet access. If the connection to internet is governed by a proxy server, then define the Applications Server-Side Proxy Host And Domain and Applications Proxy Port profile options.
Configure the Vertex Server Certificate Details in Oracle Database Wallet
As the HTTPS server needs to be accessed from UTL_HTTP, configure the Vertex Server Certificate details in Oracle Database Wallet. After the server details are configured, set up the Oracle Database Wallet path in the Database Wallet Directory profile option. You must indicate that the Wallet needs to be set up as Autologin. Ensure that the application user has access to the Database Wallet files at Host level.
Refer to the following document on My Oracle Support for Wallet setup:
Enabling SSL or TLS in Oracle E-Business Suite Release 12.2 (Doc ID 1367293.1) has instructions in Section 4: Database Tier Setup
Configure Access Control Lists (ACL) to Use Vertex Web Services for Address Validation
Configure Access Control Lists with Vertex Server details and proxy details, if any to allow access using UTL_HTTP.
The following section provides information on how to set up Access Control List to allow outbound network connections:
Starting with Oracle Database 12c, to access any hosts outside the database, it is mandatory to configure the Access Control List (ACL) to include the details related to that destination host. US Address validation using Vertex Web Services is one of such process where database invokes Vertex Web Services across internet. Therefore, you must list the details related to Vertex Web Service in ACL corresponding to the APPS user.
The host and port details of Vertex Web Services are https://payroll.ondemand.vertexinc.com and 443 respectively. In case these details change in future, you must reconfigure the Access Control list with the latest details. Confirm with Vertex on the host details while purchasing the License. You must add these details to ACL with the HTTP privilege. Note that both HTTP and HTTPS servers are to be configured with the HTTP privilege only.
Execute the following PL/SQL block to append the Vertex Web Services related details to ACL corresponding to the APPS user, with the HTTP privilege. This must be executed by a database user having SYSDBA privileges.
BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE (
host =>'payroll.ondemand.vertexinc.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(privilege_list =>
xs$name_list('http'),
principal_name => 'APPS',
principal_type =>
XS_ACL.PTYPE_DB)
);
END;
If the proxy configuration is necessary to access the internet from the application, then configure the proxy host details in ACL with http_proxy privilege. Execute the following PL/SQL block to add the proxy details to ACL. Replace <Proxy Host>, <Proxy Lower Port> and <Proxy Upper Port> with applicable details before executing the PL/SQL block.
BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE (
host => '<Proxy Host>',
lower_port => <Proxy Lower Port>,
upper_port => <Proxy Upper Port>,
ace =>
xs$name_list('http_proxy'),
principal_name => 'APPS',
principal_type => XS_ACL.PTYPE_DB)
principal_type => XS_ACL.PTYPE_DB)
END;
The following query will be helpful in determining the privileges granted to the APPS user in ACL. This can be executed to verify if the APPS user has the required privileges to Vertex Web Services host and Proxy host, after executing the above PL/SQL blocks.
select PRINCIPAL,
PRIVILEGE,
GRANT_TYPE,
HOST,
LOWER_PORT,
UPPER_PORT
from DBA_HOST_ACEs
where PRINCIPAL = 'APPS';
Set Up the HR: Use Vertex Web Services for US Address Validation Profile Option
Set the HR: Use Vertex Web Services for US Address Validation profile option to Yes to indicate that address details are to be validated using Vertex Web Services. To disable the validation temporarily for any reason, set the profile option to NO.
See: Address Validation Using Vertex Web Services Profile Options
Set Up the HR: Implementation Date for US Address Validation (DDMMYYYY) Profile Option
Set this profile option to determine the effective date that the application must consider when you run the Validate US Addresses Using Vertex Web Services Program. This date is applicable to the Update Method parameter option and the application uses this date as the basis for either updating or inserting Vertex recommended addresses. See "Running the Validate US Addresses using Vertex Web Services Program " for more information.
List States For Which Address Validation can be Skipped, if Necessary
You may wish to skip the address validation for some states such as Texas, which does not have local taxation requirements. To configure the states for which address validation can be skipped, a user updatable lookup HR_US_SKIP_VALIDATION_STATES is available. Use the HR_US_SKIP_VALIDATION_STATES lookup to list the states for which the address validation can be skipped. The application refers to this lookup before initiating the address validation using Vertex Web Services. If the state of any address is listed in the HR_US_SKIP_VALIDATION_STATES lookup, then validation of that address will be skipped.
Post Setup Step
Run the Validate US Addresses using Vertex Web Services concurrent program to perform address validation in bulk. See "Running the Validate US Addresses using Vertex Web Services Program " for more information.
See "Address Validation Using Vertex Web Services" for an overview of the feature.
See "Enabling Address Validation Using Vertex Web Services" for information on how to enable address validation using Vertex Web Services.
The Address Validation using Vertex Web Services feature enables payroll administrators to validate one person address at a time. To validate multiple addresses at the same time, run the Validate US Addresses using Vertex Web Services concurrent program.
Run this program from the Submit Request window.
To run the Validate US Addresses using Web Services program
In the Name field, select Validate US Addresses using Web Services
Enter the following parameters. Note that if the optional parameters are left blank, then all the person primary addresses and location addresses will be validated.
| Parameter | Optional or Mandatory | Description |
|---|---|---|
| Address Type | Optional | Select either value:
|
| State | Optional | Select the state that the application must use to validate addresses. |
| Skip already validated Address | Optional | If the value is set to Yes, then this concurrent program validates only those addresses that were not validated earlier using Vertex Web Services This is the default value for this parameter. If this parameter is set to No, then the program validates all the addresses, based on the selection criteria even if the addresses were validated earlier using Vertex Web Services. |
| Validate from Year (YYYY) | Optional | Enter the year from which the addresses must be validated. This parameter is applicable to person addresses only. |
| Person | Optional | Select the person whose address details must be validated. This parameter gets enabled only if Person Primary Address is selected as the Address Type. This parameter displays all the persons in the business group. This list gets filtered if a state is selected or Validate from Year (YYYY) field is entered. |
| Location | Optional | Select the location for which address details are to be validated. This parameter gets enabled only if Location Address is selected as the Address Type. This parameter displays all the US locations by default. This list gets filtered if a state is selected. |
| Output Report Type | Optional | Select the output report type that you want the program to generate:
|
| Validation Mode | Optional | This parameter provides the option to either perform only address validation or to commit the Vertex recommended addresses to the database.
|
| Update Method | Mandatory | This parameter is enabled only if you select Person Primary Address in the Person parameter and COMMIT in the Validation Mode parameter. The application processes the Update Method parameter based on the date set in the HR: Implementation Date for US Address Validation (DDMMYYYY) profile option. The concurrent program uses the following rules to process the Update Method parameter:
Select one of the following options:
The following example explains how the Update Method parameter works: Set 01082017 (that is 01-August-2017) as the value in the HR: Implementation Date for US Address Validation (DDMMYYYY) profile option. Example 1: An address is recorded in the database effective 01-July-2017. During address validation, the application will end date this address effective 31-July-2017. A new address record with Vertex recommended address details is created effective 01-August-2017. Example 2: An address is recorded in the database effective 10-August-2017 (that is after the implementation date). During address validation, the application will end date this address record on the same date, that is, 10-August-2017. A new address record with Vertex recommended address details is created effective 11-August-2017. |
| Output Report Format | Mandatory | Select Comma Delimited (.CSV) or HTML. HTML is the default value. The .csv file is a spreadsheet file with filter capabilities. The HTML file provides details in various sections. |
Viewing the Program Output
The program output file provides the following information:
Person Primary Addresses and Location Addresses validated along with the existing details and Vertex recommended details.
Addresses for which validation ends in error due to incorrect address details with the response provided by Vertex. If there is any connectivity issue, then employees will be skipped from processing after 5 employees end in error with connectivity related issues.
If an address is incorrect or not locatable, then Vertex will indicate that no correction could be provided.
Columns in the Output File
Use the following columns in the output file to get information on the validations and updates performed by the concurrent program. If the output file is a comma-delimited file (.csv), then you can filter the data in the spreadsheet.
State: You can use this column to identify states with the local taxation address such as Pennsylvania and Ohio and prioritize updates to incorrect addresses.
Details:
If REVIEW is selected as the Validate Mode parameter value, then the column heading is named “Details to be Updated”.
If COMMIT is selected as the Validate Mode parameter value, then the column heading is named “Details Updated”.
Validation Status:
Shows whether address validation is successful or validation ended in an error.
Indicates address details and status using the following descriptions:
Recommendation Accepted
Recommendation not accepted
Address Validated
Address not validated
Postal Address
Taxation Address
Payroll Professional
Self-Service User
Existing SD Code: Displays the employee's existing SD (School District) code in their local tax rules record.
Recommended Address Code: Displays the SD code that Vertex recommends.
Status of SD Code: Displays whether an employee's local tax rules record is automatically populated with the Vertex recommended school district code. A status of Success indicates that the value is automatically populated, otherwise a status of Error.
Additionally, there are separate columns for primary resident address and taxation address that show the status of address validation.
Recommendations bypassed: Shows address details for which recommendation provided by Vertex has been bypassed. This column will also indicate if it is the employee or the Payroll Professional who has bypassed the recommendations.
For Person Primary Address, the users shown are Employee or Payroll Professional.
For Location Address, the user shown is Payroll Professional.
During address validation, the application uses Vertex recommendations and following rules to update addresses:
If a self-service user has entered the address and skipped Vertex recommendations, then the concurrent program skips the Vertex recommendations for that address. But the concurrent program will populate the Taxation address if Vertex recommends any.
If an address was not validated earlier, then recommendations provided for both the Address and Taxation Address are updated.
If Multiple Taxation Addresses are recommended by Vertex and the user-entered taxation address is different from the recommended addresses, then first of the recommended taxation addresses is updated as the taxation address. If an existing taxation address matches any of the recommended taxation addresses, then update will not be made. If there is no user-entered taxation address, then the first of the recommended taxation address is updated as the taxation address. The output file includes the recommended details and details which were present earlier. This will help the payroll administrator to review in case if they wish to see what happened to a particular employee address.