Huntersummer352

Primavera Integration API Programmer's Reference

Contents
Introduction
Modes of Operation
Security
Packages
Where to Begin
Session
GlobalObjectManager
EnterpriseLoadManager
Business Objects
JobManager
Batch Exception Handling
Timestamps
Resource Security
XMLExporter
XMLImporter
XML Schema
Performance Tips
Demo Applications

Introduction
The Integration API provides a flexible, object-oriented interface to Primavera's project management functionality. The API is a cross-platform, Java-based interface.

Nov 28, 2017 Primavera P6 Project Layout Files are a valuable feature for mirroring reports on different projects in P6. It is possible to save or export and store P6 Project Layout Files in the windows operating system. These PLF files can then be imported and opened to produce a similar screen report on a different project. Microsoft Project 2000/2003, 2007, 2010 and 2013 XML files are exported and imported by Primavera, removing the requirement to have Microsoft Project loaded, Primavera Project Planner P3 and SureTrak files saved in P3 format. A SureTrak project in SureTrak format should be saved in Concentric (P3) format before importing, this function needs P3. May 01, 2020 Primavera P6 Professional has the functionality to save and store these layouts as project layout files (PLF). These PLF files can then be recalled to provide similar reports on other projects.This article introduces Primavera P6 Professional PLF files to save and restore activity screen layouts for schedule planning and reporting.PLF files are not just for the activity’s screen. Sep 17, 2013 This is an open discussion about the attached primavera schedule, This schedule submitted from our site member and we need to help improving the quality of the time schedules as we discuss the mistakes and the ways to make such schedule looks better. Download the schedule from the following link: Download primavera files. download#5 wk1-project.

This document provides information on how to use the API. See the Administrator's Guide for information on installing and configuring the API and system requirements. For information on how to use specific classes, see the Javadoc.

Modes of Operation
The API is designed to run in one of two modes: Local or Remote.

In Local Mode, the client code runs in the same Java Virtual Machine (JVM) as the Integration server. Java Remote Method Invocation (RMI) is not used, and the Integration API communicates directly with the business rule code in the server (the Business Rule Engine). Local Mode is useful for when the API client code with be deployed on the same physical machine as the internal Business Rule Engine. It can also be useful for applications that require the improved performance achieved by avoiding the RMI layer. Of course, Local Mode could be called directly from JSP pages that are deployed as part of a Web Application.

In Remote Mode, the client code runs on a different machine than the Integration server and Java Remote Method Invocation (RMI) is used for communication. Multiple clients can communicate with the Integration server simultaneously.

Note: The maximum number of clients that can access a remote server at one time is approximately 50. This number may be less, depending on multiple factors including system hardware, network configuration, and even the number of available licenses.

There are three possible service modes for the RMI server: Standard, Compression, and SSL. By default, all three modes are enabled. The RMI server also requires the RMI Registry, which listens to port 9099 by default. You can change the default settings for the RMI server via the Administrator tool, which can be launched using admin.cmd (admin.sh for Solaris). The following settings can be found under ConfigurationsCustom<Configuration Name>IntegrationServerRMI:

Enable - Enables (true) or disables (false) the RMI server (default setting is true).

RegistryPort - Port for the RMI Registry (default setting is 9099).

StandardServiceEnable - Enables (true) or disables (false) the Standard service mode (default setting is true).

StandardServicePort - Port to use for Standard service mode. A setting of 0 (default) means that any available port will be used. If the server will be accessed across a firewall, you must set this to a specific port.

Sample Project Report

CompressionServiceEnable - Enables (true) or disables (false) the Compression service mode (default setting is true).

CompressionServicePort - Port to use for Compression service mode. A setting of 0 (default) means that any available port will be used. If the server will be accessed across a firewall, you must set this to a specific port.

SSLServiceEnable - Enables (true) or disables (false) the SSL service mode (default setting is true).

SSLServicePort - Port to use for SSL service mode. A setting of 0 (default) means that any available port will be used. If the server will be accessed across a firewall, you must set this to a specific port.

