Migrating from Legacy Networking to systemd-networkd on Ubuntu 24.04

2025-11-25T00:00:00+00:00

During a recent Ubuntu server upgrade, I migrated a production system from the legacy ifupdown networking stack to the modern systemd-networkd service. This migration was part of preparing several remote production servers for a smooth upgrade to Ubuntu 24.04, which relies heavily on systemd-managed components.

In this post, I’ll walk through the full migration process, how we automated it safely across multiple remote servers, and the lessons learned from implementing rollback and watchdog mechanisms for zero-downtime transitions.

Why migrate to systemd-networkd?

Ubuntu 24.04 uses systemd-networkd as the default backend for network management. The traditional ifupdown scripts (/etc/network/interfaces) are no longer the recommended way to configure networking. Some of the modern features enabled by systemd-networkd include:

Predictable network interface naming (e.g., ens3, eth0, etc.)
Built-in support for bridges, VLANs, and bonds
Faster boot times with asynchronous network handling
Unified configuration under /etc/systemd/network

Migrating now also avoids future compatibility issues and takes advantage of systemd’s integrated logging and management.

Step 1: Check the current setup

Before the migration, I confirmed the system was still using ifupdown:

ls /etc/network/interfaces
cat /etc/network/interfaces

Output showed legacy configuration similar to:

auto eth0
iface eth0 inet static
    address 10.42.41.1
    netmask 255.255.0.0

Step 2: Install and enable systemd-networkd

Since systemd-networkd wasn’t already active, I installed and enabled it:

sudo apt install systemd-networkd systemd-resolved -y
sudo systemctl enable systemd-networkd
sudo systemctl enable systemd-resolved

Then, I stopped ifupdown to prevent conflicts.

Step 3: Create a network configuration file

Each interface now has its own .network file under /etc/systemd/network/.

DHCP-based interface:

# /etc/systemd/network/10-eth0.network
[Match]
Name=eth0

[Network]
DHCP=yes

Static interface:

# /etc/systemd/network/20-eth1.network
[Match]
Name=eth1

[Network]
Address=10.42.41.1/16
Gateway=10.42.0.1
DNS=8.8.8.8
DNS=1.1.1.1

Step 4: Configure systemd-resolved

This step ensures your system’s DNS resolver works correctly with systemd-networkd.

systemd-resolved listens locally on 127.0.0.53 and handles DNS resolution, caching, and per-interface settings.

Link your system’s /etc/resolv.conf to use it:

sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf

Then to verify:

resolvectl status

If we skip this, the system might lose DNS resolution after reboot. Applications like apt, curl, and ping may fail to resolve hostnames even though interfaces are up.

Restart and verify

Restart both services:

sudo systemctl restart systemd-networkd
sudo systemctl restart systemd-resolved

Check active links:

networkctl list

Detailed view for one interface:

networkctl status eth0

Sample output:

● 2: eth0
       Type: ether
      State: routable (configured)
     Address: 10.42.41.1/16
     Gateway: 10.42.0.1
     DNS: 8.8.8.8

Test:

ping -c 3 8.8.8.8
ping -c 3 google.com

Step 6: Reboot and confirm

Reboot once to ensure everything persists. After the reboot,

systemctl status systemd-networkd
systemctl status systemd-resolved

and confirm interface and DNS are still functional.

Handling remote migration and downtime risks

Performing this migration remotely on production systems without physical console access required special care. I prepared several layers of protection to prevent accidental lockouts.

Console or IPMI verification: Ensured each node had out-of-band access in case SSH connectivity was lost.

Timed rollback safety script: A background process automatically reverted to legacy networking if the new configuration didn’t come up within a few minutes.

#!/bin/bash
sleep 300
if ! ping -c1 8.8.8.8 &>/dev/null; then
    systemctl disable systemd-networkd
    systemctl enable networking
    reboot
fi

Automating the migration and rollback process

To streamline upgrades across multiple servers, I created automation scripts that handle migration, rollback, and ongoing monitoring.

migrate_to_systemd_networkd.sh

This script performs a complete, logged migration with built-in validation and rollback. It checks for valid .network files, disables legacy services, enables systemd-networkd, tests connectivity, and if all retries fail, restores the old configuration automatically.

Key features

Validates configuration syntax using systemd-analyze verify
Masks conflicting services (ifup@eth*, NetworkManager)
Performs up to three connectivity tests
Restarts SSH and dependent services
Schedules a controlled reboot or user-confirmed one
Rolls back cleanly if connectivity fails

upgrade_watchdog.sh

During do-release-upgrade, networking may restart multiple times. This watchdog script runs in the background to ensure systemd-networkd remains active and services like SSH come back automatically.

