Usage

Overview

This page presents the common use cases of the WorkflowGen upgrade image. This image is available as Linux and Windows containers, and is meant to be a single use container that runs until completion. You should delete it once you're done with it.

Upgrade steps

The first thing to know about the upgrade container is the steps it takes to upgrade your installation. Every step, except for the acquisition of the update package, is done within a transaction, which means that any error will revert all changes previously made. In the case of files, they will be restored from a backup done prior to the operation.

Step 1: Get the update package

Depending on if the upgrade container is online or offline, this step gets the update package of the ToVersion parameter. If the container is online, it will try to get the update package from the updatepackages volume first. If not found, the container will download it from the workflowgen-releases GitHub repository. If the container is offline, it will try to get the update package from the updatepackages volume. If it can't, it will write an error message and exit.

You have to provide your own WorkflowGen update packages when using the container offline. By default, when you mount the updatepackages volume, the container expects the following file structure:

updatepackages/
    7.14.0/
        update.zip
    7.15.0/
        update.zip

As you can see, the structure expected has only folders at the top level with the exact version of WorkflowGen. Inside them is an archive called update.zip, which is the WorkflowGen official update package. You need only to have the ToVersion update package when you run the container.

Optionally, if the update package is located elsewhere within the volume, you can specify the file name and path in the WFGEN_UPGRADE_UPDATE_PACKAGE_FILE_NAME environment variable. For example, you could specify the value 7.15.2.zip if ToVersion is 7.15.2 and the directory structure is flat. You could also specify the value workflowgen/updates/7.15.2/update.zip if the update package is further down the directory tree.

For more information about environment variables, see the Configuration page of this section.

Step 2: Merge new App_Data files into existing App_Data folder

Before this operation, a backup will be made of all the folders and files from within the bind mount and temporarily copied to a path inside the container. At all times, the Files, LogFiles, and Ws folders are ignored, including during the merge operation. The container will then merge the App_Data files from the update package into your App_Data folder that you have linked to the container through the data bind mount. The merge is additive only, which means that any file that don't exist in the update package will be kept as-is.

Step 3: Merge new wfapps files into existing wfapps folder

In the same manner as the App_Data merge operation, the wfapps folder will also be merged with your wfapps provided in the data bind mount. This operation is also additive only.

Step 4: Migrate the database if needed

The upgrade container will then apply any SQL migration files found in the update package that satisfy the condition $fv < x \le tv$ where $x$ is the version of the SQL migration file, $fv$ is the FromVersion value and $tv$ is the ToVersion value.

Online example

This is the simplest use of the upgrade container. For example, if you want to upgrade WorkflowGen from version 7.14.6 to 7.18.2 and the container has access to the Internet, you would call it like this:

PowerShell

# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade `
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' `
    --mount "type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data" `
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 `
    -FromVersion 7.14.6 -ToVersion 7.18.2

# When has terminated, you can analyse the container or review the logs.
# Then, remove the container.
docker container rm wfgen-upgrade

Bash

# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade \
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' \
    --mount type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data \
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 \
    -FromVersion 7.14.6 -ToVersion 7.18.2

# When has terminated, you can analyse the container or review the logs.
# Then, remove the container.
docker container rm wfgen-upgrade

In this example, the container will download the update package from the 7.18.2 version, merge the App_Data and wfapps files in /mnt/data/appdata and /mnt/data/wfapps respectively and apply any database migrations using the SQL scripts in the update package.

You can ignore files and folders with environment variables when the container merges files. For more information, see the Configuration page of this section.

Offline example

If the container doesn't have access to the Internet, you can pass the WorkflowGen update package yourself. Make sure that it is the exact version of the ToVersion argument passed to the container. You would call the container like this:

PowerShell

# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade `
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' `
    --mount "type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data" `
    --mount "type=bind,src=C:\path\to\packages,dst=/mnt/updatepackages" `
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 `
    -FromVersion 7.14.6 -ToVersion 7.18.2 -Offline

Bash

# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade \
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' \
    --mount type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data \
    --mount type=bind,src=C:\path\to\packages,dst=/mnt/updatepackages \
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 \
    -FromVersion 7.14.6 -ToVersion 7.18.2 -Offline

In this example, there are two changes compared to the online example. First, a bind mount has been added for provisioning update packages. The container will first look in it to find an update package. Second, the -Offline flag has been passed to the container. This flag tells the container to not try to download the update package if it doesn't find the package in the bind mount. In other words, the container will not attempt any network-related access.

The path and name of the update package can be modified with environment variables. For more information, see the Configuration page of this section.