Export and Import

From AlfrescoWiki

Jump to: navigation, search

Contents

[edit] Introduction

Alfresco provides the capability to export information held in its Repository and then subsequently import that information into either the same or another Repository. If a Repository can store it, a Repository can export and import it.

Export and Import is useful for:

  • Bulk extract and load of personal or team information from one location to another
  • Backup and restore (personal, team or complete Repository scope)
  • Integration with 3rd party systems

Note: You can only perform an import/export between compatible versions of Alfrsco.

The process for export and import is simple.

1) Export produces one or more ACP (Alfresco Content Package) files which hold the exported information. As with all files, you can place them somewhere secure, or transfer them using transports such as e-mail, ftp etc. The scope of information to export is configurable, but typically involves specifying the location within the Repository to export. Due to the hierarchical nature of the Repository every item within that location is taken e.g. exporting folder "My Documents" will export the folder, its contents, and all sub-folders. Security settings only allow export of those items which are readable by the user performing the export.

2) Import of an ACP file is the reverse of an export. The information held in the ACP file is placed into the Repository location chosen at import time. By default, the import process creates a copy of the ACP held information, although, other forms of import can take place such as "update information, if it already exists".

The format of an ACP file is described in detail later in this document, but it should be noted that any process or tool may generate one, which is very useful to system to system integration.

[edit] Web Client Export & Import of Folders & Files

Any user of Alfresco may perform an export and import of folders and files they have access to.

The process for export of a Folder within the Web Client is:

  1. Select Space to export
  2. Select More Actions -> View Details
  3. Select Export Action to launch Export Dialog
  4. Fill in export options
    1. Package name - name of the resulting export ACP file
    2. Destination - the location within the Repository to place the ACP file
    3. Include children - if selected, will also export sub-folders
    4. Include self - if selected, exports the selected folder, otherwise only export the children
    5. Run in background - if selected, the export will take place in the background eventually creating export ACP file
    6. Select Ok

On success, the destination location will contain the ACP file. At this point the ACP file can be saved to a local file system for safe backup or transfer via e-mail.

The process for importing an ACP file within the Web Client is:

  1. Select Space to import information into
  2. Select More Actions -> View Details
  3. Select Import Action to launch Import Dialog
  4. Fill in export options
    1. Location - select ACP file to import from file system
    2. Select Upload
    3. Run in background - if selected, the import will take place in the background eventually creating all folders and files held in the ACP file
    4. Select Ok

On sucess, the information exported and held in the ACP file will now reside in the destination Space.

[edit] Web Client Export & Import of a Complete Repository

An Administrator of Alfresco may perform a full Export and Import, where full means all information in the Repository is placed into a series of ACP files (plus one XML file for system related information). Full Export and Import is used for backup purposes or migrating one installation to another. Migration may take place even if source and destination Repository databases are different, or Alfresco versions are different (although some adjustment of the ACP held information may be necessary). This is particularly useful for staging deployments.

The process for full export and import is:

[edit] Export complete source Repository via Alfresco Web Client Administration Console

The Export administration screen provides a 'Complete Repository' option. This option creates several ACP files (plus one XML file) in the chosen Repository location where each ACP file represents a part of the Repository storage. All file names are prefixed with the specified 'Package Name'.

Image:fullexport.jpg

Full export may take some time. It is recommended that usage of the Repository is suspended whilst export takes place.

Image:fullexportfiles.jpg

Once complete, the next step is to extract the created files out of the Repository. This is easiest via the CIFS, FTP or WebDAV interfaces where it is possible to copy many files at once. At this point, move all the created files to a secure place for backup purposes.

[edit] Bootstrap destination Repository from ACP files exported from Full Export

The Alfresco Repository supports a bootstrap process which is initiated whenever the Repository is first started. The process populates the Repository with information that is required upon first login such as system users, data dictionary definitions and important root folders.