If the API is configured to use Remote Mode, the service mode can be chosen at runtime using the RMIURL helper class: standard, compression, and SSL modes are available. HTTP tunneling may also be used if the HTTP or HTTPS service modes are selected. These additional modes encapsulate RMI communication in HTTP, allowing RMI to communicate through a firewall with only one port required to be open.

Note: P6 Web Services were released with version 6.2 and should be considered as an alternative to using the Remote Mode of the Integration API.

Security
Application layer security for the Integration API is similar to what is used by the Primavera client/server products. To use the API, you must log in as a named user. Global and project security profiles apply when using the API, so if a user attempts to perform an action that is restricted by a security profile, an exception will be thrown.

Network layer security is achievable by using either SSL or HTTPS in Remote Mode. The HTTPS calling mode uses HTTP tunneling, requiring only one port to be open in the firewall.

Note: See the section entitled 'Java Security Manager' in the Administrator's Guide for information on how to enable additional security through the use of a custom security policy.

Packages
Within the jar file, classes in the following packages can be accessed directly by client code:

com.primavera (base classes for Primavera exceptions)
com.primavera.common.exceptions (common exception classes)
com.primavera.common.value (value object classes)
com.primavera.common.value.spread (spread value classes)
com.primavera.integration.client (main classes, including Session, JobManager EnterpriseLoadManager, and GlobalObjectManager)
com.primavera.integration.client.bo (business object base class and iterator classes)
com.primavera.integration.client.bo.enm (typesafe enumerations)
com.primavera.integration.client.bo.helper (business object helper classes)
com.primavera.integration.client.bo.object (client business object classes)
com.primavera.integration.client.xml.exporter (Hierarchical XML exporter and related classes)
com.primavera.integration.client.xml.importer (Hierarchical XML importer and related classes)
com.primavera.integration.client.xml.xmlexporter (Flat XML exporter and related classes - new in version 6.2)
com.primavera.integration.client.xml.xmlimporter (Flat XML importer and related classes - new in version 6.2)
com.primavera.integration.common (general common classes)
com.primavera.integration.network (exception classes for Remote Mode)
com.primavera.integration.util (utility and helper classes)

Other packages in the jar file contain code for internal use only.

Where to Begin
If you will be writing code against the API, the Java Software Development Kit (SDK, also known as the JDK), version 1.5.x, must be installed. The Integrated Development Environment (IDE) used to write code must work with this version. If you will not be writing code, only the Java Runtime Environment (JRE), version 1.5.x, is required to be able to run applications written for the API.

The API client code for Remote Mode is contained in intgclient.jar. For Local Mode, the API code is contained in intgserver.jar. The jar files are installed in the lib directory under the Integration API installation directory. To successfully compile and execute the code written against the API, you will need to include the appropriate jar file in your classpath.

Note: For applications running in Local Mode, your classpath must include the other jar files that are installed in the lib directory under the Integration API installation directory. Local Mode applications must also have the System property 'primavera.bootstrap.home' set to the location of the installation directory. This setting is used by the server to find the BREBootStrap.xml file.

To access data in the API, you must first establish a valid session. Code written for Local Mode is the same as code written for Remote Mode, except for calls to Session.getDatabaseInstances() and Session.login(), which require the appropriate information to be specified for finding the server.

Example 1: Establish a session in Local Mode and load a collection of projects:

Example 2: Establish a session in Remote Mode, using the standard service mode, and load a collection of projects (see the Javadoc for RMIURL for information on how to specify other service modes):

Session
Session is the main class used for communicating with the server. To establish a valid session, a static login method is used. The session reference can then be used to access other main objects, such as the EnterpriseLoadManager.

To log in, a valid database instance must be specified if multiple database instances are defined in the current configuration. Use the Administrator tool to see the settings of your configuration. If multiple configurations are defined in the database, check the 'name' attribute of the BootstrapConfigurationsBRE element in the BREBootStrap.xml file to determine the configuration used by your server installation.

