foundation apis

Implementation of Project Foundation API’s(Create_project & Update_project)

(Oracle Projects11.5.9)

An Oracle White Paper 14/Mar/05

Vamsi Andavarapu, Global Product Support,Oracle.

Implementation of Project Foundation API’s 2

Table of Contents

Abstract.................................................................................................................... 3Audience.................................................................................................................. 3Introduction.............................................................................................................. 4Prerequisites ........................................................................................................... 5

Activity Management Setup ............................................................................... 5Template Setup................................................................................................... 6Other Setups ....................................................................................................... 8

PA_PROJECT_PUB.Create Project ..................................................................... 8Parameters for Create_Projects :...................................................................... 8Project Information............................................................................................ 13Task Structure................................................................................................... 13Classifications ................................................................................................... 14Key Members .................................................................................................... 14

PA_PROJECT_PUB.Update Project .................................................................. 15Project Information............................................................................................ 16Task Structure................................................................................................... 16Classifications ................................................................................................... 17Key Members .................................................................................................... 17

Implementation of Project APIs – Case Study................................................... 17Requirement Description.................................................................................. 17Solution Approach ............................................................................................ 18

Trouble shooting ................................................................................................... 20Example Code for the Create_project API ......................................................... 21Example Code for the Update_project API ........................................................ 24Known Issues........................................................................................................ 27


Abstract

This paper has been created to assist the usage of Oracle Project

Foundation API’s “ create_project” and “update_project”. Further it also

discusses the pre-requisites for usage of API’s and general observed

behaviour with respect to API parameters- key members, classifications, work

break down structures (WBS) etc. The paper also illustrates how the project

API’s be used in migrating projects from legacy systems. Problems that are

usually encountered in the implementation of API’s, solutions for the same

and workarounds to resolve the problems are discussed. To sum up the

objective of this paper is to share the experience we have had in the

implementation of API’s- create_project and update_project and how the

API’s can be used in the migration of the projects.

Audience

You are an Oracle Application professional interested in implementing

projects API’s (create_project and Update_project) for creating projects or

updating projects in Oracle Projects Module. This paper is written with the

assumption that you have working knowledge of Oracle Projects module and

API’s in Oracle Applications. Information sources are provided at the end of

this paper. To get most out of this paper, it is recommended that you have

good understanding of the concepts in creating projects, creating project

templates and using API’s. A case study is also included which will be helpful

for the consultants involved in the design of migrating projects from legacy

systems.


Introduction

Any project-based organization implementing Oracle ERP application

will require migrating all the projects information from legacy system. If the

organization uses third party applications apart from the Oracle applications

ERP like Primavera, Microsoft Projects, CASH etc…then there may be

business requirements to integrate Oracle Projects with external systems. In

such a scenario, projects are required to be maintained parallel in both the

systems and further they are periodically updated in both the systems. We

can use Project Foundation API’s to integrate both the systems. This paper

explains behaviour of API’s and how to use API’s in migration of projects

defined in the external systems, how one can use the API’s to make

necessary updations to projects created. This paper does not delve into the

integration of the systems as such.

Projects can be created in different ways.

Setup a template project and copy the projects from the template. This

approach is best suited if number of projects to be migrated is very

less.

If projects are maintained in Microsoft projects, MS projects have a

functionality to create the same projects in Oracle projects with the

same structure. This is supported by Oracle.

Using Projects API’s.

A case study in the later section of this paper discusses how data is to be

migrated from external systems to Oracle Projects using API’s. In general, we

can expect data in flat files in predefined format to be loaded into staging

tables (custom tables created to load the data given in flat files) for validation

before passing the values to API. This loading of data from flat files into

custom tables can be done using any of the tools like SQL loader etc. After

the validation, these values will be passed to API as parameters and the

project is created or updated as desired.


Prerequisites

Activity Management Setup

Step 1: Setting up of source product is mandatory.

Navigation to setup Source Product: Projects Responsibility Setup

Activity Management Gateway Source Product

Note: One can define any number of product sources depending on the

requirement. The ‘product source code’ defined here will be passed as a

value to the parameter p_pm_product_code.

Step 2: Navigation to setup control actions: Projects Responsibility Setup

Activity Management Gateway Control Actions


Note: Entering an action in this window prevents users from performing actions in Oracle Projects, on a record that originated in the specified external system. (For more information on control actions refer to Integration with Non–Oracle Applications – Activity Management gateway section in Oracle Projects User guide)

Template Setup

Step 3: Setup template project with all the required setups. Setup quick entry

fields as mandatory to enable API to validate these fields as mandatory

parameters for the project being created.

Navigation to setup template: Projects Responsibility Setup Projects

Project Templates New.


Click on the ‘Setup Quick Entry’ to set up the quick entry fields

Note: Enabling the ‘Required’ field will enforce the API to validate the parameter as mandatory when using this template. For more information on setup of Project Templates and setup Quick Entry please refer Oracle Projects user guide.


Other Setups

Step 4: Prior to migrating projects from legacy applications, following pre-

requisites should be ensured:

Organization - Organization setup must be completed in Oracle HRMS.

Employee – Employee setup must be completed in Oracle HRMS.

Customer – Customer setup must be completed in Oracle Receivables.

Employees being defined as key members on the projects should be defined

in HRMS with valid date range and have a valid assignment. Customers