The bootstrap process is configurable allowing the population of any information during the first start of the Repository. It is this configurability that allows a Repository to be bootstrapped from an existing 'Full Repository Export' as described in step 1. Upon startup of the Repository, all information exported from the source Repository is imported, so that once started, the new Repository will look just like the source Repository.

Note: When exporting and importing from an older Repository version to a newer Repository version, all applicable patches are automatically applied.

The steps for configuring the bootstrap process for a full restore are:

  1. Install Alfresco, but do not start (or ensure existing Alfresco installation is configured against an empty database and file system).
  2. Rename existing restore-context.xml.sample to restore-context.xml and place into the configuration extension directory /alfresco/extension.
  3. By default, restore-context.xml assumes a package name of 'export' was used. If this is not the case, replace all occurrences of 'export' with your package name.
  4. Create a directory called restore within /alfresco/extension.
  5. Place the exported files from the source Repository into /alfresco/extension/restore.
  6. Start Alfresco

If configured correctly, log messages detailing the import of each backup file are presented to the Alfresco server console.

The restore-context.xml.sample file can be found in various locations, depending on the distribution of Alfresco you download. If you installed the JBoss distribution, you can find the restore-context.xml.sample in $JBOSS_HOME/server/default/conf/alfresco/extension/. If you installed the Tomcat distribution, you can find the restore-context.xml.sample in $TOMCAT_HOME/shared/classes/alfresco/extension/. For other distributions, the location of this extension directory may be slightly different.

[edit] Import Action

Using Alfresco Rules and Actions it is possible to setup an automated import whereby an ACP file is automatically imported into the Repository when placed into a designated Repository folder (or Space).

For example, the following Rule is defined against an 'Import' folder which has a condition of '*.acp' and if met, has an action to Import the ACP into the 'Dave's Space' folder.

Image:Importrule.jpg

When an ACP file is placed into the 'Import' folder it automatically kicks off the Import process and places the items held in the ACP file into the 'Dave's Space' folder.

The important point to remember, is that the Import will be initiated regardless of how the ACP file was placed into the folder. For example, the Import will initiate if the ACP file was placed there via CIFS, FTP, WebDAV, Web Client or API. This is particularly powerful for system to system data integration.

[edit] Alfresco Content Package (ACP) File Format

An Alfresco Content Package (otherwise known as an ACP file) is a single file (with an extension of .acp) that bundles together the meta-data and content files for the information to be transported.

An ACP file is simply a ZIP archive whose structure is as follows: 

/<packagename>.xml
/<packagename>/
   contentNNN.pdf
   contentNNN.txt
   ...

The packagename is assigned on export.

<packagename>.xml contains an xml rendition of the transported information in the form of Repository Nodes. There is no restriction as to what types of information can be transported but typically a bundle will contain Folders and Files. Other types of information may include Forums, Rules, Preferences, Tasks - anything that is described by a Repository Content Model.

The XML conforms to the Export and Import View Schema which describes the transported nodes in terms of their types, aspects, properties, associations and permissions. Content properties are handled specifically where the binary content of the property is held in a seperate file under the packagename directory of the ZIP archive and the xml contains a reference to the file.

Although the Repository provides different ways to create an ACP file (i.e. Export), it is also possible to manually create one via any means. This is very useful for system to system integration.

[edit] Import UUID Bindings

Within an ACP file each node may be decorated with its unique ID (known as UUID). On import, a node with the same UUID may already exist in the destination Repository. The import process is informed what to do in such scenarios by specifying one of the following 'UUID bindings' (the mechanism for specifying depends on how the import is initiated and are described later in this document):

CREATE_NEW

This binding always creates a new node in the destination Repository based on the information held in the ACP file and allocated a new UUID.

CREATE_NEW_WITH_UUID

This binding always creates a new node with the UUID as specified in the ACP file (if one is specified, otherwise a new UUID is allocated).

REMOVE_EXISTING

This binding determines if an existing node in the Repository with the same UUID already exists. If so, the import process first deletes the existing node and then creates the new node in the location as specified during the import process. If an existing node does not exist, it just creates the new node as if CREATE_NEW had been chosen.

