This document provides technical information to understand the differences and uses between Customer Interface (RACUST) and TCA API (Public API, version 2.) The TCA API is delivered to the public on TCA minipack HZ-F (1921951) or higher.
DEFINITIONS
The following are some definitions that have an important role in the functionality and use of this document.
TCA
Trading Community Architecture (TCA) is an architecture concept designed to support complex trading communities. The goal of TCA is to provide a shared data foundation for Oracle ERP, CRM, and eBusiness applications.
RACUST
Customer Interface is a concurrent program that is responsible for the import and update of AR customer information from open interface tables to AR Customer tables.
HZ
Prefix used to distinguish 11i Customer Model objects using TCA such as tables, views, and APIs from previous customer model objects such as those used within R10.7, and R11.
PARTY
A party is an entity that can enter into a business relationship and can be of two sub types; Person and Organization.
PERSON PARTY
A person party is a unique individual of interest to the owner of the software.
ORGANIZATION PARTY
An organization party is a legal entity generally recognized by some government authority.
RELATIONSHIP
Relationships in TCA allow for the linking of any two parties. When two parties are connected via a party relationship a relationship type is assigned which describes the relationship. 1
ACCOUNT
An account is the financial roll-up point to track the monitory portion of a customer’s purchases and payments. This account stores details about a customer relationship between a Party and your business. When a party becomes a customer (through creation in the AR customer screen, registering on iStore, creating a quote, placing an order etc), an account is created and associated to the party to track the attributes of the customer relationship. A Party may have one or more Accounts. Each account may have only one owner, but any number of other parties may also be associated to the account in roles other than owner.
ACCOUNT ROLE
The account role defines the relationship that a Party has in regard to controlling or using an account.
ACCOUNT SITE
The account site is a Party Site that is used within the context of a Customer Account.
ACCOUNT RELATIONSHIPS
Implies financial responsibility between owners of accounts.
CONTACT POINT
Contact points store electronic methods of communicating with an entity (e.g., phone, fax number, email address, URL etc.). A contact points is connected to a party or a party site, and there can be from one to many contact points specified for a Party or Party Site.
LOCATION
The location record in TCA is point in geographical space, usually described by an address.
PARTY SITE
The party site establishes the link between a Party and a Location.
PARTY SITE USAGE
Describes the usage of that Location (e.g., mailing address, billing address, home address, etc.). A Party Site may have one to many uses
EXCEPTION AND ERROR MESSAGES
RACUST and TCA API are very different in the way they handle error messages and exceptions.
RACUST
When the customer interface executes, a report is generated. You can view the output by selecting the request and then choosing View Output. The bottom of this report shows the errors that the interface request has. In addition, a log file is also created for the request. It will contain more detailed and technical information on any program-related errors.
API
The APIs provide an extensive error-handling and error-reporting mechanism whereby all errors encountered in the different phases of API execution are reported and put on the message stack. The calling program has the option of looking up all the error messages or the first error message on the stack. If there is only one error in the message stack, the error comes out as one of the output parameters of the API routine and the user does not need to fetch the message from the stack.
Status Error for API
The return status (x_return_status) of the API informs the caller about the result of the operation (or operations) performed by the API. The different possible values for an API return status are listed below:
· Success (FND_API.G_RET_STS_SUCCESS)
· Error (FND_API.G_RET_STS_ERROR)
· Unexpected error (FND_API.G_RET_STS_UNEXP_ERROR)
Success
A success return status means that the API was able to perform all the operations requested by its caller. A success return status may be accompanied by messages in the API message list which will be informative.
Error
An error return status means that the API failed to perform some or all of the operations requested by its caller. An error return status is usually accompanied by messages describing the error (or errors) and how to fix it. In most cases, you should be able to take corrective actions to fix regular, expected errors such as missing attributes or invalid date ranges.
Unexpected error
An unexpected error status means that the API has encountered an error condition it did not expect or could not handle. In this case, the API is unable to continue with its regular processing. Examples of such error are irrecoverable data inconsistency errors, memory errors, and programming errors (like attempting a division by zero). In most cases, the end user will not be able to correct unexpected errors. It is usually system administrators or application developers who can fix these errors.
USES
The decision of using Customer Interface (RACUST) or TCA APIs can be based on some of the following points:
Can the data be imported / modified through RACUST (are the fields available in the interface)?
Will the data import meet the existing validation rules in the application (valid AR location code)?
Will the process of the data import meet the business requirement (scheduling, quantity of records, staging of data)?
Do you have the technical support to integrate and implement the APIs (additional PL/SQL programming)?
The purpose for the TCA APIs is to provide the user a supported tool to import and modify data that currently is not available through the existing open interfaces. These APIs utilize the new TCA model, inserting directly to the HZ tables. The APIs are modular by design, creating an easy to understand, easy to maintain, and easy to extend means or updating specific TCA data. Customer Interface inserts basic, AR-related customer information such as Customer Name, Address Information, Flags, References, etc. The limitations in Customer Interface is the inability to import and update additional information such as SIC_CODE, SIC_CODE_TYPE, etc. In the 11.5 release, even more fields are now available to the AR user through the customer form but are not included in the current Customer Interface. For these situations, the user can implement a solution using the TCA APIs.
The following matrix in Figure 1, shows some of the differences in functionality between the TCA API and RACUST-Customer interface.
EXAMPLES
There ARE two examples OF how TO USE TCA APIs AND RACUST (Customer Interface.)
Example 1:
INSERT a customer using RACUST – Customer Interface
This example inserts a customer with the following information:
Customer Name: CUTOMERNAME0
Orig. System Ref: 01-00-01
Orig. Address Ref: 01-00-01
Address: ADDRESS0
Site Use: BILL_TO
City: San Mateo
County: San Mateo
State: CA
Postal Code: 94401
Customer Category Code: CUSTOMER
Org Id: 204
Profile Class: DEFAULT
1. Run these scripts in SQL*Plus
-----------------------------------
-- insert the address information
-----------------------------------
truncate table ar.ra_customers_interface_all;
INSERT INTO ar.ra_customers_interface_all (orig_system_customer_ref,
customer_name,
orig_system_address_ref,
address1,
address2,
address3,
address4,
city,
county,
state,
province,
country,
postal_code,
site_use_code,
primary_site_use_flag,
customer_status,
insert_update_flag,
last_updated_by,
last_update_date,
created_by,
creation_date,
customer_number,
customer_name_phonetic,
customer_category_code,
location,
org_id)
VALUES ('01-00-01', -- orig_system_reference
'CUSTOMERNAME0', -- customer_name
'01-00-01', -- orig_system_address_ref, change it if you put another address
'ADDRESS0', -- address1
NULL, -- address2
NULL, -- address3
NULL, -- address4
'San Mateo', -- city
'San Mateo', -- county
'CA', -- state
NULL, -- provice
'US', -- country
'94401', -- postal_code
'BILL_TO', -- SITE USE
'Y', -- primary_site_use_flag
'A', -- customer_staus
'I', -- insert_update_flag
-1, -- last_updated_by
SYSDATE, -- last_update_date
-1, -- created_by
SYSDATE, -- creation_date
NULL, -- customer_number if automatic customer number is no
'CUSTOMERNAME0', -- customer_name_phonetic
'CUSTOMER', -- customer_category_code
NULL, -- location if autositenumber is no
204 -- org_id
);
----------------------------------------------
-- insert the customer profile information
----------------------------------------------
TRUNCATE TABLE ar.ra_customer_profiles_int_all;
INSERT INTO ar.ra_customer_profiles_int_all (orig_system_customer_ref,
insert_update_flag,
customer_profile_class_name,
credit_hold,
last_updated_by,
last_update_date,
created_by,
creation_date,
org_id)
VALUES ('01-00-01', -- orig_system_customer_ref
'I', -- insert_update_flag
'DEFAULT', -- Should be valid profile class
'N', -- This can be 'Y','N' not null.
-1, -- last_updated_by
SYSDATE, -- last_update_date
-1, -- created_by
SYSDATE, -- created_by
204 -- org_id
);
COMMIT;
2. Run customer Interface Program from the application.
Example 2:
INSERT a customer using TCA API.
This example inserts a customer with the following information:
Customer Name: CUTOMERNAME1
Account Name: Test1
Site Use: BILL_TO
Address: Test
Country: US
City: San Mateo
State: CA
Postal Code: 94401
------------------------------------
-- Step 1a
-- Setup the Org_id
------------------------------------
exec dbms_application_info.set_client_info('204');
------------------------------------
-- Step 1b
-- Allow to show the output variables
------------------------------------
SET SERVEROUTPUT ON
------------------------------------
-- Step 2
-- Create a party and an account
------------------------------------
DECLARE
p_cust_account_rec HZ_CUST_ACCOUNT_V2PUB.CUST_ACCOUNT_REC_TYPE;
p_organization_rec HZ_PARTY_V2PUB.ORGANIZATION_REC_TYPE;
p_customer_profile_rec HZ_CUSTOMER_PROFILE_V2PUB.CUSTOMER_PROFILE_REC_TYPE;
x_cust_account_id NUMBER;
x_account_number VARCHAR2 (2000);
x_party_id NUMBER;
x_party_number VARCHAR2 (2000);
x_profile_id NUMBER;
x_return_status VARCHAR2 (2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2 (2000);
BEGIN
p_cust_account_rec.account_name := 'Test1';
p_cust_account_rec.created_by_module := 'TCAPI_EXAMPLE';
-- p_cust_account_rec.orig_system_reference := '01-01-01'; -- is not mandatory
p_organization_rec.organization_name := ' CUSTOMERNAME1';
p_organization_rec.created_by_module := 'TCAPI_EXAMPLE';
hz_cust_account_v2pub.create_cust_account ('T',
p_cust_account_rec,
p_organization_rec,
p_customer_profile_rec,
'F',
x_cust_account_id,
x_account_number,
x_party_id,
x_party_number,
x_profile_id,
x_return_status,
x_msg_count,
x_msg_data);
DBMS_OUTPUT.put_line ('x_cust_account_id: ' || x_cust_account_id);
DBMS_OUTPUT.put_line ('x_account_number: ' || x_account_number);
DBMS_OUTPUT.put_line ('x_party_id: ' || x_party_id);
DBMS_OUTPUT.put_line ('x_party_number: ' || x_party_number);
DBMS_OUTPUT.put_line ('x_profile_id: ' || x_profile_id);
DBMS_OUTPUT.put_line ('x_return_status: ' || x_return_status);
DBMS_OUTPUT.put_line ('x_msg_count: ' || x_msg_count);
DBMS_OUTPUT.put_line ('x_msg_data: ' || x_msg_data);
END;/* BEGIN address */
------------------------------------
-- Step 3
-- Create a physical location
------------------------------------
DECLARE
p_location_rec HZ_LOCATION_V2PUB.LOCATION_REC_TYPE;
x_location_id NUMBER;
x_return_status VARCHAR2 (2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2 (2000);
BEGIN
p_location_rec.country := 'US';
p_location_rec.address1 := 'Test';
p_location_rec.city := 'san Mateo';
p_location_rec.postal_code := '94401';
p_location_rec.state := 'CA';
p_location_rec.created_by_module := 'TCAPI_EXAMPLE';
hz_location_v2pub.create_location ('T',
p_location_rec,
x_location_id,
x_return_status,
x_msg_count,
x_msg_data);
DBMS_OUTPUT.put_line ('x_location_id: ' || x_location_id);
DBMS_OUTPUT.put_line ('x_return_status: ' || x_return_status);
DBMS_OUTPUT.put_line ('x_msg_count: ' || x_msg_count);
DBMS_OUTPUT.put_line ('x_msg_data: ' || x_msg_data);
END;
------------------------------------
-- Step 4
-- Create a party site using party_id you get from step 2 and location_id from step 3
------------------------------------
DECLARE
p_party_site_rec HZ_PARTY_SITE_V2PUB.PARTY_SITE_REC_TYPE;
x_party_site_id NUMBER;
x_party_site_number VARCHAR2 (2000);
x_return_status VARCHAR2 (2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2 (2000);
BEGIN
p_party_site_rec.party_id := 15184; --<
p_party_site_rec.location_id := 3270; --<
p_party_site_rec.identifying_address_flag := 'Y';
p_party_site_rec.created_by_module := 'TCAPI_EXAMPLE';
hz_party_site_v2pub.create_party_site ('T',
p_party_site_rec,
x_party_site_id,
x_party_site_number,
x_return_status,
x_msg_count,
x_msg_data);
DBMS_OUTPUT.put_line ('x_party_site_id: ' || x_party_site_id);
DBMS_OUTPUT.put_line ('x_party_site_number: ' || x_party_site_number);
DBMS_OUTPUT.put_line ('x_return_status: ' || x_return_status);
DBMS_OUTPUT.put_line ('x_msg_count: ' || x_msg_count);
DBMS_OUTPUT.put_line ('x_msg_data: ' || x_msg_data);
END;
------------------------------------
-- Step 5
-- Create an account site using account_id you get from step 2 and party_site_id from step 4.
------------------------------------
/* Formatted on 6/21/2011 4:05:49 PM (QP5 v5.163.1008.3004) */
DECLARE
p_cust_acct_site_rec hz_cust_account_site_v2pub.cust_acct_site_rec_type;
x_return_status VARCHAR2 (2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2 (2000);
x_cust_acct_site_id NUMBER;
BEGIN
p_cust_acct_site_rec.cust_account_id := 12722; --<
p_cust_acct_site_rec.party_site_id := 12164; --<
p_cust_acct_site_rec.language := 'US';
p_cust_acct_site_rec.created_by_module := 'TCAPI_EXAMPLE';
hz_cust_account_site_v2pub.create_cust_acct_site ('T',
p_cust_acct_site_rec,
x_cust_acct_site_id,
x_return_status,
x_msg_count,
x_msg_data);
dbms_output.put_line('x_cust_acct_site_id: '||x_cust_acct_site_id);
dbms_output.put_line('x_return_status: '||x_return_status);
dbms_output.put_line('x_msg_count: '||x_msg_count);
dbms_output.put_line('x_msg_data: '||x_msg_data);
END;
------------------------------------
-- Step 6
-- Create an account site use using cust_acct_site_id you get from step 5 and site_use_code='BILL_TO'
------------------------------------
DECLARE
p_cust_site_use_rec HZ_CUST_ACCOUNT_SITE_V2PUB.CUST_SITE_USE_REC_TYPE;
p_customer_profile_rec HZ_CUSTOMER_PROFILE_V2PUB.CUSTOMER_PROFILE_REC_TYPE;
x_site_use_id NUMBER;
x_return_status VARCHAR2 (2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2 (2000);
BEGIN
p_cust_site_use_rec.cust_acct_site_id := 9369; --<
p_cust_site_use_rec.site_use_code := 'BILL_TO';
p_cust_site_use_rec.created_by_module := 'TCAPI_EXAMPLE';
hz_cust_account_site_v2pub.create_cust_site_use ('T',
p_cust_site_use_rec,
p_customer_profile_rec,
'',
'',
x_site_use_id,
x_return_status,
x_msg_count,
x_msg_data);
DBMS_OUTPUT.put_line ('x_site_use_id: ' || x_site_use_id);
DBMS_OUTPUT.put_line ('x_return_status: ' || x_return_status);
DBMS_OUTPUT.put_line ('x_msg_count: ' || x_msg_count);
DBMS_OUTPUT.put_line ('x_msg_data: ' || x_msg_count);
END;
/* END address */
No comments:
Post a Comment