should be setup in Oracle receivables with valid ship-to-address, bill-to-

addresses and the bill-to-addresses should have bill to contact setup.

Create Project and Update Project API’s

PA_PROJECT_PUB.Create Project

This API is used to create project from an existing project

template/project. The section below discusses how the project can be created

using the AMG API create_project

Parameters for Create_Projects:

The parameters to create_project and their structures are discussed below.

Name Usage TYPE Required? P_API_VERSION_NUMBER IN NUMBER YesP_COMMIT IN VARCHAR2(1) NoP_INIT_MSG_LIST IN VARCHAR2(1) No P_MSG_COUNT OUT NUMBER P_MSG_DATA OUT VARCHAR2(2000) P_RETURN_STATUS OUT VARCHAR2(1) P_WORKFLOW_STARTED OUT VARCHAR2 P_PM_PRODUCT_CODE IN VARCHAR2(30) Yes P_PROJECT_IN IN PROJECT_IN_REC_TYPE Yes P_PROJECT_OUT OUT PROJECT_OUT_REC_TYPE P_KEY_MEMBERS IN PROJECT_ROLE_TBL_TYPE No P_CLASS_CATEGORIES IN CLASS_CATEGORY_TBL_TYPE No P_TASKS_IN IN TASK_IN_TBL_TYPE No P_TASKS_OUT OUT TASK_OUT_TBL_TYPE P_ORG_ROLES IN TABLE TYPE No P_STRUCTUR_IN IN TABLE TYPE No P_EXT_ATTR_TBL_IN IN TABLE TYPE No


PROJECT_IN_REC_TYPE:Note: Required? ‘Yes’: Indicates that the parameter is necessarily required to be passed.‘No’: Parameter is not required (not mandatory).‘B’: Indicates that the value will be based on Project Template.

Name Type Required?pm_project_reference VARCHAR2(25) Ypa_project_id NUMBER For Updatepa_project_number VARCHAR2(25) Nproject_name VARCHAR2(30) Nlong_name VARCHAR2(240) Y created_from_project_id NUMBER Bcarrying_out_organization_id NUMBER Bpublic_sector_flag VARCHAR2(1) Bproject_status_code VARCHAR2(30) Bdescription VARCHAR2(250) Bstart_date DATE Bcompletion_date DATE Bdistribution_rule VARCHAR2(30) Bcustomer_id NUMBER Bproject_relationship_code VARCHAR2(30) Yactual_start_date DATE Nactual_finish_date DATE Nearly_start_date DATE Nearly_finish_date DATE Nlate_start_date DATE Nlate_finish_date DATE Nscheduled_start_date DATE Nscheduled_finish_date DATE Nattribute_category VARCHAR2(30) Nattribute1 VARCHAR2(150) Nattribute2 VARCHAR2(150) Nattribute3 VARCHAR2(150) N..attribute10 VARCHAR2(150) Noutput_tax_code VARCHAR2(30) Nretention_tax_code VARCHAR2(30) Nproject_currency_code VARCHAR2(15) Nallow_cross_charge_flag VARCHAR2(1) Nproject_rate_date DATE Nproject_rate_type VARCHAR2(30) Ncc_process_labor_flag VARCHAR2(1) Nabor_tp_schedule_id NUMBER Nlabor_tp_fixed_date DATE Ncc_process_nl_flag VARCHAR2(1) Nnl_tp_schedule_id NUMBER Nnl_tp_fixed_date DATE Ncc_tax_task_id NUMBER Nrole_list_id NUMBER Nwork_type_id NUMBER Ncalendar_id NUMBER Nlocation_id NUMBER Nprobability_member_id NUMBER Nproject_value NUMBER N


expected_approval_date DATE Ncost_job_group_id NUMBER Nbill_job_group_id NUMBER Nteam_template_id NUMBER Ncountry_code VARCHAR2(250) Nregion VARCHAR2(250) Ncity VARCHAR2(250) Nemp_bill_rate_schedule_id NUMBER Njob_bill_rate_schedule_id NUMBER Ninvproc_currency_type VARCHAR2(30) Nrevproc_currency_code VARCHAR2(15) Nproject_bil_rate_date_code VARCHAR2(30) Nproject_bil_rate_type VARCHAR2(30) Nproject_bil_rate_date DATE Nproject_bil_exchange_rate NUMBER Nprojfunc_currency_code VARCHAR2(15) Nprojfunc_bil_rate_date_code VARCHAR2(30) Nprojfunc_bil_rate_type VARCHAR2(30) Nprojfunc_bil_rate_date DATE Nprojfunc_bil_exchange_rate NUMBER Nfunding_rate_date_code VARCHAR2(30) Nfunding_rate_type VARCHAR2(30) Nfunding_rate_date DATE Nfunding_exchange_rate NUMBER Nbaseline_funding_flag VARCHAR2(1) Nmulti_currency_billing_flag VARCHAR2(1) Ncompetence_match_wt NUMBER Navailability_match_wt NUMBER Njob_level_match_wt NUMBER Nenable_automated_search VARCHAR2(1) Nsearch_min_availability NUMBER Nsearch_org_hier_id NUMBER Nsearch_starting_org_id NUMBER Nsearch_country_id NUMBER N min_cand_score_reqd_for_nom NUMBER Nmax_num_of_sys_nom_cand NUMBER Nnon_lab_std_bill_rt_sch_id NUMBER Nsearch_country_code VARCHAR2(2) Ninv_by_bill_trans_curr_flag VARCHAR2(1) Nprojfunc_cost_rate_type VARCHAR2(30) Nprojfunc_cost_rate_date DATE Nassign_precedes_task VARCHAR2(1) N split_cost_from_workplan_flag VARCHAR2(1) Nsplit_cost_from_bill_flag VARCHAR2(1) Nadv_action_set_id NUMBER Nstart_adv_action_set_flag VARCHAR2(1) Npriority_code VARCHAR2(30) Nretn_billing_inv_format_id NUMBER Nretn_accounting_flag VARCHAR2(1) Nopp_value_currency_code VARCHAR2(15) Nrevaluate_funding_flag VARCHAR2(1) Ninclude_gains_losses_flag VARCHAR2(1) Nsecurity_level NUMBER Nlabor_disc_reason_code VARCHAR2(30) Nnon_labor_disc_reason_code VARCHAR2(30) NBill_To_Customer_id NUMBER NShip_To_Customer_id NUMBER N

