Creating Address Validation Adapters

To communicate with the TCA Registry in the Oracle E-Business Suite, your adapter must meet the following technical requirements.

Communication Protocol

HTTP v1.1 Post is the only communication protocol currently supported. Because communication failures may occur during the HTTP request, a default timeout is set in TCA for 300 seconds after which the program terminates execution. You can modify this default timeout by changing the HZ: Timeout Limit for Address Validation profile option. See: Address Validation Deployment.

XML Message Format

Mandatory XML Message Format

The following XML message format is mandatory for address validation communication with the TCA Registry:

<?xml version="1.0"?> 
    <LocationService> 
      <ADAPTERCONTENTSOURCE></ADAPTERCONTENTSOURCE> 
      <OVERWRITETHRESHOLD></OVERWRITETHRESHOLD> 
      <REQUESTTYPE></REQUESTTYPE>  
      <Location> 
        <Id></Id> 
        <Address> 
          <AddressLine index="1"></AddressLine>  
          <AddressLine index="2"></AddressLine>  
          <AddressLine index="3"></AddressLine>  
          <AddressLine index="4"></AddressLine>  
          <City></City>  
          <County></County>  
          <CountrySubEntity></CountrySubEntity>  
          <Country></Country>  
          <PostalCode></PostalCode>  
        </Address>  
        <UserArea> 
          <LocationService.Location.UserArea>  
            <LocationService.Status></LocationService.Status>  
          </LocationService.Location.UserArea>  
      </Location> 
</LocationService>

Modifiable Elements

In general, you can modify the data within the <Location> </Location> tag except for the ID tag.

Attention: You must never modify the <Id></Id> tag. This tag is the internal identifier from the TCA Registry for the specific record.

The elements you can change are:

      <Address>
         <AddressLine index="1"></AddressLine>  
          <AddressLine index="2"></AddressLine>  
        <AddressLine index="3"></AddressLine>  
         <AddressLine index="4"></AddressLine>  
          <City></City>  
          <County></County>  
         <CountrySubEntity></CountrySubEntity>  
          <Country></Country> 
          <PostalCode></PostalCode> 
        </Address> 
        <UserArea>  
          <LocationService.Location.UserArea>  
            <LocationService.Status></LocationService.Status>  
          </LocationService.Location.UserArea> 
        </UserArea>

Required Tags

The <LocationService.Status></LocationService.Status> tag is a mandatory part of the XML response message returned from the vendor adapter to the TCA Registry. This tag is defined as a standardized status code in TCA, which describes the results of the address validation. You must map your solution's return statuses for each record validated to one and only one of these statuses. You must return a status for each address validated.

Because these status codes are vendor-independent, all vendor result codes must be mapped to these TCA status codes. The mappings between the vendor codes and the TCA statuses are not stored in the TCA Registry. Any configuration or remapping of the vendor codes to the TCA statuses must be done outside of TCA, for example, either in the vendor adapter or in the vendor's product itself.

The acceptable status values and the definition for each are listed in the following table below.

Code Meaning Description
0 Valid Address The highest level of validation. The address has been certified deliverable based on postal authority certifications.
1 Multiple or Ambiguous Address The address has been validated to the street level, but there is ambiguity to locate the specific address.
2 Street or Thoroughfare Match The address has been validated to the street level, but no further.
3 Municipality Match The address has been validated to the city or town level, but no further.
4 Administrative Subdivision Match The address has been validated to be within the country's main administrative subdivision such as province or state, but no further.
5 Country Match The address has only been validated to the country level, but no further.
6 No Match The address could not be validated in any way whatsoever.

Additional Information

Extra information such as delivery route, census block, tax map key, and so on, that is related to a particular address could be useful to the caller for mailing industry demographic analysis or marketing campaigns. For this type of information, or for other information for which no specific tag exists, you may add new tags to return this information back between the <LocationService.Location.UserArea> and </LocationService.Location.UserArea> tags.

Caution: Never remove or alter any existing tags listed in the <LocationService.Location.UserArea>. TCA's bulk import process uses these tags.

Nonaddress Information Handling

If an address passed to your adapter for validation contains a line of nonaddress elements such as "Attn.: Mr. ..." or "C/O" or "Care of: ...", you must store the data in that line. Your adapter must return it to the original address line.

For example:

 <Address> 
          <AddressLine index="1">Attn: Joe Smith</AddressLine>  
          <AddressLine index="2">500 Main Street</AddressLine>  
          <AddressLine index="3"></AddressLine>  
          <AddressLine index="4"></AddressLine>  
          <City>Redwood Shores</City> 
          <County>San Mateo</County>  
          <CountrySubEntity>CA</CountrySubEntity> 
          <Country>US</Country>  
          <PostalCode>94065</PostalCode>  
  </Address>

Sending Multiple Addresses For Validation

If your adapter receives multiple addresses in a single transmission, you may use the same structure from the <Location></Location> tab downward to respond.

For example, if two addresses are being passed for processing (500 Main Street, Redwood Shores, CA, and 123 Easy Street, Mountain View, CA) the message would look like this: 

<Location> 
        <Id>1001</Id>  
        <Address>  
          <AddressLine index="1">500 Main Street</AddressLine> 
          <AddressLine index="2"></AddressLine> 
          <AddressLine index="3"></AddressLine>  
          <AddressLine index="4"></AddressLine> 
          <City>Redwood Shores</City>  
          <County>San Mateo</County>  
          <CountrySubEntity>CA</CountrySubEntity> 
          <Country>US</Country> 
          <PostalCode>94065</PostalCode>  
        </Address>  
        <UserArea>  
          <LocationService.Location.UserArea>  
            <LocationService.Status></LocationService.Status>  
          </LocationService.Location.UserArea>  
        </UserArea>
</Location> 

<Location>  
       <Id>1123</Id>  
        <Address>  
          <AddressLine index="1">123 Easy Street</AddressLine> 
          <AddressLine index="2"></AddressLine>  
          <AddressLine index="3"></AddressLine> 
          <AddressLine index="4"></AddressLine> 
          <City>Mountain View</City> 
          <County>Santa Clara</County> 
          <CountrySubEntity>CA</CountrySubEntity> 
          <Country>US</Country> 
          <PostalCode>94022</PostalCode> 
        </Address>  
        <UserArea> 
          <LocationService.Location.UserArea> 
            <LocationService.Status></LocationService.Status> 
          </LocationService.Location.UserArea>  
        </UserArea>  
</Location>

XML Message Example

The following is an example of an XML message:

<?xml version="1.0"?> 
    <LocationService> 
      <ADAPTERCONTENTSOURCE>2</ADAPTERCONTENTSOURCE>  
      <OVERWRITETHRESHOLD>2</OVERWRITETHRESHOLD> 
      <REQUESTTYPE>Validate</REQUESTTYPE> 
      <Location> 
        <Id>1001</Id> 
        <Address> 
          <AddressLine index="1">500 Main Street</AddressLine>  
          <AddressLine index="2"></AddressLine> 
          <AddressLine index="3"></AddressLine> 
          <AddressLine index="4"></AddressLine> 
          <City>Redwood Shores</City> 
          <County>San Mateo</County>  
          <CountrySubEntity>CA</CountrySubEntity> 
          <Country>US</Country> 
          <PostalCode>94065</PostalCode>  
        </Address> 
        <UserArea>  
          <LocationService.Location.UserArea> 
            <LocationService.Status></LocationService.Status> 
          </LocationService.Location.UserArea> 
        </UserArea> 
      </Location> 
</LocationService>

Related Topics