createExportArchive
Create and prepare an archive for export. The archive is defined by its settings. The settings define exactly what is exported.
This operation must be called within an explicit transaction context wrapping its usage and that of other archive operations between
beginTransaction and
closeTransaction calls. An export archive is created on the server using this operation. After it is created, the export archive can be further manipulated using
getArchiveContents,
getArchiveExportSettings, and
updateArchiveExportSettings. Multiple calls to these three operations can be made in any order to analyze and redefine what is to be exported. When satisfied, the client then calls
getArchiveExportData one or more times.
After getArchiveExportData is called, updateArchiveExportSettings can no longer be called.
When the last of the export data is returned by getArchiveExportData, or when
cancelArchive is called, the server’s concept of the archive no longer exists, and further calls to any of these operations results in a NotFound faults because the archiveId is invalid.
The archive contains all resources listed in the resources elements. Each resource has an optional includeChildren element, which defaults to TRUE if unset. If a user exports a resource that contains a child resource that the user does not have READ permission for, the child resource is omitted. (The export succeeds without generating a security fault, but the resource is not exported.) If this element is unset, no resources are exported. The “all” subelement can be used to include all resources on the server.
The archive contains definitions of all the domains, users, and groups identified in the users element. If this element is unset, no domains, users, or groups are exported. The “all” subelement can be used to includes all domains, users, and groups defined by the server. The archive contains all of the server attributes identified in the serverAttributes element. If this element is unset, no server attributes are exported.
The “all” subelement can be used to export all server attributes. See
getServerAttributeDefs for server attribute definitions and
getServerAttributes for server attribute values.
A number of additional options can be specified in the exportOptions element. If an option is specified, the associated information is exported. Otherwise it is not. By default none of these options are exported. The valid options are:
• INCLUDE_CACHING: Include caching configurations for resources.
• INCLUDE_CUSTOM_JAVA_JARS: Include custom Java JARs in the export. (ADMIN ONLY)
• INCLUDE_STATISTICS: Include any resources stats known about objects including the table boundaries, and column boundaries.
• INCLUDE_DEPENDENCY: Gather and include all dependent resources for the resources you choose to export.
• INCLUDE_PHYSICAL_SOURCE_INFO: Include sensitive connection information for included physical sources. (OWNER ONLY)
• INCLUDE_REQUIRED_USERS: Include the information about the required users in the export file.
• INCLUDE_SECURITY: Include resource privilege settings. (OWNER ONLY)
If the caller requests an option marked ADMIN ONLY and does not have admin privileges, a Security fault is generated.
If the caller requests an option marked OWNER ONLY, that option is applied only to resources where the caller is the owner. If the caller has admin privileges, the option is applied to all resources regardless of ownership. Messages are generated, but no fault occurs during export.
The importHints element contains information that can be used by the client performing an import of this exported data at a later time. This allows creation of an export archive that has built-in preconceptions of what resources and users should be rebound on import, as well as what resource attributes should be remapped (such as database connection information).
Location
/services/webservices/system/admin/archive/operations/
Request Elements
settings: Description of how much information to export. The settings have the following structure:
• name: The name of the export archive.
• description: A verbose description of the archive.
• type:
— BACKUP: All information in this archive replaces the server information when imported.
— ROOT: Resources within the archive cannot be relocated when reimported.
— PACKAGE: Resources within the archive can be relocated when reimported.
• resources (optional): List of resources to export.
— all (optional): If set, all resources on the server are exported.
— resource (0 or more): List of path-type pairs for the individual resources to export:
includeChildren (optional): If TRUE or unset, recursively include all children of this resource in the export. If FALSE, do not include any children.
• serverAttributes (optional): List of server attributes to be exported.
— all (optional): If set, all server attributes are exported.
— attributes (optional): A space-delimited list of names of the server attributes to be exported.
• exportOptions (optional): A space-delimited list of archive options.
• importHints (optional): Hints that can be used during import.
— rebindResources: List of resources that should be rebound on import.
— rebindUsers: List of users that should be mapped to other users on import.
— remapAttributes: List resource attributes that should be mapped during import.
• createInfo (optional): Any setting of this element is ignored.
Response Elements
archiveId: The archive ID. This is used by other archive operations to manipulate this archive.
Faults
IllegalArgument: If the type is malformed.
IllegalArgument: If any of the resource paths or types are malformed.
IllegalArgument: If any of the settings are malformed or contain illegal values.
IllegalArgument: If any of the server attributes are malformed.
IllegalArgument: If any of the export options are malformed.
IllegalArgument: If any of the import hints are malformed.
IllegalState: This operations can only be called within an explicit transaction context. Use beginTransaction and closeTransaction.
NotAllowed: If an explicitly named resource cannot be exported. The inclusion of implicitly identified resources, using includeChildren, that are not allowed to be exported, does not cause this fault.
NotFound: If any portion of any of the resource paths and types does not exist.
NotFound: If any of the domains, users, or groups do not exist.
NotFound: If any of the server attributes do not exist.
NotFound: If any of the resources specified in the importHints are not included in the export archive.
NotFound: If any of the users specified in the importHints are not included in any of the resources, privileges, or user data in the export archive.
Security: If the caller does not have READ access on all items in the explicitly identified resource paths. Paths to resources implicitly included, using includeChildren, that the caller does not have READ on, do not generate this fault.
Security: If the caller does not have admin privileges and attempts to use an export option that is ADMIN ONLY.
Security: If the caller attempts to use an OWNER ONLY export option does not have admin privileges and attempts to use an export option that is ADMIN ONLY.