Before logging in, you can retrieve a list of available database instances by calling Session.getDatabaseInstances().

Note: The only difference in client code for Local Mode and Remote Mode is the call to Session.getDatabaseInstances() and Session.login(). For Remote Mode, the code must specify the URL of the RMI server. You can use com.primavera.integration.client.RMIURL to generate the RMI URL for different remote modes: Standard, Compression, or SSL.

Session is not a singleton, which means you can establish multiple simultaneous communication sessions with various servers and/or database instances. This can be useful for integrating with multiple Primavera databases.

GlobalObjectManager
Retrieve the GlobalObjectManager instance for a particular session by calling Session.getGlobalObjectManager(). This object is used for accessing all global business objects: EPS, Projects, Resources, Roles, etc. In general, a business object is global if it is not a child of a different type of object.

From the GlobalObjectManager, global objects can be created, loaded, updated, and deleted. Each of these methods will cause the database to be accessed. When running in Remote Mode, each of these methods results in a remote call to the server, which in turn may update the database.

EnterpriseLoadManager
Retrieve the EnterpriseLoadManager instance for a particular session by calling Session.getEnterpriseLoadManager(). This object is used for accessing all business objects directly without having to follow a navigation model.

Business Objects
A business object is an encapsulation of business data and functionality that usually corresponds to a record in a particular database table. Business objects contain fields, exposed as properties. Get() methods exist for all fields, and set() methods exist only for writable fields. Most business objects contain an ObjectId field, which serves as the primary key for that object.

Note: Client-side business objects are transient and should not be reused. For example, when creating a new instance of a client-side business object, after you call the create() method to create the object in the database, the object should be reloaded from the database if you intend to use it. This will help ensure that the data is valid, based on the server-side business rules. This warning also applies to updating business objects; after calling update(), reload the object if you intend to use it further.

Load methods that cause multiple business objects to be loaded will return a BOIterator (a business object iterator), that can be used to iterate through the returned business objects. Similar to Java's java.util.Iterator class, it has both hasNext() and next() methods. Not all business objects are retrieved from the server at one time. As you iterate through the result set, more business objects are automatically loaded from the server as needed.

When loading an object, the fields to be loaded can be specified. If this parameter is null, the minimal fields necessary will be loaded. You can obtain lists of available fields by calling the following methods:

getAllFields() - Returns an array of all fields for this business object. Code assignment and UDF value field names are not included in this array. For more information, see the Special Handling of Codes and UDFs section below.

getRequiredCreateFields() - Returns an array of fields required to create this business object. Some business objects have fields listed in this array that are OR'ed. These fields will appear in the array separated by the '|' character. For example, the required create fields for Activity are 'Id', and 'ProjectObjectId|WBSObjectId,' meaning the Id field must always be set, and either the ProjectObjectId or the WBSObjectId must be set (setting only the ProjectObjectId will cause the Activity to be created at the project-level).

getDefaultXMLExportFields() - Returns an array of fields that are exported by default when null is specified for the fields parameter for the hierarchical XMLExporter methods. You can specify more or fewer fields as desired. User fields and Summary fields are not included in the default hierarchical XML export fields arrays.

getSpreadFields() - Returns an array of spread fields (unit and cost) for business objects that support spreads: EPS, Project, WBS, Activity, and ResourceAssignment.

getMainFields() - Returns all fields supported by the business object, except for summary, code assignment, and UDF fields.

Note: In order to have the API perform optimally, only specify to load the fields that are absolutely needed.

Primavera Sample Project Files Pdf

Business objects can be loaded directly using static load() methods of the class itself, from a parent object, from the GlobalObjectManager if the object is global, or from the EnterpriseLoadManager. Objects can be loaded by specifying an array of ObjectIds or by specifying a 'where' clause and/or an 'order by' clause. The where clause is used to filter the business objects when loaded.