PROJECT_OUT_REC_TYPE:


Name Type

pa_project_id NUMBERpa_project_number VARCHAR2(25)return_status VARCHAR2(1)

PROJECT_ROLE_TBL_TYPE: IS TABLE OF project_role_rec_type

The definition of Project_Role_rec_type is as follows:

Name Type Required?person_id NUMBER Yproject_role_type VARCHAR2(20) Ystart_date DATE Nend_date DATE N

CLASS_CATEGORY_TBL_TYPE: IS TABLE OF class_category_rec_typeThe definition of class_category_rec_type is as follows:

Name Type Required?class_category VARCHAR2(30) Yclass_code VARCHAR2(30) Ycode_percentage NUMBER N

TASK_IN_TBL_TYPE IS TABLE OF task_in_rec_typeThe definition of task_in_rec_type is as follows

Name Type Required?pm_task_reference VARCHAR2(25) Ypa_task_id NUMBER Utask_name VARCHAR2(20) Ylong_task_name VARCHAR2(240) Ypa_task_number VARCHAR2(25) Ntask_description VARCHAR2(250) Ntask_start_date DATE Ntask_completion_date DATE Npm_parent_task_reference VARCHAR2(25) Npa_parent_task_id NUMBER Uaddress_id NUMBER Ncarrying_out_organization_id NUMBER Nservice_type_code VARCHAR2(30) Ntask_manager_person_id NUMBER Nbillable_flag VARCHAR2(1) Nchargeable_flag VARCHAR2(1) Nready_to_bill_flag VARCHAR2(1) Nready_to_distribute_flag VARCHAR2(1) Nlimit_to_txn_controls_flag VARCHAR2(1) Nlabor_bill_rate_org_id NUMBER Nlabor_std_bill_rate_schdl VARCHAR2(20) N labor_schedule_fixed_date DATE N labor_schedule_discount NUMBER N non_labor_bill_rate_org_id NUMBER N non_labor_std_bill_rate_schdl VARCHAR2(30) N non_labor_schedule_fixed_date DATE N non_labor_schedule_discount NUMBER N labor_cost_multiplier_name VARCHAR2(20) N cost_ind_rate_sch_id NUMBER N rev_ind_rate_sch_id NUMBER N


inv_ind_rate_sch_id NUMBER N cost_ind_sch_fixed_date DATE N rev_ind_sch_fixed_date DATE N inv_ind_sch_fixed_date DATE N labor_sch_type VARCHAR2(1) N non_labor_sch_type VARCHAR2(1) N actual_start_date DATE N actual_finish_date DATE N early_start_date DATE N early_finish_date DATE N late_start_date DATE N late_finish_date DATE N scheduled_start_date DATE N scheduled_finish_date DATE N attribute_category VARCHAR2(30) N attribute1 VARCHAR2(150) N attribute2 VARCHAR2(150) N attribute3 VARCHAR2(150) N attribute4 VARCHAR2(150) N attribute5 VARCHAR2(150) N attribute6 VARCHAR2(150) N attribute7 VARCHAR2(150) N attribute8 VARCHAR2(150) N attribute9 VARCHAR2(150) N attribute10 VARCHAR2(150) N allow_cross_charge_flag VARCHAR2(1) N project_rate_date DATE N project_rate_type VARCHAR2(30) N cc_process_labor_flag VARCHAR2(1) N labor_tp_schedule_id NUMBER N labor_tp_fixed_date DATE N cc_process_nl_flag VARCHAR2(1) N nl_tp_schedule_id NUMBER N nl_tp_fixed_date DATE Nreceive_project_invoice_flag VARCHAR2(1) Nwork_type_id NUMBER Nemp_bill_rate_schedule_id NUMBER Njob_bill_rate_schedule_id NUMBER Nnon_lab_std_bill_rt_sch_id NUMBER Ntaskfunc_cost_rate_type VARCHAR2(30) Ntaskfunc_cost_rate_date DATE Ndisplay_sequence NUMBER Nwbs_level NUMBER NOBLIGATION_START_DATE DATE NOBLIGATION_FINISH_DATE DATE NESTIMATED_START_DATE DATE NESTIMATED_FINISH_DATE DATE NBASELINE_START_DATE DATE NBASELINE_FINISH_DATE DATE NCLOSED_DATE DATE NWQ_UOM_CODE VARCHAR2(30) NWQ_ITEM_CODE VARCHAR2(30) NSTATUS_CODE VARCHAR2(30) NWF_STATUS_CODE VARCHAR2(30) NPM_SOURCE_CODE VARCHAR2(30) NPRIORITY_CODE VARCHAR2(30) NMILESTONE_FLAG VARCHAR2(1) NCRITICAL_FLAG VARCHAR2(1) NINC_PROJ_PROGRESS_FLAG VARCHAR2(1) NLINK_TASK_FLAG VARCHAR2(1) NCALENDAR_ID NUMBER N


