1.11. Metadata import

This section explains the metatada API which is available at /api/23/metadata and /api/26/metadataendpoints. XML and JSON resource representations are supported.

The importer allows you to import metadata exported with the new exporter. The various parameters are listed below.

Table 1.12. Import Parameter

NameOptions (first is default)Description
importModeCOMMIT, VALIDATESets overall import mode, decides whether or not to only VALIDATE or also COMMIT the metadata, this have similar functionality as our old dryRun flag.
identifierUID, CODE, AUTOSets the identifier scheme to use for reference matching. AUTO means try UID first, then CODE.
importReportModeERRORS, FULL, DEBUGSets the ImportReport mode, controls how much is reported back after the import is done. ERRORS only includes ObjectReports for object which has errors. FULL returns an ObjectReport for all objects imported, and DEBUG returns the same plus a name for the object (if available).
preheatModeREFERENCE, ALL, NONESets the preheater mode, used to signal if preheating should be done for ALL (as it was before with preheatCache=true) or do a more intelligent scan of the objects to see what to preheat (now the default), setting this to NONE is not recommended.
importStrategyCREATE_AND_UPDATE, CREATE, UPDATE, DELETESets import strategy, CREATE_AND_UPDATE will try and match on identifier, if it doesn't exist, it will create the object.
atomicModeALL, NONESets atomic mode, in the old importer we always did a best effort import, which means that even if some references did not exist, we would still import (i.e. missing data elements on a data element group import). Default for new importer is to not allow this, and similar reject any validation errors. Setting the NONE mode emulated the old behavior.
mergeModeMERGE, REPLACESets the merge mode, when doing updates we have two ways of merging the old object with the new one, MERGE mode will only overwrite the old property if the new one is not-null, for REPLACE mode all properties are overwritten regardsless of null or not.
flushModeAUTO, OBJECTSets the flush mode, decides when to flush the internal cache, strongly reommended to keep this to AUTO (which is the default). Only use OBJECT for debugging purposes, where you are seeing hibernate exceptions and want to pinpoint the exact place where the stack happens (hibernate will only throw when flushing, so it can be hard to know which object had issues).
skipSharingfalse, trueSkip sharing properties, does not merge sharing when doing updates, and does not add user group accessses when creating new objects.
skipValidationfalse, trueSkip validation for import. NOT RECOMMENDED.
asyncfalse, trueAsynchronous import, returns immediately with a Location header pointing to the location of the importReport.
inclusionStrategyNON_NULL, ALWAYS, NON_EMPTYNON_NULL includes properties which are not null, ALWAYS include all properties, NON_EMPTY includes non empty properties (will not include strings of 0 length, collections of size 0 etc)
userOverrideModeNONE, CURRENT, SELECTEDAllows you to override the user property of every object you are importing, the options are NONE (do nothing), CURRENT (use import user), SELECTED (select a specific user using overrideUser=X)
overrideUserUser IDIf userOverrideMode is SELECTED, use this parameter to select the user you want override with.