|
Primavera Integration API 7.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.primavera.integration.client.xml.xmlimporter.XMLImporter
public class XMLImporter
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 Name | G/P/GP | Fields Used to Match |
---|---|---|
Activity | P | ProjectObjectId, Id |
ActivityCode | GP | CodeTypeObjectId, ParentObjectId, CodeValue |
ActivityCodeType | GP | ProjectObjectId or EPSObjectId, Name |
ActivityExpense | P | ActivityObjectId, ExpenseItem |
ActivityNote | P | ActivityObjectId, NotebookTopicObjectId |
ActivityPeriodActual | P | FinancialPeriodObjectId, ActivityObjectId |
ActivityStep | P | ActivityObjectId, Name |
Calendar | GP | ProjectObjectId, Type, Name |
CostAccount | G | ParentObjectId, Id or Name |
Currency | G | Id or Name |
ExpenseCategory | G | Name |
FinancialPeriod | G | StartDate, EndDate |
FundingSource | G | Name |
NotebookTopic | G | Name |
OBS | G | Name |
ProjectBudgetChangeLog | P | ProjectObjectId, WBSObjectId, ChangeNumber |
ProjectCode | G | CodeTypeObjectId, ParentObjectId, CodeValue |
ProjectCodeType | G | Name |
ProjectEstimate | P | ProjectObjectId, Name |
ProjectFunding | G | FundingSourceObjectId, ProjectObjectId |
ProjectIssue | P | ActivityObjectId, ProjectObjectId, WBSObjectId, Name |
ProjectNote | P | ProjectObjectId, WBSObjectId, NotebookTopicObjectId |
ProjectResource | P | ProjectObjectId, WBSOBjectId, ResourceObjectId, RoleObjectId |
ProjectResourceQuantity | P | ProjectResourceObjectId, MonthStartDate, WeekStartDate |
ProjectResourceCategory | P | Name |
ProjectRisk | P | ProjectObjectId, WBSObjectId, Name |
ProjectSpendingPlan | P | ProjectObjectId, WBSObjectId, Date |
ProjectThreshold | P | ProjectObjectId, WBSObjectId, ThresholdParameterObjectId, DetailToMonitor, LowerThreshold, UpperThreshold |
Relationship | P | SuccessorActivityObjectId, PredecessorActivityObjectId, RelationshipType |
Resource | G | Id |
ResourceAssignment | P | ActivityObjectId, ResourceObjectId, RoleObjectId, CostAccountObjectId, StartDate, RateType |
ResourceAssignmentPeriodActual | P | FinancialPeriodObjectId, ResourceAssignmentObjectId |
ResourceCode | G | CodeTypeObjectId, ParentObjectId, CodeValue |
ResourceCodeType | G | Name |
ResourceCurve | G | Name |
ResourceRate | G | ResourceObjectId, ShiftPeriodObjectId, EffectiveDate |
ResourceRole | G | ResourceObjectId, RoleObjectId |
RiskType | G | Name |
Role | G | ParentObjectId, Id or Name |
RoleLimit | G | RoleObjectId, EffectiveDate |
RoleRate | G | RoleObjectId |
Shift | G | Name |
ThresholdParameter | G | Type |
UDFCode | G | UDFTypeObjectId, CodeValue |
UDFType | G | SubjectArea, Title |
UnitOfMeasure | G | Abbreviation |
WBS | P | ProjectObjectId, ParentObjectId, Code or Name |
WBSCategory | P | Name |
WBSMilestone | P | ProjectObjectId, 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 ImportOption
s 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 |
---|
public XMLImporter(Session session)
session
- the session object
java.lang.IllegalArgumentException
- if the input parameter is null or invalidMethod Detail |
---|
public ObjectId createNewProject(ObjectId epsId, java.lang.String sFilePath) throws XMLImporterException, XMLProcessingException
epsId
- id of an EPS where a new project will be createdsFilePath
- identifies the XML file
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 invalidpublic void updateExistingProject(ObjectId projectId, java.lang.String sFilePath) throws XMLImporterException, XMLProcessingException
projectId
- id of the project to updatesFilePath
- identifies the XML file
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 invalidpublic ImportOption getImportOption(java.lang.String sObjectName, boolean bProjectSpecific) throws XMLImporterException
sObjectName
- the type of business object, such as ActivitybProjectSpecific
- indicates whether it is project-specific
XMLImporterException
- when appropriate import option is not defined for this object
java.lang.IllegalArgumentException
- if the input parameter is null or invalidpublic void setImportOption(java.lang.String sObjectName, boolean bProjectSpecific, ImportOption opt) throws XMLImporterException
sObjectName
- the type of business object, such as ActivitybProjectSpecific
- indicates whether it is project-specificopt
- the ImportOption for the business object type
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 invalidpublic ImportOption getDefaultGlobalImportOption()
public void setDefaultGlobalImportOption(ImportOption defaultGlobalImportOption)
defaultGlobalImportOption
- the default ImportOption for global objectspublic ImportOption getDefaultProjectImportOption()
public void setDefaultProjectImportOption(ImportOption defaultProjectImportOption)
defaultProjectImportOption
- the default ImportOption for project specific objectspublic com.primavera.integration.client.xml.xmlimporter.matchrule.MatchRule getMatchRule(java.lang.String sObjectName, boolean bProjectSpecific)
sObjectName
- the type of business object, such as ActivitybProjectSpecific
- indicates whether it is project-specific
java.lang.IllegalArgumentException
- if the object name is null or invalidpublic void setMatchRule(java.lang.String sObjectName, boolean bProjectSpecific, com.primavera.integration.client.xml.xmlimporter.matchrule.MatchRule matchRule)
sObjectName
- the type of business object, such as ActivitybProjectSpecific
- indicates whether it is project-specificmatchRule
- the matching rule for the business object type
java.lang.IllegalArgumentException
- if the object name is null or invalidpublic boolean getShouldIgnoreGUID()
public void setShouldIgnoreGUID(boolean bIgnoreGUID)
bIgnoreGUID
- the ShouldIgnoreGUID flagpublic boolean getShouldIgnoreSequenceNumber()
public void setShouldIgnoreSequenceNumber(boolean bIgnoreSeqNo)
bIgnoreSeqNo
- the ShouldIgnoreSequenceNumber flagpublic boolean getDeleteUnreferenced(java.lang.String sObjectName)
sObjectName
- the type of business object, such as Activity
java.lang.IllegalArgumentException
- if the input parameter is null or invalidpublic void setDeleteUnreferenced(java.lang.String sObjectName, boolean bDeleteUnreferenced)
sObjectName
- the type of business object, such as ActivitybDeleteUnreferenced
- the DeleteUnreferenced option for the business object type
java.lang.IllegalArgumentException
- if the input parameter is null or invalid, or when object
type is not allowedpublic void setLogFile(java.lang.String sLogFilePath)
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 namepublic java.lang.String getLogFile()
public void addLogHandler(java.util.logging.Handler handler)
handler
- public void removeLogHandler(java.util.logging.Handler handler)
public void setLogLevel(java.util.logging.Level level)
level
- logging level, which is standard java logging level, default is Level.INFO. If
the parameter is null, then do nothing.public java.util.logging.Level getLogLevel()
public void notifyListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEvent event, java.lang.String objectName, boolean isProjectSpecific) throws XMLImporterException, XMLProcessingException
notifyListener
in interface com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider
XMLImporterException
XMLProcessingException
public void registerListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEventsListener listener)
registerListener
in interface com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider
public void unregisterListener(com.primavera.integration.client.xml.xmlimporter.event.ImportEventsListener listener)
unregisterListener
in interface com.primavera.integration.client.xml.xmlimporter.event.ImportEventsProvider
|
Primavera Integration API 7.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |