|
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.importer.XMLImporter
public class XMLImporter
The hierarchical XMLImporter
is used to import data from an XML file into a Project Management database
based on a hierarchical schema (prmbo.xsd). The current version of the XMLImporter
only supports importing
projects and project-related data generated using the hierarchical XMLExporter.exportFullProject()
.
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 prmbo.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 | |
---|---|
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. |
boolean |
getShouldIgnoreGUID()
Gets the ShouldIgnoreGUID flag. |
boolean |
getShouldIgnoreSequenceNumber()
Gets the ShouldIgnoreSequenceNumber flag. |
void |
importFullProject(java.lang.String sFilePath,
java.io.PrintStream stream)
Deprecated. As of release 6.0, replaced by createNewProject(ObjectId, String) and updateExistingProject(ObjectId, String) |
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 |
setShouldIgnoreGUID(boolean bIgnoreGUID)
Sets the ShouldIgnoreGUID flag. |
void |
setShouldIgnoreSequenceNumber(boolean bIgnoreSeqNo)
Sets the ShouldIgnoreSequenceNumber flag. |
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 |
---|
@Deprecated public void importFullProject(java.lang.String sFilePath, java.io.PrintStream stream) throws ServerException, NetworkException, BusinessObjectException, XMLImporterException
createNewProject(ObjectId, String)
and updateExistingProject(ObjectId, String)
sFilePath
- identifies the XML filestream
- a PrintStream to receive status and warning messages
ServerException
- if a problem occurred on the server-side
BusinessObjectException
- if a problem occurred in the client-side business objects
NetworkException
- if a problem occurred in the network layer
XMLImporterException
- if error happens at importer layer
java.lang.IllegalArgumentException
- if the input parameter is null or invalidpublic ObjectId createNewProject(ObjectId epsId, java.lang.String sFilePath) throws ServerException, NetworkException, BusinessObjectException, XMLImporterException
epsId
- id of an EPS where a new project will be createdsFilePath
- identifies the XML file
ServerException
- if a problem occurred on the server-side
BusinessObjectException
- if a problem occurred in the client-side business objects
NetworkException
- if a problem occurred in the network layer
XMLImporterException
- if error happens at importer layer
java.lang.IllegalArgumentException
- if the input parameter is null or invalidpublic void updateExistingProject(ObjectId projectId, java.lang.String sFilePath) throws ServerException, NetworkException, BusinessObjectException, XMLImporterException
projectId
- id of the project to updatesFilePath
- identifies the XML file
ServerException
- if a problem occurred on the server-side
BusinessObjectException
- if a problem occurred in the client-side business objects
NetworkException
- if a problem occurred in the network layer
XMLImporterException
- if error happens at importer layer
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
java.lang.IllegalArgumentException
- if the input parameter is null or invalid
XMLImporterException
- when appropriate import option is not defined for this objectpublic 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
java.lang.IllegalArgumentException
- if the input parameter is null or invalid
XMLImporterException
- if Create New import option is specified for the objects that are not allowed to have Create New import optionpublic 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 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 allowed
|
Primavera Integration API 7.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |