Migration Project Playbook

​​

​

​

​

​​

Document Properties

Revision Details

​​Table of Contents

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​​

Objective

This document describes how to perform a standardized, flexible, content migration between two information management systems. The content to migrate can be documents, files, cases, records, digital assets, or web content.

It focuses on practical and technical steps, using software from Xillio (licensed), Microsoft, and MongoDB. 

1. Migration Engineer Skills and Knowledge

Even though Xillio aims to make content migrations easy, a considerate number of prior skills and knowledge are still needed to make a professional migration project a success. We tried to list all of them here below. When running a test migration with Xill4 for the first time, not all of these are immediately essential.

1.1 Technical Fundamentals

1. Understanding of source and target systems or repositories (e.g., SharePoint, Documentum, file shares).
2. Comfortable with configuration files (e.g., JSON or XML/YML for settings).
3. Scripting or programming experience in at least one language relevant for automation (PowerShell, JavaScript).
4. Understanding and experience with NoSQL database, MongoDB.
5. Developer mindset ability to solve problems, strong reasoning, and learning.
6. Knowledge and understanding of the APIs of the source and target systems.
7. In case of a database extraction or load, knowledge of that type of database and its query language.
8. Basic understanding of networking, firewalls, VPN.

1.2 Data Mapping & Metadata Skills

1. Read, interpret, and document metadata schemas.
2. Define mapping logic from source to target, including content types and fields (e.g., SharePoint columns).
3. Understand how metadata affects migration decisions, filters, and downstream usage.

1.3 ETL & Job Processing Understanding

1. Understand core ETL concepts (extract, transform, load).
2. Be comfortable working with batch processing, job runs, and optimization.
3. Have experience with rule-based transformations (renaming, restructuring, cleanup).

1.4 Content Analysis & Scope definition

1. Ability to analyse content repositories and identify what needs to be migrated, cleaned, archived, or transformed.

1.5 Attention to Data Quality

1. Analyze content repositories and identify what is in-scope, out-of-scope, redundant, duplicated, or archived.
2. Evaluate potential risks and complexities based on the structure and metadata of the source system.

1.6 Documentation Discipline

1. Accurately document configuration decisions, mapping logic, and migration rules.
2. Create design documents and transformation specifications suitable for internal approvals.

1.7 Data Quality Assurance

1. Plan and execute test runs.
2. Validate outcomes such as metadata integrity, permissions, document fidelity, version histories, and expected structure.

1.8 Error Identification & Troubleshooting Mindset

1. Ability to read logs and error messages & to form hypotheses and trace root causes logically.
2. Curiosity, independence, and a developer/problem-solving mindset: 
   “Try, investigate, adjust, retry before escalating.”

1.9 Training Experience

