Lease API White Paper

ORACLE APPLICATIONS Oracle Property Manager

Lease Create/Update APIs

Written by Oracle Software Support Author:

Khaled Mahdy

Date Created:

31.10.2011

Date Changed:

31.10.2011

Version:

1.1

Copyright  2011 Oracle Corporation All Rights Reserved

Contents Introduction ................................................................................... 3 Goal ........................................................................................... 3 Available APIs .......................................................................... 3 Pre-requisites ............................................................................. 4 Lease Create API .......................................................................... 5 The steps to create the API program .......................................... 5 Lease Create API Example ...................................................... 10 Lease Create API procedure .................................................... 12 Lease Update API........................................................................ 16 The steps to create the API program ......................................... 16 Lease Update API Example ..................................................... 21

Page 2

Introduction

Goal: This whitepaper is written to explain the usage and structures of the Lease Create and Update APIs and how to create the concurrent program that can be used to create/update the leases using APIs.

Available APIs: The following APIs are available 1. Lease creation and updating. 2. Index Rent creation and updating. 3. Variable Rent creation and updating. 4. Workflow, Business events for lease. 5. Client extension for variable rent calculation. 6. API to update the Lease status. ** In this Whitepaper, Only Lease Create and Update APIs will be covered.

Page 3

Pre-requisites: To be able to use the Lease APIs, the following pre-requisites must be applied:  Apply the API patch 10401569:R12.PN.B. This can be applied on Release 12.1.2 or higher. However, it can be applied on Release 12.1.1 if one of the following prerequisites is applied R12.PJ_PF.B.delta.2 (12.1.2) R12.PJ_PF.B.delta.3 (12.1.3)  It is recommended also to apply the following patches before using the API to be able to create the leases using APIs with customer space assignments (for revenue leases) and to create the lease with the accrual asset/expense account if the term template is used in the API. Patch 13043833:R12.PN.B Patch 13062833:R12.PN.B

Page 4

Lease Create API  The steps to create the API program: The lease Create API program can be created as following: 1- Create the lease create API procedure in the database (A sample API lease create procedure exists in this white paper)

Page 5

2- Create the Concurrent Program Executable.

 The execution method should be ‘PL/SQL Stored Procedure’  Enter the PL/SQL procedure name created in step 1 in the ‘Execution File Name’ field. (For example, XX_LEASE_CREATE_API)

Page 6

3- Create the API Concurrent program.

 Create the concurrent program with the executable name created already in step 2.

Page 7

4- Assign the Concurrent program to the Property Manager Request Group to be able to run the program from the Property Manager Responsibilities

Page 8

5- Submit the concurrent program ‘PN Create Lease API’

Page 9

 Lease Create API Example: The following API example procedure can be used to create a lease with the following information: Lease header information: Name: Test Lease Creation Class: Revenue Approval Status: Draft Lease Status: Active Details Tab: Execution Date: 01-JAN-2010 Commencement Date: 01-JAN-2010 Termination Date: 31-DEC-2010 Proration Rule: 365 Days/Year User Responsible: SYSADMIN Locations Tab: Type: Office Location Code: KN_NEW1-F1-O4 Usage : Office Space Estimated Occupancy Date: 01-JAN-2010 Actual Occupancy Date: 01-JAN-2010 Expiration Date: 31-DEC-2010 Customer Name: A. C. Networks Bill To Site: Provo (OPS) Page 10

Billings Tab: Term Template: KM_BILL_TT Purpose: Rent Type: Base Rent Frequency: Quarterly Normalize: Yes Schedule Day: 1 Start Date: 01-JAN-2010 End Date: 31-DEC-2010 Customer Name: A. C. Networks Bill To Site: Provo (OPS) Payment Term: IMMEDIATE Transaction Type: Invoice Actual Amount: 1,000 Currency: USD

