Primavera Integration API 7.0

com.primavera.integration.client.xml.xmlimporter
Class XMLImporter

java.lang.Object
  extended by com.primavera.integration.client.xml.xmlimporter.XMLImporter
All Implemented Interfaces:
com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider

public class XMLImporter
extends java.lang.Object
implements com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider

The XMLImporter is used to import data from an XML file into a Project Management database based on a flat xml schema (p6apibo.xsd). The current version of the XMLImporter only supports importing projects and project-related data generated using XMLExporter.exportFullProject(). An example of using the XMLImporter is provided by the importer demo application, ImportDemoApp.

Business objects are classified in two categories: global or project-specific. Any objects that are owned by a Project are project-specific, otherwise they are global. For example, Resource is global and Activity is project-specific. The Project object itself is global. Most kinds of objects are either global or project-specific, but some can be both. For example, Calendars, ActivityCodeTypes, and ActivityCodes can be either global or project-specific.

Each business object in the XML file must contain an ObjectId field, which is a unique identifier for the object corresponding most of the time to the primary key in the database. This ObjectId field will not be imported as it is. Instead, it is replaced by a new value to guarantee that it does not conflict with any existing objects in the database. The ObjectId field in the XML file is needed for when an object is referenced by other business objects in the same file. For example, ResourceAssignment has a field named ResourceObjectId that references an Resource with ObjectId field of the same value. If this foreign reference is not resolved successfully (the Resource with the same ObjectId could not be found in the file), the importer will either skips this field if the field is nullable, or will not import the object at all. It is the responsibility of the user to ensure the referential integrity of the XML file.

The importer will import all global objects before project-specific objects. The importer imports one kind of object at one time according to a predetermined order. For example, Resource will be imported before ResourceAssignment since ResourceAssignment has a reference to Resource.

For each kind of business object, there is a set of fields called "required fields" that you must set when directly creating an object using the Integration API. You can discover this set of fields by calling the static method getRequiredCreateFields() on each business object class. For the same reason, you must provide this set of fields in the XML file for the importer to create all objects successfully.

XMLImporter.createNewProject() and XMLImporter.updateExistingProject() are the methods for initiating the import process. Before calling either method, other methods can be used to specify various settings and customize the import process. The most important setting is ImportOption, as it tells the XMLImporter what to do when a match (or conflict) occurs.

You can call the setDefaultGlobalImportOption() and the setDefaultProjectImportOption() method to set the default ImportOption for all global objects or all project objects, respectively. You can also call setImportOption() to set the ImportOption for a particular type of object.

You can use the importer to not only create new objects, but also to update existing objects in the database. When updating, an object must be MATCHED to an existing object in database. You should specify the appropriate ImportOption to express your intention when a match is found. You can keep the existing object in database untouched by using ImportOption.KEEP_EXISTING, or you can update the object in database with data from the file by using ImportOption.UPDATE_EXISTING. If you want to ensure that all objects in the file are new and no match will be found, you can use ImportOption.CREATE_NEW which will create a new object, even when a match is found. You can use ImportOption.DO_NOT_IMPORT if you want to skip this kind of object altogether.

The rules for matching an object in the file to an object in the database are related mainly to unique constraint fields. Most business objects have one or more fields that are protected by unique constraints that exist in database, business logic layer, and/or both. For example, the Id field in Activity must be unique within the project. If you create an Activity with an Id that conflicts with an existing Activity in the same project in that database using the API, an exception will be thrown. Most of the time a unique constraint contains a name field (such as Id, Name) and other foreign key fields (such as ProjectObjectId in Activity). This set of matching rules is described in detail in the following table. The first column is the name of the object. The second column describes whether the object is global (G), project-specific (P) or both (GP). The third column lists the fields that are used to match.

