Alfresco Importer

Introduction

The Alfresco Importer takes care of importing the documents and folders processed in migration-center into a target Alfresco repository.

Importer is the term used for an output adapter which is most likely used at the last step of the migration process. An importer works as a job that can be run at any time and can even be executed repeatedly. For every run a detailed history and log file are created. An importer is defined by a unique name, a set of configuration parameters and an optional description.

Alfresco importers can be created, configured, started and monitored through migration-center Client, but the corresponding processes are executed inside the Alfresco Repository Server.

Install/Uninstall Alfresco Importer

Install Alfresco Importer

The Alfresco Importer it’s not included in the standard installer of migration-center Server Components but it is delivered packaged as Alfresco Module Package (amp). This is because the Alfresco Importer has to be installed within the Alfresco Repository Server. The following versions of Alfresco are supported (on Windows or Linux): 3.4, 4.0, 4.1, 4.2, 5.0.2, 5.1, 5.2, 6.1.1, 6.2.0.

Java 1.8 is required for the installation of Alfresco Importer.

For installing the other adapters you need during your migration process please install the Server Components as it is described in the Installation Guide. It is recommended to install the Server Components on another machine but it is also possible to install it on the Alfresco Server. In case you use the Alfresco Importer in combination with a Scanner running on another machine then the scanner should export the files on a network share that is accessible from the Alfresco Server.

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 it is described by the wiki guide of Alfresco under http://wiki.alfresco.com/wiki/Module_Management_Tool

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:\Alfresco34\apply_amps.bat (Windows)

/opt/alfresco/commands/apply_amps.sh (Linux)

Due to a bug of the Alfresco installer under Windows, please be careful if the amp installer via apply_amps.sh works correctly! Under Alfresco 3.4, the file apply_amps.bat must be location in the alfresco location and not in the subfolder bin!

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

The importer imports the versions in the same order as they are scanned from the source system. If the “cm:versionable” aspect is not set in the system rule “types / aspects”, the importer assigns it automatically when importing the second version. If “cm:versionLabel” was not set in the transformation rules, the importer will create major versions preserving the order of versions in the source system. By setting “cm:versionLabel” in the “cm:versionable” aspect in transformation rules, the importer will create minor or major versions following these rules: if the version label ends with “.0”, a major version is created, otherwise a minor version is created. The imported object’s version-label is determined automatically by Alfresco.

Alfresco Importer Properties

To create a new Alfresco Importer job, specify the respective adapter type in the properties window – from the list of available adapters “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 adapter’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” adapter from the list of available adapters 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:

• 1. 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.

• 1. 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).

  2. 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).

• 1. 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.

Log files

A complete history is available for the Filesystem Scanner or Alfresco Importer job from the respective items’ History window. It is accessible through the History button/menu entry on the toolbar/context menu. The History window displays a list of all runs for the selected job together with additional information, such as the number of processed objects, the start and ending time and the status.

Double clicking an entry or clicking the Open button on the toolbar opens the log file created by that run. The log file contains more information about the run of the selected job:

• Version information of the migration-center Server Components the job was run with

• The parameters the job was run with

• Execution Summary that contains the total number of objects processed, the number of documents and folders scanned or imported, the count of warnings and errors that occurred during runtime.

Log files generated by the Alfresco Importer can be found in subfolder .\logs on the

The amount of information written to the log files depends on the setting specified in the ‘loggingLevel’ start parameter for the respective job.