Upgrading

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 and <install-location>\Tasktop\connectors\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.

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.

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 and <install-location>\Tasktop\connectors\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.

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.

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 and <install-location>\Tasktop\connectors\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.

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.

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 and <install-location>\Tasktop\connectors\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.

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.

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.and <install-location>\Tasktop\connectors\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.

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.