How to Migrate Rapidship CSS Customizations to Web Profiles for On Premise Installs

Owned by Michelle Cabaya (Unlicensed)
Last updated: Jun 23, 2023
4 min read

This is for on premise customers only. Cloud customers will be automatically migrated by CXT Software.

If you have Rapidship CSS customizations, the Rapidship CSS Migration Tool should be run to migrate Rapidship customizations after upgrading to X Dispatch 21.0.

If the only customization you have is a custom logo for the Rapidship site, then there is no need to run this tool. You will only need to select and update the profile in X Dispatch to point to your custom logo. See Rapidship Customization.

What is the Rapidship CSS Migration Tool

The Rapidship CSS Migration Tool is used to help migrate current Rapidship logos, customized colors, and customized text values into the following tables.

  • tblWebTranslationProfiles - Main table that holds information about customization profiles. A default profile is automatically added with the installation/upgrade of X Dispatch 21.0.

  • tblWebTranslations - Contains the default label text in addition to their overridden values.

  • tblWebStyles - Contains the default CSS values and their overridden values for specific profiles

  • tblWebPublishedProfiles - Stores the list of Rapidship sites associated and the associated individual profile settings

Only CSS variables in the custom-colors-example.css in Rapidship Style Customizations will be migrated.

Existing data will not be deleted in the migration. The tool will only insert data to the above 4 tables.

How to Run the Rapidship CSS Migration Tool

  1. Go to [XDispatchInstallationDirectory]\Shared_Files\MigrationTools.

  2. Double click CssMigration.exe.

  3. Check the box next to your Available Instances or click Check All.

  4. Click the Migrate Data button.

For Multiple Rapidship Instances

Run the Rapidship CSS Migration Tool once for each instance. Only the first profile will be published and any additional profiles that need to be published must be performed manually using the following SQL script:

INSERT INTO tblWebPublishedProfiles (SiteID, SiteName, PublishedProfileID, RapidShipLogoID) VALUES ('<new siteId (e.g. 99031)>', '<new friendlySiteName>', <id of the profile you'd like to have (can use default of -1, which always exists)>, <id of the image that was uploaded during migration (or can be NULL to use the standard logo)>) --Logo image ID can be found in XD > Maintenance > Images

Failed Migrations

If a migration fails, it will be left checked after the initial run. You can select the Available Instances and click the Migrate Data button to attempt migration again.

Troubleshooting

I don’t see any available instances listed for selection.

This tool uses 4 sources to populate the available instances list. If there is no corresponding configuration found in any of these locations, it will not be able to gather instance information. These sources are (in the order they’re searched for):

  1. Overridden appSetting.config value for RemoteServer

  2. Azure.config file present in the directory that the executable is running from

  3. Standard location for Azure.config (C:\ProgramData\Connexion\Configuration\Azure.config)

  4. Registry key on local machine

I’m getting an error stating X Dispatch must be upgraded to 21.0 or above.

In order to support web profiles, you must be using X Dispatch 21.0 or above.

I’m getting an error stating required tables are not found.

In order to correctly migrate web profile data, 3 tables must be present in the database. This tool will verify that tblWebTranslationProfiles, tblWebTranslations, and tblWebStyles are present in the database before continuing. All 3 of these tables must be present for migration to start. Please ensure you’re using X Dispatch version 21.0 or above.

I’m getting an error stating that database update audit failed.

Database update audit logs are placed when critical updates are made to the database. This error indicates that there was either an error reading from these logs or that the logs indicated that CSS migration has already been completed. If this tool was already run successfully, there is no need to run it again. Your Rapidship should already be using the new profile. You may also check that your published profile (in XD) matches the custom profile that was just migrated. This is a safety measure to ensure we are unnecessarily creating duplicate custom profiles. As a reminder, this tool is designed to only insert new data into the tables. It will not delete any data from any tables.

There was another error not covered above.

While other errors are uncommon, they are possible (e.g. connection was lost due to internet issues). In this case, details about the specific error will be printed on the Logs screen. If the migration had started and an error was encountered half-way through the task, all data will be rolled back. This ensures that the tables do not contain partial data that might interfere with a re-run. In this case, you can simply re-attempt the migration. If it keeps failing, contact support.

After running the migration, my instance was listed under “Successful Migrations” but I don’t see anything different in Rapidship.

If there were no previous Rapidship customizations, then that instance will be moved to “Successful Migrations (or Nothing to Migrate)” section. This doesn’t mean there was a problem with the migration. It is just a sign that there was nothing found to migrate. If you think there were valid customizations before but you are experiencing the same behavior and are now missing your customizations, contact support.