Implementation of Project Foundation APIs

(Create_project & Update_project)

(Oracle Projects11.5.9) An Oracle White Paper 14/Mar/05

Vamsi Andavarapu, Global Product Support,Oracle.

Table of Contents

Abstract.................................................................................................................... 3 Audience.................................................................................................................. 3 Introduction.............................................................................................................. 4 Prerequisites ........................................................................................................... 5 Activity Management Setup ............................................................................... 5 Template Setup................................................................................................... 6 Other Setups ....................................................................................................... 8 PA_PROJECT_PUB.Create Project..................................................................... 8 Parameters for Create_Projects :...................................................................... 8 Project Information............................................................................................ 13 Task Structure................................................................................................... 13 Classifications ................................................................................................... 14 Key Members .................................................................................................... 14 PA_PROJECT_PUB.Update Project .................................................................. 15 Project Information............................................................................................ 16 Task Structure................................................................................................... 16 Classifications ................................................................................................... 17 Key Members .................................................................................................... 17 Implementation of Project APIs Case Study................................................... 17 Requirement Description.................................................................................. 17 Solution Approach ............................................................................................ 18 Trouble shooting ................................................................................................... 20 Example Code for the Create_project API......................................................... 21 Example Code for the Update_project API ........................................................ 24 Known Issues........................................................................................................ 27

Implementation of Project Foundation APIs

Abstract This paper has been created to assist the usage of Oracle Project Foundation APIs create_project and update_project. Further it also discusses the pre-requisites for usage of APIs 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 APIs be used in migrating projects from legacy systems. Problems that are usually encountered in the implementation of APIs, 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 APIs- create_project and update_project and how the APIs can be used in the migration of the projects.

Audience

You are an Oracle Application professional interested in implementing projects APIs (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 APIs 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 APIs. A case study is also included which will be helpful for the consultants involved in the design of migrating projects from legacy systems.

Implementation of Project Foundation APIs

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 etcthen 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 APIs to integrate both the systems. This paper explains behaviour of APIs and how to use APIs in migration of projects defined in the external systems, how one can use the APIs 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 APIs.

A case study in the later section of this paper discusses how data is to be migrated from external systems to Oracle Projects using APIs. 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.

Implementation of Project Foundation APIs

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

Implementation of Project Foundation APIs

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 NonOracle 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.

Implementation of Project Foundation APIs

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.

Implementation of Project Foundation APIs

Other Setups Step 4: Prior to migrating projects from legacy applications, following prerequisites 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-toaddresses and the bill-to-addresses should have bill to contact setup. Create Project and Update Project APIs 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 P_API_VERSION_NUMBER P_COMMIT P_INIT_MSG_LIST P_MSG_COUNT P_MSG_DATA P_RETURN_STATUS P_WORKFLOW_STARTED P_PM_PRODUCT_CODE P_PROJECT_IN P_PROJECT_OUT P_KEY_MEMBERS P_CLASS_CATEGORIES P_TASKS_IN P_TASKS_OUT P_ORG_ROLES P_STRUCTUR_IN P_EXT_ATTR_TBL_IN Usage IN IN IN OUT OUT OUT OUT IN IN OUT IN IN IN OUT IN IN IN TYPE NUMBER VARCHAR2(1) VARCHAR2(1) NUMBER VARCHAR2(2000) VARCHAR2(1) VARCHAR2 VARCHAR2(30) PROJECT_IN_REC_TYPE PROJECT_OUT_REC_TYPE PROJECT_ROLE_TBL_TYPE CLASS_CATEGORY_TBL_TYPE TASK_IN_TBL_TYPE TASK_OUT_TBL_TYPE TABLE TYPE TABLE TYPE TABLE TYPE Required? Yes No No

Yes Yes No No No No No No

Implementation of Project Foundation APIs

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
pm_project_reference pa_project_id pa_project_number project_name long_name created_from_project_id carrying_out_organization_id public_sector_flag project_status_code description start_date completion_date distribution_rule customer_id project_relationship_code actual_start_date actual_finish_date early_start_date early_finish_date late_start_date late_finish_date scheduled_start_date scheduled_finish_date attribute_category attribute1 attribute2 attribute3 . . attribute10 output_tax_code retention_tax_code project_currency_code allow_cross_charge_flag project_rate_date project_rate_type cc_process_labor_flag abor_tp_schedule_id labor_tp_fixed_date cc_process_nl_flag nl_tp_schedule_id nl_tp_fixed_date cc_tax_task_id role_list_id work_type_id calendar_id location_id probability_member_id project_value

Type
VARCHAR2(25) NUMBER VARCHAR2(25) VARCHAR2(30) VARCHAR2(240) NUMBER NUMBER VARCHAR2(1) VARCHAR2(30) VARCHAR2(250) DATE DATE VARCHAR2(30) NUMBER VARCHAR2(30) DATE DATE DATE DATE DATE DATE DATE DATE VARCHAR2(30) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150)

