Workarea 3.4.0

Upgrade guide for Workarea 3.4.0.

Before we get in to the details, I will assume that you are familiar with using the Workarea Upgrade tool. This is a fundamental part for every upgrade, and while we will refer to using it in this guide, we will not cover specific commands.

3.4 Release Notes

The full release notes for v3.4 are available here:

Some stand-out changes to be aware of

Dependency changes

Admin Changes

Storefront Changes

Important Changes in v3.4

In v3.4 the following changes will need to be made to your application, you should account for this in your estimate.

MongoDB v4

In order to support the new Metrics engine, which drives Admin insights and reporting. Workarea was upgraded to support MongoDB 4.

You’ll need to coordinate v3.4 upgrade with the Workarea support team due to the MongoDB v4 requirement.

If your application includes a config/mongoid.yml file, you may need to rename the database to align with autoconfiguration. This may involve changing or removing the mongoid.yml configuration in your project.

Installing MongoDB 4 locally

You will need to install MongoDB 4.0 in your local development environment, using either the package/installer for your system or Docker. If you are installing on your system, consider whether you still need to run MongoDB v3.x for other applications. Internally, the Workarea product team have found that stopping the MongoDB 3.x service and running MongoDB 4 in a docker container to be an effective approach. If your development happens entirely within a Docker environment using docker-compose you can update your docker-compose file to use a MongoDB 4.0 image.

Bamboo Updates

To support MongoDB v4 you will need to update your Bamboo configuration to use scripts.

If your application already has a /script directory for bamboo you can update the existing scripts using the app template generator (see below) and will not need to change your bamboo configuration.

If you do not have a /script directory you should create a new branch from master and add scripts for v3.3.x prior to doing your upgrade. The scripts are included in the app_template.rb and can be generated using the app:template command below. Once these scripts are merged in to master, QA and Staging branches you should create a ticket for Workarea Support to update your bamboo build plan. Once your build plan is updated, all feature branches will need to rebase or merge in the changes from master to include the scripts directory.

Generating metrics and insights

To populate your application's Metrics engine, and generate historical insights you need to run the generator provided in Workarea 3.4

Note: Depending on order volume this could take a while to run in production. You should schedule running this task accordingly.

bundle exec rails workarea:insights:generate

App Template updates

There were a number of changes to the way new Workarea applications are configured. To save time finding and fixing those configurations. Or worse, dealing with bugs due to outdated configurations. You should run this command to update your application. Be sure to commit your work before running this, and check to ensure no custom configuration, which you may need to keep, was removed. Run this script after you have bumped your application's Workarea version to the latest version of v3.4.x.

bundle exec rails generate workarea:install

This script will offer the Ynaqdhm CLI interface when conflicts are detected. Using the d option to view a diff before deciding whether to accept or reject a change in each file is recommended.

A few things to note about these configuration changes:

Update Overridden and Decorated Files

Once you've made the important changes noted above, you're ready for the bulk of every upgrade. Use the Workarea Upgrade tool to generate a diff, then work through the changes in each file. You will need to use your judgement to decide which changes to make, and which changes are not necessary.


This should have gotten you from v3.3 to v3.4! If you're stuck, or have further questions, please contact Workarea support.

Feel free to include members of the Workarea Support team on your pull request.

Now on GitHub