• Where clauses that use Date data types must use the WhereClauseHelper to format the date value. See Load Activities Example below.
• Complex where clauses can be created using AND and OR.
• Where clauses follow SQL-92 grammar and support function calls of the SQL language, with some exceptions. Join statements and nested select statements are not supported. The DATEADD function of SQL Server is also not supported.

Sample Project Proposal

The following code examples demonstrate how to specify a where clause when loading business objects:

Example 1: Load all the projects that have an Id beginning with 'SAP-Project,' ordering by Id in ascending order:

Example 2: Load activities from a project where the actual start is within a particular date range, ordering by Name in descending order:

Example 3: Load all active timesheets from a timesheet period:

Special Handling of Codes and UDFs

Project, BaselineProject, Resource, and Activity objects can have associated code objects (ProjectCodes, ResourceCodes, and ActivityCodes). The association is represented by the ProjectCodeAssignment (for Project and BaselineProject), ResourceCodeAssignment, and ActivityCodeAssignment objects.

Activity, ActivityExpense, ActivityStep, ActivityStepTemplateItem, BaselineProject, Document, EPS, Project, ProjectIssue, ProjectRisk, Resource, ResourceAssignment, and WBS objects can have associated UDFs. The association and value are represented by the UDFValue object.

In previous releases, code and UDF assignments were handled as special fields on the related business objects. These methods have been deprecated in 5.0 SP3, however, and will most likely be removed in the version 7.0 release.

See the general and export demo applications for coding examples that show how to use the new code and UDF assignment business objects.

JobManager
The Job Manager is used to invoke all asynchronous jobs: schedule, summarize, apply actuals, store period performance, run Project Architect, and create batch reports. It is retrieved for a particular session by calling Session.getJobManager(). You can check the status of a particular asynchronous job by calling getJobStatus and passing in the job ID returned when the job was created. Other methods exist for deleting a job and getting a list of all jobs.

Note: Except for jobs created with the javaSchedule() and storePeriodPerformance() methods, jobs are serviced by the Primavera Job Service, which runs as a Windows service. If you have not installed the Primavera Job Service, see the Administrator's Guide for instructions on how to install the service on a Windows machine.

Batch Exception Handling
BatchException allows you to catch and collect all business rule exceptions without stopping the batch create/update transaction. After the whole batch create/update is processed, the data transaction is still rolled back but BatchException provides you a list of business rule exceptions that occurred during the process. Looping through the exception list, you can identify the problematic business objects. You may want to remove those from the transaction list and rerun the batch update/create again.

Using BatchExceptions
Batch exception handling can be turned on and off in a session. If batch exception handling is turned off (default mode), the batch create/update process fails when the first business rule exception is thrown. If the batch exception handling is turned on, the batch create/update process continues even if business rule exceptions are thrown.

Using BatchExceptions requires the following three steps:

1. Turn on batch exception handling
   Before you start your batch create/update transaction, you have to turn on batch exception handling using the setBatchFailOnFirstFlag(false) on the Session object. (You can use getBatchFailOnFirstFlag() to verify that the batch exception handling is turned on.)
   
2. Catch BatchExceptions
   Since a BatchException is a ServerException, it is important to catch BatchExceptions before ServerExceptions.
   
3. Loop through the list of business rule exceptions
   After the batch create/update, the getExceptionList() method provides a list of business rule exceptions that occurred during the transaction. Loop through the list of exceptions and use the getSource() method to determine the source object.
   The getSource() method returns a type of Object. You can then typecast the Object to Integer, and determine the row index number: Since one business object can throw several business rule exceptions, it is possible that the same row index has multiple exceptions in the list. To get all exceptions that belong to a particular index, use the getExceptionsByIndex() method. The getExceptionsByIndex() method returns a sorted map, where the key is the index in the batch, and the value is a list of exceptions for that index (see Example 2 below). For all business rule exceptions that are not associated with one particular row, the index number is -1 (UNKNOWN_INDEX).