Object NameG/P/GPFields Used to Match
ActivityPProjectObjectId, Id
ActivityCodeGPCodeTypeObjectId, ParentObjectId, CodeValue
ActivityCodeTypeGPProjectObjectId or EPSObjectId, Name
ActivityExpensePActivityObjectId, ExpenseItem
ActivityNotePActivityObjectId, NotebookTopicObjectId
ActivityPeriodActualPFinancialPeriodObjectId, ActivityObjectId
ActivityStepPActivityObjectId, Name
CalendarGPProjectObjectId, Type, Name
CostAccountGParentObjectId, Id or Name
CurrencyGId or Name
ExpenseCategoryGName
FinancialPeriodGStartDate, EndDate
FundingSourceGName
NotebookTopicGName
OBSGName
ProjectBudgetChangeLogPProjectObjectId, WBSObjectId, ChangeNumber
ProjectCodeGCodeTypeObjectId, ParentObjectId, CodeValue
ProjectCodeTypeGName
ProjectEstimatePProjectObjectId, Name
ProjectFundingGFundingSourceObjectId, ProjectObjectId
ProjectIssuePActivityObjectId, ProjectObjectId, WBSObjectId, Name
ProjectNotePProjectObjectId, WBSObjectId, NotebookTopicObjectId
ProjectResourcePProjectObjectId, WBSOBjectId, ResourceObjectId, RoleObjectId
ProjectResourceQuantityPProjectResourceObjectId, MonthStartDate, WeekStartDate
ProjectResourceCategoryPName
ProjectRiskPProjectObjectId, WBSObjectId, Name
ProjectSpendingPlanPProjectObjectId, WBSObjectId, Date
ProjectThresholdPProjectObjectId, WBSObjectId, ThresholdParameterObjectId, DetailToMonitor, LowerThreshold, UpperThreshold
RelationshipPSuccessorActivityObjectId, PredecessorActivityObjectId, RelationshipType
ResourceGId
ResourceAssignmentPActivityObjectId, ResourceObjectId, RoleObjectId, CostAccountObjectId, StartDate, RateType
ResourceAssignmentPeriodActualPFinancialPeriodObjectId, ResourceAssignmentObjectId
ResourceCodeGCodeTypeObjectId, ParentObjectId, CodeValue
ResourceCodeTypeGName
ResourceCurveGName
ResourceRateGResourceObjectId, ShiftPeriodObjectId, EffectiveDate
ResourceRoleGResourceObjectId, RoleObjectId
RiskTypeGName
RoleGParentObjectId, Id or Name
RoleLimitGRoleObjectId, EffectiveDate
RoleRateGRoleObjectId
ShiftGName
ThresholdParameterGType
UDFCodeGUDFTypeObjectId, CodeValue
UDFTypeGSubjectArea, Title
UnitOfMeasureGAbbreviation
WBSPProjectObjectId, ParentObjectId, Code or Name
WBSCategoryPName
WBSMilestonePProjectObjectId, WBSObjectId, Name

ResourceAssignment objects will match based on ActivityObjectId, ResourceObjectId, RoleObjectId , and CostAccountObjectId. Multiple resource assignments can exist with the same values for these fields, however. If duplicate resource assignments for an activity exist in the database and/or the XML file, StartDate and RateType are also used to differentiate between the duplicate records.

ShiftPeriod objects are processed as the content of their parent Shift object. When a Shift is updated (or created), all of its ShiftPeriod are updated (or created). When a Shift is not updated (ImportOption.KEEP_EXISTING), none of its ShiftPeriod will be updated. Therefore, there is no need to set ImportOption for ShiftPeriod object.

Code assignment objects, including ActivityCodeAssignment, ProjectCodeAssignment and ResourceCodeAssignment, showing up in XML file under a Code tag within their parent object, are processed as the content of their parent object, similar to how ShiftPeriod is processed relating to Shift. UDF assignments (UDFValue), including UDF code assignments and normal UDF assignments (such as UDF types of Cost, double etc.), showing up in the XML file as under a UDF tag within their parent object, are also processed as the content of their parent object. Therefore, you don't need to set the ImportOption for code assignment objects or UDFValue objects.

If a problem occurs while importing FinancialPeriods, no Past Period Actuals business objects (FinancialPeriod, ActivityPeriodActual, ResourceAssignmentPeriodActual) will be imported. Note that the import process will continue even if a problem is encountered in Past Period Actuals data.

As of release 6.0, the importer uses the Java logging API. Information on how to configure the logger can be found in the logging overview page: http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html.