PLANNED_EFFORT NUMBER NDURATION NUMBER NPLANNED_WORK_QUANTITY NUMBER NTASK_TYPE NUMBER Nlabor_disc_reason_code VARCHAR2(30) Nnon_labor_disc_reason_code VARCHAR2(30) N

TASK_OUT_TBL_TYPE: S TABLE OF task_in_rec_type

Name Typepa_task_id NUMBERpm_task_reference VARCHAR2(25) return_status VARCHAR2(1)task_version_id NUMBER

Project Information

Basic project Information like project number, Project name, long name

required to create a project are passed as parameters to the API. Depending

on the project template setup and quick entry setup, parameters are decided

to be mandatory for API. Information like project type, project status, project

Organization, distribution rules, retention tax codes, Project classifications,

currencies, billing setup etc., can be setup at the template level so that these

project templates can be used for creation of projects. If certain parameter

information is not defined in the template or if you intend to over write the

template values the same should be passed as parameters to API.

If there is retention setup in project template, to copy this there should

either be project template date or project start date. If project template date or

project start date is not available then project will not be created despite the

customer details being passed to the API.

Task Structure

Task structure will not be copied from project template when project is

created from API unlike copying the project template to a new project from the

application. The task structure should be explicitly passed to projects API.

Task structure should be passed to API in the order they should be

created. Top tasks and parent tasks should be given prior to the task being

created. In case ordering is not done, the task structure will not be copied and

project will not be created. Further if the project is created and the task


structure created without ordering, errors would occur on entering

expenditures against the task. More information on this can be obtained from

Metalink note 278492.1.

If task structure is created when the order is not correct, there is a possibility

that the parent task_id’s and the top task_id’s will not be populated correctly.

For some of the tasks the top task_id's that are populated will not be that of

top tasks. In such a scenario, where the API is allowing creation of tasks

although task structure is passed in incorrect order, application of patch

3261065 will resolve the problem and enable the API to show a proper error

message on stopping the project creation.

Classifications

Classifications setup defined as mandatory in quick entry field should

be attached to the project. If the project template has the mandatory

classifications attached, then these classifications are not required to be

passed while uploading projects using API. In case these classifications are

not setup in the template then the classifications mandatory need to be

passed to the API as parameter using the class_category_tbl_type parameter.

These classification values will be appended to the values already defined in

the template. If the classification values being passed via API is already setup

at project template level, API execution errors. When populating the

categories if the code_percentage is not given API may populate junk

numbers or characters. To avoid this problem you need to pass the value of

code_percentage value FND_API.G_MISS_NUM. This is advisory although

not mandatory.

Key Members

Project_role_tbl_type is a table type parameter, which is passed to

create_project API for copying key members. All the key members required


on the project should be passed to the create_project API. Alternatively if

there are set of employees who will have to be defined as key members on all

the projects, the same set of employees can be setup at the template level

instead of passing the employees as parameters via API. Project manager is

a mandatory role to be defined on any project. If this role is defined at the

template level, then this should not be included in the project_role_tbl_type

parameter, as it is already passed to the API through the project record. If key

member with same role already exist on project template, the same should

not be passed as parameter to API, else the API will error out.

In the project template if transaction duration dates are given, then the

key member start date will be determined retrospective from the project start

date. If the employee is having a valid assignment during these dates, the key

member will be attached else the employee will not copied as key members.

The API will give no message or warning.

When no key member dates are being passed via API, project start

date defaults as key member start date. When all the dates (Template trans

start date, project start date, key member start date) are null, then the start

date of the key member defaults as the first day of the year in which the

project is copied, otherwise start date of assignment of the employee defaults

as key member start date if the employee is defined in HR later during the

same year.

If the employees being copied using API do not have valid HR assignments

as per the retrospective key member start date based on the project template

start date and project start date project is created with out giving any error

messages but these key members will not be copied to the new project

created.

PA_PROJECT_PUB.Update Project

This API is used to update project and task information for an existing

project. This API can also be used to update a template project.

The parameters for Update_project are as follows:


Name Usage TYPE Required?

p_api_version_number IN NUMBER Yp_commit IN VARCHAR2 Yp_init_msg_list IN VARCHAR2 Yp_msg_count OUT NUMBERp_msg_data OUT VARCHAR2p_return_status OUT VARCHAR2p_workflow_started OUT VARCHAR2p_pm_product_code IN VARCHAR2 Yp_project_in IN project_in_rec_type Yp_project_out OUT project_out_rec_typep_key_members IN project_role_tbl_type Np_class_categories IN class_category_tbl_type Np_tasks_in IN task_in_tbl_type Np_tasks_out OUT task_out_tbl_type p_org_roles IN project_role_tbl_type Np_structure_in IN structure_in_rec_type N p_structure_out OUT structure_out_rec_typep_pass_entire_structure IN VARCHAR2 N

