ORACLE APPLICATIONS

Oracle Property Manager

Lease Create/Update APIs

Written by Oracle Software Support

Author: Khaled Mahdy

Date Created: 31.10.2011

Date Changed: 14.05.2013

Version: 1.2

Copyright 2013 Oracle Corporation All Rights Reserved

Page 2

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 3

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 4

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 pre-requisites 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 latest PN consolidated patches to avoid any possible bug in PN Lease API code.

Patch 16619592:R12.PN.B is the latest consolidated patch as of May-2013.

Page 5

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 6

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 7

3- Create the API Concurrent program.

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

Page 8

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

Page 9

5- Submit the concurrent program PN Create Lease API

Page 10

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 11

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 12

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 -- for header and details tab information pn_lease_pvt.lease_tenancies_rec -- for locations tab information pn_lease_pvt.lease_terms_tbl -- for payments/billings tab information pn_lease_pvt.lease_contacts_tbl -- for lease contacts tab information pn_lease_pvt.lease_insurance_tbl_type -- for insurance tab information pn_lease_pvt.lease_obligation_tbl_type -- for Rights and Obligations pn_lease_pvt.lease_right_tbl_type tab information pn_lease_pvt.lease_option_tbl_type -- for options tab information pn_lease_pvt.lease_note_tbl_type -- for notes tab information

Page 13

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 14

-- 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 15

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 16

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 17

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 18

3- Create the API Concurrent program.

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

Page 19

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

Page 20

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

Page 21

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 22

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 23

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;