Import-Export
This topic is discussed in the "Grouper API - Part 2" training video.
Grouper includes a GrouperShell (gsh) tool that exports the registry to XML and imports it back into another database, run as gsh -xmlexport and gsh -xmlimport. It is a long-standing core tool, present in all current supported releases (confirmed in v4, v6, and v7).
The Grouper registry can be exported to XML and imported back into another database. There are a few variations, including the child pages below.
This is a server-side administrative operation. It runs from GrouperShell (gsh) on the Grouper server, so it requires filesystem access to the Grouper install. The gsh session runs as GrouperSystem (root), so it can export and import the entire registry.
What the XML tools are for
Exported XML can be used for:
backups — for example, before an upgrade
switching database backends, including to an upgraded schema (required by new Grouper API versions) in the same database
moving or syncing a folder of Grouper to another environment
initializing a new, empty registry to a known state — useful for demos, testing, and system recovery
Imported XML adds to, or updates, existing folders, groups, and group types. A whole or partial registry can be exported and then imported at a specified folder (or the root folder, if none is given) in the target instance. Folders, groups, and group types are created if not already present, or updated if they already exist, depending on the import options. Any tool that can produce XML in the correct format can be used as a loader.
For reporting or for provisioning to other systems, use Grouper web services or SQL rather than the XML export.
Limitations
The XML import/export does not cover the entire data model. It does not include external subjects, entities, point-in-time data, the change log, the grouper_ddl table (which is tied to the schema), or the subject / subjectattribute quickstart tables (which are not part of Grouper itself). Audit entries are exported. Because the coverage is partial, the tool is suited to making a backup within a version and should not be used to migrate from one Grouper version to another during an upgrade. To move or sync data between environments, use the Grouper database migration utility (linked above).
A few behaviors to be aware of:
Object metadata (uuid, created date, and so on) is kept in sync, but if an object already exists in the target it keeps its existing uuid rather than the imported one.
To load subject (membership) data, the target instance must be configured with the same subject sources. The export does not include subject registries, and subjects that cannot be resolved are logged and otherwise ignored.
If you are not using the default privilege interface in
grouper.properties, privileges are not handled automatically — export and import them yourself.
Usage
The tools are run from gsh. The original (legacy) XML format is still available as -xmlexportold and -xmlimportold.
Export
Run gsh -xmlexport with no arguments (or -h) to see the options:
gsh -xmlexport
Usage:
args: -h, Prints this message
args:
[-noprompt] filename
e.g. gsh -xmlexport f:/temp/prod.xml
e.g. gsh -xmlexport -stems a:b:c,d:e:f f:/temp/prod.xml
-includeComments, Put comments about foreign keys in XML
-stems, Only include objects in these comma separated stems or object names
-objectNames, Only include objects in these comma separated object names or stems
-excludeAudits, Put comments about foreign keys in XML
-noprompt, Do not prompt user to confirm the export
filename, The file to importImport
Before importing, turn off include/exclude and require-groups in grouper.properties (these are off by default):
grouperIncludeExclude.use = false
grouperIncludeExclude.requireGroups.use = falseRun gsh -xmlimport with no arguments (or -h) to see the options:
gsh -xmlimport
Usage:
args: -h, Prints this message
args:
[-recordReport]
[-noprompt] filename
e.g. gsh -xmlimport f:/temp/prod.xml
-recordReport, Print a file which lists each insert/update
In addition to import
-noprompt, Do not prompt user to confirm the database that
will be updated
filename, The file to importSee also
The XML import/export above is an admin tool for the whole registry. A group's owner can also import, export, and change the membership of their own group from the Grouper UI; this is covered in the Grouper UI training video (part 2).