Required?
Y For Update N N Y B B B B B B B B B Y N N N N N N N N N N N N

VARCHAR2(150) VARCHAR2(30) VARCHAR2(30) VARCHAR2(15) VARCHAR2(1) DATE VARCHAR2(30) VARCHAR2(1) NUMBER DATE VARCHAR2(1) NUMBER DATE NUMBER NUMBER NUMBER NUMBER NUMBER NUMBER NUMBER

N N N N N N N N N N N N N N N N N N N N

Implementation of Project Foundation APIs

expected_approval_date cost_job_group_id bill_job_group_id team_template_id country_code region city emp_bill_rate_schedule_id job_bill_rate_schedule_id invproc_currency_type revproc_currency_code project_bil_rate_date_code project_bil_rate_type project_bil_rate_date project_bil_exchange_rate projfunc_currency_code projfunc_bil_rate_date_code projfunc_bil_rate_type projfunc_bil_rate_date projfunc_bil_exchange_rate funding_rate_date_code funding_rate_type funding_rate_date funding_exchange_rate baseline_funding_flag multi_currency_billing_flag competence_match_wt availability_match_wt job_level_match_wt enable_automated_search search_min_availability search_org_hier_id search_starting_org_id search_country_id min_cand_score_reqd_for_nom max_num_of_sys_nom_cand non_lab_std_bill_rt_sch_id search_country_code inv_by_bill_trans_curr_flag projfunc_cost_rate_type projfunc_cost_rate_date assign_precedes_task split_cost_from_workplan_flag split_cost_from_bill_flag adv_action_set_id start_adv_action_set_flag priority_code retn_billing_inv_format_id retn_accounting_flag opp_value_currency_code revaluate_funding_flag include_gains_losses_flag security_level labor_disc_reason_code non_labor_disc_reason_code Bill_To_Customer_id Ship_To_Customer_id

DATE NUMBER NUMBER NUMBER VARCHAR2(250) VARCHAR2(250) VARCHAR2(250) NUMBER NUMBER VARCHAR2(30) VARCHAR2(15) VARCHAR2(30) VARCHAR2(30) DATE NUMBER VARCHAR2(15) VARCHAR2(30) VARCHAR2(30) DATE NUMBER VARCHAR2(30) VARCHAR2(30) DATE NUMBER VARCHAR2(1) VARCHAR2(1) NUMBER NUMBER NUMBER VARCHAR2(1) NUMBER NUMBER NUMBER NUMBER NUMBER NUMBER NUMBER VARCHAR2(2) VARCHAR2(1) VARCHAR2(30) DATE VARCHAR2(1) VARCHAR2(1) VARCHAR2(1) NUMBER VARCHAR2(1) VARCHAR2(30) NUMBER VARCHAR2(1) VARCHAR2(15) VARCHAR2(1) VARCHAR2(1) NUMBER VARCHAR2(30) VARCHAR2(30) NUMBER NUMBER

N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N

PROJECT_OUT_REC_TYPE:

Implementation of Project Foundation APIs

10

Name pa_project_id pa_project_number return_status

Type NUMBER VARCHAR2(25) VARCHAR2(1)

PROJECT_ROLE_TBL_TYPE: IS TABLE OF project_role_rec_type The definition of Project_Role_rec_type is as follows: Name

person_id project_role_type start_date end_date

Type
NUMBER VARCHAR2(20) DATE DATE

Required?
Y Y N N