As of release 6.0, the importer uses more coarse-grained transactions during the import process. Each global object is processed using a separate, single transaction. All project data is also processed in a separate, single transaction. If a problem occurs within the context of a transaction, that transaction gets rolled back. Note that any transactions committed up until that point do not get rolled back, however. For example, if a problem occurs during the processing of activity data, the project transaction gets rolled back, but the global changes remain committed.

The importer is a powerful tool if used correctly and carefully. First, you should take time to understand the meaning of ImportOptions and choose the right one for yourself. For example, you might want to use ImportOption.KEEP_EXISTING for the default global import option so that existing global objects will not be modified and new global objects can be brought in, as they may be referenced by project-specific objects.

Second, you should take time to control the field set in the XML file, especially with Activity and ResourceAssignment objects. Some fields are absolutely necessary, some are not, and some can be calculated from other fields. Activity and ResourceAssignment objects have many associated business rules, and errors can be generated in numerous ways. Some can come from your own processing errors and some can come from an unclean data source. Limiting the dataset can help with these issues.

Third, you might want to validate your XML file with the schema provided p6apibo.xsd to catch errors in the data before the importing starts. The schema may help detect errors quickly, whereas the import process could take a long time. The schema may also provide a clearer error message than the importer. The schema can be very helpful, especially when you are just starting to use the importer and are not yet familiar with it.

The XMLImporter can 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.

If the XML you want to import does not meet the above criteria, the XMLImporter may not be used. Alternatives are available, but the matching and data cleaning logic in the XMLImporter will be bypassed, and these tasks will have to be performed manually. These alternatives include using DOM, SAX, or StAX to parse the XML yourself, then calling the appropriate API methods directly. For XML files for which you have the XML Schema (XSD) available, an even better alternative might be to use the Java Architecture for XML Binding (JAXB). It is highly recommended, however, that you use the XMLImporter whenever possible.


Constructor Summary
XMLImporter(Session session)
          Construct an XMLImporter.
 
Method Summary
 void addLogHandler(java.util.logging.Handler handler)
          Add a log handler
 ObjectId createNewProject(ObjectId epsId, java.lang.String sFilePath)
          Creates a new project from an XML file.
 ImportOption getDefaultGlobalImportOption()
          Gets the default ImportOption for global objects.
 ImportOption getDefaultProjectImportOption()
          Gets the default ImportOption for project-specific objects.
 boolean getDeleteUnreferenced(java.lang.String sObjectName)
          Gets the DeleteUnreferenced option that was set for a particular type of business object.
 ImportOption getImportOption(java.lang.String sObjectName, boolean bProjectSpecific)
          Gets the ImportOption that was set for a particular type of business object.
 java.lang.String getLogFile()
          Gets the output file path for import log
 java.util.logging.Level getLogLevel()
          Gets the level for import log
 com.primavera.integration.client.xml.xmlimporter.matchrule.MatchRule getMatchRule(java.lang.String sObjectName, boolean bProjectSpecific)
          Gets the matching rule that was set for a particular type of business object.
 boolean getShouldIgnoreGUID()
          Gets the ShouldIgnoreGUID flag.
 boolean getShouldIgnoreSequenceNumber()
          Gets the ShouldIgnoreSequenceNumber flag.
 void notifyListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEvent event, java.lang.String objectName, boolean isProjectSpecific)
           
 void registerListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEventsListener listener)
           
 void removeLogHandler(java.util.logging.Handler handler)
           
 void setDefaultGlobalImportOption(ImportOption defaultGlobalImportOption)
          Sets the default ImportOption for global objects.
 void setDefaultProjectImportOption(ImportOption defaultProjectImportOption)
          Sets the default ImportOption for project specific objects.
 void setDeleteUnreferenced(java.lang.String sObjectName, boolean bDeleteUnreferenced)
          Sets the DeleteUnreferenced option for a particular type of business object.
 void setImportOption(java.lang.String sObjectName, boolean bProjectSpecific, ImportOption opt)
          Sets the ImportOption for a particular type of business object.
 void setLogFile(java.lang.String sLogFilePath)
          Sets the output file path for import log
 void setLogLevel(java.util.logging.Level level)
          Sets the level for import log
 void setMatchRule(java.lang.String sObjectName, boolean bProjectSpecific, com.primavera.integration.client.xml.xmlimporter.matchrule.MatchRule matchRule)
          Sets the matching rule for a particular type of business object.
 void setShouldIgnoreGUID(boolean bIgnoreGUID)
          Sets the ShouldIgnoreGUID flag.
 void setShouldIgnoreSequenceNumber(boolean bIgnoreSeqNo)
          Sets the ShouldIgnoreSequenceNumber flag.
 void unregisterListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEventsListener listener)
           
 void updateExistingProject(ObjectId projectId, java.lang.String sFilePath)
          Update an existing project from an XML file.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLImporter

