Skip to main content
Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

Upgrading

  1. Last updated
  2. Save as PDF
You are viewing content for Planview Hub version .

This page is not applicable to Planview Hub Cloud.

When upgrading from a version earlier than 23.2.0 with Keycloak customization:

  • Refer to the properties table here to update the Keycloak Jboss properties.

When upgrading from earlier versions to 21.1.x:

  • As 21.1.x is a checkpoint release, be aware that you must upgrade to version 21.1.x before upgrading to a later version.
  • If you do not follow instructions here, you may encounter issues with artifact association management that prevent you from viewing and deleting artifact pairs.
  • Note: Be aware that upgrading to 21.1.x from an earlier version may take longer than usual.

Upgrading

Before you Upgrade

Before upgrading Planview Hub, be sure to do the following:

  1. Shut down Hub and afterwards follow the backup instructions. The first time that Hub 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 Hub is upgraded, a service-downtime for the Hub 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.
    • To understand implications of Hub downtime, please see here.
  4. Please review the release notes for all Planview Hub versions that have been released after the version you are upgrading from. Ensure that any upgrade steps outlined in the release notes are followed.

Windows

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

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

  • Screenshot 2023-07-19 at 2.25.09 PM.png

  • Backup as described here.

  • Run the installer of the new version of Planview Hub.

  • Re-apply Tomcat/Keycloak configurations.

    • Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the new properties file can be found here.
    • Upgrading from versions earlier than 21.1:
      • If any configuration was applied to exclusion-paths property in the web.xml, it needs to be migrated to the tasktop-hub.properties file. See the following example:
        • Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file.
        • <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>

          Place them in the tasktop-hub.properties file.

          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions

           Upgrading from version 20.4 and later:

          • No action needs to be taken. Tomcat/Keycloak configurations will be applied automatically. 

  1. If you have connected to the Microsoft Azure DevOps (formerly 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 Planview Hub is started up again, navigate to the Azure DevOps repository connection screen. There, you will see instructions on how to provide the updated SDK and CLC files to Planview Hub by adding them to the connector-requirements directory on the machine that hosts Planview Hub.

    3. Restart Planview Hub after uploading the files.

  2. Start Planview.

  3. 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 Azure DevOps, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the Azure DevOps 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.
  4. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Linux

  • Shut down Hub and Keycloak.

  • Back up as described here.

  • Run the Linux installer. Follow the instructions on the Installation page.

  • Re-apply the Tomcat configuration.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in web.xml, it will need to be migrated to the tasktop-hub.properties file. See the following example: 
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file: 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file: 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. If any customization has been applied to the tasktop-hub.properties file, copy it into the new installation folder <install-location>/tasktop.

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

  • 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 Hub 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 Hub by adding them to the connector-requirements directory on the machine that hosts Hub.  

    3. Restart Hub after uploading the files.

  • Start Hub.

  • 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.
  1. 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 only available when upgrading from Planview Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a previous 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. 

Note: You must download the backup file from your Planview 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.

Screenshot 2023-07-19 at 2.30.16 PM.png

After clicking Download, the following message will appear:

Screenshot 2023-07-19 at 2.32.52 PM.png

Once the file has been downloaded, you will need to restore Hub to the prior version. Please see here 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.

Screenshot 2023-07-19 at 2.36.35 PM.png

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

Screenshot 2023-07-19 at 2.38.20 PM.png

Note: If the backup file fails to upload, you will need to contact customer care for further assistance.

When upgrading from a version earlier than 23.2.0 with Keycloak customization:

  • Refer to the properties table here to update the Keycloak Jboss properties.

When upgrading from earlier versions to 21.1.x:

  • As 21.1.x is a checkpoint release, be aware that you must upgrade to version 21.1.x before upgrading to a later version.
  • If you do not follow instructions here, you may encounter issues with artifact association management that prevent you from viewing and deleting artifact pairs.
  • Note: Be aware that upgrading to 21.1.x from an earlier version may take longer than usual.

Upgrading

Before you Upgrade

Before upgrading Planview Hub, be sure to do the following:

  1. Shut down Hub and afterwards follow the backup instructions. The first time that Hub 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 Hub is upgraded, a service-downtime for the Hub 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.
    • To understand implications of Hub downtime, please see here.
  4. Please review the release notes for all Planview Hub versions that have been released after the version you are upgrading from. Ensure that any upgrade steps outlined in the release notes are followed.

Windows

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

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

  • Screenshot 2023-07-19 at 2.25.09 PM.png

  • Backup as described here.

  • Run the installer of the new version of Planview Hub.

  • Re-apply Tomcat/Keycloak configurations.

    • Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the new properties file can be found here.
    • Upgrading from versions earlier than 21.1:
      • If any configuration was applied to exclusion-paths property in the web.xml, it needs to be migrated to the tasktop-hub.properties file. See the following example:
        • Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file.
        • <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>

          Place them in the tasktop-hub.properties file.

          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions

           Upgrading from version 20.4 and later:

          • No action needs to be taken. Tomcat/Keycloak configurations will be applied automatically. 

  1. If you have connected to the Microsoft Azure DevOps (formerly 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 Planview Hub is started up again, navigate to the Azure DevOps repository connection screen. There, you will see instructions on how to provide the updated SDK and CLC files to Planview Hub by adding them to the connector-requirements directory on the machine that hosts Planview Hub.

    3. Restart Planview Hub after uploading the files.

  2. Start Planview.

  3. 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 Azure DevOps, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the Azure DevOps 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.
  4. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Linux

  • Shut down Hub and Keycloak.

  • Back up as described here.

  • Run the Linux installer. Follow the instructions on the Installation page.

  • Re-apply the Tomcat configuration.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in web.xml, it will need to be migrated to the tasktop-hub.properties file. See the following example: 
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file: 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file: 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. If any customization has been applied to the tasktop-hub.properties file, copy it into the new installation folder <install-location>/tasktop.

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

  • 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 Hub 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 Hub by adding them to the connector-requirements directory on the machine that hosts Hub.  

    3. Restart Hub after uploading the files.

  • Start Hub.

  • 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.
  1. 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 only available when upgrading from Planview Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a previous 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. 

Note: You must download the backup file from your Planview 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.

Screenshot 2023-07-19 at 2.30.16 PM.png

After clicking Download, the following message will appear:

Screenshot 2023-07-19 at 2.32.52 PM.png

Once the file has been downloaded, you will need to restore Hub to the prior version. Please see here 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.

Screenshot 2023-07-19 at 2.36.35 PM.png

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

Screenshot 2023-07-19 at 2.38.20 PM.png

Note: If the backup file fails to upload, you will need to contact customer care for further assistance.

When upgrading from a version earlier than 23.2.0 with Keycloak customization:

  • Refer to the properties table here to update the Keycloak Jboss properties.

When upgrading from earlier versions to 21.1.x:

  • As 21.1.x is a checkpoint release, be aware that you must upgrade to version 21.1.x before upgrading to a later version.
  • If you do not follow instructions here, you may encounter issues with artifact association management that prevent you from viewing and deleting artifact pairs.
  • Note: Be aware that upgrading to 21.1.x from an earlier version may take longer than usual.

Upgrading

Before you Upgrade

Before upgrading Planview Hub, be sure to do the following:

  1. Shut down Hub and afterwards follow the backup instructions. The first time that Hub 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 Hub is upgraded, a service-downtime for the Hub 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.
    • To understand implications of Hub downtime, please see here.
  4. Please review the release notes for all Planview Hub versions that have been released after the version you are upgrading from. Ensure that any upgrade steps outlined in the release notes are followed.

Windows

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

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

  • Screenshot 2023-07-19 at 2.25.09 PM.png

  • Backup as described here.

  • Run the installer of the new version of Planview Hub.

  • Re-apply Tomcat/Keycloak configurations.

    • Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the new properties file can be found here.
    • Upgrading from versions earlier than 21.1:
      • If any configuration was applied to exclusion-paths property in the web.xml, it needs to be migrated to the tasktop-hub.properties file. See the following example:
        • Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file.
        • <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>

          Place them in the tasktop-hub.properties file.

          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions

           Upgrading from version 20.4 and later:

          • No action needs to be taken. Tomcat/Keycloak configurations will be applied automatically. 

  1. If you have connected to the Microsoft Azure DevOps (formerly 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 Planview Hub is started up again, navigate to the Azure DevOps repository connection screen. There, you will see instructions on how to provide the updated SDK and CLC files to Planview Hub by adding them to the connector-requirements directory on the machine that hosts Planview Hub.

    3. Restart Planview Hub after uploading the files.

  2. Start Planview.

  3. 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 Azure DevOps, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the Azure DevOps 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.
  4. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Linux

  • Shut down Hub and Keycloak.

  • Back up as described here.

  • Move the old Hub installation folder to an archive folder.

  • Unzip the new Hub distribution archive.

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

  • Restore DB.

    1. If you are using Hub'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 Hub's configuration, copy the tasktop-db.json file, and the /tasktop/db from the old installation into the new installation folder <install-location>/tasktop.

  • Re-apply Tomcat/Keycloak configurations.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in web.xml, it will need to be migrated to the tasktop-hub.properties file. See the following example: 
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file: 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file: 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. If any customization has been applied to the tasktop-hub.properties file, copy it into the new installation folder <install-location>/tasktop.

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

    1. Restore the keycloak database to<install-location>/keycloak/data/h2/keycloak.h2.db after installation.

      1. Note: If upgrading from 23.1 or earlier, the database used to be found in <install-location>/keycloak/standalone/data/keycloak.h2.db.

  • 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 Hub 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 Hub by adding them to the connector-requirements directory on the machine that hosts Hub.  

    3. Restart Hub after uploading the files.

  • Start Hub.

  • 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.
  1. 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 only available when upgrading from Planview Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a previous 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. 

Note: You must download the backup file from your Planview 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.

Screenshot 2023-07-19 at 2.30.16 PM.png

After clicking Download, the following message will appear:

Screenshot 2023-07-19 at 2.32.52 PM.png

Once the file has been downloaded, you will need to restore Hub to the prior version. Please see here 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.

Screenshot 2023-07-19 at 2.36.35 PM.png

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

Screenshot 2023-07-19 at 2.38.20 PM.png

Note: If the backup file fails to upload, you will need to contact customer care for further assistance.

When upgrading from a version earlier than 23.2.0 with Keycloak customization:

  • Refer to the properties table here to update the Keycloak Jboss properties.

When upgrading from earlier versions to 21.1.x:

  • As 21.1.x is a checkpoint release, be aware that you must upgrade to version 21.1.x before upgrading to a later version.
  • If you do not follow instructions here, you may encounter issues with artifact association management that prevent you from viewing and deleting artifact pairs.
  • Note: Be aware that upgrading to 21.1.x from an earlier version may take longer than usual.

Upgrading

Before you Upgrade

Before upgrading Planview Hub, be sure to do the following:

  1. Shut down Hub and afterwards follow the backup instructions. The first time that Hub 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 Hub is upgraded, a service-downtime for the Hub 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.
    • To understand implications of Hub downtime, please see here.
  4. Please review the release notes for all Planview Hub versions that have been released after the version you are upgrading from. Ensure that any upgrade steps outlined in the release notes are followed.

Windows

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

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

  • Screenshot 2023-07-19 at 2.25.09 PM.png

  • Backup as described here.

  • Run the installer of the new version of Planview Hub.

  • Re-apply Tomcat/Keycloak configurations.

    • Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the new properties file can be found here.
    • Upgrading from versions earlier than 21.1:
      • If any configuration was applied to exclusion-paths property in the web.xml, it needs to be migrated to the tasktop-hub.properties file. See the following example:
        • Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file.
        • <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>

          Place them in the tasktop-hub.properties file.

          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions

           Upgrading from version 20.4 and later:

          • No action needs to be taken. Tomcat/Keycloak configurations will be applied automatically. 

  1. If you have connected to the Microsoft Azure DevOps (formerly 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 Planview Hub is started up again, navigate to the Azure DevOps repository connection screen. There, you will see instructions on how to provide the updated SDK and CLC files to Planview Hub by adding them to the connector-requirements directory on the machine that hosts Planview Hub.

    3. Restart Planview Hub after uploading the files.

  2. Start Planview.

  3. 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 Azure DevOps, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the Azure DevOps 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.
  4. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Linux

  • Shut down Hub and Keycloak.

  • Back up as described here.

  • Move the old Hub installation folder to an archive folder.

  • Unzip the new Hub distribution archive.

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

  • Restore DB.

    1. If you are using Hub'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 Hub's configuration, copy the tasktop-db.json file, and the /tasktop/db from the old installation into the new installation folder <install-location>/tasktop.

  • Re-apply Tomcat/Keycloak configurations.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in web.xml, it will need to be migrated to the tasktop-hub.properties file. See the following example: 
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file: 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file: 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. If any customization has been applied to the tasktop-hub.properties file, copy it into the new installation folder <install-location>/tasktop.

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

    1. Restore the keycloak database to<install-location>/keycloak/data/h2/keycloak.h2.db after installation.

      1. Note: If upgrading from 23.1 or earlier, the database used to be found in <install-location>/keycloak/standalone/data/keycloak.h2.db.

  • 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 Hub 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 Hub by adding them to the connector-requirements directory on the machine that hosts Hub.  

    3. Restart Hub after uploading the files.

  • Start Hub.

  • 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.
  1. 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 only available when upgrading from Planview Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a previous 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. 

Note: You must download the backup file from your Planview 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.

Screenshot 2023-07-19 at 2.30.16 PM.png

After clicking Download, the following message will appear:

Screenshot 2023-07-19 at 2.32.52 PM.png

Once the file has been downloaded, you will need to restore Hub to the prior version. Please see here 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.

Screenshot 2023-07-19 at 2.36.35 PM.png

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

Screenshot 2023-07-19 at 2.38.20 PM.png

Note: If the backup file fails to upload, you will need to contact customer care for further assistance.

 

When upgrading from a version earlier than 23.2.0 with Keycloak customization:

  • Refer to the properties table here to update the Keycloak Jboss properties.

When upgrading from earlier versions to 21.1.x:

  • As 21.1.x is a checkpoint release, be aware that you must upgrade to version 21.1.x before upgrading to a later version.
  • If you do not follow instructions here, you may encounter issues with artifact association management that prevent you from viewing and deleting artifact pairs.
  • Note: Be aware that upgrading to 21.1.x from an earlier version may take longer than usual.

Upgrading

Before you Upgrade

Before upgrading Planview Hub, be sure to do the following:

  1. Shut down Hub and afterwards follow the backup instructions. The first time that Hub 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 Hub is upgraded, a service-downtime for the Hub 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.
    • To understand implications of Hub downtime, please see here.
  4. Please review the release notes for all Planview Hub versions that have been released after the version you are upgrading from. Ensure that any upgrade steps outlined in the release notes are followed.

Windows

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

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

  • Screenshot 2023-07-19 at 2.25.09 PM.png

  • Backup as described here.

  • Run the installer of the new version of Planview Hub.

  • Re-apply Tomcat/Keycloak configurations.

    • Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the new properties file can be found here.
    • Upgrading from versions earlier than 21.1:
      • If any configuration was applied to exclusion-paths property in the web.xml, it needs to be migrated to the tasktop-hub.properties file. See the following example:
        • Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file.
        • <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>

          Place them in the tasktop-hub.properties file.

          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions

           Upgrading from version 20.4 and later:

          • No action needs to be taken. Tomcat/Keycloak configurations will be applied automatically. 

  1. If you have connected to the Microsoft Azure DevOps (formerly 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 Planview Hub is started up again, navigate to the Azure DevOps repository connection screen. There, you will see instructions on how to provide the updated SDK and CLC files to Planview Hub by adding them to the connector-requirements directory on the machine that hosts Planview Hub.

    3. Restart Planview Hub after uploading the files.

  2. Start Planview.

  3. 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 Azure DevOps, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the Azure DevOps 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.
  4. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Linux

  • Shut down Hub and Keycloak.

  • Back up as described here.

  • Move the old Hub installation folder to an archive folder.

  • Unzip the new Hub distribution archive.

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

  • Restore DB.

    1. If you are using Hub'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 Hub's configuration, copy the tasktop-db.json file, and the /tasktop/db from the old installation into the new installation folder <install-location>/tasktop.

  • Re-apply Tomcat/Keycloak configurations.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in web.xml, it will need to be migrated to the tasktop-hub.properties file. See the following example: 
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file: 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file: 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. If any customization has been applied to the tasktop-hub.properties file, copy it into the new installation folder <install-location>/tasktop.

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

    1. Restore the keycloak database to<install-location>/keycloak/data/h2/keycloak.h2.db after installation.

      1. Note: If upgrading from 23.1 or earlier, the database used to be found in <install-location>/keycloak/standalone/data/keycloak.h2.db.

  • 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 Hub 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 Hub by adding them to the connector-requirements directory on the machine that hosts Hub.  

    3. Restart Hub after uploading the files.

  • Start Hub.

  • 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.
  1. 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 only available when upgrading from Planview Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a previous 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. 

Note: You must download the backup file from your Planview 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.

Screenshot 2023-07-19 at 2.30.16 PM.png

After clicking Download, the following message will appear:

Screenshot 2023-07-19 at 2.32.52 PM.png

Once the file has been downloaded, you will need to restore Hub to the prior version. Please see here 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.

Screenshot 2023-07-19 at 2.36.35 PM.png

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

Screenshot 2023-07-19 at 2.38.20 PM.png

Note: If the backup file fails to upload, you will need to contact customer care for further assistance.

When upgrading from a version earlier than 23.2.0 with Keycloak customization:

  • Refer to the properties table here to update the Keycloak Jboss properties.

When upgrading from earlier versions to 21.1.x:

  • As 21.1.x is a checkpoint release, be aware that you must upgrade to version 21.1.x before upgrading to a later version.
  • If you do not follow instructions here, you may encounter issues with artifact association management that prevent you from viewing and deleting artifact pairs.
  • Note: Be aware that upgrading to 21.1.x from an earlier version may take longer than usual.

Upgrading 

Before you Upgrade

Before upgrading Planview Hub, be sure to do the following:

  1. Shut down Hub and afterwards follow the backup instructions. The first time that Hub 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 Hub is upgraded, a service-downtime for the Hub 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.
    • To understand implications of Hub downtime, please see here.
  4. Please review the release notes for all Planview Hub versions that have been released after the version you are upgrading from. Ensure that any upgrade steps outlined in the release notes are followed.

Windows

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

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

    Stop Tasktop

  • Backup as described here.

  • Run the installer of the new version of Planview Hub.

  • Re-apply Tomcat/Keycloak configurations.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the new properties file can be found here.
      2. Apply all customizations that have been done in (<install-location>/keycloak/standalone/configuration/standalone.xml) to the tasktop-hub.properties file. More details about translating configurations from standalone.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in the web.xml, it needs to be migrated to the tasktop-hub.properties file. See the following example:
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file. 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file. 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. No action needs to be taken. Tomcat/Keycloak configurations will be applied automatically. 

  1. If you have connected to the Azure DevOps 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 Planview Hub is started up again, navigate to the Azure DevOps repository connection screen. There, you will see instructions on how to provide the updated SDK and CLC files to Planview Hub by adding them to the connector-requirements directory on the machine that hosts Planview Hub.

    3. Restart Planview Hub after uploading the files.

  2. Start Hub.

  3. 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 Azure DevOps, you may see issues related to unsatisfied connector requirements since you may need to upload new versions of the Azure DevOps 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.
  4. If you are upgrading from a version earlier than 19.4.1, please see details regarding the Troubleshooting User here.

Linux

  • Shut down Hub and Keycloak.

  • Back up as described here.

  • Move the old Hub installation folder to an archive folder.

  • Unzip the new Hub distribution archive.

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

  • Restore DB.

    1. If you are using Hub'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 Hub's configuration, copy the tasktop-db.json file, and the /tasktop/db from the old installation into the new installation folder <install-location>/tasktop.

  • Re-apply Tomcat/Keycloak configurations.

    1. Upgrading from versions earlier than 20.4:
      1. Apply all customizations done in (<install-location>/container/conf/server.xml) to the tasktop-hub.properties file. More details about translating configurations from server.xml to the properties file can be found here.
      2. Apply all customizations done in (<install-location>/keycloak/standalone/configuration/standalone.xml) to the tasktop-hub.properties file. More details about translating configurations from standalone.xml to the properties file can be found here.
    2. Upgrading from versions earlier than 21.1:
      1. If any configuration was applied to exclusion-paths property in web.xml, it will need to be migrated to the tasktop-hub.properties file. See the following example: 
        1. Copy /auth/realms/Tasktop/broker/saml and /auth/realms/Tasktop/login-actions from the web.xml file: 
          1. <filter>
    <filter-name>CORSFilter</filter-name>
    <filter-class>com.tasktop.servlet.cors.CorsHeaderScrutinyServletFilter</filter-class>
    <init-param>
        <description>A comma or whitespace separated list of paths to exclude from the CORSFilter</description>
        <param-name>exclusion-paths</param-name>
        <param-value>
            /auth/realms/Tasktop/broker/saml
            /auth/realms/Tasktop/login-actions
        </param-value>
    </init-param>
</filter>
        2. Place them in the tasktop-hub.properties file: 
          1. # A list of paths that will be excluded from the CORS verification.
# This list is separated by comma. Example: /first-path,/second-path
hub.security.cors.exclusionPaths=/auth/realms/Tasktop/broker/saml,/auth/realms/Tasktop/login-actions
    3. Upgrading from version 20.4 and later:
      1. If any customization has been applied to the tasktop-hub.properties file, copy it into the new installation folder <install-location>/tasktop.

  • Restore Keycloak (user management) configuration. Note that keycloak's database and Hub'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 here.

      1. Note: You must create an account to access these.

  • 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 Hub 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 Hub by adding them to the connector-requirements directory on the machine that hosts Hub.  

    3. Restart Hub after uploading the files.

  • Start Hub.

  • 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.
  1. 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 only available when upgrading from Planview Hub versions 20.1 and later. To utilize this feature, please see the section below.

To restore Hub to a previous 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. 

Note: You must download the backup file from your Planview 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.

Screenshot 2023-07-19 at 2.30.16 PM.png

After clicking Download, the following message will appear:

Screenshot 2023-07-19 at 2.32.52 PM.png

Once the file has been downloaded, you will need to restore Hub to the prior version. Please see here 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.

Screenshot 2023-07-19 at 2.36.35 PM.png

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

Screenshot 2023-07-19 at 2.38.20 PM.png

Note: If the backup file fails to upload, you will need to contact customer care for further assistance.