Transformation

This accelerator contains multiple transformation flows that will help you kick-start your transformation. It contains flows that set the migration scope, transform the metadata, and handle long name and paths. Since no migration is the same, these flows will have to be adjusted based on the determined migration rules.

Flows

Transformation (1. Structure Mapping)

note

Warning: this flow will overwrite the target field! Before running this flow, make sure the source.ancestors have been calculated.

This flow reads an Excel workbook containing the mapping of source folders to locations in the target system, also called a structure mapping. The flow will first reset the migration and set migration.migrate to false for CONTAINER and RECORD objects. Furthermore, the source object will be copied to the target object without the source.properties. Afterwards, each row in the mapping will be used to set migration.migrate to true for the mentioned objects. The Excel column values will be saved on all the mapped objects in source.properties.mapping.

An example of the structure mapping is shipped with the accelerator (Structure mapping.xlsx). The columns in this Excel file are:

• *Xillio ID: Refers to the _id of the folder that is to be migrated.
• Source ID: Refers to the source.id of the folder that is to be migrated.
• Source Name: Refers to the source.name.systemName of the folder that is to be migrated.
• Source Path: Refers to the source.hierarchies[0] of the folder that is to be migrated.
• Only contents: When set to TRUE the folder and its contents are migrated, otherwise only its contents.
• Target ID: Refers to the identifier of the already existing container in the target system.
• Target Name: Refers to the name of the already existing container in the target system.
• Target Path: Refers to the path of the already existing container in the target system.
• Target Type: Refers to the content type of the already existing container in the target system.

Any metadata that has to be set on all the contents that are migrated can be set in additional columns in this Excel sheet. In the provided example, a metadata field Branch has been added.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

structureMappingPath

The path to the Excel workbook containing the structure mapping. The sheet containing the mapping should be named Structure Mapping.

Transformation (2. Exclude Content)

After setting the scope of the migration, additional rules for excluding content are configured here. As an example, this flow excludes configured content types as well as folders and their children based on configured identifiers.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

excludedContentTypes

A list of content types (source.contentType.systemName) that are to be excluded from the migration.

Example: ["Financial Document", "HR Document"]

excludedIds

A list of identifiers (source.id) that are to be excluded from the migration. When the identifier references a CONTAINER, that object and all its children will be excluded.

Example: ["0b0007c280006115", "090007c28000a762"]

Transformation (3. Update Migration Flags)

Now that the full migration scope has been set, this flow will retrieve all excluded CONTAINER and RECORD objects and set migration.migrate to false for their non-current versions. Furthermore, all their related BINARY and AUDITLOG objects are also excluded.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

Transformation (4. Metadata Mapping)

This flow reads an Excel workbook containing the content type mapping and field mapping. For all objects that are to be migrated, these mappings will be applied to set the content type and their metadata fields. Two sheets are mandatory: Content Type Mapping and Field Mapping. An example of these mappings is shipped with the accelerator (Content type & Field mapping.xlsx).

The Content Type Mapping sheet is used to transform the source content type to a target content type. The columns in this sheet are:

• *Source SystemName: Refers to the source.contentType.systemName of the object.
• Source DisplayName: Refers to the source.contentType.displayName of the object.
• Target SystemName: Refers to the target content type's system name of the object and is stored in target.contentType.systemName. When left empty, the display name is used.
• Target DisplayName: Refers to the target content type's display name of the object and is stored in target.contentType.displayName.
• Comments: Optional column to insert remarks.

The Field Mapping sheet is used to transform the properties (fields) that are available on the target content type. The columns in this sheet are:

• *Source Content Types SystemName: Refers to the source.contentType.systemName of the objects for which this mapping has to be applied. Values in here should be comma separated.

• Source Content Types DisplayName: Optional column containing the source.contentType.displayName of the objects for which this rule has to be applied.

• Source DisplayName: Optional column with the display name of the source property to be mapped.

• Source Content Store Path: The location of the property in the object, for example: source.properties.category.

• *Target SystemName: The system name of the target property that is mapped to.

