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 P6 Integration API provides a flexible, object-oriented interface to Oracle Primavera P6 EPPM functionality. The API is a cross-platform, Java-based interface.
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 will 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 can be less, depending on multiple factors including system hardware and network configuration.
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 AIX, HPUX, Linux, Solaris). The following settings can be found under Configurations\Custom\<Configuration Name>\Integration API Server\RMI:
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.
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.
Note: P6 Web Services should be considered as an alternative to using the Remote Mode of the P6 Integration API.
Security
Application layer security for the Integration API is similar to what is used by the Primavera client/server products. 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 SSL.
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.xmlexporter
com.primavera.integration.client.xml.xmlimporter
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.6_20 and above, 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.6.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:
import com.primavera.integration.client.Session;
import com.primavera.integration.client.EnterpriseLoadManager;
import com.primavera.integration.client.RMIURL;
import com.primavera.integration.common.DatabaseInstance;
import com.primavera.integration.client.bo.BOIterator;
import com.primavera.integration.client.bo.object.Project;
public class APITest
{
public static void main( String[] args )
{
Session session = null;
try
{
DatabaseInstance[] dbInstances = Session.getDatabaseInstances( RMIURL.getRmiUrl( RMIURL.LOCAL_SERVICE ) );
// Assume only one database instance for now, and hardcode the username and
// password for this sample code
session = Session.login( RMIURL.getRmiUrl( RMIURL.LOCAL_SERVICE ), dbInstances[0].getDatabaseId(), "admin", "admin" );
EnterpriseLoadManager elm = session.getEnterpriseLoadManager();
BOIterator<Project> boi = elm.loadProjects( new String[]{ "Name" }, null, "Name asc" );
while ( boi.hasNext() )
{
Project proj = boi.next();
System.out.println( proj.getName() );
}
}
catch ( Exception e )
{
// Best practices would involve catching specific exceptions. To keep this
// sample code short, we catch Exception
e.printStackTrace();
}
finally
{
if ( session != null ) session.logout(); }
}
}
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):
import com.primavera.integration.client.Session;
import com.primavera.integration.client.EnterpriseLoadManager;
import com.primavera.integration.client.RMIURL;
import com.primavera.integration.common.DatabaseInstance;
import com.primavera.integration.client.bo.BOIterator;
import com.primavera.integration.client.bo.object.Project;
public class APITest { public static void main( String[] args )
{
Session session = null;
try
{
DatabaseInstance[] dbInstances = Session.getDatabaseInstances( RMIURL.getRmiUrl( RMIURL.STANDARD_RMI_SERVICE, "localhost", 9099 ) );
// Assume only one database instance for now, and hardcode the username and
// password for this sample code. Assume the server is local for this sample code.
session = Session.login( RMIURL.getRmiUrl( RMIURL.STANDARD_RMI_SERVICE, "localhost", 9099 ), dbInstances[0].getDatabaseId(), "admin", "admin" ); EnterpriseLoadManager elm = session.getEnterpriseLoadManager();
BOIterator<Project> boi = elm.loadProjects( new String[]{ "Name" }, null, "Name asc" );
while ( boi.hasNext() )
{
Project proj = boi.next();
System.out.println( proj.getName() );
}
}
catch ( Exception e )
{
// Best practices would involve catching specific exceptions. To keep this
// sample code short, we catch Exception e.printStackTrace();
}
finally
{
if ( session != null ) session.logout();
}
}
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 Bootstrap\Configurations\BRE 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 Oracle 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 might 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).
getSpreadFields() - Returns an array of spread fields (unit and cost) for business objects that support spreads: EPS, Project, WBS, Activity, Role, Resource, 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.
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.
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 "API-Project," ordering by Id in ascending order:
EnterpriseLoadManager elm = session.getEnterpriseLoadManager();
BOIterator<Project> boi = elm.loadProjects( new String[]{ "Id", "Status", "StartDate", "FinishDate" },
"Id like 'API-Project%'", "Id asc" );
while ( boi.hasNext() )
{
Project proj = boi.next();
// Add code here to process each Project...
}
Example 2: Load activities from a project where the actual start is within a particular date range, ordering by Name in descending order:
SimpleDateFormat formatter = new SimpleDateFormat( "MM/dd/yyyy" );
Date date = formatter.parse( "03/03/2005" );
String dateBegin = WhereClauseHelper.formatDate( session, date );
date = formatter.parse( "03/09/2005" );
String dateEnd = WhereClauseHelper.formatDate( session, date );
String whereClause = "ActualStartDate between " + dateBegin + " and " + dateEnd;
BOIterator<Activity> boi = project.loadAllActivities( new String[]{ "Id", "Name" }, whereClause, "Name desc" );
while ( boi.hasNext() )
{
Activity act = boi.next();
// Add code here to process each Activity...
}
Example 3: Load all active timesheets from a timesheet period:
BOIterator<Timesheet> boi = timesheetPeriod.loadTimesheets( new String[]{ "ResourceName", "ResourceId", "Status" }, "Status='" + com.primavera.integration.client.bo.enm.TimesheetStatus.ACTIVE.getValue() + "'", "" );
while ( boi.hasNext() )
{
Timesheet ts = boi.next();
// Add code here to process each Timesheet...
}
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 removed in the version 8.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, level, summarize, apply actuals, recalculateResourceAssignmentcosts, and store period performance. 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.
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 might 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:
Integer src = (Integer)e.getSource(); int row = src.intValue();
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).
Notes:
BatchException examples
Example 1: Catching BatchExceptions and looping through the exception list
try
{
// call update or create here... ...
}
catch ( BatchException e )
{
// Display stack trace of batch exception
e.printStackTrace();
System.out.println();
// Display index and exception message of all exceptions in the batch exception
List exceptions = e.getExceptionList();
for ( int i = 0; i < exceptions.size(); i++ )
{
ServerException se = (ServerException)exceptions.get(i);
System.out.println( se.getSource() + " - " + se.getMessage() );
}
}
Example 2: Separating business objects that had business rule exceptions during batch update using the getExceptionsByIndex() method
// Load activities
BOIterator<Activity> boi = proj.loadAllActivities( new String[]{"Id" }, null, null ); List<Activity> activities = new ArrayList<Activity>();
while ( boi.hasNext() )
{
Activity act = boi.next();
// Set data here...
...
activities.add( act );
}
try
{
// Update all activities in the list (note that the count must be less than the batch limit)
Activity.update( session, activities.toArray( new Activity[activities.size()] );
}
catch ( BatchException e )
{
// Get exceptions by index
Map exceptions = e.getExceptionsByIndex();
List<Activity> validData = new ArrayList<Activity>();
List<Activity> invalidData = new ArrayList<Activity>();
for ( int i = 0; i < activities.size(); i++ )
{
// Check if business object at row i had any exceptions
if ( exceptions.containsKey( new Integer( i ) ) )
{
// Exceptions occurred; add to invalidData List invalidData.add( activities.get( i ) );
} else
{
// No exceptions occurred; add to validData List
validData.add( activities.get( i ) );
}
}
// Resubmit valid data
Activity.update( session, validData.toArray( new Activity[validData.size()] ) );
// Process invalid data here...
...
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:
java.util.Calendar calendar = new java.util.GregorianCalendar();
// 2005-6-30 06:00AM
calendar.set( 2005, 5, 30, 6, 0, 0);
java.util.Date testDate = new java.util.Date( calendar.getTimeInMillis() );
String wc = WhereClauseHelper.formatDate( session, testDate );
BOIterator<User> boi = elm.loadUsers( User.getAllFields(), "LastUpdateDate > " + wc, "LastUpdateDate asc" );
while ( boi.hasNext() )
{
User user = boi.next();
// Process user here...
}
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
If the User.AllResourceAccessFlag is True, the user has access to all resources and resource security does not apply.
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 reassign 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 P6 Professional Help or P6 Web Services 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: On the P6 Users page, users are filtered based on your resource access settings. As an exception, Admin Super Users will always see all users. 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 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. For the flat exporter, the default fields are the writable fields. You can obtain this list of default fields by calling getWritableFields() on each business object class.
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 p6apibo.xsd schema.
XMLImporter
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: 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 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 XMLExporter and XMLImporter uses the p6apibo.xsd schema. If the API is installed into a web/app server to support Remote Mode, the schema file can be downloaded from the web server with the URL http://<host>:<port>/PrimaveraAPI/schema/p6apibo.xsd.
Performance Tips
Many factors can affect the performance of an application that uses the P6 Integration API. The following tips will help the programmer avoid some of the more common performance problems:
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:
P6 Commercial Notices and Disclosures for Documentation
To view the P6 Commercial Notices and Disclosures for Documentation, go to the \Documentation\<language>\Notices_and_Disclosures folder of the P6 EPPM physical media or download.
Copyright © 2003, 2010, Oracle and/or its affiliates. All rights reserved.