The Syracuse Migration Tool is one way of transferring the Administration data across different servers. You can read more about the general approach in my blog “How to copy Administration data to a separate server” ( https://www.sagecity.com/gb/sage-x3/b/sage-x3-uk-support-insights/posts/how-to-copy-administration-data-to-a-separate-server )
What does the Syracuse Migration Tool allow you to do?
The Syracuse Migration Tool allows you to take data stored in a MongoDB database and transfer it to another MongoDB database. In most use cases, the target MongoDB database is located on a remote server with a different hostname and possibly using different port numbers, so the Migration Tool scripts allow you to modify such information as part of this transfer process.
What data does Sage X3 store in MongoDB?
The Administration data to run a Sage X3 instance is stored in MongoDB, mostly relating to the functions under the “Administration” section of the menu structure. For example, Syracuse layer users, X3 solution and EndPoint information, Certificates, Navigation Pages, User Bookmarks and Preferences, SOAP pool configuration, etc.
Where can I read more?
You can read more in the online help “Using the Syracuse Server Migration Tool” https://online-help.sageerpx3.com/erp/12/staticpost/syracuse-server-migration-tool/
The Syracuse server migration tool can theoretically be run from the SOURCE server, the TARGET server, or any other server with Syracuse that has access to both the source and target servers. In most customer implementations it would likely make most sense to run from the TARGET server, as customers may not want you to be editing files and running this process on a working live server. Just to be clear though, this process does not update the SOURCE MongoDB data in any way.
What does the tool do?
The Syracuse migration tool takes the data out of the SOURCE server by using “mongodump” tool and then does a “mongorestore” on the TARGET server, then it updates some of the MongoDB collections in the TARGET instance to take into account differences of server name and different runtimes, etc.
What does the tool NOT do?
None of these steps upgrade the Mongo data collections to the latest version, as this is done when you upgrade the Syracuse component. You therefore need to be running the same MongoDB and Syracuse versions on both the SOURCE and TARGET servers. After bringing over the MongoDB data to the TARGET server, you can then upgrade MongoDB (if needed) and then upgrade Syracuse to the latest version, which will allow the Syracuse installer to upgrade the Mongo data itself to correspond to the latest version.
Where do I find the tool?
The tool is included with Syracuse installations, located in “SYRACUSE_BASE_DIR\syracuse\bin\node_modules\tools\syracuse-migration” directory.
Note that Syracuse 12.4 migration scripts do not run correctly (Syracuse 12.5 works OK) and Syracuse 12.17 does not include these scripts at all (expected to be resolved soon).
Can I customise the tool?
The simple answer is “No”. If you want to see what the tool is doing exactly, the source code is there for you to review in the “SYRACUSE_BASE_DIR\syracuse\bin\node_modules\tools\syracuse-migration” directory.
What steps do I need to take to run the tool?
These steps can be taken on the TARGET server only.
- Check firewall rules on both SOURCE and TARGET servers allow the TARGET server access to MongoDB port on the SOURCE server (By default, port 27017)
- I recommend copying “config-template.yml” file to “config.yml” in the directory “SYRACUSE_BASE_DIR\syracuse\bin\node_modules\tools\syracuse-migration”, rather than directly editing the “config-template.yml” file.
- Edit “config.yml” as appropriate for your SOURCE and TARGET server setup. You will find my example attached to this blog.
For my configuration, I need to create working directories in the Windows file system:
D:\SageSupport\work\sourceCerts
D:\SageSupport\work\dump
D:\SageSupport\work\logs
- If your SOURCE MongoDB database is using SSL connections, copy the SOURCE server MongoDB “certs” directory to TARGET server (In my case this will be “D:\SageSupport\work\sourceCerts”)
- Run the Migration Script. I have created a CMD batch file “mzRunSyrMig.cmd” to make this slightly easier and have attached it to this blog.
- Review the log files
"mzRunSyrMig.log" located in the same directory as the mzRunSyrMig.cmd script
"mongodump_xxx.log" and "mongorestore_xxx.log" located in the directory defined in the config.yml as “logsDir:” (In my case this will be “D:\SageSupport\work\logs”)
- Check results
On the TARGET server, connect to MongoDB and review the data that has now been transferred across.
What next?
If you just want to transfer data across without upgrading anything (for example as part of a cloning process), then you’re done. If you are transferring the data as part of an upgrade process, you can now upgrade MongoDB to the appropriate version, then upgrade Syracuse to the latest version. This Syracuse upgrade will update the MongoDB collection data as needed.
Do I really have to upgrade my MongoDB binaries version by version, why can’t I just upgrade straight to the latest version?
The upgrade process for MongoDB is stipulated by MongoDB not Sage. You can read the steps needed in more detail at https://www.mongodb.com/docs/v4.4/release-notes/4.4-upgrade-standalone/ but if you are currently on MongoDB 3.4 (for example) you need to upgrade Mongo to 3.6, then 4.0, then 4.2 before then being able to upgrade to 4.4. Also note the mongo tools themselves (mongodump, mongorestore, etc.) are also restricted to being used only with the version they were provided with, until MongoDB 4.4 where the tools are provided separately. See https://www.mongodb.com/docs/database-tools/ for more details.
Why do I need to install the SOURCE server Syracuse version on the TARGET server if I intend to immediately upgrade to the latest Syracuse version anyway?
The first reason is trivial in that if you want to use the Syracuse migration tool on the TARGET server, you must have Syracuse installed. You can get around this issue by running the Syracuse migration tool from the SOURCE server instead. The more troublesome reason is that you need the latest Syracuse component to migrate the MongoDB data on the TARGET server when it is installed. If you don’t have the correct old Syracuse version already installed to migrate (i.e. you try just installing the latest Syracuse version as a fresh install) you will get an error complaining the nanny already exists.
I hope you find this article useful, as always let me know in the comments below.
Files
