This chapter covers the following topics:
Adapters allow for data integration services between the Oracle Trading Community Architecture (TCA) Registry and a third party or deploying company data source. TCA uses adapters for D&B integration and address validation.
TCA provides a seeded Dun & Bradstreet adapter for integration with D&B. After proper configuration, this adapter enables online purchasing of D&B data through Oracle E-Business Suite applications. See: Online Purchasing, Oracle Trading Community Architecture User Guide.
Address validation is the process of comparing a raw or user-entered address against a verified or authorized database to determine if the address is recognized and factually correct according to the source database. An outcome of address validation is address correction, in which a user-entered address is evaluated, corrected, completed, and returned for further processing.
The TCA address validation feature uses a central XML open-standards based "black box" that allows integration with third party service providers and custom solutions, through adapters that you or the third party provide. The black box can accept requests from callers, such as the Address Validation program, and integrate with adapters to process those requests.
An example of this process is:
The Address Validation program sends requests with address data to the address validation black box.
The black box invokes the appropriate vendor adapter based on adapter configuration settings, and passes an XML message request to the appropriate third party or custom adapter.
Utilizing an XML message format, the adapter generates an outbound XML document and passes a location service request to a vendor solution that allows single or bulk synchronous transaction requests using a synchronous HTTP v1.1 Post connection.
The vendor solution interprets these transaction requests, validates the addresses against the vendor's location libraries, and sends an XML response back to the adapter.
The adapter returns an XML response to the Address Validation program.
Through this process, addresses are validated in the TCA Registry against the standard address information that the adapter is linked to, resulting in a validated, corrected, enriched, or geocoded address in the TCA Registry.
This solution is optimized for synchronous processing of bulk requests. It is not intended for asynchronous processing of single interactive requests such as when users enter data through a user interface.
Related Topics
Creating Address Validation Adapters
To use a third party, custom-made, or seeded Dun and Bradstreet adapter with TCA, you must define and administer adapter configurations. For each third party or custom adapter, you specify information such as the adapter name and description, the method used to invoke the adapter, and the XML message format that the adapter uses.
First you search for the adapter to administer, by name or, for address validation adapters, the country that the adapters support. You can then:
View adapter configurations.
Update adapter configurations.
Create adapter configurations after you verify from the search results that the adapters do not already exist.
See: Configuring Adapters.
Note: Only enabled adapters can be used to process data from the TCA Registry.
Related Topics
Introduction to Administration
When you view, create, or update adapter configurations, the information displayed or to be entered is the same. After you view an adapter, you can optionally update its configuration.
Adapter configuration is the same for all third party or custom address validation adapters, but different for the seeded Dun and Bradstreet adapter. D&B adapter configuration is part of the D&B integration setup. See: Setting Up Third Party Data Integration.
This table describes some terms in the pages used for this procedure.
| Term | Description |
|---|---|
| Host Address | The D&B HTTPS URL which D&B provides for access to the D&B database. |
| User Name | The user ID that D&B provides for users to log in to the D&B database. |
| Password | The password that D&B provides for users to log in to the D&B database. |
Update the default host address only if D&B provides you a different URL.
Register all users who need access to purchase D&B data online.
Note: The user names you enter become the available values for the HZ: D&B User Name profile option. As part of D&B integration, this profile option must be set with all the available values. If there are multiple user names, then all values are set at the User level.
This table describes some terms in the pages used for this procedure.
| Term | Description |
|---|---|
| Invoke Method | The method used to communicate with the adapter, for example HTTP V1.1 Post. |
| Host Address | The host address of the adapter, applicable only if the invoke method is HTTP. |
| Default Batch Size | The default number of records the adapter can handle in one batch. This number is used if the maximum batch size is not defined. |
| Maximum Batch Size | The maximum number of records the adapter can handle in one batch. This number must be greater than or equal to 1. |
| Message Format | The XML message format that the adapter uses. |
| Default Replace Status Code | For adapters used with address validation, the default code that must be reached or exceeded for an address to be updated with data from the adapter service. This default code is used if the caller to address validation adapters does not specify a code. For example, if the code is 2, the service linked to the adapter must validate a TCA address up to at least the street or thoroughfare level before updating that address with the service's standard address. Addresses with validation status 0, 1, or 2 would be updated. |
This table describes the available status codes.
| Status | 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 | Address has been validated to the street level, but there is ambiguity to locate the specific address. |
| 2 | Street or Thoroughfare Match | Address has been validated to the street level, but no further. |
| 3 | Municipality Match | Address has been validated to the city or town level, but no further. |
| 4 | Administrative Subdivision Match | Address has been validated to be within the country's main administrative subdivision, such as province or state, but no further. |
| 5 | Country Match | Address has only been validated to the country level, but no further. |
| 6 | No Match | Address could not be validated in any way. |
Enter the adapter details.
For adapters used with address validation, specify the countries that the adapter supports. For example, if an adapter can validate only addresses from France and Australia, only those two countries should be listed.
Enable the adapter to process addresses for specific countries.
Note: If an adapter is used to set the HZ: Default Location Service Adapter profile option, you cannot disable that adapter unless you set the profile option with another adapter. See: Address Validation Deployment Category.
Indicate if the adapter is the default to use for specific countries. Only one adapter can be the default for each country. For example, if the Gorman adapter is already the default for Italian addresses, and you try to set Elcaro as the default adapter, you can either stay with Gorman or switch to Elcaro.
Related Topics
To communicate with the TCA Registry in the Oracle E-Business Suite, your adapter must meet the following technical requirements.
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.
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>
In general, you can modify the data within the <Location> </Location> tag except for the ID tag.
Important: 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>
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 address is verified. |
| 1 | Multiple or Ambiguous Address | The address is verified only up to the street level. However, there is ambiguity in locating the specific address. |
| 2 | Street or Thoroughfare Match | The address is verified only up to the street level. |
| 3 | Municipality Match | The address is verified only up to the city or town levels. |
| 4 | Administrative Subdivision Match | The address is verified only up to the state level. |
| 5 | Country Match | The address is verified only at the country level. |
| 6 | No Match | The address cannot be verified. |
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.
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>
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>
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