REPLACE_EXISTING

This binding determines if an existing node in the Repository with the same UUID already exists. If so, the import process first deletes the existing node and then creates a new node in the same location as the one just deleted. If an existing node does not exist, it just creates the new node as if CREATE_NEW had been chosen.

UPDATE_EXISTING

This binding determines if an existing node in the Repository with the same UUID already exists. If so, the import process updates the existing node with information held in the ACP file. If an existing node does not exist, it just creates the new node as if CREATE_NEW had been chosen.

THROW_ON_COLLISION

This binding determines if an existing node in the Repository with the same UUID already exists. If so, the import process stops with an exception.

[edit] Export & Import Command Line Tools

Alfresco Export and Import Tools are developed directly against the Alfresco Repository Foundation APIs. This means they execute stand-alone with an embedded Repository. To perform an Export and Import via these tools requires configuration of the Repository to ensure the appropriate storage locations (e.g. database and file system directory) are used.

Note: On Windows, Alfresco 2.1, run this from TOMCAT\webapps\alfresco\WEB-INF directory. 


java.exe -classpath classes\alfresco\module;..\..\..\shared\classes;classes;lib\acegi-security-0.8.2_patched.jar;lib\activation.jar;lib\addressing-1.0.jar;lib\alfresco-core.jar;lib\alfresco-deployment.jar;lib\alfresco-linkvalidation.jar;lib\alfresco-mbeans.jar;lib\alfresco-remote-api.jar;lib\alfresco-repository.jar;lib\alfresco-web-client.jar;lib\ant.jar;lib\antlr-2.7.5H3.jar;lib\aopalliance.jar;lib\avalon-framework-4.2.0.jar;lib\bcel.jar;lib\bcprov-jdk15-137.jar;lib\bsf-2.4.0.jar;lib\bsh-1.3.0.jar;lib\catalina.jar;lib\cglib-nodep-2.2_beta1.jar;lib\chiba-1.3.0.jar;lib\commons-beanutils-1.7.0.jar;lib\commons-codec-1.3.jar;lib\commons-collections-3.1.jar;lib\commons-dbcp-1.2.1.jar;lib\commons-digester-1.6.jar;lib\commons-discovery-0.2.jar;lib\commons-el.jar;lib\commons-fileupload-1.1.1.jar;lib\commons-httpclient-3.0.jar;lib\commons-io-1.1.jar;lib\commons-jxpath-1.2.jar;lib\commons-lang-2.1.jar;lib\commons-logging-1.0.4.jar;lib\commons-modeler.jar;lib\commons-pool-1.3.jar;lib\commons-validator.jar;lib\cpool.jar;lib\cryptix-jce-provider.jar;lib\dom4j-1.6.1.jar;lib\ehcache-1.3.0-patched.jar;lib\fontbox-0.1.0.jar;lib\fop-0.92beta.jar;lib\freemarker.jar;lib\guessencoding-1.0.jar;lib\hibernate-3.2.1.jar;lib\hrtlib.jar;lib\hsqldb.jar;lib\htmlparser-1.6.jar;lib\icu4j_3_6_1.jar;lib\jakarta-oro-2.0.8.jar;lib\jaxen-1.1-beta-8.jar;lib\jaxrpc.jar;lib\jbpm-identity-3.2.jar;lib\jbpm-jpdl-3.2-patched.jar;lib\jcr-1.0.jar;lib\jgroups-2.2.8.jar;lib\jibx-bind.jar;lib\jibx-run.jar;lib\jid3lib-0.5.jar;lib\JMagick.jar;lib\joda-time-1.2.1.jar;lib\jooconverter-2.1.0.jar;lib\json.jar;lib\jstl-1.1.0.jar;lib\jta.jar;lib\jug-lgpl-2.0.0.jar;lib\jut.jar;lib\log4j-1.2.8.jar;lib\lucene-analyzers-2.1.0.jar;lib\lucene-core-2.1.0.jar;lib\lucene-snowball-2.1.0.jar;lib\mail.jar;lib\myfaces-api-1.1.5.jar;lib\myfaces-impl-1.1.5.jar;lib\naming-factory.jar;lib\naming-resources.jar;lib\odf_utils.jar;lib\odmg-3.0.jar;lib\openoffice-juh-2.0.3.jar;lib\openoffice-jurt-2.0.3.jar;lib\openoffice-ridl-2.0.3.jar;lib\openoffice-sandbox-2.0.3.jar;lib\openoffice-unoil-2.0.3.jar;lib\opensaml-1.0.1.jar;lib\pdfbox-0.7.3.jar;lib\poi-2.5.1_patched.jar;lib\portlet-api-lib.jar;lib\quartz-1.6.0.jar;lib\resolver.jar;lib\rhino-js-1.6R4.jar;lib\saaj.jar;lib\saxpath.jar;lib\spring-2.0.2.jar;lib\springmodules-jbpm31.jar;lib\standard.jar;lib\tlc124.jar;lib\tm-extractors-0.4_patched.jar;lib\tomcat-coyote.jar;lib\tomcat-util.jar;lib\truezip.jar;lib\wsdl4j-1.5.1.jar;lib\wss4j.jar;lib\xercesImpl-2.8.0.jar;lib\xml-apis.jar;lib\xmlgraphics-commons-1.0.jar;lib\xmlsec-1.4.0.jar;lib\xpp3-1.1.3_8.jar;lib\xstream-1.1.3.jar;..\..\..\common\lib\mysql-connector-java-5.0.3-bin.jar;..\..\..\common\endorsed\serializer.jar;..\..\..\common\endorsed\xalan.jar;lib\axis-1.4.jar;lib\jug.jar org.alfresco.tools.Export -user admin -pwd admin -store user://alfrescoUserStore -verbose users.acp


