Upgrading

Please be aware of additional upgrade steps needed for the scenarios outlined below.

When upgrading from a version earlier than 19.3.0.20190603:

  • If users do not follow instructions here, they may experience errors that prevent pages from loading or be unable to log out of Tasktop.   
  • If you are upgrading from a version that is also earlier than 19.2.1, please additionally follow the instructions below:
    • While we always recommend backing up the operational database, it is imperative that a backup is made prior to upgrading to 19.2.1 or later. Upon upgrade from a version earlier than 19.2.1 to 19.2.1 or later, a one-time change to the operational database will occur that may take an hour or longer to complete. During the upgrade process, the UI will not be available. To monitor the upgrade process, please inspect the log files. You can find more details in our FAQ here.

Backup 

A working backup strategy is a critical element of disaster recovery, since only backups can mitigate complete hardware failure and user error. A strategy that ensures correct and current backups is essential. Backups of the Tasktop database include both configuration and operational data.  

Backup frequency should mirror your practices for all software tools your organization utilizes. Backup frequency should be daily, ideally with incremental backups performed more frequently.

General Application Configuration

The recommended practice is to back up the entire installation/program data directory to cover all customizations (excluding logs)

  • Back up Tomcat customizations (in Linux install directory or Windows Program Data)

    • container/conf/server.xml

    • Any keystores for certificates

    • For Linux: bin/setenv.sh

    • For Windows: any changes to the Java section of the Manage Tasktop application (e.g. memory, command line parameters, etc)

  • Back up keycloak data and customizations

    • keycloak/standalone/data

    • keycloak/standalone/configuration/standalone.xml

Operational Data

Default Derby Database

(warning) Tasktop automatically stores operational data to a built-in database. However, for production environments, we strongly recommend that operational data is stored to an external database for improved maintainability. This will enable you to perform frequent backups without having to stop Tasktop Integration Hub, and ensure that your Tasktop Integration Hub practices are consistent with your existing disaster and recovery process. For details on how to store your operational data to an external database, rather than Tasktop's built-in database, please refer to General (Settings).

If you have chosen to utilize Tasktop's built-in Derby Database, ensure you've backed up the following:

  • File backup of db directory (in Linux install directory or Windows Program Data)

External Database

In order to back up Tasktop Integration Hub, follow the instructions below:

  1. Ensure that you have migrated your operational data to an external database. For details on how to set up your external database, please see General (Settings).

  2. Back up the following folders

    1. on Linux:

      1. /tasktop/db

      2. /tasktop/drivers

      3. /tasktop/libraries

    2. on Windows:

      1. The Tasktop data folder, typically C:\ProgramData\Tasktop
  3. Back up the external database using that database's backup tools.

  4. Back up the Tomcat and Catalina configuration (Note: this only needs to occur if/when changes are made to the Tomcat and Catalina configuration).

Restore from Backup 

If Tasktop fails to restart after an upgrade or there are unresolvable errors preventing your integrations from running, Tasktop may need to be returned to the previous version.

(warning) Care should be taken whenever restoring from a backup as the state of the integration is maintained in the database and restoring to an older copy could result in duplicated items and data (e.g. comments and attachments). It is recommended to only restore when directed by Tasktop support or after a failed upgrade where no items were processed. 

(lightbulb) Note: In cases where integrations were resumed individually during an upgrade, you can prevent duplicating items and data when restoring to an earlier version by utilizing the upgrade from backup file feature described below.

Stop Tasktop before restoring.

General Application Configuration

  • Restore any changes identified in the backup

Operational Data

Default Derby Database

In order to restore Tasktop Integration Hub, follow the instructions below:

  1. Copy the database directory from backup to the Tasktop data folder.
  2. Restore the backed up Tomcat and Catalina configuration files from part 4 of the backup instructions.

External Database

In order to restore Tasktop Integration Hub, follow the instructions below:

  1. Restore the external database backup using the tools from that database.

  2. Restore the backed up Tomcat and Catalina configuration files from part 4 of the backup instructions.

Operating Systems