• Target DisplayName: The display name of the target property that is mapped to.

• Target Content Store Path: The location to store the property in the content store object, for example: target.properties.category. When left blank, it will be stored in target.properties with the name specified in the Target SystemName columns.

• Target Type: The type of the target property.

• Rule: Optional column for the rule that has to be applied. Supported values are: sheet and fixed. A sheet rule references another sheet in the Excel workbook for a value mapping, and a fixed rule indicates that a fixed value should be used (specified in column Parameter). Additional rules can be added in the code component with id illf34cng and note map object metadata at the line with comment ADD CUSTOM RULES HERE.

• Parameter: The parameter for the rule that has to be applied. When the rule is set to sheet the parameter indicates the name of the sheet. In that sheet there should be a mapping from a source value to a target value. Required columns are:

  • *Source: value found in the source for the specified mapped field.
  • Target: target value to be set.

  In the provided example workbook there is a category rule and corresponding sheet.

• Max Length: The maximum string length of the mapped value. When it exceeds this value, an error is thrown by the flow.

• Format: Optional column that specifies a value conversion. Supported values are: string and toIsoDate.

• Comments: Optional column to insert remarks.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

contentTypeFieldMappingPath

The path to the Excel workbook containing the content type and field mapping. There should be two sheets: Content Type Mapping and Field Mapping.

Transformation (5. Transform Binaries)

In many systems, such as SharePoint Online, each RECORD object should have a BINARY associated with it. Furthermore, missing or zero-byte files can causes issues. This flow sets a dummy file for these BINARY objects so that the RECORD itself can still be migrated.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

dummyFilePath

The path to the dummy file that has to be used. This path will be set in target.externalReference on the BINARY object.

Transformation (6. Principal Mapping)

This flow automatically tries to map the source.created and source.lastModified principals based on their email address and is to be used in SharePoint Online migrations. When the target is not SharePoint Online, use a mapping sheet instead (not supported by this flow). For ideas on building such a flow, please check the Transformation (7. Permission Mapping) flow.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

mongoSPOConnection

The Mongo connection string to connect to containing the exported SharePoint Online PRINCIPAL objects.

source

The name of the source system. Currently only OpenText is supported.

fallbackUserSystemName

The source.id value of a SharePoint Online PRINCIPAL object to be used as a fallback when the user could not be mapped.

fallbackUserDisplayName

The source.name.displayName value of a SharePoint Online PRINCIPAL object to be used as a fallback when the user could not be mapped.

Transformation (7. Permission Mapping)

This flow maps the principals and permissions in ACL objects using an Excel workbook. Two sheets are mandatory: Principal Mapping and Permission Mapping. An example of these mappings is shipped with the accelerator (Permission mapping.xlsx).

The Principal Mapping sheet is used to transform the principals on the ACL object. The columns in this sheet are:

• *Source SystemName: Refers to the source.principals[].systemName of the principal.
• Source DisplayName: Refers to the source.principals[].displayName of the principal.
• Target SystemName: Refers to the system name of the target principal.
• Target DisplayName: Refers to the display name of the target principal.

The Permissions Mapping sheet is used to transform the principals on the ACL object. Only one permission will be set. The columns in this sheet are:

• *Source: Refers to the name of the permission in source.permissions.
• `Target: Refers to the name of the target permission.
• Priority: When there are multiple permissions, the priority determines which one is used. A lower value means higher priority here.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.

permissionMappingPath

The path to the Excel workbook containing the principal and permission mappings. There should be two sheets: Principal Mapping and Permission Mapping.

Transformation (8. Long Name & Path Restructuring)

In certain systems there are limitations on the maximum number of characters an object name and/or path can have. This flow is mostly tailored towards SharePoint Online migrations and does the following:

• Shortens object names to 255 characters
• Shortens object names that exceed the 400 characters in the hierarchy

Any object that still exceeds the 400 characters in the hierarchy field will be moved to a Migration Exceptions folder created directly under the ROOT of the object.

Settings

mongoConnection

The Mongo connection string including the database name to connect to.