CLASS_CATEGORY_TBL_TYPE: IS TABLE OF class_category_rec_type

The definition of class_category_rec_type is as follows:

Name
class_category class_code code_percentage

Type
VARCHAR2(30) VARCHAR2(30) NUMBER

Required?
Y Y N

TASK_IN_TBL_TYPE IS TABLE OF task_in_rec_type

The definition of task_in_rec_type is as follows

Name
pm_task_reference pa_task_id task_name long_task_name pa_task_number task_description task_start_date task_completion_date pm_parent_task_reference pa_parent_task_id address_id carrying_out_organization_id service_type_code task_manager_person_id billable_flag chargeable_flag ready_to_bill_flag ready_to_distribute_flag limit_to_txn_controls_flag labor_bill_rate_org_id labor_std_bill_rate_schdl labor_schedule_fixed_date labor_schedule_discount non_labor_bill_rate_org_id non_labor_std_bill_rate_schdl non_labor_schedule_fixed_date non_labor_schedule_discount labor_cost_multiplier_name cost_ind_rate_sch_id rev_ind_rate_sch_id

Type
VARCHAR2(25) NUMBER VARCHAR2(20) VARCHAR2(240) VARCHAR2(25) VARCHAR2(250) DATE DATE VARCHAR2(25) NUMBER NUMBER NUMBER VARCHAR2(30) NUMBER VARCHAR2(1) VARCHAR2(1) VARCHAR2(1) VARCHAR2(1) VARCHAR2(1) NUMBER VARCHAR2(20) DATE NUMBER NUMBER VARCHAR2(30) DATE NUMBER VARCHAR2(20) NUMBER NUMBER

Required?
Y U Y Y N N N N N U N N N N N N N N N N N N N N N N N N N N

Implementation of Project Foundation APIs

11

inv_ind_rate_sch_id cost_ind_sch_fixed_date rev_ind_sch_fixed_date inv_ind_sch_fixed_date labor_sch_type non_labor_sch_type actual_start_date actual_finish_date early_start_date early_finish_date late_start_date late_finish_date scheduled_start_date scheduled_finish_date attribute_category attribute1 attribute2 attribute3 attribute4 attribute5 attribute6 attribute7 attribute8 attribute9 attribute10 allow_cross_charge_flag project_rate_date project_rate_type cc_process_labor_flag labor_tp_schedule_id labor_tp_fixed_date cc_process_nl_flag nl_tp_schedule_id nl_tp_fixed_date receive_project_invoice_flag work_type_id emp_bill_rate_schedule_id job_bill_rate_schedule_id non_lab_std_bill_rt_sch_id taskfunc_cost_rate_type taskfunc_cost_rate_date display_sequence wbs_level OBLIGATION_START_DATE OBLIGATION_FINISH_DATE ESTIMATED_START_DATE ESTIMATED_FINISH_DATE BASELINE_START_DATE BASELINE_FINISH_DATE CLOSED_DATE WQ_UOM_CODE WQ_ITEM_CODE STATUS_CODE WF_STATUS_CODE PM_SOURCE_CODE PRIORITY_CODE MILESTONE_FLAG CRITICAL_FLAG INC_PROJ_PROGRESS_FLAG LINK_TASK_FLAG CALENDAR_ID

NUMBER DATE DATE DATE VARCHAR2(1) VARCHAR2(1) DATE DATE DATE DATE DATE DATE DATE DATE VARCHAR2(30) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(150) VARCHAR2(1) DATE VARCHAR2(30) VARCHAR2(1) NUMBER DATE VARCHAR2(1) NUMBER DATE VARCHAR2(1) NUMBER NUMBER NUMBER NUMBER VARCHAR2(30) DATE NUMBER NUMBER DATE DATE DATE DATE DATE DATE DATE VARCHAR2(30) VARCHAR2(30) VARCHAR2(30) VARCHAR2(30) VARCHAR2(30) VARCHAR2(30) VARCHAR2(1) VARCHAR2(1) VARCHAR2(1) VARCHAR2(1) NUMBER

N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N N

Implementation of Project Foundation APIs

12

PLANNED_EFFORT DURATION PLANNED_WORK_QUANTITY TASK_TYPE labor_disc_reason_code non_labor_disc_reason_code