Executes every 10 minutes
Verifies /etc/systemd/network/*.network exists and services are running as expected if it fails, this script restarts the service
Restarts systemd-networkd, ssh, and dependent services

Together, both scripts allowed us to perform fully remote OS upgrades with zero manual downtime and consistent recovery paths.

Conclusion

Migrating to systemd-networkd modernizes Ubuntu servers and simplifies long-term maintenance. With the automation scripts and safety mechanisms in place, we successfully migrated multiple remote servers with no downtime and automatic rollback protection.

This upgrade not only prepares infrastructure for Ubuntu 24.04 but also integrates cleanly with our automation and monitoring systems, ensuring reliable networking for years ahead.

How to Migrate from Struts 2 to Struts 6

2025-04-17T00:00:00+00:00

With the introduction of Struts 6, developers are provided enhanced features, security improvements, and modern practices that align with contemporary Java development. If you’re currently using Struts 2, migrating to Struts 6 is a worthwhile endeavor that can future-proof your application.

Also, since Struts 2.5.x reached its end of life, there won’t be any security updates for this version. This guide will walk you through the key differences between Struts 2 and Struts 6, including some significant changes in Struts 6 with practical configuration and code examples.

Getting Ready for Migration from Struts 2 to Struts 6

Starting from Struts 6.0.0 the framework requires Java 8 at minimum. So, if you are running a Struts 2.x environment on an old version of Java, it needs to be upgraded to Java 8 at least. Check out the Struts 6.0.0 version notes for a list of changes.

Config and Code Changes

Servlet API Dependency

Struts 6.0.0 requires Servlet API 3.1 or newer and won’t work with the older versions. The Maven dependency that you can use for this is below:

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <scope>provided</scope>
</dependency>

Deprecated Sitegraph Plugin Removed

Support for the sitegraph plugin, which was already deprecated, has now been removed entirely.

Velocity Plugin

Velocity support has been moved into a dedicated plugin. To continue using the Velocity plugin in your Struts application, you can extend the Struts config package definition, adding velocity-default in struts.xml as in the below example:

<package name="mystrutsapp" extends="struts-default, velocity-default">
  ...
</package>

DTD of struts.xml

The proper DTD (Document Type Definition) header of struts.xml should be updated as below:

<!DOCTYPE struts PUBLIC
    "-//Apache Software Foundation//DTD Struts Configuration 6.0//EN"
    "https://struts.apache.org/dtds/struts-6.0.dtd">

Class Changes

There are some class changes you might need to consider.

com.opensymphony.xwork2.config.providers.XmlConfigurationProvider was made abstract. You should now use org.apache.struts2.config.StrutsXmlConfigurationProvider instead.
com.opensymphony.xwork2.conversion.TypeConversionException was replaced byorg.apache.struts2.conversion.TypeConversionException.
com.opensymphony.xwork2.XWorkException was replaced by org.apache.struts2.StrutsException.

Constant Changes

Xwork config constants like devMode were already deprecated and replaced with new constants like struts.devMode. In Struts 6.0.0, the deprecated constants were completely removed. Also, new constants struts.i18n.search.defaultbundles.first and struts.ui.escapeHtmlBody were introduced.

OGNL

Starting from Struts 6.0.0 OGNL expression length is limited to 256 characters by default as longer expressions can be considered harmful. However, the limit can be changed by adjusting the struts.ognl.expressionMaxLength constant in struts.xml.

Static method access is not possible using OGNL expressions like @com.mypack.MyClass@MyStaticMethod(). This usage should be converted to alternative approaches such as Value Stack access through Action methods:

// MyAction.java
public class MyAction extends ActionSupport {

    public String getMyData() {
        return MyStaticClass.getMyStaticData();
    }

    public String execute() {
        return SUCCESS;
    }
}

// MyClass.java
public class MyStaticClass {
    public static String getMyStaticData() {
        return "Data from static method";
    }
}

In your JSP you can access the data using an OGNL expression:

<s:property value="myData" />

HTML Escaping

Struts 6 uses a newer FreeMarker version with auto-escaping enabled by default, affecting how output is rendered. You should avoid manual escaping (e.g., ?html) in FreeMarker templates when migrating to Struts 6.

Struts 2 manual escaping:

${user.name?html}

Struts 6 auto-escaping happens by default, so no ?html escape is necessary:

${user.name}

Tiles Support

Until version 6.3.0, Struts 2 and Struts 6 had been supporting Tiles through Apache Tiles. The Apache Tiles project has been retired and is not updated anymore. The Struts team incorporated the Apache Tiles codebase into Struts and essentially added built-in support for Tiles starting with Struts version 6.3.0 through the new Tiles Plugin.

If you are using Maven you can use the following dependency to setup the Tiles plugin in Struts 6.x:

<dependency>
  <groupId>org.apache.struts</groupId>
  <artifactId>struts2-tiles-plugin</artifactId>
  <version>${version.tiles}</version>
</dependency>

And then register the Tile listener in your web.xml:

<listener>
  <listener-class>org.apache.struts2.tiles.StrutsTilesListener</listener-class>
</listener>

Conclusion

Migrating from Struts 2 to Struts 6 involves several significant changes due to updates in the framework’s architecture, dependencies, and requirements. Struts 6 (starting with version 6.0.0) introduces modernizations to align with newer Java versions, servlet specifications, and security practices.

Migration from Struts 1 to Struts 2

2024-10-04T00:00:00+00:00

Apache Struts is an open source web framework. Struts 1 was first released in 2000 and its latest version (1.3.10) was released in December 2008, marking the EOL of Struts 1. So Struts 1 is an ancient, dead version. Organizations still using it need to move away from Struts 1.

Apache adapted the WebWork framework as Struts 2. Its architecture significantly differs from that of Struts 1. There are key points and obvious differences provided by Apache to cover a migration plan from Struts 1 to Struts 2.

The market share of Apache Struts is around 0.01%, which gives relatively lower relevance to Apache Struts. However, there are companies still using Apache Struts 1 in their legacy applications, which may not be counted in market share statistics.

A Comparison of Struts 1 and Struts 2

Struts 1 and Struts 2 differ significantly in their approach to handling web requests. Struts 1 follows a more rigid structure where Action classes must extend an abstract base class, limiting flexibility. In contrast, Struts 2 is more dynamic, allowing Action classes to implement interfaces or even function as simple POJOs, enhancing adaptability. Struts 2 also includes the ActionSupport class, which implements commonly used interfaces, making development easier and more versatile.

The threading model in Struts 1 is based on a singleton pattern, meaning only one instance of an Action class exists to handle all requests, which requires careful management of thread safety. Struts 2, on the other hand, creates a new Action object for every request, which eliminates concerns about thread safety.

When it comes to servlet dependency, Struts 1 is tightly coupled with the servlet API, requiring Actions to work directly with HttpServletRequest and HttpServletResponse. Struts 2 decouples the Action from the servlet container, using simple maps to represent the context. This allows for easier testing and more modular code. Struts 2 still offers the flexibility to access the request and response objects when necessary, but often through other architectural patterns that minimize the need for direct servlet interaction.

Testing Struts 1 applications is challenging due to its tight coupling with the servlet API. External libraries like Struts TestCase are often required to mock servlet objects for testing purposes. Struts 2 makes testing far more straightforward by supporting dependency injection and allowing Action classes to be tested in isolation, without needing complex mocks.

Input handling in Struts 1 revolves around ActionForm objects, which must extend a base class which often leads to redundancy. Struts 2 simplifies this by using Action properties directly, eliminating the need for separate ActionForm objects. Additionally, Struts 2 supports complex object types for input and output, allowing domain specific objects to be used.

In terms of expression languages, Struts 1 integrates with JSTL, which provides basic object graph traversal but lacks robust support for collections. Struts 2 uses OGNL (Object Graph Notation Language), offering more advanced and flexible expression capabilities, giving developers more control over data handling in views.

Binding values into views is handled differently as well. Struts 1 uses standard JSP mechanisms, while Struts 2 introduces the ValueStack, a system that decouples the view from the object being rendered. This allows for a greater degree of reuse and flexibility, especially when dealing with varying property types across different objects.

Type conversion in Struts 1 is handled by Commons-Beanutils, which operates on a per-class basis. This can be limiting as it doesn’t allow for instance-level customization. Struts 2 improves on this by utilizing OGNL for type conversion, offering built-in converters for common types while also providing a flexible system for adding custom converters.

Lastly, the control over action execution is much more granular in Struts 2. While Struts 1 uses a single request processor per module, Struts 2 introduces Interceptor Stacks, allowing developers to define different lifecycles for individual Actions. This customization helps tailor the flow of execution to fit specific application requirements.

Actions are central components in both Struts 1 and 2 and play a major role in the architectures of both Struts versions. Struts 2 offers a more modern, flexible, and test-friendly framework, improving upon Struts 1’s limitations by embracing POJO actions, better type conversion, enhanced validation, and a decoupled threading model. These changes make Struts 2 more adaptable and easier to maintain, particularly for complex web applications.

You can see more about request processing flow in Struts 2 in this InfoQ article.

Migration

Dependencies

Add the Struts 2.0 Jars to the existing Struts 1.3 application. The latest Jar files can be downloaded from the Apache Struts download page. Alternatively, you can download the Jar files for any of the previous versions from the archive.

Request handling

Configure Struts 2 to handle requests with the *.action extension, differently from Struts 1, which uses the *.do extension.

Configure web application

The web application is enabled in the web.xml configuration file. There are a few changes to this file needed for Struts 2. Dispatcher configuration is done by simply renaming the configuration tags from <servlet> and <servlet-mapping> to <filter> and <filter-mapping>.

A very basic web.xml configuration for Struts 1 would look like:

<servlet>
    <servlet-name>action</servlet-name>
    <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
    <init-param>
        <param-name>config</param-name>
        <param-value>/WEB-INF/struts-config.xml</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>action</servlet-name>
    <url-pattern>*.do</url-pattern>
</servlet-mapping>

The corresponding conversion to Struts 2 would look like:

<filter>
    <filter-name>webwork</filter-name>
    <filter-class>org.apache.struts.action2.dispatcher.FilterDispatcher</filter-class>
</filter>

<filter-mapping>
    <filter-name>webwork</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Migrating actions

A general structure of a Struts 1 action class is below.

public class CustomAction extends Action {
    public ActionForward execute(
        ActionMapping mapping,
        ActionForm form,
        HttpServletRequest request,
        HttpServletResponse response) throws Exception {
        // add logic
        return (mapping.findForward("success"));
    }
}

Struts 1 actions are singletons and extend the base Action class. Alternatively, DispatchAction can be used instead of the base class. In either case, the execute method is the entry point to an Action class. Actions have to be thread-safe and hence all the necessary variables should be handled in method scope. Finally, the execute method returns an ActionForward response.

On the other hand, in Struts 2 a basic action class structure would look like this:

public class MyAction extends ActionSupport {
   public String execute() throws Exception {
        // add logic
        return "success";
   }
}

A Struts 2 action class will usually (but not necessarily) extend ActionSupport. The usual entry point is again the execute method—however, this method has no parameters. In Struts 2 action classes are not singletons. Instead an instance of the action class is created for each request, so class scope variables can be used safely, alleviating many thread-safety concerns in Struts 1 actions. Struts 2 will inject a HttpServletRequest for the current request into actions implementing the ServletRequestAware interface, allowing you access to the underlying request object.

Action Configuration

In Struts 1 applications, action configurations are made in struts-config.xml located in the WEB-INF directory. Struts 1 applications need to configure actions and action form beans in this configuration file.

<struts-config>

     <form-beans>
         <form-bean name="myForm" type="com.endpoint.blog.struts.MyForm"/>
         ...
     </form-beans>

    <global-forwards>
       <forward name="home" path="/home.do" redirect="true" />
       <forward name="projects" path="/myactionProcess.do?dispatch=myDispatch" redirect="true"/>
       ...
   </global-forwards>

   <action-mappings>
       <action path="/myPackage/add" type="org.apache.struts.actions.ForwardAction" />
       ...
   </action-mappings>

 </struts-config>

Struts 2 configuration involves a package wrapper around the action definitions.

<struts>
  <package name="myPackage" extends="struts-default">
      <action name="add" >
          <result>/myPackage/add.jsp</result>
        </action>
        ...
    </package>
 </struts>

However, in Struts 2, actions can be defined in a more general way using Struts conventions:

<struts>
  <constant name="struts.action.extension" value="ep"/>
    <constant name="struts.convention.action.packages" value="com.endpoint.blog.actions.*"/>
    ...
</struts>

In this article we covered migrating the most basic components from Struts 1 to Struts 2 and compared several features between each version. Complete configuration and code migration from Struts 1 to Struts 2 can be done gradually, involving actions, interceptors, tags, and many other details. Not completely straightforward, but the patterns and convention changes adopted in Struts 2 become clearer as you dive in.

Migrating Rails 6 React to Rails 7 React

2023-06-26T00:00:00+00:00

CasePointer’s disease reporting portal is built on React and Rails 6, and it’s time for an upgrade to Rails 7. This blog post will cover the steps, benefits, and challenges of migrating from Rails 6 to Rails 7, and offer valuable insights into the world of Ruby on Rails.

With the recent release of Rails 7, there are many new features and improvements to explore. One of the biggest changes in Rails 7 is the retirement of Webpacker in favor of using the native webpack for bundling JavaScript.

For those who are not familiar, Webpacker is a Rails gem which is a wrapper around the webpack build system that provides a standard webpack configuration and reasonable defaults.

Steps for migrating Rails 6 React to Rails 7 React

To migrate a Rails 6 React application to Rails 7 React, follow these steps:

1. Update the Rails Gem in the Gemfile

In your application’s Gemfile, update the Rails gem version to Rails 7:

-gem "rails", "~> 6.1.4"
+gem "rails", "~> 7.0.0"

2. Upgrade Rails packages

Upgrade the Rails packages using Yarn:

yarn upgrade @rails/actioncable --latest
yarn upgrade @rails/activestorage --latest

3. Run the Rails update task

Run the following command to initiate the Rails update task:

bin/rails app:update

This task guides you file by file to integrate the new Rails 7 defaults. Refer to the Rails documentation for detailed information on this update task.

4. Remove Webpacker

Since Webpacker is no longer the default in Rails 7, follow these steps to remove it:

Remove the webpacker gem from your Gemfile:

-gem 'webpacker', '~> 4.0'

Remove the webpacker.yml file and any other files associated with webpacker.

Run bundle install to update the Gemfile.lock:

bundle install

5. Setting up Webpack

To set up Webpack for your Rails 7 React application, follow these steps:

Install webpack and other necessary libraries:

yarn install webpack webpack-cli @babel/core

Create a webpack.config.js file at the root of your application:

// webpack.config.js

const path = require("path");
const webpack = require("webpack");
// Add other necessary plugins and configurations

module.exports = {
  // Webpack configuration options
  output: {
    // Make sure to use the path of the rails asset pipeline
    path: path.join(__dirname, '/app/assets/builds'),
    // ...
  }
  module: {
    rules: [
      // Add CSS/SASS/SCSS rule with loaders
      {
        test: /\.(?:sa|sc|c)ss$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'],
      },
      {
        test: /\.(png|jpe?g|gif|eot|woff2|woff|ttf|svg)$/i,
        use: 'file-loader',
      },
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: {
          loader: "babel-loader"
        }
      }
    ],
  },
  // ...
};

Add a .babelrc file for Babel configuration:

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

Update the scripts section in your package.json:

{
  "scripts": {
    "build": "webpack",
    "dev": "webpack --watch"
  }
}

6. Update Rails asset tags

In your application views, update the asset tags from stylesheet_pack_tag and javascript_pack_tag to stylesheet_link_tag and javascript_include_tag, respectively:

<%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
<%= javascript_include_tag 'application', 'data-turbolinks-track': 'reload' %>

7. Start the dev server

Start the Rails development server with:

rails server

Then start the React development server with:

yarn run dev

By following these steps, we can take advantage of the new features and improvements in Rails 7 while continuing to leverage the power of React.

Data Migration Tips

2023-02-04T00:00:00+00:00

When you’re in the business of selling software to people, you tend to get a few chances to migrate data from their legacy software to your shiny new system. Most recently for me that has involved public health data exported from legacy disease surveillance systems into PostgreSQL databases for use by the open source EpiTrax system and its companion EMSA.

We have collected a few tips that may help you learn from our successes, as well as our ~~mistakes~~particularly educational experiences.

Customer Management

Your job is to satisfy your customers, and your customers want to know how the migration is progressing. Give them an answer, even if it’s just a generalization. This may be a burndown chart, a calculated percentage, a nifty graphic, or whatever, but something your project managers can show to their managers, to know more or less how far along things are.

Your job is also to know your system; that’s not the customer’s job. They shouldn’t have to get their data into a specific format for you to make use of it. Be as flexible as possible in the data format and structure you’ll accept. In theory, so long as your customer can provide the legacy data in a machine-readable format, you should be able to use it. Let them focus on getting the data out of their legacy system — which is sometimes quite an effort in itself! Real data is almost always messy data, and your customer will probably want to take the opportunity to clean things up; make it as easy as possible for them to do that, while still ensuring the migration proceeds quickly and smoothly.

Be careful about the vocabulary you use with your customer. Your system and the legacy system probably deal with the same kinds of data, and do generally the same kinds of things. Of course, your software does it better than the old ’n’ busted mess you’re replacing, but in order to be better, your software has to be different from what it’s replacing. Different software means different methods, different processes, and different concepts. You and your customer might use the same words to mean totally different things, and unless you’re careful, those differences can remain hidden well into the implementation process, coming to light just in time to highlight some horrible mistake you’ve made. Try to avoid that. Talk with your customer to make sure your team and their team share a common vocabulary. If your system’s core function is to track widgets, and their legacy system’s function is also to track widgets, make sure you understand the differences between your software’s concept of a widget and their legacy system’s concept of a widget.

Migration Scripting

For our products and our customers, we’ve found pretty much every migration process is different, and each one is a custom programming job. Your team should decide at the beginning what steps the migration needs to include, and what technologies it will use in each step. Here at End Point, we often like to work directly in the database, in SQL. Migrations are all about manipulating data, and SQL is well suited for that task. With whatever technology you use, decide how you’ll use it, to manage the considerations given here. You can change your mind later and refactor accordingly, but always have a plan you’re following.

Design the migration as a sequence of processes. That is, first you might import one type of record, next another type of record that depends on the previous one, followed by several further steps to import data from a third source, clean it, map values from the legacy system to the new system, validate the results, and create records in the destination database. Of course the steps will vary from project to project, but the point is your migration will probably include several steps which need to be run in a specific order, so plan your development conventions accordingly. At End Point, we often like to put each step in a SQL file, and name each file beginning with a number, so you can run each script in order sorted by filename, and achieve the correct result. We might have files called:

01_import_products.sql
02_import_customers.sql
03_import_order_history.sql

It’s also common to implement each step one at a time, and to need to run each step several times as it’s being developed. We find it very helpful to wrap each step in a transaction. Often that means each SQL file begins with a BEGIN; statement, and ends with COMMIT;. Often I’ll leave out the COMMIT until I’m finished working on a file. That way to work on the code I can open a database session and run the migration script I’m working on, and when it completes, it will leave me inside the open transaction where I can inspect the results of my work. I make changes to the script, roll back the transaction, and run the script again, for as many iterations as it takes. I only add a COMMIT when I’ve tested the whole file and think it’s ready for the next step in testing.

I mentioned above that the customer may want to use this opportunity to clean their data. You should want this, too. Make sure the data you’re feeding your new system is as clean and well-structured as possible. You may find, as we do, that most of the work in your migrations is in validating the input data, and that actually creating new records in your application is almost an afterthought. That’s OK. You may also find there are places where your application, wonderful though it may be, could stand to be more strict about the data it accepts. I have often discovered my application’s database needs a uniqueness constraint, or a foreign key, thanks to a migration I was working on.

Data Migration History

I wish I could truthfully claim all our migrations go off flawlessly, but that would be a lie. It’s not unheard of to run into some corner case, a few weeks or even months after the migration goes live, where data wasn’t migrated correctly.

On the other hand, it’s certainly not uncommon for a customer or coworker to spot something that strikes them as odd, after the migration goes live, only to find later that everything was in fact correct. In either case, it’s important to preserve a history of the migration to investigate these concerns. We accomplish this with a few specific steps:

Create a database schema for the migration, and a table within that schema for each data file or object type we’re importing. I call these tables “staging tables”, where the incoming data is “staged” as it’s cleaned and validated. Having a separate schema means these tables can remain in the production database long after the migration is complete, generally without interfering with anything.
These staging tables should generally use text fields, to be as forgiving and flexible as possible with the incoming data. We can clean, parse, and reformat the data after it’s imported.
Don’t change the data in these staging tables; add to the data instead. In other words, if you need to map a value from the legacy system to a different value for your new system, don’t change the column you imported into the staging table; instead, add a new column to the staging table where you’ll store the re-mapped value. If you need to parse a text field into a date (because you followed the instruction to use text fields!), don’t change the type of an imported column; instead, add a new column of date or timestamp type, to store the parsed value. That way, when three months down the road someone discovers that some of the imported records have weird dates, you have all the information you need to determine whether the fault lies with the imported data or some step of the migration progress. Knowing exactly where the fault crept in leaves you that much more empowered to fix it.
Keep track of your migrated records’ primary keys, in the legacy system and the new system. Imagine you’ve just imported your client’s legacy customer list into a staging table. This data includes the legacy system’s primary key. Add a new column to the table for your new system’s primary key, and populate it. Many of our systems use an integer sequence as a primary key, so we’d add a new integer column to the staging table, and fill it with the next values from the sequence. Following this principle will give you several important abilities:
- You can always connect a record in the legacy system with its corresponding record(s) in the new system. If you’ve imported a customer list in this fashion, then when you’re importing the order data later, and each order points to a customer using a legacy customer primary key, you can easily find the correct customer primary key to use in your system.
- You can easily know if a record in your system comes from the migration, or from normal day-to-day business. You will probably use this every time you try to debug something with your migration.
- If you need to remove all imported records and re-import them, you can identify exactly which records those are. This should be only rarely needed.

Finally, document the decision making process, in comments directly in your code. For instance, if you have a table of mappings from one value to another, chances are good you arrived at the final version of that mapping table only after some discussion with the customer. Chances are also good someone’s going to question it later on. It’s helpful to keep a comment around, something like, # Joe Rogers verified this is the correct mapping in the daily standup meeting, 23 Nov 2022. This is especially common if you eventually decide to ignore a certain class of records. /* Rebecca says ignore all records with type = "ARCHIVED", via group email 9 Jan 2023 */ is a very helpful clue when someone comes around wondering where those records went.

