Does this site look plain?

This site uses advanced css techniques

The Evolution™ payroll service-bureau software from iSystems, LLC is updated regularly to fix bugs and to reflect changes in tax/HR law, and these updates must be applied by Evolution licensees as needed. Patches are released several times a month.

Table of Contents

Notice of a new release is sent to the evolution-announce mailing list, and the updates themselves are posted on the support website (iSystems-provided credentials required) for download. This document describes the procedure for applying these updates.

We'll note that this is not the only way to perform this task, but it's a process we've been refining for years, and has worked quite well.

Furthermore, this is only for the routine updates: we're not touching on the much more substantial major version upgrades that involve DB patching. You'll need to get help for that.

Users on the SaaS environment need not worry about this, as updates are done for you automatically by the Systems Engineering team at iSystems.


What's included in an update

Each release includes at least one, but usually two kinds of files:

SYSTEM database
This is a compressed backup of the SYSTEM.gdb database, and it contains static database tables, tax rates, reports, and the like. The file is unzipped after download, and then restored into the production database.
These downloadable files are named like system_17.15.00.02.zip, and every update you apply will include one of these.
Application Version
This contains application program code, and it updates the executables for the middle tier plus the GUI client (Evolution.exe). These are usually included in an Evo release, but not always.
Though it's possible to download this file directly from the iSystems support download site, we recommend using the Evo Management Console to do this; see [later section]. You won't ever unzip this file.

The files are found on the support site under a directory named for the release: as of this writing, the current directory is Evolution_v17_Ryegate/.

Prep work / downloading

Actually installing any kind of update requires bringing down Evolution, but there's some work that can be done in advance to get ready for the update, work that does not impact production.

NOTE: though it's technically possible to do the Evo MC parts of this upgrade from your desktop and not the Request Broker machine, I recommend that you do everything from the RB machine to avoid confusion, at least until these updates are routine for you.

Download new Application version

Using the Evo Mgmt Console, login and navigate to MaintenanceVersion Update, and see where the version you want is found. If you see it at the top, section, it's already been downloaded and this part is done.

Tip
This step can be done anytime in advance; downloading does not impact production.

But if it's in the bottom section, it's not here yet so you'll need to download it. Click the radio button for the version you want, then [Download selected version]. After confirmation it will start downloading.

Evo MC: Select version and download

This could take a while, even 5-10 minutes depending on the speed of your internet connection: just wait it out.

When done, it will show the version you just downloaded in the upper section as available but not selected; it will be installed later.

Evo MC: Version ready for installation

Download SYSTEM database

As noted, every update includes one of these, so it will be a common operation.

Tip
This step can be done anytime in advance; downloading does not impact production.

While on the Request Broker machine, use your browser to visit the iSystems download site. Hopefully it's in a shortcut, and you'll use your (hopefully-remembered) credentials to navigate to the Ryegate area and to the version you're looking for.

Picking a random sample directory, we see a handful of SYSTEM databases, along with some other files you won't consider. There is often only one, but sometimes more than one: you should know which version you're looking for.

support files listing

There are of course many ways to download a file, but we recommend doing it this way.

Right-click on the SYSTEM database you want, then select "Save target as..." or "Save link as..." (depending on your browser) - the idea is that you choose where the file is saved rather than just going into your Downloads folder.

Most of my customers have an Evolution Updates area on the Request Broker machine, usually available as a shortcut on the desktop. Navigate to there, then to the directory for this release ("Ryegate"), then save the file there.

Tip
It's acceptible — and recommended! — to run both downloads at once. You'll need to open a browser window or tab for each one, but there's no reason to wait for one to finish before staring the next one.

Extracting SYSTEM.gbk

Once the downloads have finished, we have to unpack the ZIP file to extract the file within.

No matter what the name of the System_x.x.x.x.zip file is, the file inside the archive is always SYSTEM.gbk, and this must be extracted to the same directory, overwriting any file that already exists.

As with downloading, there are many ways to extract files from a ZIP archive, and you can always use what you're comfortable with, but most of my customers use the native tools available with Windows (i.e., with no third-party add-ons).

Right-click on the System_x.x.x.x.zip file and select (depending on your operating system) "Open in new window" or "Explore". This should open a new window: using your mouse, drag the SYSTEM.gbk from that new window back to the original window. It will likely ask you to confirm overwriting the file; approve, then close the new window.

This marks the end of the prep work, all which can be done while Evolution is running.

Notifying & booting the users

Applying any kind of update brings down Evolution, so you may want to check that users are not interrupted in the middle of critical operations unless this is an emergency update that can't wait.

Tip
Many bureaus don't send these messages as a matter of practice; they instead just wait for an idle time with no activity and then just complete the update quickly.

Most Evolution service bureaus do not provide advance customer notice of downtime for updating, because the procedure doesn't take very long and is very low risk. This is unlike the major version upgrades, which put Evolution out of service for hours or days, and warrants an announced maintenance window.

Even though it's easy to tell when payroll staff has all checked out, there still may be customers online via Evolution Remote. Customers often work at odd hours, especially the evening before due-tomorrow payrolls.

To find out, visit the Evolution Management Console with the web browser and navigate to:

