Notice
These instructions are intended
for use by local CM4D Administrators, DBA's, or other IT personnel
that are familiar with CM4D databases and installations.
Topic Contents: Hide
Notice
These instructions are intended
for use by local CM4D Administrators, DBA's, or other IT personnel
that are familiar with CM4D databases and installations.
This document is a general guide that will help get you started if you are upgrading an existing CM4D installation (v21 or older) up to version 23.
There was a limited release of v22, but most upgrades will bypass that version except for running the Schema 22a Database Update scripts.
· If you are installing CM4D for the first time with v23, this migration is not required. Install v23.1 CM4D using the standard installation procedure.
· If you are currently running v22 (limited release), this migration is not required. Follow normal upgrade procedures to update to v23.1.
· If you are currently running v21, you must be running v21.1 or newer (Site Schema 21b) before running the v23 migration. When updating your database(s) to v23.1, you will also need to run the Schema 22 update scripts between Schema 21b and Schema 23a.
· If you are currently running v20, you must perform the v21 Migration Step 1 - Pre-Upgrade Tasks on a v20 (Schema 20b-20b) Database. When updating your database(s) to v23.1, you will then also need to run all Schema 21 and Schema 22 update scripts between Schema 20b and Schema 23a.
Always back up all of your CM4D-related files and databases BEFORE attempting to upgrade, patch or migrate any CM4D applications, files, or databases.
For this migration, the databases and CM4D.4ds files are particularly important. In addition to the normal Schema update scripts that are run on the databases, the databases will also go through a migration that will change the encryption of passwords to allow for Unicode support. The CM4D.4ds files are required to perform the database password encryption migration. This process is expanded in Step 5. Migrate Database Passwords, here.
The CM4D installation directory typically has permissions that limits what is allowed to be modified in that folder. For the migration process, you need to copy all required files from the Installation folder into another folder that has modify privileges.
Depending on the type of installation you have, you need to store a copy of the following files that you will copy back into your CM4D installation folder after you have upgraded.
· If you are running a Server version of CM4D:
§ CM4D.4ds
§ Cm4d.ini
§ DataSmithBatch.settings
§ Scheduler.settings
§ Launcher.settings
· If you are running a stand-alone Workstation version of CM4D:
§ Cm4d.4ds
§ Cm4d.ini
CM4D v23 requires a new version of all CM4D license files. Contact [email protected] for help with license requests.
Tip
You should request new license files
to be used before upgrading to v23 to allow time for ATS to process
your license request and deliver the files to you before you upgrade
to v23.
Remember that if you are upgrading from v20, you will need to upgrade your ATS Licensing Server to v2.1. See here for more information.
For best results for upgrading to a new major version:
a. Uninstall CM4D.
i. If you are running a v20 or older, do not uninstall CM4D until you have performed all v21 Pre-Migration Tasks.
ii. If you are running v21, uninstall CM4D.
b. Clean out the install directory.
c. Install ATS CM4D v23.1.
d. Update your configuration files:
(1) Copy the Cm4D.4ds file into the v23 install directory.
(2) Save a copy of the Cm4d.4ds in a folder with Modify privileges for use in Step 5. Migrate Database Passwords.
ii. Cm4d.ini file - do not overwrite the Cm4d.ini file in the new v23 CM4D install directory. The Cm4D.ini file installed with v23 is in a format that is Unicode compatible.
(1) Open the Cm4D.ini file you backed up in Step 2. Gather Required Files.
(2) Copy the relevant content from the old file into the new Cm4d.ini file the installer created.
(3) Save your changes.
iii. Settings files - do not overwrite the settings files in the new v22 CM4D install directory. The settings files installed with v23 are in a format that are Unicode compatible.
(1) Open the *.settings files you backed up in Step 2. Gather Required Files.
(2) Copy the relevant content from the old files into the new settings files the installer created.
(3) Save your changes.
e. Import your v23 licenses into the ATS Licensing Manager.
Major version upgrades require Database Schema updates. In order to upgrade your Site and/or CM4D Databases, you must run the Update scripts provided either by your installation or downloaded from the ATS Client Portal (https://portal.ats-cm4d.com/).
You may have databases from one or more schema versions back that you want to upgrade to v23. To do this, you will need to migrate the databases to the latest schema version using the upgrade path(s) in the tables below. You will need to run all intermediate update scripts on your database(s) consecutively, even if you do not install the interim version of CM4D.
Do not update any Schema 20 databases until you have completed all v21 Pre-Migration Analysis! See the v21 Migration Guide here for details.
Find the column for the version you are currently running. Starting with the row with a check mark, run all scripts that have check marks in that column:
|
Current Version |
|||||
Run... |
v20.0-v20.2 |
v20.3-v20.4 |
v21.0 |
v21.1-v21.5.10 |
v21.5.11-v21.9 |
v22.0 |
UpdateSite20b.sql |
|
|
|
|||
UpdateSite21a.sql |
|
|
|
|||
UpdateSite21b.sql |
|
|
|
|
|
|
UpdateSite21c.sql |
|
|
|
|
|
|
UpdateSite22a.sql |
|
|
|
|
|
|
UpdateSite23a.sql |
|
|
|
|
|
|
Find the column for the version you are currently running. Starting with the first available row, run all scripts that have check marks in that column:
|
Current Version |
|||
Run... |
v20.0-v20.2 |
v20.3-v20.4 |
v21.0-v21.5 |
v22.0 |
Update20b.sql |
|
|
||
Update21a.sql |
|
|
||
Update22a.sql |
|
|
|
|
Update23a.sql |
|
|
|
|
Tip
Typically, the Grant scripts will
only need to be run if you are transferring CM4D databases that use
SQL Authentication between servers or restoring a backup. However,
if you are getting a 'Syntax Error
or Access Violation' message when attempting to connect to
the database using SQL Authentication, you might try running the Grant
scripts. See the topic, Troubleshooting.
The CM4D Password Migrator is a stand-alone tool that is used to upgrade your database connections and passwords to v23. This migration updates the encryption that is used in order to allow for Unicode support.
If you have not yet run the Migrator, but you have copied an existing Cm4d.4ds file into the install folder, you will not be able to see any existing connection information when you run DbConnect. Also, before you run the Migration Utility, you will not be able to run any CM4D applications. For example, if you try to log in to SiteManager, you will get the following error:
The Migration utility includes the option of creating a backup of the database tables affected by this migration. If you want to have the Migrator create database backups for you, then you must have a database Server Role that allows you to create tables in the Database.
Notice
We highly recommend that you back
up your current databases and 4ds files before running the CM4D Password
Migrator, especially if you choose not to have the Migrator create
database table backups for you. Once you are certain everything was
migrated correctly, you can delete or archive any backups you made.
The application is installed with v23 of ATS CM4D. By default, the CM4D install directory is located here: .\Program Files\Applied Tech Systems\CM4D\.
a. Run CM4D Password Migrator.exe.
Tip
The dialog shows v22, but it is also
used for v23.
b. Click Start.
c. Browse to the CM4D.4ds file that is configured to connect to the database that will be migrated.
Reference
At this point the CM4D.4ds file should
already be copied to a folder other than the CM4D install directory,
as instructed in Step 3.d.i of
this migration guide. The migration can be done from any folder with
modify privileges as long as a successful connection can be made to
the specified server and database.
Notice
Keep in mind that running this
migration will upgrade the database
for all users of that database, not just the current user connection.
Once the CM4D.4ds file is migrated, you copy the migrated CM4D.4ds
file to all Client machines.
d. Click Convert.
e. Once the conversion is complete, click Yes to continue.
f. Your next step will be one of the following choices:
i. If you have a Site Database, click Next. Go to the next step to continue the migration.
ii. If you have an unmanaged Database, click Exit. For this database type, there are no additional steps and the migration is complete.
g. For Site Databases, continue here:
i. Choose your version from the dropdown menu. The version must correspond to the major version that you are migrating from.
ii. Backup Database Tables: leave this option selected if you want the Migration utility to save a backup copy of the non-migrated user table in your database(s). To use this option, you must have a Server Role that allows you to create database tables.
iii. Click Convert Passwords to execute the migration.
h. If your password encryption was successful, you will see messages in the Results window similar to the one pictured below.
i. Click Exit.
j. The following screen will appear when your migration was successful.
k. Click Exit to close the Migration Utility.
DataSmith instructions have changed as of v23 in order to accommodate an adjustment in Unicode character set definitions as defined by Microsoft. Because of this, any translators created before v23 must be reviewed to make sure that instructions are correct. Adjustments may need to be made to how your translators are written in order for them to work correctly going forward.
Notice
Any translators used by DataSmithBatch
must be cleared of all Warnings before the job will run. Data files
will remain in the Inbox until the translator is cleared of all Warnings,
saved, and the DataSmithBatch service is restarted.
The new definitions apply to all 'Locate' and 'Must be' instructions, as well as a subset of the 'Mark' instructions (Label, Word, and Number). If a translator created in v21 or earlier contains any of the effected instructions, a Warning dialog will appear listing the instructions that occur in the document.
| Instruction | v21 Definition | v22 Definition |
| Alpha | Alphabetic character (A-Z, a-z) | Alphabetic character. Includes full-width alphabetic characters. |
| Comma | Comma character | Comma character. Includes ideographic commas; does not include full-width commas. |
| Digit | Digit character (0-9) | Decimal-digit character. Includes full-width decimal-digit characters. |
| Label | Label (A-Z,a-z,0-9,-,_); includes spaces | Alphanumeric (alphabetic or decimal-digital) and Whitespace characters. |
| Number | Number character (0-9, +, -, .) | Decimal-digit character. Includes full-width digit characters; does not include ideographic periods. |
| Period | Period character (.) | Period (decimal point) character. Does not include full-width or ideographic periods. |
| Punctuation | Punctuation character (~, !, @, #, $, %, ^, &, *, (, ), <carriage return>, |, `, =, \, {, }, [, ], :, ", ;, ', <, >, ?, /, <comma>) | Character that is not an alphanumeric character or a whitespace character. |
| Sign | Sign character (+.-) | Positive or Negative sign characters. Does not include full-width sign characters. |
Space |
Space character | Space characters. Includes narrow, non-breaking, and ideographic spaces. |
| Tab | Tab character | Tab character |
| Word | Finds the next word (A-Z,a-z,0-9,-,_) | Alphanumeric characters. Includes full-width alphanumeric characters. |
| Whitespace | <n/a> | Spaces, tabs, line breaks, or carriage returns. |
Instructions can be cleared either individually or for the entire translator document. We highly recommended reviewing each instruction to ensure that the instruction is correct.
To clear a single instruction warning:
1. Select the instruction with the -=Warning=-.
2. Double-click the instruction to open the Instruction bar.
3. Modify the instruction if needed.
4. Click Commit.
5. The warning will be cleared.
6. Repeat steps 1 through 4 on all remaining instructions marked with the warning.
7. Save the translator file.
To clear all instruction warnings in a translator:
1. Right-click the top node in the Data tree, the name of the DataSmith translator.
2. Select Clear Instruction Warnings.
3. Save the translator file.
Any translators used by DataSmithBatch must be cleared of all Warnings before the job will run. Data files will remain in the Inbox until the translator is cleared of all Warnings, saved, and the DataSmithBatch service is restarted.
If you are seeing 'Job xx has translator warning!' messages in your DataSmithBatch log files, you have one or more Batch jobs with translators that have not been cleared of all instruction warnings.
Once all translators are cleared, restart your DataSmithBatch Service.
If you are upgrading from v20, at this point you will need to continue the migration at Step 3. Execute the Migration here.
If you are upgrading from v21, your migration is finished.
If you require further assistance with your upgrade, please contact ATS Technical Support: [email protected].
