1.11 Metadata import

This section explains the metadata API which is available at /api/23/metadata and /api/26/metadata endpoints. 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.

Import Parameter
Name Options (first is default) Description
importMode COMMIT, VALIDATE Sets overall import mode, decides whether or not to only VALIDATE or also COMMIT the metadata, this has similar functionality as our old dryRun flag.
identifier UID, CODE, AUTO Sets the identifier scheme to use for reference matching. AUTO means try UID first, then CODE .
importReportMode ERRORS, FULL, DEBUG Sets 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).
preheatMode REFERENCE, ALL, NONE Sets 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.
importStrategy CREATE_AND_UPDATE, CREATE, UPDATE, DELETE Sets import strategy, CREATE_AND_UPDATE will try and match on identifier, if it doesn’t exist, it will create the object.
atomicMode ALL, NONE Sets 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.
mergeMode MERGE, REPLACE Sets 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 regardless of null or not.
flushMode AUTO, OBJECT Sets the flush mode, which controls when to flush the internal cache. It is strongly recommended 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).
skipSharing false, true Skip sharing properties, does not merge sharing when doing updates, and does not add user group access when creating new objects.
skipValidation false, true Skip validation for import. NOT RECOMMENDED .
async false, true Asynchronous import, returns immediately with a Location header pointing to the location of the importReport . The payload also contains a json object of the job created.
inclusionStrategy NON_NULL, ALWAYS, NON_EMPTY NON_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.)
userOverrideMode NONE, CURRENT, SELECTED Allows 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)
overrideUser User ID If userOverrideMode is SELECTED, use this parameter to select the user you want override with.