Teamwork

My remaining tips apply to almost any programming project. First, use source control, and commit your code to it often. I can’t count how often I’ve been grateful the Git repository had a backup of my work, or made my work accessible to fill some unexpected need on some other system, nor can I count how many times I’ve been stuck because someone else didn’t commit their code so I couldn’t get at it when I needed it. Let’s not talk about how many times I’ve caused someone else to get stuck in the same way… Of course, don’t commit your customer’s data. But you should commit your code, and commit it often.

Finally, where possible, work with someone else. Two programmers reviewing each other’s code and collaborating on solutions are often far better than two programmers working alone, or one programmer working twice as much.

Speaking of working out solutions together, I’d love your help improving this list. What keys have you found are important for data migration projects? I welcome your comments. And if you’re looking for someone to handle a data migration project for you, give us a call!

Salesforce data migration: promoting data changes from a sandbox to production

2021-11-24T00:00:00+00:00

Photo by Dylan Wooters, 2021

Intro

End Point recently completed a new e-commerce website built using Nuxt, Node.js, and Algolia and backed by Salesforce data. As part of the project, the client also wanted to re-categorize their products. They had already updated the data in a Salesforce sandbox and needed a way to move their changes to production in conjunction with the launch of the new website.

This data migration initially seemed like a simple request, but it ended up being one of the more challenging parts of the project. While there are clear instructions on how to migrate code changes from a sandbox to production (via change sets), there is very little information on how to migrate data.

