Alfresco CS Importer
Introduction
The Alfresco CS Importer can import documents and folders processed in migration-center into a target Alfresco on-premises or PAAS repository.
The following versions of Alfresco are supported 7.1, 7.2, 7.3.1.
Known Issues and Limitations
The new Alfresco CS importer should not be installed with the old Alfresco importer or scanner. Having both installed can result in either of them not working.
Empty file update made to an empty file original object does not create new minor version (#72565)
Update cannot change object type (#72213)
Not setting required attributes does not throw error on import (#72019)
Import fails when extension changes in name in version tree when content doesn't exist in S3 with mapContentToStorage (#71932)
Non descriptive error message when defaultFolderType is empty (#72582)
Prerequisites
WebScript component
The Alfresco CS Importer requires an additional WebScript component to be installed on the Alfresco Server. This WebScript is delivered as an Alfresco Module Package (.amp) which has to be installed in the Alfresco Repository Server.
The AMP file can be found inside the Jobserver folder under:
\lib\mc-alfresco-cs-importer\WebScripts
On-premises install
To install the WebScript component on an on-premises Alfresco system, please see the official Alfresco documentation: https://docs.alfresco.com/content-services/latest/install/zip/amp
PAAS install
To install the WebScript component in an Alfresco PAAS, please send the AMP file to Hyland support and they will install it in your Alfresco instance.
Uploading content to the server
If you are uploading content to the server during the import and not using the mapContentToStorage feature, the following configuration needs to be done on the Alfresco server:
In ...\Tomcat\shared\classes\alfresco-global.properties set:
contentPropertyRestrictions.enabled=false
If this property is not set, you will receive an error as follows:
The node's content can't be updated via NodeService#setProperty directly
Mapping content to storage
If you are using the mapContentToStorage feature without uploading it during the import, the ContentPropertyRestrictionInterceptor property must be disabled on the server.
Importer Configuration
To create a new Alfresco CS Importer, create a new importer and select Alfresco CS 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 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.
Importer parameters
The common adaptor parameters are described in Common Parameters.
The configuration parameters available for the Alfresco importer are described below:
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.
password* The user’s password.
serverURL* The URL to the Alfresco Server API. i.e. http://my-alfresco-server/alfresco
importLocation The root path inside Alfresco where all documents/folder will be imported for this importer.
The path must start below the "company_home" node inside the spacesStore. i.e. /sites/demosite/documentLibrary - the document library of a share site with internal name demosite
This path will be concatenated in front of the parentfolder system rule value for each object.
autoCreateFolders When checked, the importer will automatically create any missing folders in the folderpath for any object (folder or documents).
Leave unchecked if the target repository already has the needed folder structure and creating new ones is not desired.
defaultFolderType Specifies the default folder type when creating folders using the autoCreateFolders option described above.
"cm:folder" for standard folder type
"fme:folder" for your own folder type
batchSize The number of documents objects to be sent in the same batch. Default: 100.
mapContentToStorage If checked, content is searched in the Alfresco Content Store and directly mapped without any upload. See mapContentToStorage.
loggingLevel* See Common Parameters.
Parameters marked with an asterisk (*) are mandatory.
Migset System Rules
The new Alfresco CS Importer uses the existing ...toAlfresco migset types from the old Alfresco Importer.
Documents
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 Spaces store. 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). Example: If the importLocation 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
inheritPermissions Boolean flag indicating if permission inheritance should be applied for that object. (true / false)
mc_content_location If this rule is has a value, it will be used to fetch the content instead of the default content_location. If mapContentToStorage
permissions Multivalue attribute used to set object permissions. See Permissions.
types / aspects Multivalue. Allows the setting of one mandatory type and zero, one or multiple aspects. See System Types And Aspects for the Alfresco system types and aspects that come with your installation of migration-center. Important: The first value in this attribute must be the content type. Example values: - 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.
Folders
folderpath Same as document system rules.
inheritPermissions Same as document system rules.
permissions Same as document system rules.
types / aspects Same as document system rules.
Details on folder migration
Compared to migrating documents and having the folder structure auto-created by the importer, migrating folder objects allows you to set detailed metadata on the folders themselves (such as permissions or aspects).
This approach involves migrating the folder structure first and then migrating the documents in that structure with the autoCreateFolders parameter unchecked.
In order to execute a folder-only migration the following steps should be performed to configure the migration process accordingly:
With the scanner you need to export folders as distinct migration-center objects. Only some scanners support this so please read the specific scanner userguide for details.
Creater a migset of type <SourceType>ToAlfresco(folder) and add the scan run containin gthe folder objects.
In the transformation rules use cm:folder for the base type and ensure to recreate the folderpath structure in a consistent way.
Example: To import the "MainFolder" folder object to the "/Folder/SubFolder/SubSubFolder" path your attributes should be set like this: folderpath: /Folder/SubFolder/SubSubFolder cm:name: MainFolder
The folderpath does not need to also contain the cm:name of the folder object.
Permissions
In Alfresco each object (document or folder) can have several permissions. 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). You can configure permissions for all object types (folder and documents).
Permission value format: Authority(Role, User or Group)###Permission###ACCESSSTATUS (ALLOWED or DENIED)
### is used as separator. ACCESSTATUS can be omitted, in which case the permission will default to ALLOWED.
Examples: ROLE_ADMINISTRATOR###Read UserName###Contributor###ALLOWED GROUP_GroupName###Consumer###DENIED GROUP_EVERYONE###CONSUMER###ALLOWED
When setting a permission for a group the name of the group must be preceded by "GROUP_".
Note that user, group and permission names are all case sensitive. Giving a "READ" permission instead of "Read" will result in errors.
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.
Delta Migration (Updates)
Due to limitations with the Alfresco API importing updated versions works differently than with other importers.
When importing update objects for any version in a version tree the update will create a new minor version in Alfresco.
Example: Importing an update for an object with version 3.0 will result in the Update object being imported as 3.1.
Importing update objects for objects without any versions will not create a new minor version and behaves like other standard Updates.
Map Content To Storage
This features allows the importer to skip the content upload and map the content that already exists in the Alfresco Content Store. So far the feature was tested with a filesystem store and an Amazon S3 store.
To use this feature, make sure the mapContentToStorage parameter is checked in the importer.
When this feature is active, the values for the content_location or mc_content_location attributes need to reflect the location of the content inside the Alfresco Content Store in the following format:
<protocol>://<path>
Example for regular Alfresco Store:
store://2024/4/17/10/41/71e92d20-8ac8-41b0-a92c-83b02820d1e5.bin
Example for S3 bucket:
s3v2://myFolder/test.txt
For an S3 store make sure to match the protocol that Alfresco is using either s3:// or s3v2://.
Also note that the S3 path does not include the actual bucket.
The importer will validate that the content exists and it will calculate the content size, mimetype and encoding based on it. If the content cannot be found or it is a folder, the object will fail to import with an error message.
System Types and Aspects
Your migration-center installation will come with the following Alfresco System Types and Aspects configured as Object Types. Any custom object type which is derived from cm:content or cm:folder can also be used.
Types
cm:content - Default Alfresco Document type
cm:name String. The document name
cm:folder - Default Alfresco Folder type
cm:name String. The folder name
Aspects
cm:auditable
cm:accessed Date. Date at which the object was last accessed
cm:created Date. Date at which the object was created
cm:creator User. Creator username
cm:modified Date. Date at which the object was last modified
cm:modifier User. Modifier username
cm:author
cm:author User. Author username
cm:ownable
cm:owner User. Owner username
cm:titled
cm:description String. Object description
cm:title String. Object title
cm:versionable
See Versions.
Last updated