Linux

  1. Shut down Tasktop.
  2. Remove the new Tasktop installation folder and restore the old Tasktop installation folder from step 3 of the upgrade steps.
  3. If you are using an external database for Tasktop's configuration, restore the external database as described above.
  4. Restart Tasktop.
    1. If you'd like, you can restart Tasktop in 'safe mode' which ensures all integrations are paused.

Windows

  1. Shut down Tasktop.
  2. Uninstall Tasktop, then run the previous installer.
  3. Restore from backup as described in section above.
  4. Restart Tasktop.
    1. If you'd like, you can restart Tasktop in 'safe mode' which ensures all integrations are paused.

Upgrading 

Before you Upgrade

(warning) Before upgrading Tasktop, be sure to do the following:

  1. Shut down Tasktop and afterwards follow the backup instructions outlined above. The first time that Tasktop restarts after an upgrade, the internal database will be migrated to the new version and it will no longer be possible to return to the prior version without the backup. 
  2. Additionally, ensure that backups are made of the Tomcat, Catalina, and Keycloak configuration files that have been customized. The upgrade process will overwrite these configuration files and customizations will need to be re-applied.
  3. When Tasktop is upgraded, a service-downtime for the Tasktop service is required in order to upgrade the database. Note that a second instance cannot be running while the first instance is attempting to upgrade the database.
    1. To understand implications of Tasktop downtime, please see here.
  4. Please review the release notes for all Tasktop versions that have been released after the version you are upgrading from.  Ensure that any upgrade steps outlined in the release notes are followed.