public XMLImporter(Session session)
Construct an XMLImporter.

Parameters:
session - the session object
Throws:
java.lang.IllegalArgumentException - if the input parameter is null or invalid
Method Detail

createNewProject

public ObjectId createNewProject(ObjectId epsId,
                                 java.lang.String sFilePath)
                          throws XMLImporterException,
                                 XMLProcessingException
Creates a new project from an XML file.

Parameters:
epsId - id of an EPS where a new project will be created
sFilePath - identifies the XML file
Returns:
ObjectId the ObjectId of the newly created Project
Throws:
XMLImporterException - if error happens at importer layer
XMLProcessingException - if error happens processing the XML content
java.lang.IllegalArgumentException - if the input parameter is null or invalid

updateExistingProject

public void updateExistingProject(ObjectId projectId,
                                  java.lang.String sFilePath)
                           throws XMLImporterException,
                                  XMLProcessingException
Update an existing project from an XML file.

Parameters:
projectId - id of the project to update
sFilePath - identifies the XML file
Throws:
XMLImporterException - if error happens at importer layer
XMLProcessingException - if error happens processing the XML content
java.lang.IllegalArgumentException - if the input parameter is null or invalid

getImportOption

public ImportOption getImportOption(java.lang.String sObjectName,
                                    boolean bProjectSpecific)
                             throws XMLImporterException
Gets the ImportOption that was set for a particular type of business object.

Parameters:
sObjectName - the type of business object, such as Activity
bProjectSpecific - indicates whether it is project-specific
Returns:
ImportOption the ImportOption for the business object type
Throws:
XMLImporterException - when appropriate import option is not defined for this object
java.lang.IllegalArgumentException - if the input parameter is null or invalid

setImportOption

public void setImportOption(java.lang.String sObjectName,
                            boolean bProjectSpecific,
                            ImportOption opt)
                     throws XMLImporterException
Sets the ImportOption for a particular type of business object.

Parameters:
sObjectName - the type of business object, such as Activity
bProjectSpecific - indicates whether it is project-specific
opt - the ImportOption for the business object type
Throws:
XMLImporterException - if Create New import option is specified for the objects that are not allowed to have Create New import option
java.lang.IllegalArgumentException - if the input parameter is null or invalid

getDefaultGlobalImportOption

public ImportOption getDefaultGlobalImportOption()
Gets the default ImportOption for global objects.

Returns:
ImportOption the default ImportOption for global objects

setDefaultGlobalImportOption

public void setDefaultGlobalImportOption(ImportOption defaultGlobalImportOption)
Sets the default ImportOption for global objects.

Parameters:
defaultGlobalImportOption - the default ImportOption for global objects

getDefaultProjectImportOption

public ImportOption getDefaultProjectImportOption()
Gets the default ImportOption for project-specific objects.

Returns:
ImportOption the default ImportOption for project specific objects

setDefaultProjectImportOption

public void setDefaultProjectImportOption(ImportOption defaultProjectImportOption)
Sets the default ImportOption for project specific objects.

Parameters:
defaultProjectImportOption - the default ImportOption for project specific objects

getMatchRule

public com.primavera.integration.client.xml.xmlimporter.matchrule.MatchRule getMatchRule(java.lang.String sObjectName,
                                                                                         boolean bProjectSpecific)
Gets the matching rule that was set for a particular type of business object.

Parameters:
sObjectName - the type of business object, such as Activity
bProjectSpecific - indicates whether it is project-specific
Returns:
MatchRule the matching rule for the business object type
Throws:
java.lang.IllegalArgumentException - if the object name is null or invalid

setMatchRule