1. Xill4 Migration Associate certification (the course can be taken at ://xillio.talentlms.com).
2. Knowledge and experience of MongoDB setup, usage & aggregations.

2.0 Data Quality Awareness

1. Recognize inconsistencies, anomalies, duplicates, and invalid structures in content.
2. Document data quality issues and translate them into migration rules or preprocessing tasks.
3. Migration Workplace Setup

This section describes what is needed to set up a digital workplace with all the tools required to automate a content migration.

2.1 Server Configuration

Migration infrastructure and access to the source and target systems are needed before a migration project can begin. The infrastructure and access needed can vary depending on the source, the target, and the size of the migration. The attached hardware and access documentation provides a comprehensive overview of what is needed per system. In a nutshell, a dedicated migration server should be set up that has access to the API or database and file storage of the source system and the target system, preferably with a separate database server. Take extra care when getting proper access if SharePoint is involved, because this system needs more configuration than any other system.

See attachment ‘Xillio access hardware requirements.docx’ for more detailed instructions.

2.2 Software Installation & Configuration

Below is a list of software and configuration instructions. You will need a license key to access certain areas.

1. MongoDB à Download page à https://www.mongodb.com/try/download/community:
   1. Download and install Mongo DB Community Edition from the link above.
   2. Install MongoDB Compass as part of MongoDB Community Edition
   3. Set up MongoDB Authentication à after completing the steps a. and b. follow the instructions here https://docs.xill.io/xill4/content-store/authentication/.
   4. Download MongoDB Database Tools from the link above.
2. Xill4:
   1. Download & unzip the latest release from https://xillio.community/products.

Figure 1: Xill4 window view on the Community Products page.

1. Configure variables à Installation Guide | Xill4:
   1. XILL4_DATABASE_CONNECTION_STRING, MongoDB database where the Xill4 logs will be stored.
   2. XILL4_ENVIRONMENT_SECRET, a secret used to encrypt and decrypt secrets stored in the environment editor.
   3. XILL4_LICENSE_KEY, a key used to activate the Xill4 license key.
   4. XILL4_PROJECT_PATH, a location where the Xill4 projects will be stored.
   5. XILL4_WORKDIRS, list of paths where the Xill4 can read from and write to files.

1. The required variables can be set as Windows system environment variables.

Figure 2: Windows system environment editor view with an example of the Xill4 environment variables

1. The required variables can also be added to the ‘config.yml’ located in the Xill4 installation directory. For more information please see: Updating your Xill4 configuration | Xill4. This method supports currently only a limited set of variables and is not sufficient by itself.

Figure 3: Contents of the 'config.yml' file (on the left) and its location in the Xill4 repository (on the right).

1. Install and/or run Xill4:
   1. Install and run as a service à run Command Prompt as administrator, navigate to the Xill4 installation directory, type install.bat and press Enter. To uninstall the service, type uninstall.bat and press Enter.
   2. Or run it as an application à run Command Prompt as administrator, navigate to the Xill4 installation directory, type xill4.exe and press Enter.
2. Validate if Xill4 is running by opening the localhost:8000 in a browser (preferred: Edge). If it fails to load, then run the program in a Command Prompt terminal and read the error message displayed there. Send an e-mail to support@xillio.com if you are unable to resolve the issue by yourself.
3. Insights (optional):
4. Xillio offers use of standardized set of dashboards that are populated with the Insights Accelerator à Insights | Xill4.
5. Install and configure the Elasticsearch and Kibana applications; both should be versions 8.8.1. How to download and install these applications is described in the documentation mentioned above.
6. Connection Checker (optional):
7. Recommended when the project involves SharePoint Online extraction and/or load.
8. Download & unzip the latest release from https://xillio.community/products page, under Connection Checker click on the Release button.
9. Read the documentation on how to run it, under Connection Checker, click on the Docs button.

Figure 4: A Connection Checker window view on the Community Products page. Highlighting the options B. (release button) and C. (docs button).

1. Other (recommended):
   1. GitHub Desktop, used for backing up our progress.
   2. LibreOffice (if there is no Microsoft Office installed) used for reporting.
   3. Notepad++ (and/or VS Code), for editing files in different formats (XML, JS, JSON, etc.).
   4. PowerShell 7 in combination with OpenSSL and PnP.PowerShell module.

2.3 Create a GitHub Repository (recommended)

If you use version control or collaborate with others on the migration project, it is recommended to create a repository in a developer platform like GitHub and regularly commit changes during the development process made in the Xill4 Project.

Keep in mind that you should store sensitive configuration in the Environment Editor, which encrypts the values. Do not save the sensitive credentials or passwords in the flow variables, as these values are not encrypted and will be visible in the repository to anyone with access.

Figure 5: Xill4 application in the browser with the Environment Editor button highlighted

2.4 Download Xill4 Migration Accelerator

When migrating to SharePoint Online, Xillio offers an uncomplicated way to download all of the necessary accelerators to execute the migration through Migration Accelerator. If you have another target system, and that system also has a target accelerator (https://xillio.community/accelerators), email support@xillio.com to ask if the system can be added as target option in Migration Accelerator. For now, proceed to 2.5 to download accelerator modules individually.

To download a Migration Accelerator, click the button on the Xillio Community page under Xill4.

Figure 6: Xill4 window view on the Community Products page. Highlighting the Migration Accelerator button.

The navigation has the following few steps:

1. Choose any of the source systems for which we already have a productized connector within Xill4. If you are missing a source connector, please contact the support team.
2. Choose the target system. At the moment of this writing, the Migration Accelerator only supports SharePoint Online Target connector.
3. Choose configuration options:
   1. Report Generation Flow à when enabled, it will include a framework accelerator that generates reports which are useful during a migration à Reports | Xill4
   2. Insights Analysis Flow à when enabled, it will include a framework accelerator that analyses and ingests data into the Insights dashboards, mentioned in the previous chapter. Download the Calculate Hash flow manually from the list of Xill4 Accelerators as it is currently not included in the package.
   3. Advanced MongoDB Configuration à when TLS is enabled, it allows self-signed certificates through advanced MongoDB options.
4. Confirm and download the Migration Accelerator package, and unzip it.

2.5 Download Xill4 Accelerators

Skip this step if you finished 2.4. If the source or target connect is not available in Xill4 Migration Accelerator, you will need to download the accelerators individually à https://xillio.community/accelerators.

We recommend following these steps:

1. Change 'All Types' to Source and choose a source connector 
   1. Example: ‘File System’, used to extract data from a local network drive.
2. Change 'All Types' to Target if you are planning to load the data into a new system. 
   1. Example: ‘OpenText CS Target’
3. Change 'All Types' to Framework to pick flows that do necessary transformations on the content store:
   1. Calculate Ancestors, populates source.ancestors (a list of ‘source.id’ values of the folders located higher up in the source structure)
   2. Transformation contains multiple transformation flows that will help you kick-start your transformation. Sets properties, which will be displayed in or used by the target system.
   3. Calculate hierarchies, used to calculate the source or target hierarchies for container and record documents. After the Transformation we should choose the ‘target’ option, which will allow to calculate the target hierarchies by taking the root documents as a starting point. We do not need this flow when using SharePoint Online Target connector, as this accelerator already does it.
   4. Deduplicates names, after the Transformation, it is common that objects are restructured and moved into a new target location. This can cause objects with the same name ending up in the same location. This accelerator adds a unique suffix to these names and prevents duplication errors.
   5. Remove invalid characters, allows for a replacement of invalid, or unwanted characters, usually prohibited by the target system.
   6. Reports, contains multiple report flows to support the migration process.
   7. Extraction Report creates a report of the extracted CONTAINER and RECORD documents.
4. Choose the following framework accelerators if you wish to visualize the metadata with Insights:
   1. Calculate Hash, calculates the hash value for the binary documents with a matching byte size, used for duplicates analysis.
   2. Insights, contains a bundle of flows that analyse the metadata and ingest the analysed information to the Insights dashboards

Note:

When choosing an accelerator, keep in mind that Xillio only provides support for accelerator that has been productized, meaning that the author is Xillio (see screenshot below). These accelerators are the preferred choice over the accelerators where the author is Community, which means that accelerator has been created by one of the users of Xill4.

2.6 Setup Xill4 Project

Once Xill4 is running and the accelerators are downloaded we are ready to create a project in Xill4. 

2.6.1 Create a New Project

We recommend following these steps when creating a Xill4 Project:

1. Open (Edge) browser and navigate to http://localhost:8000.
2. In the upper left corner of the project view, click on the ‘Select Project’ button, and choose from the dropdown menu the ‘+ New Project’ button.
3. In the ‘New Project’ window, click on ‘Choose Project Files’ highlighted text.
4. Navigate to the downloaded Xill4 Accelerators or Xill4 Migration Accelerator’s package.
5. Select all .json files. In case of Xill4 Migration Accelerator option, those are the following files:
   1. File ‘project.json’ à this will add the project name.
   2. File ‘environment.json’ à this will add a set of secrets used in the flows to the Environment Editor.
   3. Contents of the ‘flows’ folder à all the necessary flow to kick start the migration process.

Figure 7: 'New Project' window view after completing steps ‘5a.’ to ‘5c.’, highlighting boxes shows the results of each step.

1. If the project has no name yet, give it a name

Figure 8: 'New Project' window after completing steps ‘6a.’ and ‘6b.’.

1. Select ‘Create Project’

2.6.2 Configure the Project’s View

After creating the Xill4 Project, you will see vertical lanes. These lanes should contain flows related to a specific migration process. We recommend to re-arrange the flows in the following way:

1. Extract lane contains flows from the source connectors and Calculate Ancestors accelerator.
2. Transform lane contains flows from the Transformation, Remove invalid characters and Deduplicate names farmwork accelerators.
3. Load lane contains flows from the target connectors. 
4. Insights lane: contains flows from the Insights and Calculate Hash framework accelerators.
5. Reports lane: contains flows from the Reports framework accelerator.
6. Tips: change the flow names to rearrange them in the lane. Change the flow reference to move them to a new lane (or first create a new lane and drag-and-drop the flow to this lane).

Figure 9: The rearranged Project View from the File Share to SharePoint Online Migration Accelerator.

2.6.3 Configure the Environment Editor

After creating a new project, we need to add all sensitive variables which are used to connect to the database, source, and target systems to the Environment Editor*. This ensure that these secrets will be encrypted.

If you have setup the Xill4 Project by using the Migration Accelerator, all variables have been already added automatically to the Environment Editor. Follow these steps to configure the Environment Editor:

1. Open the Environment Editor from the project view by clicking on the icon: .
2. In the left side of the Environment Editor window, select the ‘environment’ instead of the ‘default’. This environment contains all the secrets which has been automatically added by the Migration Accelerator installation (if applicable). 
   

Figure 10: A screenshot of the new environment added by default with Migration Accelerator.

1. Click on each variable or secret and change their values accordingly. After updating the value click on the green checkmark button 
   

Figure 11: The Environment Editor where ‘mongo_connection' key's value is being updated.

1. After updating all the values, save the configuration by selecting the ‘Save’ button at the bottom of the window.

If you have added a Xill4 Accelerator(s) manually that was/were not included in the Xill4 Migration Accelerator, or you have used the Xill4 Accelerators option, you will need to add variables and secrets manually to the Environment Editor. Follow these steps to configure the Environment Editor:

1. Open the Environment Editor from the project view by clicking on the icon: .
2. Open the Project View in another tab. Split the tabs, keep on the left side of the screen the Environment Editor tab, and on the right side of the screen the Project View tab.
3. In the Project. View, click on one of the flows that has not been configured yet, such as Calculate Hash. 
4. Open the flow variables and view the value of the mongoConnection variable. By default, it points to the Windows system environment variable. We want it instead to point to the Environment Editor.
5. In the Environment Editor window, create a new environment by clicking on ‘+ Add Environment’ button. Type in a desired name, for example ‘demo’ and save it by pressing green checkmark.

 
 
Figure 11: The Environment Editor with a new 'demo' environment added (left) and the Calculate Hash flow variables with the value of 'mongoConnection' key displayed (right).

1. Add a new secret to the new environment. Keep in mind that the secret in the Environment Editor must be unique in relation to all of the flows. We recommend starting all the mongo connection strings with mongo_connection. In our case this is enough, as it is the first connection string to the database. 
2. Paste the value of the flow variable mongoConnection as the value of the secret mongo_connection. 
3. Change the value of the flow variable and point it to the key to the new secret.
4. Select the green checkmark and press ‘Save’ buttons in both widows, or press ctrl+Enter multiple times until the window and popups are closed.

Figure 12: The Environment Editor with a new 'mongo_connection' secret added (left) and the Calculate Hash flow variables with the value of 'mongoConnection' key modified to the key to the correlating secret (right).

1. Repeat these steps for all the flows and their variables which should be kept secret. Keep in mind that multiple flows can share the same flow variables, such as mongoConnection. If the related secret has already been added to the Environment Editor, you only must change the value of the flow variable, as mentioned in step 8.

2.6.4 Documentation Resources

HelloWorld! | Xill4 à step-by-step tutorial on building your first flow using Xill4.

Projects | Xill4 à documentation of the features related to the Xill4 Project.

Environment Editor | Xill4 à documentation of the features related to Environment Editor.

1. Extraction

After setting up our migration workplace, it is time to perform the first extraction. To complete this phase, we need to run the flows from Extract and Reports lanes (Figure 6) in sequence from top to bottom.

NOTE: if you have SharePoint Online as a target system, but not as a source system, you will still need a source accelerator for SPO because the target accelerator needs an extraction of the target. However, we don't consider that part of the Extraction phase, because it has nothing to do with the source content, so in this scenario you can skip the SPO source flow.

3.1 Perform the Extraction

The exact scope of the migration is usually not known yet, so we extract everything first. The goal of this step is to have the Content Store* populated with the (meta)data of the source system(s). When extracting more than one system, it is recommended to use a separate database for each system. 

Figure 13: Example of two different environment names, each dedicated to a separate source system.

Start the extraction by running the extraction flow(s). Once a flow is running you will see the pending message count, on the bottom of the flow, go up to 1 or higher. Most flows have count components too for tracking the progress. In the Console* you will be able to see log messages confirming the completion of specific extraction milestones, for example ‘Started’. When the extraction is done, the count of the pending message will go back down to 0. 

Figure 14: Running ‘File System’ flow, highlighting the number of 'Pending' messages with the logs displayed in the 'Console' (bottom).

3.2 Validate the Extraction

After the extraction is finished, all the content to migrate should be in the Content Store. The Content Store can be viewed and queried in MongoDB Compass or Studio 3T. Studio 3T is only free for personal use, not for commercial use, but it is significantly more powerful and, in some cases, also easier to use. A MongoDB interface is needed in (many) next steps of the migration process.

If you are not yet familiar with querying a MongoDB databas, you could start here https://www.mongodb.com/docs/compass/query/filter. 

The completeness of the extraction needs to be checked. This means two things: 

1. The number of objects in the source system should match the number of objects (of the same type) in the Content Store. It depends on the source system and the way it was used what types of objects can be counted (for example files, document registrations, cases, folders).
2. All the variety/complexity that must be migrated should be in the Content Store. This can mean metadata fields, content types, people, addresses, permissions, etc. which vary per system and the way it was used.

A migration engineer does not automatically know how the system was used, so they will need to ask the key users what content is in their system and how it is structured. Only when the migration engineer understands that, by taking a good look at the Content Store, they can be confident that an extraction has completed successfully.

3.3 Calculate Ancestors

Most of the source connectors do not immediately store the ancestors on the documents in the Content Store. The ancestors are stored as a list in the field source.ancestors in the RECORD and CONTAINER content schemas of the Content Store. This list contains values of the source.id field of the documents above in the structure. If the field source.ancestors is not populated anywhere after the extraction, run the Calculate Ancestors accelerator. This field is needed to easily implement Structure Mapping rules.

3.4 Documentation Resources

Content Store | Xill4 à documentation on the Xill4 database concept for storing any type of content targeting migrations.

Flows | Xill4 à documentation of the Console.

1. Analysis & Design Migration Rules (mapping)

4.1 Standard Migration Accelerator Extraction Reports

Following the recommended Migration Workplace Setup steps will provide us with a bundle of flows that generate reports, listed below:

1. Extraction
2. Container Structure
3. Content Types Count
4. Metadata Field
5. Content Type Fields SPO (used when migrating to SPO)
6. Content Types SPO (used when migrating to SPO)

Figure 15: Default report flows.

For more information, visit Extraction report | Xill4 & Reports | Xill4 documentation.

Run these flows to get a basic overview of all content in the source system and unique content types and fields in the target system.

If SharePoint Online is the target system, you can use the same flows to report on the target system (metadata structure), if the SPO source accelerator is run (on the target system) first.

These reporting flows help to analyse the content we’re working with. The analysis phase gives input for the design phase, determining the desired result of the production migration. But if migration rules are already known, further analysis can be skipped. And when using Xill4 Migration Accelerator, you might want to jump forward to the transformation phase now (chapter 5). Once a test migration is done, it is still possible to revisit previous phases. 

4.2 More Analysis Reports (background info for more complex migrations)

After standard analysis reports, try to find out what kind of (other) analysis the project needs, in contact with the key users. Most projects need some custom reports. The goal of the analysis and reports is to give the key users all information they need to make decisions for a migration design (a set of migration rules).

The source system and the target system in a migration project are never the same. They have their own way of structuring the content. Even if they are very much alike, a migration is a good opportunity to clean or enrich content in the process. A migration always needs migration rules. A mapping is a type of migration rule. The amount of possible migration rules is infinite. Every project is different. There are some types of migration rules that are needed in most projects though. For complex migrations, it is needed to write down very specifically how to convert the source content so it will fit in the target system. 

4.3 Design Document (background info for more complex migrations)

This subchapter contains guidelines for how to compose a migration design document. Although this is important for many content migrations, kickstarting a migration can be done by skipping to the Transformation, chapter 5.

4.3.1 Scope

If a system is used for many years, chances are that part of the content is no longer needed. The scope should be defined so only the content that is needed will migrate. There is no fixed format for this. The migration design document should clearly describe what exactly is in scope. If the migration is cut into multiple parts, the scope should be defined for every part.

4.3.2 Structure Mapping

The most common type of migration rules is based on the structure of the source and target systems. Each rule describes clearly where each source root repository will be migrated into the target system. This happens especially when the migration is cut into multiple parts. More information regarding this topic will be explained in the chapter 5.3. In the Migration Design document, we have to clearly describe all the rules based on the structure mapping. These rules should be based on source and target repositories that already exist. If the target system is not setup yet, then we should also mention it, including the expected date where the implementation of it will be ready.

4.3.3 Field Mapping

This is the next most common type of migration rules. A 'field' is an elementary piece of metadata, like a title or creation date. In the Content Store, source fields are stored in source.properties. Some of them might not be relevant, others need to be migrated to a field (or elsewhere) in the target system. A field mapping describes exactly what will happen for each field. This can be done roughly two ways. Either you describe a destination for each source field, or you describe how to fill each target field. Both options are fine, but usually one of the two is a bit easier to do than the other. In the next paragraph we will assume that we start mapping from the source fields.

The field mapping is described in a table in a spreadsheet file. The first column has one source field name per row. Usually in the analysis phase of a migration project, we already make an overview of all source fields and how often they are filled, this supports us in creating the field mapping (see chapter 4.1 Metadata Fields report). The second column has the (technical) name of the target field where the values must be migrated to. With two columns, the basics are covered, but most projects need more. It can be useful or needed to add these columns to the field mapping file too:

• Technical field name and display field name
• Field type (number, text, date, choice, boolean)
• Max length
• Migrate yes/no
• Migration rules

The name, type and length can be described for both source and target fields. Including those in the mapping file makes it easy to check if the content will fit. If you do not, you will get errors during a test migration if the content does not fit.

4.3.4 Content Types

Most systems have a form of content types, document types, or case types. If the source and target system have content types, they also need to be mapped from source type to target type. A content type is usually coupled to a specific set of fields. If the mapping rules for some fields are different between different content types, the project need a field mapping for every content type (example: field1 of content type A has a different mapping rule than field1 of content type B).

4.3.5 Field-Level Rules (value mapping)

Migration rules on a field level can be anything. For instance, if the field is mandatory, but not always filled in the source system, you need a fallback value. And if a target field has a choice or lookup type, usually a value mapping is needed because some old values are not allowed in the new system anymore. On the mapping sheet, in the row of that field, you can refer to a separate file or a different sheet in the same file for the value mapping. A value mapping can be a simple two-column table; one column for the source value and one for the target value. 

4.3.6 How to Map Files in the Transformation?

If a mapping sheet is a simple two-column table, it is good practise to read this file automatically with Xill4. It can then be easily changed and again copied to the migration server. Mapping sheets with migration rules that are less straightforward should not be automatically read but used as a reference to build the transformation scripts/flows.

4.3.7 Templates & attachments

The overview of mappings and other migration rules (like scope and possibly enrichment and cleaning) will be written in a migration design document. The mappings themselves are normally stored in separate Excel files, referenced by the migration design document.

See attachments examples: 

• ‘Migration Design Document template.dotx’ 

‘Mapping file template.docx’

1. Transformation

Transformation is the T in the ETL process. The Extraction is done, but the Load cannot start yet. This is because choices need to be made on how to make the source content fit into the target system. And the Content Store needs to be updated to reflect each of those choices exactly. 

In other words, the migration rules need to be configured and translated into the database with transformation flows. All the transformed metadata values and structure information will be stored in the target nodes the items selected for migration in the Content Store. The target information will be used by the target connector during the Load phase.

Transformation is the most technically complex, flexible, and diverse process of the phases. But the good news is that Xill4’s standardized transformation flows will support us in making this phase as smooth as possible.

Again, this section will be focused primarily on usage of the Xill4 Migration Accelerator. If there is no standard Migration Accelerator available for the relevant systems or the required functionality, some parts of the transformation will not have an accelerator ready and therefore project-specific flows or other solutions will have to be built. The possibilities are endless.

To make this process less daunting, it helps to do a basic test load with standard flows first on a small test batch. Without worrying about the needed migration rules. When that works, implement the necessary transformation rules and test again. Repeat this process until the desired result is achieved. 

To complete this phase, we need to run all flows from the Transform lane (Figure 6) in sequence from top to bottom. However, as a prerequisite we need to configure the mapping templates and the flows which are related to this phase. Complete all steps of chapter 5 to achieve that. 

5.1 SharePoint Online Target extraction

The full documentation of the SPO extraction accelerator can be found at https://docs.xill.io/xill4/accelerators/source/sharepoint-online. 

If the migration project has SharePoint Online (SPO) as target system, an extraction of that system is required before starting the mapping. It is important that the target system’s design and implementation are finished before running this step. 

Run the SharePoint Online source connector flows to complete the extraction, by following these steps:

1. Run the SharePoint Online Source (1. Content), this flow extracts the structure, users, groups and lists that can be migrated to or mapped.
2. Run the SharePoint Online Source (2. Content Types & Term Store), this flow extracts the content types, terms, and term sets of the extract lists in the previous step.
3. Run the SharePoint Online Source (3. Permission Levels), this flow is optional and extracts all permissions of each site.

Figure 16: SharePoint Online source connector flows.

1. Create a structure report of the SPO. To do that clone the Container Structure flow and change the name to Container Structure SPO. This flow was already used to create a report of the source system’s container structure. 
2. Open the flow and modify the flow variables. Change the reportPath by adding SPO in the name and change the value of mongoConnection key to use the same value as in the SharePoint Online source connector flows in the steps 1-3, which is %mongo_connection_target%. 
3. Open the configuration of the Excel Writer component and change the path by modifying the name to Container Structure SPO.xlsx.
4. Create a SharePoint Online container structure report by running this flow.

Figure 12: A two-part screenshot, visualizing the new 'Container Structure SPO' flow and its flow variables examples.

1. Open the created SPO report and check if it has the root folder(s) that we need to load the content to. If any needed folder is in the ‘Remainder levels’ columns of the report, recreate this report after setting the flow variable maxLevels to a higher value.
2. The extraction of the SPO is complete, we are ready to proceed to the next phase. Keep in mind that you will have to execute these steps again if there are any changes performed in the target locations that have impact on our mapping. We recommend to always repeat this step before the loading of the content is performed. 

After the source extraction and the target extraction are done, the mapping templates can be created.

5.2 Default Mapping Templates

Following the recommended Migration Workplace Setup approach you will be provided with a default Excel-files mapping templates. Located either in the Migration Accelerator package sheets folder, or in the Transformation accelerator’s folder. See the list below:

1. Structure mapping.xlsx à read Transformation | Structure Mapping | Xill4.
2. Content type & Field mapping.xlsx à read Transformation | Metadata Mapping | Xill4.
3. Permission mapping.xslx à read Transformation | Permission Mapping | Xill4. 
   

Figure 13: The templates in the 'sheets' folder, in the Migration Accelerator package.

Figure 14: The template reports in the 'transformation' folder.

1. In the next chapters we will refer to these templates and how use them.

5.3 Multiple Parents

In some source systems it is possible that RECORD documents have multiple parents, meaning that they can exist in multiple locations. The Transformation (1a. Multiple Parents) flow helps us to translate this in the Content Store by creating a copy of RECORD documents for each parent location, these documents are linked to the original RECORD document by referencing its source.id in the source.link field. See Transformation | Multiple Parents | Xill4 for more information.

This flow can be run without any configuration.

5.4 Structure Mapping

The structure mapping is set of rules that will define the new structure in the target location. This step allows us to specify the source root repositories which can be mapped to the target root repositories in three main different ways:

1. One-to-One à a source root repository will be mapped to a target root repository.
2. Many-to-Many à children’s repositories of the source root repository will be mapped into different target root repositories.
3. Many-to-One à multiple root repositories will be mapped into a single target root repository.

There are other customizations possible within this phase, however they may not be yet implemented in this template. If that is the case, please feel free to implement this yourself or contact the support team for advice on how to approach your use case.

5.4.1 Configuration

The structure mapping process is done by filling in the Structure mapping.xlsx document, listed the previous chapter, with the information reported by the Container Structure and Container Structure SPO flows and running the Transformation (1b. Structure Mapping) flow of the Transformation accelerator.

Follow these steps to update the Structure mapping.xlsx document:

1. Open the following reports: Structure mapping.xlsx, Container Structure.xlsx and Container Structure SPO.xlsx.

Figure 15: Columns A-E of the 'Structure mapping.xlsx' file.

Figure 16: Columns F-J of the 'Structure mapping.xlsx' file.

Figure 17: Example of the 'Structure Container.xlsx' report.

Figure 18: Example of the 'Container Structure SPO.xlsx' report.

1. The Structure mapping.xlsx comes with 3 rows of example values. These indicate in which format we should add new column values. Let us go through the steps of adding a new row, where we map One-to-One source and target root repositories.
2. The first five columns (A-E) of the structure mapping should be filled in based on the Container Structure.xlsx report (Figure 16). 
3. The last five columns (F-J) should be filled in based on the Container Structure SPO.xlsx report (Figure 17). 
4. Below is a table of the columns names, columns example values and descriptions of where the values are coming from, based on the screenshots above (Figure 16 & 17).

1. The result of the steps above will look like this:

Figure 19: A screenshot of a new structure mapping rule, with the links of where the values are coming from.

1. We have created first structure mapping rule, let us see how this rule is being implemented and processed by Xill4 in the next chapter.

5.4.2 Processing

The Transformation (1b. Structure Mapping) flow processes the structure mapping file in the following steps:

1. Before the mapping is read the transformation progress is being reset in the Reset migration group. If you have run a transformation previously, this step will undo it. This flow resets the following fields:
   1. The field migration.migrate is set to true for all documents of kind AUDITLOG and BINARY.
   2. The target objects are set to the source objects for all documents. This step resets any previously created transformations, additionally the target.properties are set to an empty object.
   3. The field migration.migrate is set to false for all documents of kind CONTAINER and RECORD.
2. The mapping is being read from the location specified in the structureMappingPath flow variable. The content of the file is loaded into the mappings collection of the Content Store by using the Load Mapping component (Load Mapping | Xill4). (Figure 21).
3. For each unique target root directory, a new ROOT document will be created (Figure 22).
4. All source documents that have been mapped to a ROOT document will be updated with its target.id value in the target.parentIds field. The source documents will also be updated with source.properties.mapping field, which will contain all values of the mapping rule (Figure 23).
5. Screenshots of the results in the Content Store: 
   

Figure 20: A screenshot of the mapping rule being stored in the Content Store’s ‘mappings’ collection.  
Each mapping rule will be stored as a separate document.  
 

Figure 21: A screenshot of the created ROOT document in the Content Store’s ‘documents’ collection.  
Based on the example mapping rule mentioned above, with the values highlighted.

Figure 22: A screenshot of a RECORD document in the Content Store's 'documents' collection.  
Highlighting added mapping properties and the updated 'target.parentIds' field with the  
'source.id' of the ROOT document from the ‘Figure 22’.

1. After the flow has finished without any error messages in the Console and we have verified that the content is mapped correctly, we can continue to the next phase of the Transformation.

5.5 Exclude Content

The structure mapping rules allows us to set the scope based on the structure of the content. By default, the Transformation (1c. Exclude Content) flow gives us the ability to exclude content based on the five additional filters, stored in the flow variables:

1. The value of the source.contentType.systemName field, all CONTAINER and RECORD documents with these content-type values will be excluded. Modify the excludedContentTypes value to an array of content types string values, example: [ “146”, “729” ].
2. The value of the source.id field, all CONTAINER and RECORD documents with this value either in the source.id or source.ancestors field will be excluded. Modify the excludedIds value to an array of source id string values, example: [ “2121212”, “12345678”].
3. Exclude the permissions from the scope of the migration if we don’t need to map them to the target system. Set the excludeACLs to true. 
4. Exclude the RECORD documents without a BINARY document relation. Modify the excludeRecordsWithoutBinary.
5. Exclude the RECORD documents with an empty BINARY document relation, meaning the file size is 0. Modify the excludeRecordsWithEmptyBinaries.

If there any other custom exclusion rules, we recommend adding them to this flow in a similar fashion. In case of doubt, contact the support team for guidance.

This flow can be run without any configuration.

5.6 Update Migration Flags

Now that the full migration scope has been set, the Transformation (1d. Update Migration Flags) flow will retrieve all excluded CONTAINER and RECORD objects and set migration.migrate field to false for their non-current versions. Furthermore, all their related BINARY and AUDITLOG objects will also be excluded.

This flow can be run without any configuration.

5.7 Transform Binaries

In systems such as SharePoint Online, each RECORD object must have a BINARY associated with it. Furthermore, missing or zero-byte files can cause issues. 

The Transformation (2. Transform Binaries) flow sets a dummy file for these BINARY documents so that the RECORD document can still be migrated. 

To achieve this, we must select or create a dummy file and use its location as the value of the dummyFilePath flow variable before running this flow.

Configure the flow variables and run the flow.

5.8 Metadata Mapping

The metadata mapping is set of rules that will be used to define the content type and metadata fields of the migrated objects in the target location. This step allows us to update, enrich and leave behind the source information by utilizing the Content type & Field mapping.xlsx mapping file, which consists of two mandatory sheets:

1. content type mapping à this sheet is used to map the source content-types to target content-types. See chapter 5.8.1 for more information.
2. field mapping à this sheet is used to map the source properties to target properties that are available on the mapped target content types. See chapter 5.8.2 for more information.

The Transformation (3a. Metadata Mapping) flow is responsible for reading the mapping from the location specified in the contentTypeFieldMappingPath flow variable. The content of the file is loaded into the mappings collection of the Content Store.

Configure the flow variable, complete this chapter (5.8), and then run the flow.

5.8.1 Content Type Mapping

By default, the content-type mapping supports only One-to-One mapping based on the source.contentType.systemName values. If we need to map the target content types based on a different source field, we will have to modify the content type mapping sheet and the Transformation (3a. Metadata Mapping) flow accordingly.

5.8.1.1 Configuration

The content-type mapping process is done by filling in the content-type mapping sheet of the Content type & Field mapping.xlsx document, with the information reported by the Content Types Count and Content Types SPO.

Follow these steps to update the content-type mapping sheet:

1. Open the following reports: Content type & Field mapping.xlsx (select content type mapping sheet), Content Type Count.xlsx, and Content Types SPO.xlsx.  
   The view could be something like this: 
   

Figure 23: A screenshot of the open reports 'Content type & Field mapping.xlsx' (top), 'Content Type Count.xlsx' (bottom-left) and 'Content Types SPO.xlsx' (bottom-right).

1. The content-type mapping sheet comes with 2 rows of example values, these indicate in which format we should add new column values. Let us go through the steps of adding a new row, where we map One-to-One source and target content types.
2. First two columns (A & B) of the content-type mapping should be filled in based on the Content Type Count.xlsx report. Keep in mind that these reports display all unique content-types that exist in the source system. To generate a list of only the unique content types of the documents that are selected for the migration follow these steps:
   1. Open Content Types Count flow.
   2. Open the configuration of the Mongo Query component and ensure that only the content types are extracted from the content selected for the migration. To achieve that add the following parameter: “migration.migrate”:true.
   3. Screenshot of the update query: 
      

Figure 24: A screenshot of the updated 'Mongo Query' component.

1. The columns C & D of the content-type mapping should be filled in based on the Content Types SPO.xlsx report. Make sure to choose the content types that are available in the chosen target root repository in the previous steps.
2. The column E contains any additional information that might be useful to use in the next phases.
3. Below is the list of columns, descriptions and example values in a table, based on the screenshot below (Figure 26):

1. The result of the steps above will look like this:

Figure 25: A screenshot of a new content-type mapping rule, with the links of where the values are coming from.

1. We have created first field mapping rule, to see how this rule is being implemented and processed by Xill4 go to the chapter 5.8.3 Processing.

5.8.2 Field Mapping

By default, the field mapping supports only One-to-One or One-to-Many mapping based on any source fields values. This means that for each source content type we can only map a given target field once. If we need to map the target fields based on another value then source content type, we will have to modify the field mapping sheet and the Transformation (3a. Metadata Mapping) flow accordingly.

5.8.2.1 Configuration

The field mapping process is done by filling in the field mapping sheet of the Content type & Field mapping.xlsx document, with the information reported by the Metadata Fields and Content Type Fields SPO.

Follow these steps to update the field mapping sheet:

1. Open the following reports: Content type & Field mapping.xlsx (select field mapping sheet), Metadata Fields.xlsx, and Content Type Fields SPO.xlsx.  
   The view could be something like this: 
    

Figure 26: A screenshot of the open reports 'Content type & Field mapping.xlsx' (top), 'Metadata Fields.xlsx' (bottom-left) and 'Content Type Fields SPO.xlsx' (bottom-right).

1. The field mapping sheet comes with 4 rows of example values; these indicate in which format we should add new column values. Let us go through the steps of adding a new row, where we map One-to-One source and target fields.
2. First columns A – D of the field mapping should be filled in based on the Metadata Fields.xlsx report. Keep in mind that this report by default only displays unique fields from the source.properties field in the Content Store, see Reports | Metadata Fields | Xill4 for more information. If you wish to display different fields, feel free to modify the Metadata Fields flow. View Figure 27 (left-bottom corner) for an example result. Make sure to choose the fields of the source content type that has been mapped in the content-type mapping sheet in the sub-chapter (5.8.1.1).
3. The columns E & F of the field mapping should be filled in based on the Content Type Fields SPO.xlsx report. Make sure to choose the fields of the target content type that has been mapped in the content-type mapping sheet in the sub-chapter (5.8.1.1).
4. The column G is optional; it sets the location to store the property in the content store object. When left blank, it will be stored in target.properties with the name specified in the Target SystemName columns.
5. The column I is optional and by default supports only two values:
   1. sheet à references another sheet in the Content type & Field mapping.xlsx for a value mapping, see screenshot example above: Figure 27 (row 3). This row refers to the sheet category which should exist with the unique values from the source and to be mapped values in the target, see screenshot example below: 
      

Figure 27: A screenshot of the ‘category’ sheet with example values of the columns ‘*Source’ and ‘Target’. These columns are required and should be based on the existing/allowed values in the source and target systems. When source objects do not have a value in the field, use the ‘(empty)’ notification to handle map these values.

1. fixed à indicates that a fixed value should be used (specified in column J, Parameter), see example below Figure 27 (row 5). In this example all objects with source content types 144 and 0 will have the value 2024 (cell J4) in the SPO target column Year. When we use a fixed rule, we can leave the column D empty.
2. Additional rules can be added in the flow Transformation (3a. Metadata Mapping) in the code component with a note map object metadata and with id illf34cng, at the line with comment ADD CUSTOM RULES HERE. 
   Screenshot: 
   

Figure 28: A screenshot of a 'Transformation (3a. Metadata Mapping') 
flow, with the code component and its configuration highlighted. 

1. Below is the list of columns, descriptions and example values in a table, based on the screenshot below (Figure 30):

1. The result of the steps above will look like this:

Figure 29: A screenshot of a new field mapping rule, with the links of where the values are coming from.

1. The screenshot of a Document content type in the Content Store’s SPO extraction database:

Figure 30: A screenshot of the 'Document' content type in the SPO database, highlighting the columns values.

1. The new rule added in the example above (Figure 30) could be implemented in the Transformation (3a. Metadata mapping) flow in the following way: 
   

Figure 31: A screenshot of added custom rule ‘title’, highlighting the function’s name, the declared variables, and the added custom rule’s elseif-statement.

1. The SharePoint Online’s system fields do not have to be mapped as by default they will be mapped based on the target fields in the following way: 
   

1. We have created first field mapping rule, to see how this rule is being implemented and processed by Xill4 go to the chapter 5.8.3 Processing.

5.8.3 Processing

The Transformation (3a. Metadata Mapping) flow processes the content type and field mapping sheets in the following steps:

1. The mapping is being read from the location specified in the contentTypeFieldMappingPath flow variable. The content of the file is loaded into the mappings collection of the Content Store by using the Load Mapping component (Figure 33).
2. All source documents of which the content type and field(s) have been mapped will be updated with these values in the target fields (Figure 34).
3. Screenshots of the results in the Content Store: 
   

Figure 32: A screenshot of the mapping rules used in the examples above  
(5.8.1.1 & 5.8.2.1), being stored in the Content Store’s ‘mappings’ collection.  
Each mapping rule will be stored as a separate document.  
 

Figure 33: A screenshot of a document with the ‘File’ content type, highlighting  
the updated source and target values, based on the mapping rules’ examples.

1. After the flow is Done without any error messages in the Console and we have verified that the content is mapped correctly, we can continue to the next phase of the Transformation.

5.9 Principal Mapping

The principal mapping is a set of rules that maps the users and groups values from the source system to their target counterparts. In this phase we must consider the following scenarios:

1. The source system does not have any principal information that can be mapped.
   1. Example of this type of source system is File Share (aka network drive). 
   2. In this scenario we will have to select a fallback username. (Chapter 5.9.1).
2. The source system does have principal information that can be mapped.
   1. In this scenario we will map principals based on their e-mail addresses.
   2. Example: from the source e-mail address ‘testUser@sourceDomain.com’ we will extract the ‘testUser’ value and we will see if there is a ‘testUser@targetDomain.com’ in the target system’s extraction database. (Chapter 5.9.1).
   3. It is quite common that principals from the source system do not exist anymore in the target system, as perhaps they are inactive or they have not been created on purpose. In those cases, we need to select a fallback username. (Chapter 5.9.1).
   4. In rare cases we want to map principals to a new values. For example, the ‘testUser’ has now a different value in the target such as ‘testingAccount’. In the next chapter 5.10 Permission Mapping, we will have this option, for now these values will be mapped to a fallback username. 

5.9.1 Configuration

The principal mapping process is done automatically by the Transformation (3b. Principal Mapping) flow. This flow automatically maps the source.created and source.lastModified principals based on their email address. It requires PRINCIPAL objects to be present in the source and target system Content Store databases. When there is no export of source or target system PRINCIPAL objects, programmatically create those. The target system should be already setup and include all the users before we run this step. We can only map the principal information that already exists in the target system, we do not create these values in the target.

5.9.2 Processing

The Transformation (3b. Principal Mapping) flow maps the principals in the following steps:

1. Firstly, there are indexes being created for the source principal fields in the Content Store.
2. The unique list of sources and target principal fields is being created and stored as separate local variables. Source principal values are stored in an object with the source.id as a key and source.email as value. Target principal values are stored in an object with the source.email as a key and source.id as a value.
3. The unique list of source principals (creators and modifiers) is being looked up in the locally stored target principal’s variable. When the source principal’s source.email matches one of the keys of the target principal’s variable, the value or the target.principal fields in the Content Store will be mapped (read: updated) with the values of the matching target source.id. 
   à à à  
   

Figure 34: A screenshot examples of source local variable (top-left), target local variable (top-right), the mapped principal values (center-left) and the configuration of the Document Update component (bottom-left) which updates the target metadata of the principal fields.

1. After the target metadata of the principal fields has been updated based on current list of source and target variables, the remaining values of unmapped principal fields will be updated with the fallback username based on the two flow variables: 
   1. fallbackPrincipalSystemName: this is the source.id of the selected PRINCPAL object.
   2. fallbackPrincipalDisplayName: this is the source.email of the selected PRINCPAL object.
   3. Screenshot examples: 
      

Figure 35: A screenshot of the flow variables (top) and the ‘PRINCPAL’  
object in the Content Store’s target extraction database (bottom).

1. After the flow variables have been setup and the flow has been executed without errors, we have completed the principal mapping phase. The result of this transformation could look like this: 
   

Figure 36: A screenshot of the transformed principal values of a ‘RECORD’.  
Highlighting the ‘source.created.principal’ and ‘target.created.principal’ fields.

1. After the validation of the transformation in the Content Store, we can continue to the next chapter.

5.10 Permission Mapping

The permission mapping is a set of rules that maps the users and permissions values from the source system to their target counterparts. In this phase we cover the following scenarios:

1. The source system principal must be mapped to a totally different target system principal. The Principal Mapping sheet captures this mapping and is used to perform the principals on the ACL object. 
   1. Example: testUser1@sourceSystem.com becomes qualitAssurance@targetSystem.com.
2. The source system permission must be mapped to the available target system permission values. The Permission Mapping sheet captures this mapping and is used to update the single permission on the ACL object.
   1. Example: modify permission value in OpenText becomes Editor permission value in SPO.

Note: If we don’t need permissions to be mapped, go back to the flow ‘Transformation (1c. Exclude Content’ and set the flow variables ‘excludeACLs’ to ‘true’.

5.9.1 Configuration

The permission mapping process is done automatically by the Transformation (3c. Permission Mapping) flow. This flow automatically 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.

5.9.2 Processing

The Transformation (3c. Permission Mapping) flow maps the principals in the following steps:

1. Firstly, the contents of the mapping are loaded in the mappings collection in the Content Store.
2. The contents of the mapping’s sheets are stored as local variables in the flow.
3. The ACL objects that are in the scope of migration are retrieved and the value of the principals and permissions are mapped to the target counterparts. 
4. After the flow has been executed without errors, we have completed the principal mapping phase. The result of this transformation could look like this: 
   

Figure 37: A screenshot of the transformed principal and permission values of a ‘ACL.  
Highlighting the ‘source.principals’, ‘target.principals’, ‘source.permissions’ and ‘target.permissions’ fields.

1. After the validation of the transformation in the Content Store, we can continue to the next chapter. 
   

5.11 Remove invalid characters

The target system usually has restrictions on what characters may be used in names. The flow Transformation (4a. Remove Invalid Characters) automatically replaces occurrences of forbidden characters by a replacement character. This flow has three flow variables:

1. replacementChar: a variable that specifies the value of the replacement of the invalid character.
2. invalidChars: the list of invalid characters that will be replaced.
3. replaceInvalidXMLChars: when set to true it will automatically replace characters that are not allowed in XML.

 
Figure 38: A screenshot of the flow variables of the flow  
‘Transformation (4a. Remove Invalid Characters). 

5.12 Deduplicate names

For most systems (like SPO) the combination of path and file name (or document name) is unique for each document. If the source system does not have this restriction, or multiple source containers are mapped to the same target container, duplicate names can occur, which will clash or overwrite on import. 

The flow Transformation (4b. Deduplicate Names) will make all names per hierarchy unique, by automatically adding suffix numbers to names that would otherwise be duplicates.

This flow has only one flow variables uniqueNameContainersAndRecords, which when set to true will deduplicated the names of RECORD and CONTAINER documents which are directly related to one another.

5.13 Long Name & Paths

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:

1. Shortens objects names to 255 characters
2. 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.

1. Load

When the transformation steps have finished, the load can be started. A Migration Accelerator has SharePoint Online as its default target system, so the rest of this chapter will assume this is the system to load into. Any other target accelerator has its own documentation, not included in this file here. 

The full documentation of the SPO load connector can be found at https://docs.xill.io/xill4/accelerators/target/sharepoint-online/.

6.1 SPO (1. Prepare)

The first flow to run, is called Prepare. It does important calculations and transformations and validates the content types and metadata against the provisioned sites.

6.2 SPO (2. Load Document Sets) – optional

This flow is needed to load document sets but can be skipped if there are no document sets in scope.

6.3 SPO (3. Generate packages)

Run Generate packages next.

6.4 SPO (4. Upload)

When the packages were all created, they can be uploaded with the Upload flow. When this has finished, the load packages are stored in Azure, where all documents and metadata are processed to finally land in SharePoint. The performance of this process can vary quite a bit.

6.5 SPO (5. Monitor)

The processing of the load packages between Azure and SharePoint can be monitored by starting the Monitor flow. The Upload flow does not have to be finished, so the Monitor flow can be started right after Upload started. This flow downloads migration logs from Azure. A log file is created for each package, and once a log file has been downloaded, that is the sign that the package fully processed.

6.6 SPO (6. Parse logs)

The Parse logs flow reads all log messages and scans for warnings and error messages. If there was a warning or error, this flow stores that information in the Content Store on the relevant document, and outputs the message to the flow console.

6.7 SPO (7. Delete containers)

The Delete containers flow cleans the storage account by removing the containers that were used for import.

1. Test and rework

When the first documents have landed in the target system, a huge milestone has been achieved! Now, the migration can be tested, and any findings should be noted. Test and rework is a normal part of a migration process. The transformation flows may need many iterations of changing and testing.

1. Production migration

When the last test migration was a success and there are no findings left, the production migration can be planned and executed. If the production environment is different from the testing environment, use the environment editor to add the production environment variables and secrets. Do not forget to switch to the production environment in every flow that is started for the production migration.

1. Attachments 

This manual focuses on the technical steps of how to perform a migration, but we also included some templates to help with the process, like planning.

• Project WBS Planning Migration with Feasibility Study Template.xlsx

This is a template for a work breakdown structure planning. The task breakdown is roughly the same for all migration projects, so this template can be useful. When filling it in, keep in mind:

• the availability of at least one migration engineer and a project manager
• a high-level technical overview of the project
• the planning of the owner, system admin, and key users of the source and target systems
• Migration Runbook.xlsx

This is an example of a runbook. It is especially useful to create a runbook if two or more parties are involved in running a production migration. With a migration runbook, you can carefully align and plan all steps, their order and time to execute the final migration, so all dependencies are met and expectations are managed.

• Migration Design Document template.dotx

An example of a migration design document.