Sample Code to Create Relationship between two Party using TCA API

HZ_RELATIONSHIP_V2PUB (Doc ID 758278.1)

APPLIES TO:
Oracle Trading Community - Version 11.5.10.2 to 11.5.10.3 [Release 11.5]
Oracle Trading Community - Version 12.0 and later
Oracle Receivables - Version 12.0.0 and later
Information in this document applies to any platform.
PURPOSE
Oracle has provided Create Relationship API HZ_RELATIONSHIP_V2PUB.create_relationship to create a
Relationship between two parties or other entities.This Note will provide a sample code to use this API. It
will create Relationship between a Party of type PERSON with party of type ORGANIZATION by attaching
Person as Organization Contact of Organization.
REQUIREMENTS
You can use SQL PLUS /SQL*Plus / Oracle SQL Developer to run the script
CONFIGURING
Create Relationship API HZ_RELATIONSHIP_V2PUB.create_relationship creates a record in the
HZ_RELATIONSHIPS table. This defines the relationship that exists between Parties of type PERSON,
ORGANIZATION, and other entities that are defined in FND_OBJECT_INSTANCE_SETS. Each relationship
can be viewed from either ways. So an additional relationship record is created to store the reverse
relationship. The relationship code, relationship type, subject type and object type must be a valid
combination already defined in the HZ_RELATIONSHIP_TYPES table. The two relationship records have
the same relationship_id, they are distinguishable by the directional_flag column.
In HZ_RELATIONSHIP_V2PUB you should pass a subject_id,subject_type, subject_table_name,
object_id, object_type and object_table_name.
The API description says:object_id and subject_id are validated against Primary Key in
fnd_objects.obj_name where fnd_objects.object_id = fnd_object_instance_sets.object_id and
fnd_object_instance_sets.instance_set_name = subject_type.
INSTRUCTIONS
Run this code in the APPS schema.
CAUTION
This sample code is provided for educational purposes only, and is not supported by Oracle Support. It
has been tested internally, however, we do not guarantee that it will work for you. Ensure that you run it
in your test environment before using.
SAMPLE CODE
Scenario: Task is to create relationship between parties of type PERSON and ORGANIZATION

(A person "Ralph Karmer" is "Organization Contact" of organization "Bigmart") .

Before creating relationship, the above party records should exist in TCA, i.e. they should exist in
HZ_PARTIES table.
The primary key in the HZ_PARTIES to identify these records is PARTY_ID
HZ_PARTIES is part of FND_OBJECTS
select party_id
from hz_parties
where party_name in ( 'Bigmart','Ralph Karmer');