Project Information

Basic projects information like project name, long name, project

description, task structure, and key member information can be updated using

update_project. The unique project that is to be updated will be identified by

the pm_project_reference. In case the project is created manually (ie, using

copy to functionality) the project will be created with out populating the

pm_task_reference. To update such projects created using ‘copy to’

functionality, pass the project_id along with the pm_project_reference, which

will be used to identify the unique project to be updated by the update_project

API.

Task Structure

Tasks can be added to the project. When the project is updated, tasks

will be appended to existing task structure. When trying to update existing

task, unique task will be identified by pm_task_reference. In case the task is

not created with the project API (for the projects created using copy to

function), then pm_task_reference is not populated and hence it will try to add

this task, which in turn will give an error “unique constraint” as the same

already exists. In this case the unique task will be identified by the


task_number and task_id. So these values need to pass to update_project

API.

In general, the task structure should be updated to add additional tasks

to the existing WBS structure. In such case we have to follow the same

process as we do in the creation of project.

Classifications

If additional classifications need to be appended to the project, you can

pass these values to the update API and append new classifications to the

project.

Key Members

If more key members need to be added to the project we can use

update API to add key members in bulk. Key members may play a major role

in terms of project security.

Implementation of Project APIs – Case Study

This case study of project API’s (create_project and update project) will

provide you assistance in migration from legacy systems to Oracle Projects

and further in the maintenance of projects with WBS structure.

Requirement Description

XYZ Corporation has been using various business information systems

like Microsoft projects, Excel, Primavera, CASH, and COINS for maintaining

their management information system. In the process of providing an

integrated solution for the company, XYZ Corporation decides to implement

Oracle Applications. XYZ Corporation intends to implement Oracle Projects


Accounting (Projects Billing and Costing). As a part of implementation, the

company decided to migrate all the projects existing in the legacy system to

Oracle projects. The requirement is to create projects in Oracle projects from

all the existing legacy systems.

When the implementation takes off, the exact WBS structure is not

known for few projects. But as the projects progresses, WBS is added and

hence XYZ Corporation wants to update projects with new task structure quite

often. XYZ Corp. is also very keen in security of the projects. There is a

security need for based on the key members and roles setups. Further, the

users in XYZ Corporation want to add more employees as key members. This

addition of key members can happen in two ways. One is where different key

members can be added to all the projects or a set of employees will be

required to be added to the same project.

Project should be created with the following information:

- Basic information to create a project like project number, name,

description, long name, start date, end date, project status, project type

- WBS structure

- Key Members

- Classifications

- Billing Information like billing setup, billing assignments, retention

setup.

- Customer and contacts with bill to information

- Attributes for DFF

Solution Approach

Step1: Data template for gathering project information is designed which

consist of all the fields required for the project, customer, task, classification and key members. All parameter values required for create_project and update_project are included in data template. Additional fields can be added to the data template to build the logic for custom programs like line_type to identify creation or updation of project, record_number to identify the


sequence to be used for sorting records and task structure. Task structure need to be passed in same order as expected task structure to be created; otherwise, the API will fail.

Step2: Custom tables are designed to insert values from data files provided

from legacy systems and custom programs are developed to read the data into standard tables, validate the data and make calls to the Project API’s.

Step3: Create few project templates with common setups for creation of the

projects using API’s. Multiple templates are required, as the same template cannot be used for all the projects. The number of templates can be decided by the project organizations, project types, billing setup, billing assignments, retention setup etc.

All required setups in project creation should be setup in quick entry as mandatory fields so that API validates these values as mandatory parameters. For example, if projects created from this template requires a key member with the Project Manager role as mandatory, then we need to Setup a key member with role project manger in the quick entry fields. When this is in place, unless a key member with role of project manager is defined either in the template or passed as a parameter for the create project API, project cannot be created and API will result in an error. Similarly, If the project type is contract, then customer setup is mandatory for billing purposes. So customer can also be setup at the quick entry setup as mandatory.

Common key members required on all the projects are defined at project template level so that these key members will be copied to all the projects created from the template. If there are any additional key members for a specific projects created from this template, the additional key members should be given in the data template so that these key members will be passed to project API and will be assigned as key members on the project.

Similarly, project classifications attached to project template will be copied to the project created from this project template. The common classifications are defined at the template level and project specific classifications are given in the data template.

Task structure in the project template will not have much significance in creation of the project from the Project API, as the task structure will not be copied when the project is created from this template using API. Task structure will be copied only when the project is created using the ‘copy to’function in the application. In case task structure is too big to be created it is easy to use update API to update the project template to add the task structure.

A project template of Project type contract is attached with the retention setup. If retention setup need to be copied from the template, there should be either project start date or project template start date. Otherwise the project


cannot be created as the API cannot determine the retention start dates and end dates. There are no parameters defined to create retention setup for the project-using project API.

In case projects created in the oracle system need to be approved or unapproved these values can be passed in the project API parameter and hence the template status can be any.

