Migrating Connectors in an Existing Map
The Connector Migration Wizard allows you to change connector types within an existing map. You can migrate to newer versions of the same connector or even migrate to a totally different connector if the connector parts and schema are similar. For example, you can migrate from SQLServer 2012 to SQLSever 2016 or SQLSever 2019. You can also migrate from SQL Server to Oracle as long as the schemas are similar. With this utility you no longer need to manually edit the XML or JSON of a map to accomplish connector migration.
You can choose to perform the connector migration on:
• A single map
• Only maps in a selected project
• All maps in the workspace
Note: This wizard can deal with source or targets, but not both. For example, if you have maps where you want to migrate both the sources that are currently on say SQLServer 2012 and the targets that are currently on SQLServer 2012, you will need to run the migration wizard twice: Once for sources and again for targets.
There are three ways to migrate connectors:
• Using the File > Migrate Connector menu option.
• Loading a map and changing the connector.
If the new connector has similar parts and capabilities of the old connector, you will be prompted to either overwrite the connection, cancel, or migrate. Choose migrate to migrate the connector.
• Loading a map that contains a deprecated connector.
When you load a map that contains a deprecated source or target connector, you will be prompted to migrate the connector if a newer compatible version exits.
To migrate connectors using the menu option:
1. Launch the Actian DataConnect Studio.
2. Go to File > Migrate Connector.
The Connector Migration Wizard is displayed.
3. Choose which maps to perform the connector migration on. You can choose from the following options:
• All maps in the workspace: In this case all maps in your current workspace folder are discovered for migration.
• Only maps in the selected project: In this case you need to specify the Project Name.
• Only the single map selected: In this case you need to browse and select the map. If the map has a connector that is deprecated or is not installed, an error message is displayed, but you can still choose to proceed with the migration. Then the migration wizard appears with auto-filled information with most options disabled.
4. Select if you are migrating Source (includes lookups and joins) or Target.
As noted earlier, you can run the wizard twice if you want to migrate both.
5. Select a migrate From Connector.
If you are entering the wizard from a deprecated connector message or after launching a single map and changing a connector type, the From Connector will be already filled in for you.
6. Select a migrate To Connector.
To Connector list is filtered to match the capabilities of the From Connector (for example if both need to support multiple records or tables). This list is also filtered based on From and To Connector parts. They must be similar. This enhances the possibility of a successful and smooth migration.
Note: If there are multiple versions of the selected From Connector you will not see the older versions in the To Connector list (you can migrate to a higher version only). It is recommended that you set the To Connector to the latest version.
7. Click Next.
The Map Selection page is displayed. All maps found under the selected context and type (source/target) are displayed. There may be more than one dataset in the same map that matches the selection criteria for migration. All maps will be selected by default.
Note: A backup folder prefixed with MapBackups followed by a date timestamp is created to back up the map and rtc/tf files under the project or folder containing the map. This folder has a date and time stamp in milliseconds to avoid overwriting of backups.
8. Select the maps to migrate and click Next.
The Connector Parts and Properties Page is displayed. You can validate and change the To Connector credentials and properties from this page.
9. Update the connector credentials and properties.
Select Propagate Credentials if you want to copy credentials (server, db, userid, password) to each of the remaining selected map/datasets.
You can navigate through all map dataset using the Previous and Next button that is displayed on the top of the page.
WARNING! Warning: Do not change parts (like table) to where the schema is radically different, or the migration may fail.
10. Click Finish.
A success message and Log file location is displayed. You can click View Log to open the Log file for viewing.
IMPORTANT! After migrating a connecter, you should load the migrated map and run to verify if the migrated connector is working fine. Only after this you should remove the newly created backup folder. It is recommended that you do not delete the backup folder for a few days.
IMPORTANT! Each migration produces a separate backup folder. To retrieve the original maps, remove the newly created maps and copy the old maps from the backup folder and paste them at the project level. After this remove the .bak extension from the map file names.
IMPORTANT! Users cannot migrate the connector if there is a schema mismatch between the From and To schemas. This is possible when the record counts are different, and the old field count is less than or equal to new field count. Also 0.5% of the old field names must be contained in the new schema, in any order, and this is not case sensitive. In other words, Account can match account.