Checking users in the EMC

This shows all users logged in, and the last-active-time column showing user last-active time; this makes it possible to tell if your customers are actively working on the system.

Note that users identified as "guest" can generally be disregarded: they are associated either with the system's ADR replication process, or with connections from the Evolution web tier (Employee Portal / Evolution Payroll / Advanced HR); these have no mechanism to notify them, so can they be ignored.

We'll note that the EMC has no way to boot an individual user session, nor to kill sessions which are actually dead, but it's possible to send a Maintenance Notice to all connected users.

Sending a maintenance message

A reasonable time before shutdown, enter a message in the box and click Send. All users will receive this message, and as a helpful side effect, this will automatically log out some dead sessions, leaving only "real" users behind.

Stopping All Services

Once zero hour arrives, stop all services, bringing Evolution down.

This Evo Tip assumes you have experience starting and stopping services via the Evo Mgmt Console, so coverage here will be cursory.

Navigate to MaintenanceService Control, and look for the "All Services" buttons in the upper left of the right panel: click [Stop].

Stopping all services in the Evo MC

At this point, Evolution is down and we normally like to move this process along to minimize downtime to the users.

Activate the Version in the Evo MC

If this update includes an application version, it should be applied now. Navigate in the Evo Mgmt Console to MaintenanceVersion Update, click the radio button for the version you want, then click [Install Selected Version].

Install version via Evo MC

It takes perhaps a minute to activate this version, after which it will show the version that's installed.

Tip
If the version you think you want is already activated, then this Evo update is the kind that includes a SYSTEM database only. This is common, meaning you can skip this step.

Install SYSTEM database

There are a number of ways to install the applicable SYSTEM database, including by the use of the Evo Db Maintenance tool, we prefer my own clickrestore mechanism that I've been using for years. This is already installed on most of my customer system.

Still in the same Evo Updates\Ryegate folder, right-click on the SYSTEM.gbk file and select "Evolution: Update LIVE" (or TEST, if you have a test system) from the context menu.i

right-click on SYSTEM.gbk

It will open a black-background console window, show what it's about to do, and ask you to press any key to make it so.

Press RETURN to start the update process, and a few minutes later it should finish with an exit status and the version it just updated you to.

Results of SYSTEM db update

IMPORTANT: Always verify that the version is what you expect; because you can't tell from the name "SYSTEM.gbk" which exact version is inside, it's easy to slip up and restore the wrong version.

Tip
If the wrong version is inadvertently installed, simply locate the proper System_x.x.x.x.zip file, unpack it, and re-run the SYSTEM.gbk installer.

Also keep an eye out for errors in the output listing; they are usually obvious. Seek help if you see one.

Start Evo up again

Assuming all appropriate updates have completed successfully, it's time to start Evolution back up to allow the users back in.

In the past, services were started all in one click ("Start all services"), but I've found that this is not always reliable, and that starting services in a particular order works better.

Service start order in the Evo MC

Services should be started in this order, waiting each time for the start to complete:

  1. Start Request Broker; this is the traffic cop for the whole application, and it should be running before all the others. At some installations, the Request Broker might take a minute or two to start.
  2. Start all Request Processors; these are the payroll workerbees, and the first thing they do is phone home to the Request Broker looking for things to do - this is why it's helpful to have the Request Broker running and waiting first.
  3. Start all remaining services. These include Remote Relay, API Adapter, and the ADR client. The "Start all services" button in the upper left can be used for this, as it will skip any services that are already running (which means the Request Broker and Request Processors will be left alone).
Tip
Don't ever use the [Restart] button for services in the Evo Mgmt Console. This Restart operation is not reliable and will occasionally leave services in a bad state, which is unfortunate because we often want to do exactly this. Instead, always [Stop], then [Start] any service you wish to restart.

At this point, Evolution is now running and the update is complete!

Check your work

Though the upgrade is complete, it's nevertheless wise to check your work by actually logging into Evolution to make sure it's as you expect. Launch the standard Evolution GUI client that you use every day, allow it to update itself, then login as usual.

Look in the upper left of Evolution's title bar and you'll see both of the versions; these should be what you installed:

System and App versions in GUI client title bar

But if you make a mistake and mix-and-match versions, you (and your remote clients) will see:

System DB version mismatch

This can happen if you either forget to install the version in the Evo MC or if you install the wrong System database, and though technically Evolution might be able to limp along in this condition it really must be fixed immediately.

Looking at the error message, the upper line shows the System database version (here, 17.15.0.2), and this means it's expecting the application version to be 17.15.0.X as well, but it's actually got 17.14.0.X. In this case, obviously we forgot to activate 17.15.0.X in the Evo MC.

If this happens, stop Evolution immediately and doublecheck your work.

Tip

Installed Evolution versions always must agree in the first three numbers; there are no exceptions. If the SYSTEM database is 17.15.0.X then the application version must be 17.15.0.X.

The last digit ("X") will almost never match, but they aren't designed to. What matters are the first three numbers.


This Evo Tip is not supported or endorsed by iSystems, LLC.

First published: 2008/11/18
Updated 2017/06/03 for Ryegate