Note: You can use the getSource() method on the BatchException object itself. It provides you a convenient way of getting the source Object of the first exception in the list without writing a loop.

Note: General, not business rule-related exceptions, may occur during the batch create/update but BatchException does not contain those. BatchException does not support batch deleting.

BatchException examples

Example 1: Catching BatchExceptions and looping through the exception list

Example 2: Separating business objects that had business rule exceptions during batch update using the getExceptionsByIndex() method

TimeStamps
Each business object now provides information about the user (getCreateUser()) and the date (getCreateDate()) when the business object was created. Similarly, the getLastUpdateUser() and getLastUpdateDate() return the user who updated the business object and the date it was updated respectively. The getCreateUser() and getLastUpdateUser() only return the name of the user. If the User object is needed, it will need to be loaded separately.

Example: Load all users that have been updated after June 30, 2005 at 6:00 AM. The results are ordered by the update date:

Resource Security
Resource security allows you to restrict a user's ability to access resources. Restricted resource access means that a user has access to a part of the resource hierarchy only. Privileges that control the resource hierarchy (add/edit/delete resource) still apply but only to those resources that the user has access to.

Resource access types

• Access to all resources
  

  If the User.AllResourceAccessFlag is True, the user has access to all resources and resource security does not apply.

• Restricted access to resources
  If the User.AllResourceAccessFlag is False, the user has limited access to resources.
  If the user is assigned to a resource in the hierarchy, that user has access to the assigned resource and all its children. You can assign only one resource to a user, multiple resource access nodes are not supported.
  If the user is not assigned to any resource in the hierarchy, that user does not have access to any resources.

Note: Admin Superusers always have access to all resources.

Accessing resources assigned to a project

If a user can access a project, that user is able to see all resources assigned to that project (activity, issue, risk, WBS) even if they are outside the user's resource access node. The user then can re-assign these resources anywhere, but will only be able to edit those that are under the user's resource access node. For more information on the resource security feature, refer to the Primavera Project Management module or P6 Web Access documentation.

The API implementation of resource security

Use the ResourceAccess business object to implement and maintain resource access in the API. For details on specific methods, refer to the JavaDoc.

Note: In the Project Management module's Users dialog, users are filtered based on your resource access settings. In the API, all users are loaded but the ability to modify a user's resource access settings is determined by your resource access settings. If the user is associated to a resource that is outside your resource access, you cannot change that user's resource access settings.

XMLExporter
The hierarchical XML Exporter is retrieved for a particular session by calling Session.getXMLExporter(). As of release 6.2, a new flat XML Exporter exists, located in the com.primavera.integration.client.xml.xmlexporter package. The flat exporter is simpler to use for integration, and also performs better than the hierarchical XML Exporter.

Sample Project Proposal Letter

The XML Exporters are used for writing business objects to XML. Every business object can be exported, either by specifying an array of ObjectIds or by specifying a where clause to use for loading the objects. Exporting non-global objects requires the parent object to be specified for the methods that have where clause parameters.

Another XMLExporter method, exportFullProject, exports a project and all of its child objects (such as WBS, Activities, ResourceAssignments, etc.). XML files created using exportFullProject can be imported using the XMLImporter.

When objects are exported, the fields to be exported can be specified. If the fields parameter is null, the default XML export fields will be used for each object. You can obtain this list of default fields for the hierarchical exporter by calling getDefaultXMLExportFields() on each business object class. For the flat exporter, the default fields are a combination of the default load fields and the required for create fields, with a few exceptions.

To specify specific business object types or fields to be included in the export, use XMLExporterListener. See the exporter demo application (ExportDemoApp.java) for example code.

Note: All business objects can be written individually to XML even without using the XMLExporter. Simply call toString() on a business object instance and all fields currently loaded in that business object will be output to XML using the same schema (p6apibo.xsd) as the flat XMLExporter.

XMLImporter
The hierarchical XML Importer is retrieved for a particular session by calling Session.getXMLImporter(). As of release 6.2, a new flat XML Importer exists, located in the com.primavera.integration.client.xml.xmlimporter package. The flat importer is simpler to use for integration, and also performs better than the hierarchical XML Importer.