Here I will outline the solution we developed, which involved writing a custom migration script using the JSForce library, testing using additional sandboxes, and planning for a rollback. This can serve as a blueprint for developers faced with the same task.

Why not use Data Loader to migrate?

The Salesforce Data Loader is a clunky yet reliable application that allows you to load large amounts of data directly into a Salesforce org. It will work to migrate data if the requirements are not complex. For example, if you only need to load data into a few objects and there are no connected objects or parent-child relationships. We chose not to use Data Loader for a few important reasons:

The data we were migrating was complex. Three levels of hierarchical categories were stored in Salesforce as separate custom objects, attached to another custom object representing products. To make things worse, the category objects were also all attached to each other in a parent-child hierarchy. To load this data using the Data Loader and CSV files was very time-consuming and error-prone.
We needed a fast and reproducible migration process. We had a strict cutover time for the launch of the new website, and the migration therefore had to run quickly.

We did end up using Data Loader as part of our rollback process, but more on that in step 6.

Our solution

1. Export JSON data from the sandbox

For our source data, I exported JSON from the Salesforce sandbox using the JSForce CLI, specifically the query function. Having the source data in JSON was easier than parsing CSV files exported directly from Salesforce. I committed the query commands to our Git repo for easy access during the actual production migration.

Here is a basic example of how to export data using the JSForce CLI.

