Alfresco Scanner

Introduction

The Alfresco Scanner allows extracting object such as document, folders and lists and saves this data to migration-center for further processing. The key features of Alfresco Scanner are:

  • Extract documents, folders, custom lists and list items

  • Extract content, metadata

  • Extract documents versions

Scanner is the term used in migration-center for an input adapter. Using a scanner such as the Alfresco Scanner to extract data that needs processing in migration-center is the first step in a migration project, thus scan also refers to the process used to input data to migration-center.

Scanners and importers work as jobs that can be run at any time, and can even be executed repeatedly. For every run a detailed history and log file are created. Multiple scanner and import jobs can be created or run at a time, each being defined by a unique name, a set of configuration parameters and a description (optional).

Known issues & limitations

  • Last version content is missing online edits when cm:autoVersion was false and then it's switched to true before scanning (#55983)

Install/Uninstall Alfresco Scanner

Alfresco Jobserver

The Alfresco adapters 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 adapters in it. For using other adapters 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. Java 1.8 is required for the installation of Alfresco Scanner.

To use the Alfresco Scanner, your scanner configuration must use the Alfresco Server as a Jobserver, with port 9701 by default.

Install Alfresco Scanner

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 Jobserver 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 Scanner

The Alfresco Scanner 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 Scanner installation

  • Remove the file mc-alfresco-adaptor-<version>.amp from the “amps-folder”

Alfresco Scanner Properties

To create a new Alfresco Scanner, create a new scanner and select Alfresco from the Adapter Type drop-down. Once the adapter type has been selected, the Parameters list will be populated with the parameters specific to the selected adapter type. Mandatory parameters are marked with an *.

The Properties of an existing scanner can be accessed after creating the scanner by double-clicking the scanner in the list, or selecting the Properties button/menu item from the toolbar/context menu. A description is always displayed at the bottom of the window for the selected parameter.

Multiple scanners can be created for scanning different locations, provided each scanner has a unique name.

Common scanner parameters

Configuration parameters

Values

Name

Enter a unique name for this scanner

Mandatory

Adapter type

Select Alfresco from the list of available adapters

Mandatory

Location

Select the Jobserver location where this job should be run. Jobservers are defined in the Jobserver window. If no Jobserver has been created by the user to this point, migration-center will prompt the user to define a Jobserver Location when saving the Scanner.

Note that the Alfresco Server must be used as a Jobserver Location with default port 9701.

Mandatory

Description

Enter a description for this job (optional)

Alfresco Scanner parameters

The configuration parameters available for the Alfresco Scanner are described below:

Configuration parameters

Values

username*

User name for connecting to the source repository. A user account with admin privileges must be used to support the full Alfresco functionality offered by migration-center.

Example: Alfresco.corporate.domain\spadmin

Mandatory

password*

Password of the user specified above

Mandatory

scanLocations

The entry point(s) in the Alfresco repository where the scan starts.

Multiple values can be entered by separating them with the “|” character.

Note that this value(s) needs to be according to the Alfresco Repository folder structure, ex:

/Sites/SomeSite/documentLibrary/Folder/AnotherFolder

/Sites/SomeSite/dataLists/02496772-2e2b-4e5b-a966-6a725fae727a

The scanner allows as a scan location: an entire site, a specific library, a specific folder in a library, a specific data list.

If one location is invalid the scanner will report an appropriate error to the user so it will not start.

contentLocation*

Folder path. The location where the exported object content should be temporary saved. It can be a local folder on the same machine with the Jobserver or a shared folder on the network. This folder must exist prior to launching the scanner and must have write permissions, migration-center will not create this folder automatically. If the folder cannot be found an appropriate error will be raised and logged. This path must be accessible by both scanner and importer so if they are running on different machines, it should be a shared folder.

Mandatory

exportLatestVersions

This parameter specifies how many versions from every version tree will be exported starting from the latest version to the older versions. If it is empty, not a valid number, 0 or negative, greater than the latest "n" versions, all versions will be exported.

exportContent

Setting this parameter to true will extract the actual content of the documents during the scan and save it in the contentLocation specified earlier.

This setting should always be checked in a production environment.

dissolveGroups

Setting this parameter to true will cause every group permission to be scanned as the separate users that make up the group

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

History, Reports, Logs

A complete history is available for any Alfresco Scanner 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 Scanner can be found in the Alfresco log folder on the machine where the job was run, e.g. C:\Alfresco\logs

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