Note: On Linux Fedora, Alfresco 2.1, run this from TOMCAT/webapps/alfresco/WEB-INF directory. 


java -classpath classes/alfresco/module:../../../shared/classes:classes:lib/acegi-security-0.8.2_patched.jar:lib/activation.jar:lib/addressing-1.0.jar:lib/alfresco-core.jar:lib/alfresco-deployment.jar:lib/alfresco-linkvalidation.jar:lib/alfresco-mbeans.jar:lib/alfresco-remote-api.jar:lib/alfresco-repository.jar:lib/alfresco-web-client.jar:lib/ant.jar:lib/antlr-2.7.5H3.jar:lib/aopalliance.jar:lib/avalon-framework-4.2.0.jar:lib/bcel.jar:lib/bcprov-jdk15-137.jar:lib/bsf-2.4.0.jar:lib/bsh-1.3.0.jar:lib/catalina.jar:lib/cglib-nodep-2.2_beta1.jar:lib/chiba-1.3.0.jar:lib/commons-beanutils-1.7.0.jar:lib/commons-codec-1.3.jar:lib/commons-collections-3.1.jar:lib/commons-dbcp-1.2.1.jar:lib/commons-digester-1.6.jar:lib/commons-discovery-0.2.jar:lib/commons-el.jar:lib/commons-fileupload-1.1.1.jar:lib/commons-httpclient-3.0.jar:lib/commons-io-1.1.jar:lib/commons-jxpath-1.2.jar:lib/commons-lang-2.1.jar:lib/commons-logging-1.0.4.jar:lib/commons-modeler.jar:lib/commons-pool-1.3.jar:lib/commons-validator.jar:lib/cpool.jar:lib/cryptix-jce-provider.jar:lib/dom4j-1.6.1.jar:lib/ehcache-1.3.0.jar:lib/fontbox-0.1.0.jar:lib/fop-0.92beta.jar:lib/freemarker.jar:lib/guessencoding-1.0.jar:lib/hibernate-3.2.1.jar:lib/hrtlib.jar:lib/hsqldb.jar:lib/htmlparser-1.6.jar:lib/icu4j_3_6_1.jar:lib/jakarta-oro-2.0.8.jar:lib/jaxen-1.1-beta-8.jar:lib/jaxrpc.jar:lib/jbpm-identity-3.2.jar:lib/jbpm-jpdl-3.2-patched.jar:lib/jcr-1.0.jar:lib/jgroups-2.2.8.jar:lib/jibx-bind.jar:lib/jibx-run.jar:lib/jid3lib-0.5.jar:lib/JMagick.jar:lib/joda-time-1.2.1.jar:lib/jooconverter-2.1.0.jar:lib/json.jar:lib/jstl-1.1.0.jar:lib/jta.jar:lib/jug.jar:lib/jut.jar:lib/log4j-1.2.8.jar:lib/lucene-analyzers-2.1.0.jar:lib/lucene-core-2.1.0.jar:lib/lucene-snowball-2.1.0.jar:lib/mail.jar:lib/myfaces-api-1.1.5.jar:lib/myfaces-impl-1.1.5.jar:lib/naming-factory.jar:lib/naming-resources.jar:lib/odf_utils.jar:lib/odmg-3.0.jar:lib/openoffice-juh-2.0.3.jar:lib/openoffice-jurt-2.0.3.jar:lib/openoffice-ridl-2.0.3.jar:lib/openoffice-sandbox-2.0.3.jar:lib/openoffice-unoil-2.0.3.jar:lib/opensaml-1.0.1.jar:lib/pdfbox-0.7.3.jar:lib/poi-2.5.1_patched.jar:lib/portlet-api-lib.jar:lib/quartz-1.6.0.jar:lib/resolver.jar:lib/rhino-js-1.6R4.jar:lib/saaj.jar:lib/saxpath.jar:lib/spring-2.0.2.jar:lib/springmodules-jbpm31.jar:lib/standard.jar:lib/tlc124.jar:lib/tm-extractors-0.4_patched.jar:lib/tomcat-coyote.jar:lib/tomcat-util.jar:lib/truezip.jar:lib/wsdl4j-1.5.1.jar:lib/wss4j.jar:lib/xercesImpl-2.8.0.jar:lib/xml-apis.jar:lib/xmlgraphics-commons-1.0.jar:lib/xmlsec-1.4.0.jar:lib/xpp3-1.1.3_8.jar:lib/xstream-1.1.3.jar:../../../common/lib/mysql-connector-java-5.0.3-bin.jar:../../../common/endorsed/serializer.jar:../../../common/endorsed/xalan.jar:lib/axis-1.4.jar org.alfresco.tools.Export -user admin -pwd admin -store user://alfrescoUserStore -verbose users.acp