jsforce -c dylan@endpointdev.com \
  -e "query('SELECT Id, Name, CreatedDate FROM Account')" > sandbox-export.json

2. Write a custom migration script

We were already using JSForce in our project to sync Salesforce data with the Algolia search engine, so we decided to also use the library to migrate data. I won’t dive into the specifics of how to use JSForce in this article, since we have another post that does that well.

My basic approach to writing the script started with asking the question “What would we do if we had direct access to the Salesforce database”? Once I had all of the set-based INSERT and UPDATE operations mapped out, I then translated that into procedural TypeScript code.

Here is a basic example from the migration script, where we are reading data from the JSON exported from the sandbox and loading it into Salesforce production.

import * as fs from 'fs';
import * as path from 'path';
import * as jsforce from 'jsforce';

const openConnection = async() => {
  let conn = new jsforce.Connection({
    loginUrl : process.env.instanceURL
  });
  await conn.login(process.env.username as string, process.env.password as string);
  console.log('info', `Connected to Salesforce.`);
  return conn;
}

const getJson = (filename: string) => {
  return JSON.parse(
    fs.readFileSync(
      path.resolve(__dirname, 'sandbox-data/' + filename)
    ).toString()
  );
};

const segmentData = getJson('new-segments.json');
const connection = await openConnection();

