Enabling Address Validation Using Vertex Web Services (Oracle HRMS)

Enabling Address Validation Using Vertex Web Services

For an overview of the feature, see: Address Validation Using Vertex Web Services.

To enable the Address Validation Using Vertex Web Services feature, complete the following steps:

Prerequisites

To utilize the address validation functionality, you must purchase the license from Vertex to access Vertex Web Services.

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
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