NUMBER NUMBER NUMBER NUMBER VARCHAR2(30) VARCHAR2(30)

N N N N N N

TASK_OUT_TBL_TYPE: S TABLE OF task_in_rec_type

Name pa_task_id pm_task_reference return_status task_version_id Type NUMBER VARCHAR2(25) VARCHAR2(1) 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 Implementation of Project Foundation APIs 13

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_ids and the top task_ids 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

Implementation of Project Foundation APIs

14

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:

Implementation of Project Foundation APIs

15

Name p_api_version_number p_commit p_init_msg_list p_msg_count p_msg_data p_return_status p_workflow_started p_pm_product_code p_project_in p_project_out p_key_members p_class_categories p_tasks_in p_tasks_out p_org_roles p_structure_in p_structure_out p_pass_entire_structure

Usage IN IN IN OUT OUT OUT OUT IN IN OUT IN IN IN OUT IN IN OUT IN

TYPE NUMBER VARCHAR2 VARCHAR2 NUMBER VARCHAR2 VARCHAR2 VARCHAR2 VARCHAR2 project_in_rec_type project_out_rec_type project_role_tbl_type class_category_tbl_type task_in_tbl_type task_out_tbl_type project_role_tbl_type structure_in_rec_type structure_out_rec_type VARCHAR2

Required? Y Y Y

Y Y N N N N N 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

Implementation of Project Foundation APIs

16

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 APIs (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

Implementation of Project Foundation APIs

17

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

Implementation of Project Foundation APIs

18

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 APIs. Step3: Create few project templates with common setups for creation of the projects using APIs. 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

Implementation of Project Foundation APIs

19

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 APIs 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_text FROM fnd_new_messages WHERE message_name like 'PA%AMG' AND language_code = 'US'

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

SELECT FROM WHERE AND AND AND substr(text,1,150) all_source name = 'PA_PROJECT_PUB' owner = 'APPS' line = 2 type = 'PACKAGE'

Implementation of Project Foundation APIs

20

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 l_commit l_return_status l_init_msg_list l_msg_count l_msg_index_out l_msg_data l_data l_workflow_started l_pm_product_code NUMBER := 1.0; VARCHAR2(1) := 'T'; VARCHAR2(1); VARCHAR2(1) := 'F'; NUMBER; NUMBER; VARCHAR2(2000); VARCHAR2(2000); VARCHAR2(1) := 'Y'; VARCHAR2(30);

-- Predefined Composite data types that are required to pass as parameters to Create_Project API. l_project_in -- Record Type l_project_out -- Record Type l_key_members -- Table l_class_categories -- Table l_tasks_in_rec -- Record Type l_tasks_in -- Table PA_PROJECT_PUB.PROJECT_IN_REC_TYPE; IN PA_PROJECT_PUB.PROJECT_OUT_REC_TYPE; OUT PA_PROJECT_PUB.PROJECT_ROLE_TBL_TYPE; IN PA_PROJECT_PUB.CLASS_CATEGORY_TBL_TYPE; IN PA_PROJECT_PUB.TASK_IN_REC_TYPE;

Type

Type

PA_PROJECT_PUB.TASK_IN_TBL_TYPE; Type IN PA_PROJECT_PUB.TASK_OUT_REC_TYPE;

l_tasks_out_rec -- Table Type l_tasks_out -- Table API_ERROR BEGIN

PA_PROJECT_PUB.TASK_OUT_TBL_TYPE; Type OUT EXCEPTION;

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,

Implementation of Project Foundation APIs

21

p_responsibility_id p_user_id p_msg_count p_msg_data p_return_status

=> => => => =>

fnd_profile.value('RESP_ID'), fnd_profile.value('USER_ID'), l_msg_count, l_msg_data, l_return_status );

-- PRODUCT RELATED DATA l_pm_product_code := 'EXCEL'; defnied in Projects as source Code. -- PROJECT DATA (PROJECT_IN_REC_TYPE)

-- This is the value

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 Project Number :='PROJECT1'; --

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 for the project := 'UNAPPROVED'; -- valid status