Note: Future versions of the tools will allow direct Export and Import against a remote Repository.

Note: This tool has name collision with unix/linux bash built-in command 'export' . Use proper name for it, like import.sh or other.


[edit] Export Tool

org.alfresco.tools.Export 

Usage: export -user username -s[tore] store [options] packagename

username: username for login
store: the store to extract from in the form of scheme://store_name
packagename: the filename to export to (with or without extension)

Options:
 -h[elp] display this help
 -p[ath] the path within the store to extract from (default: /)
 -d[ir] the destination directory to export to (default: current directory)
 -pwd password for login
 -packagedir the directory to place extracted content (default: dir/<packagename>)
 -root extract the item located at export path
 -nochildren do not extract children
 -overwrite force overwrite of existing export package if it already exists
 -quiet do not display any messages during export
 -verbose report export progress
 -zip export in zip format

For example:

export -user admin -pwd admin -s workspace://SpacesStore -verbose SpacesStore.acp

[edit] Default Stores

The following are default Alfresco repository stores to be used as parameters:

  • archive://SpacesStore - archival workspace
  • system://system
  • user://alfrescoUserStore - user information
  • workspace://lightWeightVersionStore
  • workspace://SpacesStore - most of the information in the repository


[edit] Import Tool

org.alfresco.tools.Import 