Linux

  1. Shut down Tasktop and Keycloak.

  2. Back up as described in section above.

  3. Move the old Tasktop installation folder to an archive folder.

  4. Unzip the new Tasktop distribution archive.

  5. Restore drivers, copy the /tasktop/drivers directory from the old installation into the new installation folder <install-location>/tasktop.

  6. Restore DB.

    1. If you are using Tasktop's internal configuration database, copy the tasktop/db folder from the old installation into the new installation folder <install-location>/tasktop.

    2. If you are using an external database for Tasktop's configuration, copy the tasktop-db.json file, and the /tasktop/db from the old installation into the new installation folder <install-location>/tasktop.

  7. Re-apply any customizations to the Tomcat and Catalina configuration. 

    1. After installation, open the default file provided by installation (<install-location>/container/conf/server.xml).

    2. Compare the previous file with customization to the new default file and add the customization to the new file line by line.

  8. Re-apply any customizations to the Keycloak configuration.

    1. After installation, open the default file provided by installation (<install-location>/keycloak/standalone/configuration/standalone.xml)

    2. Compare the previous file with customization to the new default file and add the customization to the new file line by line.

  9. Restore Keycloak (user management) configuration.  Note that keycloak's database and Tasktop's database are separate.

    1. If you are using Keycloak's internal configuration database, restore the database (<install-location>/keycloak/standalone/data/keycloak.h2.db) after installation.

    2. If you are using an external database for Keycloak's configuration, reconfigure the external database as described in https://keycloak.gitbooks.io/documentation/server_installation/topics/database.html (Note that you must create an account to access these)

  10. If you have connected to the Microsoft TFS repository in the past:

    1. Remove all files and folders, except for the com.tasktop files, under <install-location>\Tasktop\libraries\microsoft-tfs.

    2. Once Tasktop is started up again, navigate to the TFS repository connection screen.  There, you will see instructions on how to provide the updated SDK and CLC files to Tasktop by adding them to the connector-requirements directory on the machine that hosts Tasktop.  

    3. Restart Tasktop after uploading the files.

  11. Start Tasktop.

  12. Navigate to the Activity screen.
    1. Review the 'Background Jobs' tab to review status on Integration Data Migration jobs.
      1. Resolve any associated issues shown here. These issues will need to be resolved and their associated data migration jobs completed before the affected integrations can run (unrelated integrations should continue to process). 
      2. Once the associated issue is resolved, failed Integration Data Migration processes can be prioritized using the 'prioritize' button on the Background Jobs tab.  Ensure that these jobs complete successfully.
    2. Review the 'Issues' tab to resolve any configuration issues.
      1. If there are configuration migration issues, those will be shown in the Issues tab.  They will block affected integrations from running (but unrelated integrations should continue to process).  Once the source of the issue is resolved, configuration migration issues can be retried using the 'retry' button on the Issues tab.
    3. Review the 'Errors' tab to resolve any errors related to specific integration activities.
    4. Once all issues and errors are resolved, the internal upgrade will complete and information will begin processing for those affected integrations.
  13. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Windows

  1. Ensure a copy of the old installer is available in case a roll-back is required.

  2. Click the 'Stop Tasktop' button on your desktop, and make sure services are stopped: 

    Stop Tasktop

  3. Backup as described in section above.

  4. Run the installer of the new version of Tasktop.

  5. Re-apply any customizations to the Tomcat and Catalina configuration.

    1. After installation, open the default file provided by installation (\ProgramData\Tasktop\container\conf\server.xml).

    2. Compare the previous file with customization to the new default file and add the customization to the new file line by line.

  6. Re-apply any customizations to the Keycloak configuration.

    1. After installation, open the default file provided by installation (ProgramData\Tasktop\keycloak\standalone\configuration\standalone.xml)

    2. Compare the previous file with customization to the new default file and add the customization to the new file line by line.

  7. If you have connected to the Microsoft TFS repository in the past:

    1. Remove all files and folders, except for the com.tasktop files, under <install-location>\Tasktop\libraries\microsoft-tfs and <program-data>\Tasktop\libraries\microsoft-tfs.  Note that the parent folders (marked in red here) for each location could differ if they were customized during original installation.  

    2. Once Tasktop is started up again, navigate to the TFS repository connection screen.  There, you will see instructions on how to provide the updated SDK and CLC files to Tasktop by adding them to the connector-requirements directory on the machine that hosts Tasktop.

    3. Restart Tasktop after uploading the files.

  8. Start Tasktop.

  9. Navigate to the Activity screen.

    1. Review the 'Background Jobs' tab to review status on Integration Data Migration jobs.
      1. Resolve any associated issues shown here. These issues will need to be resolved and their associated data migration jobs completed before the affected integrations can run (unrelated integrations should continue to process). 
      2. Once the associated issue is resolved, failed Integration Data Migration processes can be prioritized using the 'prioritize' button on the Background Jobs tab.  Ensure that these jobs complete successfully.
    2. Review the 'Issues' tab to resolve any configuration issues.
      1. If there are configuration migration issues, those will be shown in the Issues tab.  They will block affected integrations from running (but unrelated integrations should continue to process).  Once the source of the issue is resolved, configuration migration issues can be retried using the 'retry' button on the Issues tab.
      2. If using TFS, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the TFS SDK and CLC zip files.
    3. Review the 'Errors' tab to resolve any errors related to specific integration activities.
    4. Once all issues and errors are resolved, the internal upgrade will complete and information will begin processing for those affected integrations.
  10. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Upgrade from Backup File 

This feature is not applicable to Tasktop Cloud and is only available when upgrading from Tasktop Integration Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a prior version in cases where integrations were resumed individually during an upgrade, you must use the upgrade backup file available on the Advanced Configuration screen. The downloaded data in the file corresponds to artifacts that may have been modified when migrations were still running to ensure artifact updates aren't duplicated when restoring. 

(warning) Note: You must download the backup file from your Hub instance before beginning the steps to restore.

To use this feature, you will first need to download the upgrade backup file. This file can be downloaded on the 'Advanced Configuration' screen.

Click 'Download'

After clicking 'Download,' the following message will appear:

Download Upgrade Backup File Warning

Once the file has been downloaded, you will need to restore Tasktop to the prior version. Please see the section above for more details on how to restore to a prior version.

After restoring to the earlier version, you can then select the backup file you would like to import and click 'Upload.' 

Upload Upgrade Backup File

If the backup file is imported successfully, the following message will appear and your integrations will resume:

(warning) Note: If the backup file fails to upload, you will need to contact Tasktop support for further assistance.