Transcript
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
Implementation of Project Foundation API’s 3
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.
Implementation of Project Foundation API’s 4
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.
Implementation of Project Foundation API’s 5
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 API’s 6
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.
Implementation of Project Foundation API’s 7
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 API’s 8
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
Implementation of Project Foundation API’s 9
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
Implementation of Project Foundation API’s 10
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:
Implementation of Project Foundation API’s 11
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
Implementation of Project Foundation API’s 12
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
Implementation of Project Foundation API’s 13
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
Implementation of Project Foundation API’s 14
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
Implementation of Project Foundation API’s 15
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 API’s 16
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
Implementation of Project Foundation API’s 17
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
Implementation of Project Foundation API’s 18
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 API’s 19
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
Implementation of Project Foundation API’s 20
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'
Implementation of Project Foundation API’s 21
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,
Implementation of Project Foundation API’s 22
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)
Implementation of Project Foundation API’s 23
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(
Implementation of Project Foundation API’s 24
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;
Implementation of Project Foundation API’s 25
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
Implementation of Project Foundation API’s 26
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
Implementation of Project Foundation API’s 27
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.
Implementation of Project Foundation API’s 28
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.
top related