for (let i = 0; i < segmentData.records.length; i++) {
  let segment = segmentData.records[i];
  // Ignore Marine Equipment segment since it already exists
  if (segment.Name != 'Marine Equipment') {
    await connection.sobject('Segment__c').create({
      Name: segment.Name,
      Description__c: segment.Description__c,
      Meta_Description__c: segment.Meta_Description__c,
      Meta_Keywords__c: segment.Meta_Keywords__c,
      SubHeader__c: segment.SubHeader__c
    });
  }
}

3. Come up with a plan for testing data changes

After the migration script runs, you’ll need a way to verify that the data was loaded successfully and according to the requirements. For us, this meant working with our client to develop a smoke testing plan. After running our script, we switched a test version of the website to run against the migrated data in a Salesforce sandbox, and then used the plan to test all of the website functionality to make sure everything worked and the data looked correct. You’ll want to develop a plan based on your specific use case, whether that means verifying changes in Salesforce or an integrated system/website.

4. Test the migration script against a copy of production

Once you have the migration script and test plan completed, you’ll want to run the script against a copy of Salesforce production. The easiest way to do this is to create a new Full sandbox in Salesforce. However, if you’re short on Full sandbox licenses, you can create a Partial Copy, choosing only the options that are targeted in your script. Both sandboxes can be created by navigating to the Setup page in Salesforce, and then going to Platform Tools > Environments > Sandboxes.