Step4: Prior to creation of projects, ensure customers, employees and the required setups are done in the Oracle applications system.

Step5: Run the custom programs that create the projects in the Oracle system. The custom program should do the following:

- Load data from the flat files to the staging tables- Validate the data loaded into the staging tables.- Pass these values to the API’s as parameters.- Should create output file, which gives the list of projects created, and

the projects failed with error messages, which will enable the user to input the right values to the parameters.

Step6: A manual activity is required to complete the process. - If the projects are copied with unapproved status, approve them

manually. - Add bill to contacts manually for every project of type contract.

Trouble shooting

- The package pa_interface_utils_pub.get_messages helps in providing output error messages. The messages help in troubleshooting. One can make necessary changes to the wrapper code or parameters being passed to help the API create the projects.

- The following SQL statement executes to list the error messages that can show up on running the AMG API:

SELECT message_number, message_name,

message_textFROM fnd_new_messagesWHERE message_name like 'PA%AMG' AND language_code = 'US'

- The following statement executes to find the version of AMG Api.

SELECT substr(text,1,150)

FROM all_source WHERE name = 'PA_PROJECT_PUB' AND owner = 'APPS' AND line = 2 AND type = 'PACKAGE'


Example: Code for the Create_project API

Note: The code below is only a sample. The input parameters may vary depending on the requirements.

-- Sample code to create a project

DECLARE

-- Declaration of the API standard parameters l_api_version_number NUMBER := 1.0; l_commit VARCHAR2(1) := 'T'; l_return_status VARCHAR2(1); l_init_msg_list VARCHAR2(1) := 'F'; l_msg_count NUMBER; l_msg_index_out NUMBER; l_msg_data VARCHAR2(2000); l_data VARCHAR2(2000); l_workflow_started VARCHAR2(1) := 'Y'; l_pm_product_code VARCHAR2(30);

-- Predefined Composite data types that are required to pass as parameters to Create_Project API.

l_project_in PA_PROJECT_PUB.PROJECT_IN_REC_TYPE;-- Record Type IN

l_project_out PA_PROJECT_PUB.PROJECT_OUT_REC_TYPE;-- Record Type OUT

l_key_members PA_PROJECT_PUB.PROJECT_ROLE_TBL_TYPE;-- Table Type IN

l_class_categories PA_PROJECT_PUB.CLASS_CATEGORY_TBL_TYPE;-- Table Type IN

l_tasks_in_rec PA_PROJECT_PUB.TASK_IN_REC_TYPE;-- Record Type

l_tasks_in PA_PROJECT_PUB.TASK_IN_TBL_TYPE;-- Table Type IN

l_tasks_out_rec PA_PROJECT_PUB.TASK_OUT_REC_TYPE;

-- Table Type l_tasks_out PA_PROJECT_PUB.TASK_OUT_TBL_TYPE;

-- Table Type OUT

API_ERROR EXCEPTION;

BEGIN

Fnd_global.apps_initialize(user_id,resp_id, resp_appl_id);

-- SET GLOBAL VALUES pa_interface_utils_pub.set_global_info(

p_api_version_number => 1.0,


p_responsibility_id => fnd_profile.value('RESP_ID'),p_user_id => fnd_profile.value('USER_ID'),p_msg_count => l_msg_count,p_msg_data => l_msg_data,p_return_status => l_return_status );

-- PRODUCT RELATED DATA l_pm_product_code := 'EXCEL'; -- This is the value defnied in Projects as source Code.

-- PROJECT DATA (PROJECT_IN_REC_TYPE)

l_project_in.created_from_project_id := 1199; -- Project id of project/template from which project is being created.

l_project_in.pa_project_number :='PROJECT1'; --Project Number

l_project_in.project_name :='Project Name'; -- project Name l_project_in.pm_project_reference := 'PROJECT1'; -- Project Reference in the external system.(This can be same as project number/name) l_project_in.description := 'This is sample code for create project';

l_project_in.project_status_code := 'UNAPPROVED'; -- valid status for the project

l_project_in.carrying_out_organization_id := 2; -- can default from template

l_project_in.start_date := '01-JAN-2000';-- can override default from template

l_project_in.completion_date := ''; -- can override default from template

l_project_in.actual_start_date := ''; l_project_in.actual_finish_date := ''; l_project_in.early_start_date := ''; l_project_in.early_finish_date := ''; l_project_in.late_start_date := ''; l_project_in.late_finish_date := ''; l_project_in.customer_id := 1086;

--KEY MEMBERS DATA (PROJECT_ROLE_TBL_TYPE)-- can be defaulted from the Template, but not from a Project -- any additional key members need to be assigned to the project need to be passed.-- here show for one key member, use loop to add multiple key members

l_key_members(1).person_id := 29757; l_key_members(1).project_role_type := 'PROJECT MANAGER'; l_key_members(1).start_date := '01-Jan-2000'; l_key_members(1).end_date := null;

--CLASS CATEGORIES DATA (CLASS_CATEGORY_TBL_TYPE)


l_class_categories(1).class_category := 'XXXXXXXX'; l_class_categories(1).class_code := 'XXXXXXX1'; l_class_categories(1).code_percentage:= Null;

--TASKS DATA -- Here in this example, I am presenting data for one task. use loop for multiple tasks.