public void setMatchRule(java.lang.String sObjectName,
                         boolean bProjectSpecific,
                         com.primavera.integration.client.xml.xmlimporter.matchrule.MatchRule matchRule)
Sets the matching rule for a particular type of business object.

Parameters:
sObjectName - the type of business object, such as Activity
bProjectSpecific - indicates whether it is project-specific
matchRule - the matching rule for the business object type
Throws:
java.lang.IllegalArgumentException - if the object name is null or invalid

getShouldIgnoreGUID

public boolean getShouldIgnoreGUID()
Gets the ShouldIgnoreGUID flag. When this flag is set to true, the XMLImporter ignores all GUID fields in the XML file, and allows new GUID values to be generated.

Returns:
boolean the ShouldIgnoreGUID flag

setShouldIgnoreGUID

public void setShouldIgnoreGUID(boolean bIgnoreGUID)
Sets the ShouldIgnoreGUID flag. When this flag is set to true, the XMLImporter ignores all GUID fields in the XML file, and allows new GUID values to be generated.

Parameters:
bIgnoreGUID - the ShouldIgnoreGUID flag

getShouldIgnoreSequenceNumber

public boolean getShouldIgnoreSequenceNumber()
Gets the ShouldIgnoreSequenceNumber flag. When this flag is set to true, the XMLImporter ignores all SequenceNumber fields in the XML file, and allows new SequenceNumber values to be generated.

Returns:
boolean the ShouldIgnoreSequenceNumber flag

setShouldIgnoreSequenceNumber

public void setShouldIgnoreSequenceNumber(boolean bIgnoreSeqNo)
Sets the ShouldIgnoreSequenceNumber flag. When this flag is set to true, the XMLImporter ignores all SequenceNumber fields in the XML file, and allows new SequenceNumber values to be generated.

Parameters:
bIgnoreSeqNo - the ShouldIgnoreSequenceNumber flag

getDeleteUnreferenced

public boolean getDeleteUnreferenced(java.lang.String sObjectName)
Gets the DeleteUnreferenced option that was set for a particular type of business object.

Parameters:
sObjectName - the type of business object, such as Activity
Returns:
boolean the DeleteUnreferenced option for the business object type
Throws:
java.lang.IllegalArgumentException - if the input parameter is null or invalid

setDeleteUnreferenced

public void setDeleteUnreferenced(java.lang.String sObjectName,
                                  boolean bDeleteUnreferenced)
Sets the DeleteUnreferenced option for a particular type of business object. You can only turn on this option for the following object types: Activity, ProjectThreshold, ProjectRisk, Relationship, ResourceAssignment

Parameters:
sObjectName - the type of business object, such as Activity
bDeleteUnreferenced - the DeleteUnreferenced option for the business object type
Throws:
java.lang.IllegalArgumentException - if the input parameter is null or invalid, or when object type is not allowed

setLogFile

public void setLogFile(java.lang.String sLogFilePath)
Sets the output file path for import log

Parameters:
sLogFilePath - the log file path, if not set, or set to null or empty, then use import file name appended with ".log" as log file name

getLogFile

public java.lang.String getLogFile()
Gets the output file path for import log

Returns:
the current import log file path

addLogHandler

public void addLogHandler(java.util.logging.Handler handler)
Add a log handler

Parameters:
handler -

removeLogHandler

public void removeLogHandler(java.util.logging.Handler handler)

setLogLevel

public void setLogLevel(java.util.logging.Level level)
Sets the level for import log

Parameters:
level - logging level, which is standard java logging level, default is Level.INFO. If the parameter is null, then do nothing.

getLogLevel

public java.util.logging.Level getLogLevel()
Gets the level for import log

Returns:
the current logging level

notifyListener

public void notifyListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEvent event,
                           java.lang.String objectName,
                           boolean isProjectSpecific)
                    throws XMLImporterException,
                           XMLProcessingException
Specified by:
notifyListener in interface com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider
Throws:
XMLImporterException
XMLProcessingException

registerListener

public void registerListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEventsListener listener)
Specified by:
registerListener in interface com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider

unregisterListener

public void unregisterListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEventsListener listener)
Specified by:
unregisterListener in interface com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider

Primavera Integration API 7.0

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