Page 11

 Lease Create API procedure: The following procedure is an example of the lease create API  The values of some parameters may need to be changed according to the system setup and Property Manager data.  The API is designed to get the org_id while running the concurrent program from the PN responsibility used through the variable fnd_profile.VALUE ('ORG_ID') in the package pn_lease_pub.  The variable lv_lease_rec.status_code can be ‘D’ (if the lease to be created with status ‘Draft’ , or ‘F’ , if the lease to be created with status ‘Final’. If created as ‘Final’, then the “Schedules and Items” program will run automatically after the API program.  The Lease create API can create the lease with the other information like Contacts, Options, Insurance, Notes ..etc. The following structures can be used for inserting the header and tabs information of the lease pn_lease_pvt.lease_rec pn_lease_pvt.lease_tenancies_rec pn_lease_pvt.lease_terms_tbl pn_lease_pvt.lease_contacts_tbl pn_lease_pvt.lease_insurance_tbl_type pn_lease_pvt.lease_obligation_tbl_type pn_lease_pvt.lease_right_tbl_type pn_lease_pvt.lease_option_tbl_type pn_lease_pvt.lease_note_tbl_type

-- for header and details tab information -- for locations tab information -- for payments/billings tab information -- for lease contacts tab information -- for insurance tab information -- for Rights and Obligations tab information -- for options tab information -- for notes tab information

Page 12



The API procedure is a simple code to create 1 lease.

Create or replace PROCEDURE XX_LEASE_CREATE_API (ERRBUF OUT VARCHAR2 , RETCODE OUT VARCHAR2) IS lv_mesg varchar2(2000); lv_api_version number; lv_init_msg_list varchar2(100); lv_validate varchar2(100); lv_lease_rec pn_lease_pvt.lease_rec; lv_lease_tenancies_rec pn_lease_pvt.lease_tenancies_rec; lv_lease_payment_term_rec pn_lease_pvt.lease_terms_rec; lv_lease_exp_rev_accounts_rec pn_lease_pvt.lease_account_rec; lv_lease_accrual_account_rec pn_lease_pvt.lease_account_rec; lv_lease_liab_rcvl_account_rec pn_lease_pvt.lease_account_rec; lv_contacts_tbl pn_lease_pvt.lease_contacts_tbl; lv_tenancies_tbl pn_lease_pvt.lease_tenancies_tbl; lv_insurance_tbl pn_lease_pvt.lease_insurance_tbl_type; lv_right_tbl pn_lease_pvt.lease_right_tbl_type; lv_obligation_tbl pn_lease_pvt.lease_obligation_tbl_type; lv_option_tbl pn_lease_pvt.lease_option_tbl_type; lv_lease_payment_term_tbl pn_lease_pvt.lease_terms_tbl; lv_note_tbl pn_lease_pvt.lease_note_tbl_type; lv_msg_count number; lv_msg_data varchar2(1000); lv_return_status varchar2(10); lv_lease_context varchar2(1000);

begin lv_lease_rec.lease_name := 'Test Lease Creation'; lv_lease_rec.creation_date := sysdate; lv_lease_rec.created_by := 1013756; lv_lease_rec.last_update_date := sysdate; lv_lease_rec.last_updated_by := 1013756; lv_lease_rec.status_code := 'D'; lv_lease_rec.lease_status_code := 'ACT'; lv_lease_rec.lease_type_code := 'OS'; lv_lease_rec.lease_class_code := 'THIRD_PARTY'; -- 'DIRECT' lv_lease_rec.abstracted_by_user_id := 1013756; lv_lease_rec.location_code := null; lv_lease_context := 'ABS';

Page 13

-- Details Tab lv_lease_rec.lease_execution_date

:= to_date('01-JAN-2010' , 'DD-MON-YYYY');

lv_lease_rec.lease_commencement_date := to_date('01-JAN-2010' , 'DD-MON-YYYY'); lv_lease_rec.lease_termination_date := to_date('31-DEC-2010' , 'DD-MON-YYYY'); lv_lease_rec.pymt_term_pro_rule_id := 365; lv_lease_rec.responsible_user_id := 1013756; --lv_lease_rec.term_template_name := ; --lv_lease_rec.customer_id := ; --lv_lease_rec.customer_name := ; --lv_lease_rec.grouping_rule_name := ; --lv_lease_rec.grouping_rule_id := ; --lv_lease_exp_rev_accounts_rec.account_id := ; --lv_lease_accrual_account_rec.account_id := ; --lv_lease_liab_rcvl_account_rec.account_id := ; -- Locations tab lv_lease_tenancies_rec.location_code := 'KN_NEW1-F1-O4'; lv_lease_tenancies_rec.tenancy_usage_lookup_code := 'OFFICE'; lv_lease_tenancies_rec.occupancy_date := to_date('01-JAN-2010' , 'DD-MON-YYYY'); lv_lease_tenancies_rec.estimated_occupancy_date := to_date('01-JAN-2010' , 'DD-MON-YYYY'); lv_lease_tenancies_rec.expiration_date := to_date('31-DEC-2010' , 'DD-MON-YYYY'); lv_lease_tenancies_rec.fin_oblig_end_date := to_date('31-DEC-2010' , 'DD-MON-YYYY'); lv_lease_tenancies_rec.creation_date := Trunc(SYSDATE); lv_lease_tenancies_rec.created_by := 1013756; lv_lease_tenancies_rec.last_update_date := Trunc(SYSDATE); lv_lease_tenancies_rec.last_updated_by := 1013756; lv_lease_tenancies_rec.status := 'A'; lv_lease_tenancies_rec.primary_flag := 'N'; lv_lease_tenancies_rec.customer_id := 1290;

lv_lease_tenancies_rec.allocated_area_pct := 100; lv_lease_tenancies_rec.location_assignable_area := 100; lv_lease_tenancies_rec.assignable_flag := 'N'; lv_lease_tenancies_rec.subleaseable_flag := 'N'; lv_lease_tenancies_rec.tenants_proportionate_share := 0; lv_lease_tenancies_rec.lease_assignable_area := null; lv_tenancies_tbl(1) := lv_lease_tenancies_rec; -- Billings Tab (with term template) lv_lease_payment_term_rec.term_template_name := 'KM_BILL_TT'; lv_lease_payment_term_rec.lease_id := lv_lease_rec.lease_id; lv_lease_payment_term_rec.lease_change_id := lv_lease_rec.lease_change_id; lv_lease_payment_term_rec.frequency_code := 'QTR'; lv_lease_payment_term_rec.start_date := lv_lease_rec.lease_commencement_date; lv_lease_payment_term_rec.end_date := lv_lease_rec.lease_termination_date;

Page 14

lv_lease_payment_term_rec.actual_amount := 1000; lv_lease_payment_term_rec.lease_status := 'ACT'; lv_lease_payment_term_tbl(1) := lv_lease_payment_term_rec;

pn_lease_pub.create_lease (p_api_version => 1.0 , p_init_msg_list => FND_API.g_false , p_commit => FND_API.g_true , p_validate => FND_API.g_false , p_lease_rec => lv_lease_rec , p_lease_exp_rev_accounts_rec => lv_lease_exp_rev_accounts_rec , p_lease_accrual_account_rec => lv_lease_accrual_account_rec , p_lease_liab_rcvl_account_rec => lv_lease_liab_rcvl_account_rec , p_contacts_tbl => lv_contacts_tbl , p_tenancies_tbl => lv_tenancies_tbl , p_insurance_tbl => lv_insurance_tbl , p_right_tbl => lv_right_tbl , p_obligation_tbl => lv_obligation_tbl , p_option_tbl => lv_option_tbl , p_lease_payment_term_tbl => lv_lease_payment_term_tbl , p_note_tbl => lv_note_tbl , x_msg_count => lv_msg_count , x_msg_data => lv_msg_data , x_return_status => lv_return_status , p_lease_context => lv_lease_context); FND_FILE.PUT_LINE (FND_FILE.LOG,'V_RETURN_STATUS : '||lV_RETURN_STATUS); IF (lV_RETURN_STATUS FND_API.G_RET_STS_SUCCESS) THEN lv_msg_count := FND_MSG_PUB.COUNT_MSG; IF lv_msg_count > 0 THEN lV_MESG := ';' || SUBSTR(FND_MSG_PUB.GET(FND_MSG_PUB.G_FIRST, FND_API.G_FALSE),1, 512); FOR I IN 1..(lv_msg_count-1) LOOP lV_MESG := lV_MESG || ';' || SUBSTR(FND_MSG_PUB.GET (FND_MSG_PUB.G_NEXT,FND_API.G_FALSE), 1, 512); END LOOP; FND_MSG_PUB.DELETE_MSG(); END IF; FND_FILE.PUT_LINE (FND_FILE.LOG,'lV_MESG : '||lV_MESG); END IF; FND_FILE.PUT_LINE (FND_FILE.LOG, 'Lease ID : ' || lv_lease_rec.lease_id); commit; END;

Page 15

Lease Update API The lease Update API program can be created with the same steps as the Lease Create API program as following:

 The steps to create the API program: 1- Create the lease update API procedure in the database

Page 16

2- Create the Concurrent Program Executable.

 The execution method should be ‘PL/SQL Stored Procedure’  Enter the PL/SQL procedure name created in step 1 in the ‘Execution File Name’ field. (For example, XX_LEASE_UPDATE_API)

Page 17

3- Create the API Concurrent program.

 Create the concurrent program with the executable name created already in step 2.

Page 18

4- Assign the Concurrent program to the Property Manager Request Group to be able to run the program from the Property Manager Responsibilities.

Page 19

5- Then submit the concurrent program ‘PN Update Lease API’ from the Property Manager responsibility

Page 20

 Lease Update API Example: The following example uses the Lease update API to edit a finalized revenue lease by adding one more billing term. For example, assume lease number 4093 is created and finalized, and then we need to edit it by adding the following billing term: Term Template: KM_BILL_TT Purpose: Rent Type: Base Rent Frequency: Monthly Normalize: Yes Schedule Day: 1 Start Date: 01-JAN-2010 End Date: 31-DEC-2010 Customer Name: A. C. Networks Bill To Site: Provo (OPS) Payment Term: IMMEDIATE Transaction Type: Invoice Actual Amount: 700 Currency: USD

Page 21

The API can be created as following: Create or replace PROCEDURE XX_LEASE_UPDATE_API (ERRBUF OUT VARCHAR2 , RETCODE OUT VARCHAR2) IS lv_mesg varchar2(2000); lv_api_version number; lv_init_msg_list varchar2(100); lv_validate varchar2(100); lv_lease_rec pn_lease_pvt.lease_rec; lv_lease_tenancies_rec pn_lease_pvt.lease_tenancies_rec; lv_lease_payment_term_rec pn_lease_pvt.lease_terms_rec; lv_lease_exp_rev_accounts_rec pn_lease_pvt.lease_account_rec; lv_lease_accrual_account_rec pn_lease_pvt.lease_account_rec; lv_lease_liab_rcvl_account_rec pn_lease_pvt.lease_account_rec; lv_contacts_tbl pn_lease_pvt.lease_contacts_tbl; lv_tenancies_tbl pn_lease_pvt.lease_tenancies_tbl; lv_insurance_tbl pn_lease_pvt.lease_insurance_tbl_type; lv_right_tbl pn_lease_pvt.lease_right_tbl_type; lv_obligation_tbl pn_lease_pvt.lease_obligation_tbl_type; lv_option_tbl pn_lease_pvt.lease_option_tbl_type; lv_lease_payment_term_tbl pn_lease_pvt.lease_terms_tbl; lv_note_tbl pn_lease_pvt.lease_note_tbl_type; lv_msg_count number; lv_msg_data varchar2(1000); lv_return_status varchar2(10); lv_lease_context varchar2(1000); begin lv_lease_rec.lease_num := '4093'; lv_lease_rec.creation_date := sysdate; lv_lease_rec.created_by := 1013756; lv_lease_rec.last_update_date := sysdate; lv_lease_rec.last_updated_by := 1013756; lv_lease_context := 'ED'; -- Billings Tab (with term template) lv_lease_payment_term_rec.term_template_name := 'KM_BILL_TT'; lv_lease_payment_term_rec.lease_id := lv_lease_rec.lease_id; lv_lease_payment_term_rec.lease_change_id := lv_lease_rec.lease_change_id; lv_lease_payment_term_rec.frequency_code := 'MON'; lv_lease_payment_term_rec.start_date := to_date('01-JAN-2010','DD-MON-YYYY'); lv_lease_payment_term_rec.end_date := to_date('31-DEC-2010','DD-MON-YYYY'); lv_lease_payment_term_rec.actual_amount := 700; lv_lease_payment_term_rec.lease_status := 'ACT'; lv_lease_payment_term_tbl(1) := lv_lease_payment_term_rec;

Page 22

pn_lease_pub.update_lease (p_api_version => 1.0 , p_init_msg_list => FND_API.g_false , p_commit => FND_API.g_false , p_validate => FND_API.g_false , p_lease_rec => lv_lease_rec , p_lease_exp_rev_accounts_rec => lv_lease_exp_rev_accounts_rec , p_lease_accrual_account_rec => lv_lease_accrual_account_rec , p_lease_liab_rcvl_account_rec => lv_lease_liab_rcvl_account_rec , p_lease_contacts_tbl => lv_contacts_tbl , p_lease_tenancies_tbl => lv_tenancies_tbl , p_insurance_tbl => lv_insurance_tbl , p_right_tbl => lv_right_tbl , p_obligation_tbl => lv_obligation_tbl , p_option_tbl => lv_option_tbl , p_lease_payment_term_tbl => lv_lease_payment_term_tbl , p_note_tbl => lv_note_tbl , x_msg_count => lv_msg_count , x_msg_data => lv_msg_data , x_return_status => lv_return_status , p_lease_context => lv_lease_context); FND_FILE.PUT_LINE (FND_FILE.LOG,'V_RETURN_STATUS : '||lV_RETURN_STATUS); IF (lV_RETURN_STATUS FND_API.G_RET_STS_SUCCESS) THEN lv_msg_count := FND_MSG_PUB.COUNT_MSG; IF lv_msg_count > 0 THEN lV_MESG := ';' || SUBSTR(FND_MSG_PUB.GET(FND_MSG_PUB.G_FIRST, FND_API.G_FALSE),1, 512); FOR I IN 1..(lv_msg_count-1) LOOP lV_MESG := lV_MESG || ';' || SUBSTR(FND_MSG_PUB.GET (FND_MSG_PUB.G_NEXT,FND_API.G_FALSE), 1, 512); END LOOP; FND_MSG_PUB.DELETE_MSG(); END IF; FND_FILE.PUT_LINE (FND_FILE.LOG,'lV_MESG : '||lV_MESG); END IF; FND_FILE.PUT_LINE (FND_FILE.LOG, 'Lease ID : ' || lv_lease_rec.lease_id); commit; END;

Page 23