Migrating Connectors in an Existing Map
Use the Connector Migration Wizard to smoothly change connectors used within existing maps. The wizard mitigates the need to manually edit the XML or JSON of a map in order to migrate a connector.
A connector can be migrated to any connector that has similar connector parts and a similar schema. For example, users can migrate from a SQLServer 2016 connector to a SQLSever 2019 connector. They can also migrate to an Oracle connector since they have similar connector parts and schemas.
Connector parts are the fields configured to connect with a data source or target. The fields that are available depend on the connector.
The wizard can migrate multiple maps simultaneously. During the migration process users specify whether to migrate a single map, maps in a selected project, or maps in the workspace. If one of the latter two options is selected, the wizard auto-discovers all maps within the specified context which use the specified connector, and then presents a map list. Users select each map they want to migrate.
Source connector migrations include lookups and joins.
Both source and target connectors in a map can be migrated. However, source and target connectors in a map cannot be migrated simultaneously. To migrate both the source and target connectors, execute the wizard twice - once for the source connector and once for the target connector.
Note: When a map with a deprecated connector is executed, the user is prompted to migrate the connector if a newer compatible version exists.
There are several ways to open the Connector Migration Wizard:
• Loading a map and changing the connector.
If a different connector is selected which has connector parts and a schema that are similar to the original connector, users will be prompted to either overwrite, cancel, or migrate the connector. Choose Migrate to migrate the connector.
• Loading a map that contains a deprecated connector.
When a map is loaded which contains a deprecated source or target connector, an error message prompts users to migrate the connector if a newer compatible version exists. Choose Yes to open the wizard and migrate. By default, the deprecated connector will be migrated to the latest connector version.
Note: When the wizard opens from loading a single map which uses a deprecated connector, these migration options are disabled: Only maps in the selected project, and the option to migrate All maps in the workspace.
Prerequisites
• The new connector must have connector parts that are similar to the currently used (original) connector.
• When the new connector connects to the migrated parts and properties, the schema generated must be similar to the original connector. Otherwise, a schema mismatch occurs. For example, this can happen when migrating from a SQL Server table an Oracle table and the tables are too different.
• The original schema and the new schema must be compatible enough to meet the following thresholds:
• After migration is complete, the new schema has the same number of record types as the original schema.
• After migration is complete, over 50% of the field names from the original schema reside in the new schema. The field names can be in any order, and they are not case sensitive (for example, Account matches account).
• For the Actian Avalanche connector and Actian Warehouse connectors, their respective Actian Data Platform servers must be running.
To migrate connectors using the menu option
1. Open Actian DataConnect Studio.
2. Go to File > Migrate Connector.
The Connector Migration Wizard opens.
3. In the Connector Migration Settings dialog, choose which maps to perform the connector migration on:
• All maps in the workspace: All maps in your current workspace folder are discovered for migration.
• Only maps in the selected project: All maps in the project which you specify by entering the Project Name are discovered for migration.
• Only the single map selected: A single map which you specify by browsing to and selecting the map will be migrated. If the map has a connector that is deprecated or is not installed, an error message is displayed (you can still choose to proceed with the migration). The migration wizard then displays auto-filled information with most options disabled.
4. Specify whether you are migrating Sources (which will include lookups and joins) or Targets.
Note: Run the wizard twice if you want to migrate both.
5. In the From Connector dropdown menu (which includes deprecated connectors), select the connector to migrate from (the connector currently used by the map, and which you no longer want to use).
Note: This field is already set if the wizard opened from a deprecated connector message, or after launching a single map and changing a connector type.
6. In the To Connector dropdown menu, select the connector to migrate to (the connector you want the map to use).
Connectors that are compatible for the migration are listed.
Note: Even though there might be multiple versions of the selected From Connector, you will only see the latest version in the To Connector list. This is because you can only migrate to the higher version. It is recommended that you set the To Connector to the latest version if that version is installed.
7. Click Next.
The Map Selection page is displayed. All maps found within the selected context (project or workspace) and type (source or target) are displayed. There may be more than one dataset in the same map that matches the selection criteria for migration. By default, all maps are selected.
8. In the Map Selection dialog, select each map you want to Add for migration, then click Next.
Note: A backup folder for storing backups of the map, .rtc and .tf files is created under the project or folder containing the map. The folder name is prepended with MapBackups and followed by a date timestamp. This folder has a date and time stamp in milliseconds to avoid overwriting of backups.
9. Select the maps to migrate and click Next.
The Connector Parts and Properties Page is displayed.
10. In the Connector Parts and Properties dialog, carefully edit values for the connector as needed. Use the Previous and Next buttons to view each map dataset. You can validate and change the To Connector credentials and properties from this page.
WARNING! Do not make edits that will dramatically change the schema or the migration will fail.
11. If you want to copy credentials (server, db, userid, password) to each of the remaining selected map/datasets, select Propagate Credentials.
IMPORTANT! If you are both changing connection credentials and migrating multiple maps, or a map with multiple source or target connections:
Use the Next button (rather than clicking Finish) to cycle through the source or target connections. This will ensure that the newly entered credentials are propagated.
12. Click Finish.
A success message and Log file location is displayed. Click View Log to open the Log file for viewing.
13. Load the migrated map, run it and verify that the migrated connector works properly.
14. Verify the following:
• The new schema has the same number of record types as the original schema.
• Over 50% of the field names from the original schema reside in the new schema. The field names can be in any order, and they are not case sensitive (for example, Account matches account).
IMPORTANT! Each migration produces a separate backup folder. It is recommended that you not delete the backup folder for a few days.
Tip... To retrieve the original maps, remove the newly created maps, copy the old maps from the backup folder and paste them at the project level, then remove the .bak extension from the map file names.