After the script runs successfully, you can evaluate the data in the target sandbox to make sure everything looks correct. In our case, this involved pointing a test version of the new site to the migrated data.

One important caveat in this step is the refresh interval for the sandbox. Full sandboxes have a refresh interval of 30 days, and partials have an interval of 5 days. Essentially what this means is that you can’t easily press a button and refresh the sandbox after running the migration script, in case you need to make a change or fix an error. As a result, it’s best to have the data exported from Salesforce production and understand how to rollback the script updates, which I’ll explain more later on.

5. Export data from Salesforce production

Obtain a copy of the Salesforce production data by using the Data Export feature. This can be used as source data for a rollback, if errors occur in either testing the migration script or the real run against production.

To export data from Salesforce, first make a list of all the objects that will be affected by the migration. Then, navigate to the Salesforce Setup page, and go to Administration > Data > Data Export. Click the “Export Now” button and choose the applicable objects (or choose “Include All Data”), and hit “Start Export”. The data export will take a bit, but you should get an email from Salesforce once it is complete.

6. Perform a test rollback

After you test the migration script, if you find that the data is incorrect, you can perform a rollback using the Salesforce Data Loader. Even if the script runs successfully, you’ll want to test a rollback in case an error occurs during the real run. Here’s how I did it:

Download and install the Data Loader for your platform
Delete all the data for each affected object. To do this, log into Salesforce and open the Developer Console, then click on the “Debug” menu and choose “Open execution anonymous window”. Use the following code snippet to delete all data, replacing the Yourobject__c with the name of the target object. Again, you’ll need to do this for each object that was affected by your script.