Usage: import -user username -s[tore] store [options] packagename

username: username for login
store: the store to import into the form of scheme://store_name
packagename: the filename to import from (with or without extension)

Options:
 -h[elp] display this help
 -p[ath] the path within the store to import into (default: /)
 -d[ir] the source directory to import from (default: current directory)
 -pwd password for login
 -encoding package file encoding (default: windows-1252)
 -quiet do not display any messages during import
 -verbose report import progress
 -uuidBinding CREATE_NEW, REMOVE_EXISTING, REPLACE_EXISTING, UPDATE_EXISTING, THROW_ON_COLLISION (default: CREATE_NEW)

For example:

import -user admin -pwd admin -s workspace://SpacesStore -verbose SpacesStore.acp
import -user admin -pwd admin -s workspace://SpacesStore -verbose SpacesStore.xml

As you'll see from the examples, it is possible to import from an ACP file or just an XML file. Importing just XML is useful if you want to import Nodes without associated binary content e.g. People.

[edit] Export & Import Foundation APIs

The Alfresco Foundation Services API provides export and import capabilities.

[edit] Export Foundation API Example

The Alfresco Java service API provides an Exporter service. This service provides various ways of exporting data out of the Repository, although the most commonly used method is: 

public void exportView(ExportPackageHandler exportHandler, ExporterCrawlerParameters parameters, Exporter progress)
   throws ExporterException;

where:

  • exportHandler is responsible for how the exported data is rendered
  • parameters defines the set of nodes to export
  • progress is a call-back for tracking what is being exported during export

For example, to export the complete Workspace used by Alfresco's Web Client to an ACP file the following code snippet can be used: 

// define which part of the Repository to export
Location location = new Location(new StoreRef("workspace", "SpacesStore"));
location.setPath("/");
ExporterCrawlerParameters parameters = new ExporterCrawlerParameters();
parameters.setExportFrom(location);


// setup an ACP Package Handler to export to an ACP file format
ExportPackageHandler handler = new ACPExportPackageHandler(...);


// now export (note: we're not interested in progress in the example)
exporter.exportView(handler, parameters, null);

Upon completion of exportView, the ACP file will exist at the location defined by the handler.

[edit] Import Foundation API Example

The Alfresco Java service API provides an Importer service. This service provides various ways of importing data into the Repository, although the most commonly used method is: 

public void importView(ImportPackageHandler importHandler, Location location, ImporterBinding binding, ImporterProgress progress)
   throws ImporterException;

where:

  • importHandler is responsible for extracting repository nodes from the provided import file (e.g. ACP file)
  • location defines where to import into the repository
  • binding provides the ability to substitute variables within the import file and specifiy the import binding
  • progress is a call-back for tracking what is being imported during export

For example, to import the complete Workspace as exported above into a fresh repository, the following code snippet can be used: 

// specify the location within the Repository to import into
Location location = new Location(new StoreRef("workspace", "SpacesStore") );


// setup an ACP Package Handler to import from an ACP file
ImportPackageHandler handler = new ACPImportPackageHandler(...);


// import (note: in this example we're not interested in progress)
importer.importView(handler, location, null, null);

Upon completion of importView, the information held within the ACP file will now reside within the Repository. As with all service API calls, the import takes place within the context of a transaction and so now the imported data can be committed or rolled-back.


[edit] JSR-170 Export & Import Support

The Alfresco Repository supports JSR-170 Level 1 and Level 2 which includes export and import of:

  • JSR-170 System View XML
  • JSR-170 Document View XML

Refer to the JSR-170 specification for details of these file formats and the APIs used for exporting and importing.

[edit] Export & Import of the AVM (Web Projects)

The export / import functionality described here currently does not include support for AVM stores (which form the basis of the Alfresco WCM functionality). This is planned for a future release.

Back to Server Administration Guide

Retrieved from "http://wiki.alfresco.com/wiki/Export_and_Import"