Alfresco Importer
Introduction
The Alfresco Importer takes care of importing the documents and folders processed in migration-center into a target Alfresco repository.
Install/Uninstall Alfresco Importer
Alfresco Jobserver
The Alfresco connectors are not included in the standard migration-center Jobserver but it is delivered packaged as Alfresco Module Package (.amp) which has to be installed in the Alfresco Repository Server. This amp file contains an entire Jobserver that will run under the Alfresco's Tomcat, and contains only the Alfresco connectors in it. For using other connectors please install the regular Server Components as it is described in the Installation Guide and use that one.
The following versions of Alfresco are supported (on Windows or Linux): 4.0, 4.1, 4.2, 5.2, 6.1.1, 6.2.0, 7.1, 7.2, 7.3.1. Java 1.8 is required for the installation of Alfresco Importer.
To use the Alfresco Importer, your importer configuration must use the Alfresco Server as a Jobserver, with port 9701 by default.
Install Alfresco Importer
The first step of the installation is to copy mc-alfresco-adaptor-<Version>.amp file in the “amps-folder” of the Alfresco installation.
The last step is to finish the installation by installing the mc-alfresco-adaptor-<version>.amp file as described in the Alfresco documentation:
https://docs.alfresco.com/content-services/latest/install/zip/amp
Before doing this, please backup your original alfresco.war and share.war files to ensure that you can uninstall the migration-center Job Server after successful migration. This is the only way at the moment as long the Module Management Tool of Alfresco does not support to remove a module from an existing WAR-file.
The Alfresco-Server should be stopped when applying the amp-files. Please notice that Alfresco provides files for installing the amp files, e.g.:
C:\Alfresco\apply_amps.bat (Windows)
/opt/alfresco/commands/apply_amps.sh (Linux)
Due to a bug of the Alfresco installer under Windows, please be careful that the amp installer via apply_amps.sh works correctly!
Uninstall Alfresco Importer
The Alfresco can be uninstalled by following steps:
Stop the Alfresco Server.
Restore the original alfresco.war and share.war which have been backed up before Alfresco importer installation
Remove the file mc-alfresco-adaptor-<Version>.amp from the “amps-folder”
Rules for Alfresco system attributes
For migration in Alfresco systems, there are some system attributes available for transformation which need further explanation because they have a special syntax or meaning.
name of system attribute
description
examples
folderpath
Each object in Alfresco must be created under a parent object (parent-child-association). This parent object must be a Alfresco folder or a subtype of the Alfresco folder object (cm:folder).
For defining the parent object for an object which should be imported into Alfresco, use the system attribute folder.
©©
Currently, only one folder path is supported and the starting point for imports is the company_home-node of the Spacesstore. Only imports below this path are currently possible.
The format of the value must be a valid child node path (without using prefixes for the namespace).
If the import location of the Importer Module (see section 5.2) is set to /Sites/demosite
and the folderpath value is set to
/documentLibrary/Alfresco Demo
The object will be created under the documentLibrary of the demosite
Full path is:
/Sites/demosite/documentlibrary/Alfresco Demo
mc_content_location
This rule offers the possibility to overwrite the location of the objects content.
Leave empty in case the scanned content_location should be used.
Initial content location:
\\server\data\alfresco\testdocument.txt
Set a new location in order to access it from a linux mount of the above share:
/server/data/alfresco/testdocument.txt
permissions
In Alfresco each object (document or folder) can have several permissions where as one permissions consists of an Authority (person or group) which have a certain right (a certain role like Consumer or a certain right like Read). The access status (Allow/Deny) allows to define if the authority has the permission or not.
User and groups can be configured via Alfresco Explorer or Alfresco Share (Admin functions). Roles can be defined via permissions.xml (look at the Alfresco wiki to find more information).
To configure permissions for an object, use the system attribute permissions.
It can be multivalue and each value must have the following format:
AUTHORITY###PERMISSION### ACCESSSTATUS (ALLOWED|DENIED)
### is used as separator.
You can leave the last part of the value, so the default access status will be ALLOWED.
You can configure the permissions for all object types (folder and documents).
ROLE_ADMINISTRATOR###READ
each user in the administrator role will get read permission on the object for which this permission is set
GROUP_EVERYONE###CONSUMER###ALLOWED
Each user of the system (because each user is in the group everyone) will have the permissions of the consumer role.
types / aspects
Alfresco as an ECM-System provides built-in object types which can be used for documents and folders. It is also possible to define your own custom types.
Alfresco also provides the functionality to attach and detach aspects on nodes. Additionally, Alfresco has built-in aspects like a “cm:titled” or “cm:author” aspect. More information is provided here: http://wiki.alfresco.com/wiki/Aspect
To configure the object type and aspects for the object to be imported, use the systemattribute types / aspects.
The attribute is multi-value, so it is possible to define exactly one object type and zero, one or more aspects for one object to be imported.
Please note that any custom object type can be used which are derived from cm:content or cm:folder.
Important: The first value in this attribute must be the content type.
cm:content
cm:auditable
cm:titled
The object imported will be of type cm:content (alfresco standard document type) and will get the aspects cm:auditable and cm:titled.
Importing Versions
To import major/minor versions in Alfresco, you need to set the "cm:versionable" aspect with the "cm:versionLabel" attribute. If the version label ends with “.0”, a major version is created, otherwise a minor version is created. The actual version label numbers are determined automatically by Alfresco.
If you do not set the “cm:versionLabel” in the aspect association, the importer will create all versions as major.
If you do not assign the “cm:versionable” aspect in the system rule “types / aspects”, the importer assigns it automatically when importing the second version.
Version Comments can be assigned by setting the "versionComments" attribute.
Note that the first version of a version tree cannot have a comment, since it was not checked in, but created.
Alfresco Importer Properties
To create a new Alfresco Importer job, specify the respective adapter type in the properties window – from the list of available connectors “Alfresco” must be selected. Once the adapter type has been selected, the parameters list will be populated with the parameters specific to the selected adapter type, in this case the Alfresco connector’s parameters.
The properties window of an importer can be accessed by double-clicking an importer in the list or selecting the Properties button or entry from the toolbar or context menu.
Common importer parameters
Configuration parameter
description
Name
Enter a unique name for this importer
Mandatory
Adapter type
Select the “Alfresco” connector from the list of available connectors
Mandatory
Location
Select the Alfresco Importer location where this job should be run. Locations are defined in the Jobserver window. If there is no Job Server Location configured, migration-center will prompt the user to define a Job Server Location when saving the importer.
Mandatory
Note: that the Alfresco server must be used as a Job Server Location with default port 9701.
Description
Enter a description for this job (optional)
Alfresco importer parameters
Configuration parameters
Description
username*
User name for connecting to the target repository.
A user account with admin privileges must be used to support the full Alfresco functionality offered by migration-center.
Mandatory
password*
The user’s password.
Mandatory
importLocation
The path inside the target repository where objects are to be imported. It must be a valid Alfresco path and have to start below the “company_home”-node inside the spacesStore.
Examples for valid values of importLocation:
“/sites/demosite/documentLibrary/” for import into the document library of a share site with internal name demosite
“/demofolder” for import a folder with name demofolder below the company home folder.
This path will be appended in front of each folder value (for documents and folders) before creating parent-child association for this object if both the importLocation parameter and the folder attribute values are set.
If the attributes mentioned previously already contain a full path, the importLocation parameter does not need to be filled.
Examples:
importLocation = ”sites/demosite/documentLibrary/” and folder for documents “/test” = complete path “/sites/demosite/documentLibrary/test”
autoCreateFolders
This option will be used for letting the importer automatically create any missing folders (spaces) that are part of the folderpath for any object (folder or documents).
Use this option to have migration-center re-create a folder structure at the target repository during import. If the target repository already has a fixed/predefined folder structure and creating new folders is not desired, deselect this option.
defaultFolderType
Specifies the default folder type when creating folders using the autoCreateFolders option described above. If the parameter is empty, “cm:folder” will be used by default.
Examples for valid values:
“cm:folder” for standard folder type
“fme:folder” for your own folder type
loggingLevel*
Sets the verbosity of the log file.
Values:
1 - logs only errors during scan
2 - is the default value reporting all warnings and errors
3 - logs all successfully performed operations in addition to any warnings or errors
4 - logs all events (for debugging only, use only if instructed by fme product support since it generates a very large amount of output. Do not use in production)
Mandatory
On the | Migsets | tab, the user can select the migration sets to be imported with this importer. Depending on the chosen Adapter Type only the migration sets compatible with this type of importer will be displayed and can be selected for import. Also, only migration sets containing at least one object in a validated state will be displayed (since objects which haven’t been validated cannot be imported).
Available migration sets can be moved between the two columns by double clicking or using the arrows buttons.
Information on folder migration
When scanning and importing documents, their folder paths are also scanned and the folder structure can be automatically created by migration-center in the target repository. This procedure will not keep any of the metadata attached to the folder objects, such as owners, permissions, specific object types, or any custom attributes. Depending on project requirements, it may be required to do a “folder-only migration”, e.g. for migrating a complete folder structure including custom folder types, permissions and other attributes first, and then populate this folder structure with documents afterwards. In order to execute a folder-only migration the following steps should be performed to configure the migration process accordingly:
Scanner: Folder migration works only in conjunction with on the scanners that support scanning folders as distinct migration-center objects. For more information about scanning folders please read the specific scanner userguide.
Migration set: When creating a new migration set choose the <SourceType>ToAlfresco(folder) type. Now only the scanner runs containing folder objects will be displayed on the |Filescan Selection| tab. Note that the number of objects contained in the displayed scanner runs now indicates folders and not documents, which is why the number on display (folders) can be different from the total number of objects processed by the scan (if it contains other types of objects besides folders).
Transformation rules: When creating transformation rules for the migration set, keep in mind that folder-only migration sets have folder-specific attributes to work with.
“name” and “folder” are key attributes for folders in Alfresco. If these attributes are transformed without taking into consideration how these objects build into a tree structure, it may no longer be possible to reconstruct the folder tree. This is not due to migration-center, but rather because of the nature of folders being arranged in a tree structure which does create dependencies between the individual objects.
In Alfresco the “folder” attribute contains the path(s) to the current folder, as well as the folder itself at the end of the path (e.g. /folder_null/folder_one/folder_two/current_folder), while “foldername” contains only the folder name (e.g. current_folder).
Importer: When configuring the importer on the |Parameters| tab, the “importObjects” and “autoCreateFolders” options are not used for the folder-only migration. Note that these parameters will still be in effect if other migration set(s) containing <SourceType>ToAlfresco(document) objects will be imported together with the folder migration set.
Folder migration is important. It is necessary to take the approach described above when migrating folder structures with complex folder objects containing custom object types, permissions, attributes, relations, etc.