l_tasks_in(1).pm_task_reference := 'TASK1'; l_tasks_in(1).task_name := 'TASK1'; l_tasks_in(1).long_task_name := 'TASK1'; l_tasks_in(1).pa_task_number := 'TASK1'; l_tasks_in(1).task_description := 'SCRIPT TO TEST API'; l_tasks_in(1).task_start_date := '09-JUN-03'; l_tasks_in(1).task_completion_date := Null; l_tasks_in(1).pm_parent_task_reference := NULL; --CREATE_PROJECT pa_project_pub.create_project(

l_api_version_number,p_commit => l_commit,p_init_msg_list => l_init_msg_list,p_msg_count => l_msg_count,p_msg_data => l_msg_data,p_return_status => l_return_status,p_workflow_started => l_workflow_started,p_pm_product_code => l_pm_product_code,p_project_in => l_project_in,p_project_out => l_project_out,p_key_members => l_key_members,p_class_categories => l_class_categories,p_tasks_in => l_tasks_in,p_tasks_out => l_tasks_out);

-- Check for errors if l_return_status != 'S' -- if 'S' then the project is created successfully. then raise API_ERROR; end if;

-- can use fnd_message.put_line if running in Oracle applications dbms_output.put_line('New Project Id: '|| l_project_out.pa_project_id);

--HANDLE EXCEPTIONS-- Get the error message that were returned if it did not complete sucessfully EXCEPTION When API_ERROR then if l_msg_count >= 1 then for i in 1..l_msg_count loop pa_interface_utils_pub.get_messages(


p_msg_data => l_msg_data,p_encoded => 'F',p_data => l_data,p_msg_count => l_msg_count,p_msg_index => l_msg_count, -- Added in 11i.PA.Ip_msg_index_out => l_msg_index_out);

dbms_output.put_line('error message: ' || l_data); end loop; rollback; end if; When OTHERS then if l_msg_count >= 1 then for i in 1..l_msg_count loop pa_interface_utils_pub.get_messages(

p_msg_count => l_msg_count,p_encoded => 'F',p_msg_data => l_msg_data,p_data => l_data,p_msg_index => l_msg_count, -- Added in 11i.PA.Ip_msg_index_out => l_msg_index_out);

dbms_output.put_line('error message: ' || l_data); end loop; rollback; end if;END;

Note: The procedure pa_interface_utils_pub.set_global_info is called

before the call is made to the Create project API. Access to Oracle Projects is controlled not only by a user’s responsibility, but also by the user’s organization for that responsibility. The package ensures that the level access to data matches a user’s organization.This procedure is used to output the error messages given by the API. Usage of this procedure displays a meaningful error message and also the actions to be taken to clear the error.

Example: Code for the Update_project API

-- sample code to update a project DECLARE -- Variables needed for API standard parameters l_api_version_number NUMBER := 1.0; l_commit VARCHAR2(1) := 'T'; l_return_status VARCHAR2(1); l_init_msg_list VARCHAR2(1) := 'F'; l_msg_count NUMBER; l_msg_index_out NUMBER; l_msg_data VARCHAR2(2000); l_data VARCHAR2(2000); l_workflow_started VARCHAR2(1) ; l_pm_product_code VARCHAR2(10);

-- Predefined Composite data types l_project_in PA_PROJECT_PUB.PROJECT_IN_REC_TYPE; l_project_out PA_PROJECT_PUB.PROJECT_OUT_REC_TYPE; l_key_members PA_PROJECT_PUB.PROJECT_ROLE_TBL_TYPE; l_class_categories PA_PROJECT_PUB.CLASS_CATEGORY_TBL_TYPE; l_tasks_in_rec PA_PROJECT_PUB.TASK_IN_REC_TYPE;


l_tasks_in PA_PROJECT_PUB.TASK_IN_TBL_TYPE; l_tasks_out_rec PA_PROJECT_PUB.TASK_OUT_REC_TYPE; l_tasks_out PA_PROJECT_PUB.TASK_OUT_TBL_TYPE;

API_ERROR EXCEPTION;

BEGIN

-- SET GLOBAL VALUES pa_interface_utils_pub.set_global_info(

p_api_version_number => 1.0,p_responsibility_id => fnd_profile.value('RESP_ID'),p_user_id => fnd_profile.value('USER_ID'),p_msg_count => l_msg_count,p_msg_data => l_msg_data,p_return_status => l_return_status);

-- PRODUCT RELATED DATA l_pm_product_code := 'EXCEL';-- This is the value defnied in Projects as source Code.

-- PROJECT DATA (PROJECT_IN_REC_TYPE)l_project_in.project_name := 'Project Name Updated';l_project_in.pm_project_reference := 'PROJECT1';

l_project_in.pa_project_id := 1391; -- pass this if this project is not created using API

l_project_in.Customer_id := 1082;l_project_in.bill_To_Customer_id := 1056;l_project_in.Ship_To_Customer_id := 1056;

--KEY MEMBERS DATA (PROJECT_ROLE_TBL_TYPE)-- can be defaulted from the Template, but not from a Project -- any additional key members need to be assigned to the project need to be passed.-- here show for one key member, use loop to add multiple key members

l_key_members(1).person_id := 29757; l_key_members(1).project_role_type := 'CLERK'; l_key_members(1).start_date := '01-Jan-2002'; l_key_members(1).end_date := null;