Two records exists in HZ_PARTIES for Bigmart and Ralph Karmer with the PARTY_ID as 299403 and
5549.
When you create EMPLOYEE relationship between them, you have to pass the following values to the
API :
OBJECT_TABLE_NAME = 'HZ_PARTIES'
OBJECT_ID = PARTY_ID i.e.299403
OBJECT_TYPE = 'ORGANIZATION' i.e. PARTY TYPE
SUBJECT_TABLE_NAME = 'HZ_PARTIES'
SUBJECT_ID = PARTY_ID i.e.5549
SUBJECT_TYPE = 'PERSON' i.e. PARTY TYPE
The purpose of these parameters is to identify the entities and the primary key between which you are
creating relationship. Technically, you are creating relationship between 2 database records, which
already created and are uniquely identified by a primary key in a table.
You can also use other entities records to create relationship if those entities are defined in
FND_OBJECTS. It is normal practice that mostly relationships are created between parties
('ORGANIZATION/PERSON and PERSON/PERSON ).
You need to pass RELATIONSHIP_CODE which is validated against AR lookup type
PARTY_RELATIONS_TYPE as:
select lookup_code from ar_lookups
where lookup_type= 'PARTY_RELATIONS_TYPE';

You need to pass RELATIONSHIP_TYPE which should exist in hz_relationship_types.relationship_type;

Another mandatory parameter is created_by_module which is validated against AR lookup type
HZ_CREATED_BY_MODULES as:
select lookup_code from ar_lookups
where lookup_type= 'HZ_CREATED_BY_MODULES';

DECLARE
p_relationship_rec_type HZ_RELATIONSHIP_V2PUB.RELATIONSHIP_REC_TYPE;
x_relationship_id NUMBER;
x_party_id NUMBER;
x_party_number VARCHAR2(2000);
x_return_status VARCHAR2(2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2(2000);

BEGIN
p_relationship_rec_type.subject_id := 5549;
p_relationship_rec_type.subject_table_name := 'HZ_PARTIES';
p_relationship_rec_type.subject_type := 'PERSON';
p_relationship_rec_type.object_id := 299403;
p_relationship_rec_type.object_table_name := 'HZ_PARTIES';
p_relationship_rec_type.object_type := 'ORGANIZATION';
p_relationship_rec_type.relationship_type := 'CONTACT';
p_relationship_rec_type.relationship_code := 'CONTACT_OF';
p_relationship_rec_type.start_date := sysdate;
p_relationship_rec_type.created_by_module := 'TCA_V2_API';
hz_relationship_v2pub.create_relationship(
'T',
p_relationship_rec_type,
x_relationship_id,
x_party_id,
x_party_number,
x_return_status,
x_msg_count,
x_msg_data);
dbms_output.put_line('x_return_status = '|| SUBSTR (x_return_status,1,255));
dbms_output.put_line('x_msg_count = '||TO_CHAR(x_msg_count));
dbms_output.put_line('Relationship Id ='||TO_CHAR(x_relationship_id));
dbms_output.put_line('Party Number = '|| SUBSTR (x_party_number,1,255));
dbms_output.put_line('x_msg_data = '|| SUBSTR (x_msg_data,1,255));
IF x_msg_count >1 THEN
FOR I IN 1..x_msg_count LOOP
dbms_output.put_line(I||'.'||SUBSTR(FND_MSG_PUB.Get(p_encoded=>
FND_API.G_FALSE ), 1, 255));
END LOOP;
END IF;
END;
/
commit;
/

Important: Do not use the Create Relationship API to create D&B hierarchy relationships.

To add a PERSON to a Group as Member, please use following code :

DECLARE
p_relationship_rec_type HZ_RELATIONSHIP_V2PUB.RELATIONSHIP_REC_TYPE;
x_relationship_id NUMBER;
x_party_id NUMBER;
x_party_number VARCHAR2(2000);
x_return_status VARCHAR2(2000);
x_msg_count NUMBER;
x_msg_data VARCHAR2(2000);
BEGIN
-- initialize
fnd_global.APPS_INITIALIZE (31822,24089,431);
p_relationship_rec_type.subject_id := 20370; -- party_id of person
p_relationship_rec_type.subject_table_name := 'HZ_PARTIES';
p_relationship_rec_type.subject_type := 'PERSON';

p_relationship_rec_type.object_id := 4221627;-- party_id of Group

p_relationship_rec_type.object_table_name := 'HZ_PARTIES';
p_relationship_rec_type.object_type := 'GROUP';
p_relationship_rec_type.relationship_type := 'MEMBERSHIP';
p_relationship_rec_type.relationship_code := 'MEMBER_OF';
p_relationship_rec_type.start_date := sysdate;
p_relationship_rec_type.created_by_module := 'TCA_V2_API';
hz_relationship_v2pub.create_relationship(
'T',
p_relationship_rec_type,
x_relationship_id,
x_party_id,
x_party_number,
x_return_status,
x_msg_count,
x_msg_data);
dbms_output.put_line('x_return_status = '|| SUBSTR (x_return_status,1,255));
dbms_output.put_line('x_msg_count = '||TO_CHAR(x_msg_count));
dbms_output.put_line('Relationship Id ='||TO_CHAR(x_relationship_id));
dbms_output.put_line('Party Number = '|| SUBSTR (x_party_number,1,255));
dbms_output.put_line('x_msg_data = '|| SUBSTR (x_msg_data,1,255));
IF x_msg_count >1 THEN
FOR I IN 1..x_msg_count LOOP
dbms_output.put_line(I||'.'||SUBSTR(FND_MSG_PUB.Get(p_encoded=>
FND_API.G_FALSE ), 1, 255));
END LOOP;
END IF;
END;
/
commit;
/

SAMPLE OUTPUT
The same output for may be
x_return_status = S
x_msg_count = 0
Relationship Id =176037
Party Number = 55521
x_msg_data =
You can also check the relationship as

select * from hz_relationships

where relationship_id= 176037; -- value returned by API
select * from hz_parties
where party_number='55521';-- value returned by API