l_project_in.carrying_out_organization_id from template l_project_in.start_date override default from template l_project_in.completion_date 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 := := := := := := :=

:= 2;

-- can default

:= '01-JAN-2000';-- can

:= '';

-- can

''; ''; ''; ''; ''; ''; 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 l_key_members(1).project_role_type l_key_members(1).start_date l_key_members(1).end_date := 29757; := 'PROJECT MANAGER'; := '01-Jan-2000'; := null;

--CLASS CATEGORIES DATA (CLASS_CATEGORY_TBL_TYPE)

Implementation of Project Foundation APIs

22

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 l_tasks_in(1).task_name l_tasks_in(1).long_task_name l_tasks_in(1).pa_task_number l_tasks_in(1).task_description l_tasks_in(1).task_start_date l_tasks_in(1).task_completion_date l_tasks_in(1).pm_parent_task_reference := := := := := := := := 'TASK1'; 'TASK1'; 'TASK1'; 'TASK1'; 'SCRIPT TO TEST API'; '09-JUN-03'; Null; 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(

Implementation of Project Foundation APIs

23

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.I p_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.I p_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 users responsibility, but also by the users organization for that responsibility. The package ensures that the level access to data matches a users 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;

Implementation of Project Foundation APIs

24

l_tasks_in l_tasks_out_rec l_tasks_out API_ERROR BEGIN

PA_PROJECT_PUB.TASK_IN_TBL_TYPE; PA_PROJECT_PUB.TASK_OUT_REC_TYPE; PA_PROJECT_PUB.TASK_OUT_TBL_TYPE; EXCEPTION;

-- 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 l_project_in.pm_project_reference l_project_in.pa_project_id this if this project is not created using l_project_in.Customer_id l_project_in.bill_To_Customer_id l_project_in.Ship_To_Customer_id

:= 'Project Name Updated'; := 'PROJECT1'; := 1391; -- pass API := := := 1082; 1056; 1056;

--to --

--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 be passed. here show for one key member, use loop to add multiple key members l_key_members(1).person_id l_key_members(1).project_role_type l_key_members(1).start_date l_key_members(1).end_date := 29757; := 'CLERK'; := '01-Jan-2002'; := 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

Implementation of Project Foundation APIs

25

l_tasks_in(1).long_task_name l_tasks_in(1).pa_task_number l_tasks_in(1).task_description API';

:= 'TASK5 long name'; := 'TASK4'; := 'SCRIPT TO TEST UPDATE

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 => p_init_msg_list => p_msg_count => p_msg_data => p_return_status => p_workflow_started => p_pm_product_code => p_project_in => p_project_out => p_key_members => p_class_categories => p_tasks_in => p_tasks_out =>

l_commit, l_init_msg_list, l_msg_count, l_msg_data, l_return_status, l_workflow_started, l_pm_product_code, l_project_in, l_project_out, l_key_members, l_class_categories, l_tasks_in, l_tasks_out);

-- Check for errors if l_return_status != 'S' then dbms_output.put_line('Status ' || l_return_status); raise API_ERROR; ELSE dbms_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.I p_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

Implementation of Project Foundation APIs

26

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.I p_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 APIs 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-01 2) Oracle Activity Management Gateway Technical Reference Manual, Release 11i, Part Number A83510-01 3) Oracle Projects Technical Reference Manual, Release 11i,Part Number A81201-01 3) Oracle Projects - APIs, Client Extensions and Open Interfaces Reference 4) Oracle Projects Implementation Guide, Release 11i, Part Number B1238901 5) Oracle Applications Developer Guide.

Implementation of Project Foundation APIs

27

White Paper Title: IMPLEMENTATION OF PROJECT FOUNDATION APIs [MAR] 2005

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

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 www.oracle.com Oracle is a registered trademark of Oracle Corporation. Various product and service names referenced herein may be trademarks of Oracle Corporation. All other product and service names mentioned may be trademarks of their respective owners. Disclaimer: This document is provided for information purposes only and the contents hereof are subject to change without notice. Oracle does not warrant that this document is error-free, nor does it provide any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Oracle specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the prior written permission of Oracle. Copyright 2003 Oracle Corporation All rights reserved.

Implementation of Project Foundation APIs

28