List<Yourobject__c> SobjLst = [select id from Yourobject__c];
delete SobjLst;

Finally, re-insert the data using the CSV backups from step 4. In the Data Loader, choose the Insert method, and log into Salesforce. Be sure to use an account with the proper write permissions. Then go through the Data Loader wizard, choosing the applicable CSV backup file and load the data back into Salesforce. Repeat for each affected object.

Not the prettiest application, at least on a Mac. Circled in red is the Insert button.

This process turned out to be quite cumbersome for our project, due to the complexity of the data. It ended up taking several rounds of manual work in Excel (vlookups) to align all of the connected object ids correctly. It took me back to my first job after college. Hopefully your attempt will be easier! If it proves to be challenging, check out the online version of the Data Loader. It has expanded features that make it easier to import objects with relationships. Note, however, that the online version is only free for up to 10,000 records.

7. Run the script against production

Starting the “livestream” of our website launch in Slack!

Finally it’s time for the main event. Before you run your script against Salesforce production, be sure to export both the data from the sandbox and the data from Production (steps 1 and 4). This will ensure that the most recent data gets migrated and will set you up for a rollback if something goes wrong.

After your migration script runs without errors, use the testing plan from step 3 to verify that the data is correct. Once you’ve verified everything, give yourself a pat on the back for successfully navigating the arcane and treacherous world of a Salesforce data migration!

Summary

If your Salesforce data model is complex, consider using the steps above to migrate data from your sandbox to production. It will ensure a successful migration, especially if need a fast and repeatable process. If your data is simple and you are migrating a few objects, check out the Salesforce Data Loader application or DataLoader.io.

For more info about the tech we used in this project, check out:

Algolia
Nuxt