--CLASS CATEGORIES DATA (CLASS_CATEGORY_TBL_TYPE)

l_class_categories(1).class_category := 'XXXXXXXX'; l_class_categories(1).class_code := 'XXXXXXX1'; l_class_categories(1).code_percentage:= Null;

--TASKS DATA -- Here in this example, I am presenting data for one task. use loop for multiple tasks.

l_tasks_in(1).pm_task_reference := 'TASK2';l_tasks_in(1).pa_task_number := 'TASK2';l_tasks_in(1).task_name := 'TASK5 Name2';l_tasks_in(1).task_START_DATE := '01-JAN-2005';

-- l_tasks_in(1).pa_task_id := ; -- pass this value if trying to update a task created manually


l_tasks_in(1).long_task_name := 'TASK5 long name';l_tasks_in(1).pa_task_number := 'TASK4';

l_tasks_in(1).task_description := 'SCRIPT TO TEST UPDATE API';

l_tasks_in(1).task_start_date := '09-JUN-03'; l_tasks_in(1).task_completion_date := Null; l_tasks_in(1).pm_parent_task_reference := NULL;

--CREATE_PROJECT pa_project_pub.UPDATE_project(

l_api_version_number,p_commit => l_commit,p_init_msg_list => l_init_msg_list,p_msg_count => l_msg_count,p_msg_data => l_msg_data,p_return_status => l_return_status,p_workflow_started => l_workflow_started,p_pm_product_code => l_pm_product_code,p_project_in => l_project_in,p_project_out => l_project_out,p_key_members => l_key_members,p_class_categories => l_class_categories,p_tasks_in => l_tasks_in,p_tasks_out => l_tasks_out);

-- Check for errors if l_return_status != 'S' then

dbms_output.put_line('Status ' || l_return_status);raise API_ERROR;

ELSEdbms_output.put_line('Status ' || l_return_status);

end if;

Commit;

--HANDLE EXCEPTIONS-- Get the error message that were returned if it did not complete sucessfully EXCEPTION When API_ERROR then if l_msg_count >= 1 then for i in 1..l_msg_count loop pa_interface_utils_pub.get_messages(

p_msg_data => l_msg_data,p_encoded => 'F',p_data => l_data,p_msg_count => l_msg_count,p_msg_index => l_msg_count, -- Added in 11i.PA.Ip_msg_index_out => l_msg_index_out);

dbms_output.put_line('error message: ' || l_data||'Status '|| l_return_status); end loop; rollback; end if; When OTHERS then if l_msg_count >= 1


then for i in 1..l_msg_count loop pa_interface_utils_pub.get_messages(

p_msg_count => l_msg_count,p_encoded => 'F',p_msg_data => l_msg_data,p_data => l_data,p_msg_index => l_msg_count, -- Added in 11i.PA.Ip_msg_index_out => l_msg_index_out);

dbms_output.put_line('error message: ' || l_data||'Status '|| l_return_status); end loop; rollback; end if;END;

Known Issues

- Create_project API performance is good. But the performance in updations/deletion of a huge task structure (say 30000 tasks) is generally poor.

- No error message when key members in a project template are not being copied onto the new project. The key members assignment date is not active in the given scenario. (Bug/Enhancement 3951335)

- Create_Project and Update_project API’s do not have parameters to create the contacts, which are necessary for billing the project. This has to be populated manually for the project.

- Create project/Update will not allow the addition of retention setup. Only if project template has a project start date, the retention setup will be copied to the new project.

- Bill To Address and Ship To Address will not be copied using API. The primary Bill To and Ship To will be populated for the customer.

Reference:

1) Oracle Projects User Guide, Release 11i, Part Number A82836-012) Oracle Activity Management Gateway Technical Reference Manual, Release 11i, Part Number A83510-013) Oracle Projects Technical Reference Manual, Release 11i,Part Number A81201-013) Oracle Projects - APIs, Client Extensions and Open Interfaces Reference4) Oracle Projects Implementation Guide, Release 11i, Part Number B12389-015) Oracle Applications Developer Guide.


White Paper Title: IMPLEMENTATION OF PROJECT FOUNDATION API’s [MAR] 2005

Author: VAMSI ANDAVARAPU, GLOBAL PRODUCT SUPPORT, ORACLEReviewer:HELEN MOSES, GLOBAL PRODUCT SUPPORT, ORACLE

Oracle CorporationWorld Headquarters500 Oracle ParkwayRedwood Shores, CA 94065U.S.A.

Worldwide Inquiries:Phone: +1.650.506.7000Fax: +1.650.506.7200www.oracle.com

Oracle is a registered trademark of Oracle Corporation. Variousproduct and service names referenced herein may be trademarksof Oracle Corporation. All other product and service namesmentioned may be trademarks of their respective owners.

Disclaimer: This document is provided for information purposes only and the contentshereof are subject to change without notice. Oracle does not warrant that this documentis error-free, nor does it provide any other warranties or conditions, whether expressedorally or implied in law, including implied warranties and conditions of merchantabilityor fitness for a particular purpose. Oracle specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectlyby this document. This document may not be reproduced or transmitted in any form orby any means, electronic or mechanical, for any purpose, without the prior written permission of Oracle.

Copyright © 2003 Oracle CorporationAll rights reserved.

foundation apis

Documents