The current version of the XML Importer only supports importing projects and project-related data generated using XMLExporter.exportFullProject(). For the list of business objects and related data exported by the XMLExporter.exportFullProject(), refer to the XMLExporter JavaDoc.

The XMLImporter can also import XML generated data from other sources if the XML conforms to the required schema and all necessary data are provided. However, anything that is not in the full-project export, does not get imported, even if it is in the schema (for example, Users). Note that read-only fields or business objects do not get imported either, and this version of the XMLImporter does not support importing Documents and related business objects.

An example of using the flat XMLImporter is provided by the importer demo application (ImportDemoApp.java).

Note: The XML Importer will not allow invalid data to be imported. It is your responsibility to ensure the data is valid before initiating the import process. For example, activities and resource assignments will not be imported if the actual finish date precedes the actual start date in the XML file.

If the data you would like to import is incomplete or does not conform to the full project export schema, you can still use the API to create an integration solution. One possibility would be to use DOM, SAX, or StAX to parse the XML yourself and then call the appropriate methods of the API directly. For XML files for which you have the XML Schema (XSD) available, an even better alternative might be to use an XML binding technology such as JAXB.

Note: It is highly recommended that you use the XMLImporter whenever possible due to the many complexities that can be involved in the import process in data dependency and matching.

XML Schema
The XML schema used by the hierarchical XMLExporter and XMLImporter is defined in the file prmbo.xsd, and can be found in the schema directory located under the installation directory. The new flat XMLExporter and XMLImporter use the p6apibo.xsd schema, found in the same directory. If the API is installed into a web/app server to support Remote Mode, the hierarchical schema file can be downloaded from the web server with the URL http://<host>:<port>/PrimaveraAPI/schema/prmbo.xsd, and the flat schema can be downloaded with the URL http://<host>:<port>/PrimaveraAPI/schema/p6apibo.xsd.

Performance Tips
Many factors can affect the performance of an application that uses the Integration API. The following tips will help the programmer avoid some of the more common performance problems:

• Login to the API as a user with the Admin Superuser global security profile.
• When creating or updating business objects, use methods that allow multiple objects to be processed at one time.
• When loading business objects, load only the fields that are absolutely necessary.
• Use where clauses to load business objects intelligently.
• When choosing the methods used to access business objects, be sure to use the methods that will most effectively minimize server and database traffic . For example, a project is the parent of its WBS hierarchy, and individual WBS objects can be parents of other business objects, such as activities. To access activities quickly, use the loadAllActivities() method of project to bypass the child WBS objects.
• Use only Local Mode with the XML exporter and importer.

Demo Applications
Demo applications are installed in the demo directory under the Integration API installation directory. Demo applications include source code, so they provide a working example of how to use the API.

The following demo applications are included with this release:

• demo.general.GeneralDemoApp provides sample code for creating, loading, updating, and deleting business objects. It will, among other things, add a new project, add activities to that project, add expenses to those activities, add global and project-specific activity code types, add new activity codes for those types, and assign some activity codes to activities. It will then load the activities from the server and output them to XML.
  
• demo.assignments.AssignmentsDemoApp loads all resource assignments across projects for the first 50 resources and generates an output HTML file. This application demonstrates the speed at which at which data can be accessed across projects.
  
• demo.xmlexport.ExportDemoApp performs an XML export of the first ten projects in the database, and using the XMLExportListener interface, specifies to include all fields when exporting activities and skip activity notes and WBS milestones.
  
• demo.xmlimport.ImportDemoApp performs an import of an XML file created using XMLExporter.exportFullProject().

Copyright

Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved.

P6 Commercial Notices and Disclosures for Documentation

Primavera Sample Project Files Download

To view the P6 Commercial Notices and Disclosures for Documentation, go to the Documentation<language>Notices and Disclosures folder of the P6 physical media or download.