Accessing Settings

To access the 'Settings' screen, click the Settings button in the upper right corner of your screen

Click 'Settings'

From here, you'll be able to access things like polling interval configuration, extensions, license information, and more.

Change Detection Interval Configuration 

The Configuration section allows the administrator to change the polling frequency of the connected repositories.

Polling Interval Configuration

  • Change Detection Interval: The time between polling requests made by Tasktop to your external repositories to detect only changed artifacts. This defaults to 1 minute, but can be customized as desired.
    • Note: this global setting can be overridden with an integration-specific change detection interval, by updating the Change Detection settings for that integration

  • Full Scan Interval: The time between polling requests to detect changed artifacts, in which all artifacts that have previously synchronized in the integration are scanned.

    Not all changes to an artifact will register as a change. Some repositories do not mark items as changed when (for example) a relationship is added or an attachment has changed. These may not be picked up by regular Change Detection, but will be picked up by a Full Scan. You can review our connector docs to see types of updates that will require a full scan. The Full Scan Interval defaults to 24 hours on the Settings screen, but can be overridden with an integration-specific full scan interval, by updating the Change Detection settings for that integration

    Note that since the Full Scan only scans artifacts that have previously synchronized, artifacts that are newly eligible for synchronization due to updated artifact filtering or routing will not be picked up by the Full Scan. These artifacts will only be processed by clicking the 'process all artifacts' button, or when a new integration-eligible change is made to them.

    You can learn more about change detection and full scan styles in our FAQ here.
  • Integration Maximum Concurrency: This limits the number of events processed concurrently by each integration. Increasing this value will enable more artifact changes to flow concurrently, whereas decreasing this value will reduce the level of concurrent changes. Changing this value has the potential to affect the load on the end-points of an integration, and may have an adverse effect on performance if set too high. The default setting (10) should be used unless advised to change by Tasktop Support.

Email Notifications

To facilitate troubleshooting, you can configure automated email notifications for new errors and issues encountered in Tasktop. 

Emails will contain a count of new issues and errors (excluding 'ignored' errors) since the last email notification, and a link to the Activity screen to view the errors/issues. Emails will be sent only if a new error or issue occurs. 

Email Sample

To configure email notifications click '+Add Email Server' on the Settings screen (or 'Configure Notification Settings' if using Tasktop Cloud).

Click 'Add Email Server'

This will bring you to the Email Notifications screen.

Note: If you are using Tasktop Cloud, you will only see three fields available: To Email Address, Subject Prefix, and Notification Frequency.

Email Notifications Screen

The form requires that the following fields be filled out:

Basic Details

  • To Email Address: The email address that will receive the notifications.  This field is limited to one email address.
  • From Email Address: The email address listed in the 'sender address' (or 'from') field of notification emails sent by Tasktop.  In many cases, this will match the email whose settings are configured in the 'Email Server Settings' section below, though a different email (such as can be configured here.  If a user were to hit  'reply' on an email notification, this is the email the reply would be sent to.
  • Subject Prefix: The prefix appended to the subject line of the Error Notification emails.  This defaults to [Tasktop] but can be edited if needed.  This can help users filter email notifications from Tasktop based on prefix.
  • Tasktop Server URL: The URL used to access your instance of Tasktop.  This is used to construct links to errors and issues in the notification emails.
  • Notification Frequency: The frequency of email notifications.  Emails will contain a count of new issues and errors since the last notification and will only send if a new error or issue has occurred since the prior email.

Email Server Settings

These are the email server settings that allow Tasktop to send notifications.

  • Username (optional): Username for the authenticated SMTP server.
  • Password (optional): Password for the authenticated SMTP server.
  • SMTP Server: The SMTP host name of your mail server. 
  • SMTP Port: The SMTP Port number to use.
    • If Protocol = SMTP, the value for this will typically be 25.  
    • If Protocol = SMTPS, the value for this will typically be 465.
    • If Protocol = SMTP_STARTTLS, the value for this will typically be 587, but can also be port 25.
  • Connection Timeout: Specifies the maximum period, in seconds, that establishing an email server connection is permitted to take. This defaults to 60 seconds, which should cover most scenarios.
  • Protocol
    • SMTP: Basic unencrypted SMTP Protocol.  
    • SMTPS: A more advanced, encrypted SMTP Protocol (SMTP Secure), which will perform server certificate validation.
    • SMTP_STARTTLS: A modern protocol that wraps the unencrypted SMTP protocol in TLS (formerly known as SSL encryption), and will perform server certificate validation.  This will attempt the STARTTLS wrapper, but if it is not supported by the server, the client will fall back to basic SMTP.

(lightbulb) Google email users should select SMTP_STARTTLS.

Here's an example of a filled in form:

Email Notifications Form - Filled Out

You can test your email server settings by clicking the 'Test Connection' button in the upper right corner of the screen.

Once settings are filled in and the connection has been tested, click 'Save' to save your settings, and 'Turn On Notifications' to enable email notifications. 

Once saved, you will be able to turn email notifications on or off and to delete the notification settings from the Settings screen.  You can also click 'Configure Notification Settings' to modify your existing settings:

Update Email Notification Settings from Settings Screen

(lightbulb) Note: If an email notification fails, an issue will be surfaced on the Activity screen in Tasktop.


For troubleshooting purposes, Tasktop logs various events that the application performs.

There are two logging levels available:

  • Normal: This is sufficient for most scenarios. 
  • Troubleshooting: This setting provides more detailed logs.  Due to the large volume of logs created during Troubleshooting logging, this option has a time limit with a maximum of 24 hours. If Troubleshooting level is selected, the Normal logging level can be enabled at any time by clicking the 'Stop Troubleshooting Now' button.

Updating the logging levels immediately changes the logging granularity.  Tasktop does not need to be restarted for the change to take effect.

Default Logging Enabled

Logging with Normal logging enabled

Troubleshooting Logging Enabled

Troubleshooting logging level

Downloading Logs

Please reference the Troubleshooting page for instructions on downloading the logs as part of the Support and Usage Report.


Extensions add to Tasktop's basic functionality by facilitating processes such as custom data transformations, payload transformations, advanced person reconciliation, and state transitions.

You can create and save custom extensions for use in your integrations on the 'Settings' screen. To create and edit your extensions, click the 'Manage Extensions' button.

Below, you will find basic information about each extension type.  You can also see example extensions, and learn technical implementation details in the Extensions section.

Manage Extensions
Create New Extension
Select Extension Type

Custom Data Transformation 

Custom Data Transformation Extensions enable you to map fields to one another which do not have out-of-the-box transforms. You can apply this extension when updating your transform on the  Field Configuration screen.

Payload Transformation 

Payload Transformation Extensions enable you to take the payload sent in by your Gateway Collection and transform it into a format that Tasktop can accept. Once you have saved your extension, you can select it on the  Gateway Collection screen.

Person Reconciliation  

Tasktop comes with a default person reconciliation strategy ("Copy with Default Matching"), which matches based on name, ID, and/or e-mail. This strategy should cover most use cases.  If needed, you can also configure a custom Person Reconciliation Extension to match 'person' fields from one repository to another.  You can select the extension on the  Person Reconciliation screen during the Collection configuration process.

State Transition 

State Transition Extensions enable you to transition artifacts from one state to another according to a set workflow. The extension can be applied from the State Transition Sash on the Collection Configuration screen.


This feature is not applicable to Tasktop Cloud.

A license is required to run the application. Upon initial log-in, you will see that your product is currently un-licensed:

No License Set

Click 'Apply New License' to enter your license.

The Master Password must be set and the License must be entered before the application can be used.

Enter New License Key

On the license panel you can see:

  • License Type
  • Description
  • Maximum Users
  • Created Date
  • Expiration Date
  • Issuer
  • Licensee

LIcense Information

You will also see a warning if your license is expired:

Expired License

Should your license expire, in addition to seeing a warning on the Settings screen, you'll also see that an issue is surfaced on the Activity screen:

Error Message - Expired License

When your license is expired, you'll still be able to navigate within the Tasktop UI, but your integrations will be stopped from running. Note that though they will still display the Run or Stopped state they were in at the time your license expired, no artifacts will process in an integration until a new license is applied.

(lightbulb) Please consult your license agreement or contact your account representative if you have any questions about your license settings or usage policy.

Master Password Configuration

This feature is not applicable to Tasktop Cloud.

After installation, you will be prompted to set a Master Password.

Set Master Password Prompt

The Master Password is used to encrypt the credentials used in your repository connections and proxy settings, along with any other configuration values that are considered secret, which could include API keys and tokens. 256 bit AES encryption is used. Tasktop Integration Hub will automatically use the stored Master Password to decrypt repository credentials.

Normally you will not need to re-enter your Master Password.  However, if the stored Master Password is missing, or if you'd like to change your Master Password from the Settings screen, you will need to enter your current Master Password.

The Master Password is encrypted and stored separately from the encrypted repository credentials.  On Windows, the encrypted Master Password is stored in the Windows Registry, encrypted using the Windows Data Protection (DPAPI). On Linux, the encrypted Master Password is stored in the Home Directory of the User running Tasktop Integration Hub.

If desired, you can change or reset the Master Password from the 'Settings' page.  

  • Change Master Password: In order to change the Master Password, you must enter your current Master Password.  
  • Reset: If resetting the Master Password, you will not need to enter your current Master Password, but previously encrypted repository passwords will be lost, and must be provided after resetting.

Change or Reset Master Password

Move Routes Between Integrations 

There may be rare scenarios when you must move routes from an existing integration to another integration.  For example, you may have configured Tasktop incorrectly and mistakenly created multiple integrations which should be combined into one.  Or you could be upgrading Micro Focus (HPE) ALM, which requires moving projects from an instance running an old version of ALM to a server running a newer instance of ALM.  Since existing projects are moved to a completely new ALM instance with a different URL, users must create a new repository connection, collection(s), and integration(s) in Tasktop.  Once the new integration is created, existing routes must be migrated to prevent the risk of duplicate artifacts.  This feature will allow users to easily migrate routes from an existing integration to a new one.

To move routes from one integration to another, they must both:

  • be synchronize integrations
  • use the same artifact types
  • use the same repository connections (except for Micro Focus/HPE ALM connections used in an upgrade scenario)

(lightbulb) We recommend stopping both integrations before moving routes so that you can review your mappings and configuration before running.

To use this feature click 'Move Routes.'

Click 'Move Routes'

Select your source integration:

Select Source Integration

Then select your target integration:

Select Target Integration

Select the routes from the source integration that you'd like to move to the target integration.  Once moved, they will no longer exist in the source integration.  Click 'Move' in the upper right corner.

Select Routes and Click 'Move'

Review the pop-up message and if approved, click 'I understand...' and 'Move.'  This process may take some time.  Progress can be tracked on the Background Jobs tab of the Activity Screen.

Once the move is complete, review your integration configuration, field mappings, etc, before clicking 'run' on the target integration.

Import Artifact Pair Information 

Importing artifact pairs allows Tasktop Integration Hub to know about existing artifact pairs that were created by Tasktop Sync. This prevents duplicate artifacts from being created when you switch from using Tasktop Sync to Tasktop Integration Hub to administer your integrations. Please contact Tasktop Support for additional information on how to use this capability.

Storage Settings 

This feature is not applicable to Tasktop Cloud.

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 back-ups without having to stop Tasktop Integration Hub, and ensure that your Tasktop Integration Hub practices are consistent with your existing disaster and recovery process.  

(lightbulb) Please see our  Hardware Requirements to see which databases are supported for storing operational data.

Migrating from the Internal Database to an External Database

To migrate your Tasktop operational data from the internal database to an external database, click the 'Use External Database' button.

Click 'Use External Database'

Next, click 'Configure JDBC Driver' to select the JDBC driver for your database. 

Click 'Configure JDBC Driver'

To download the JDBC driver:

  • Microsoft SQL Server: The JDBC driver for Microsoft SQL Server can be downloaded from the Microsoft support site
    • Tasktop currently supports use of the 7.0.0.jre8 driver version.
  • MySQL Server: The JDBC driver for MySQL can be downloaded from the MySQL download site
  • OracleThe JDBC driver for Oracle can be downloaded from the Oracle support site.  Note that it is best if the Oracle JDBC driver that is used matches the version of the Oracle server that you are connecting to.
  • PostgreSQL: The JDBC driver for PostgreSQL can be downloaded from the PostgreSQL download site.

To upload the JDBC driver to Tasktop, a system administrator (a user with file system access to the machine that hosts Tasktop) must extract the *.jar file from the downloaded driver file and add the file to the designated directory:

  • On Windows, the default folder is C:\ProgramData\Tasktop\jdbc-drivers
  • On Linux, the jdbc-drivers folder can be found in the Tasktop installation directory
  • If needed, the user can change the location in which Tasktop looks for the files. This is done by changing the system property jdbc.drivers.path

Once the JDBC driver is uploaded, it can be selected from the 'Choose File' field on the Configure JDBC Driver pop-up.

Select JDBC Driver

Next, fill out the Database Connection credentials.

Authentication credentials must be in SQL server authentication mode (aka mixed-mode with SQL credentials).  Windows authentication mode is not supported.

Once the JDBC driver is successfully uploaded, enter the location, username, and password for your database.

Location formats are as follows:

You can click 'Test Connection' to confirm that your credentials have been accepted by Tasktop.  Once confirmed, click 'Save.'

You will see a warning message telling you that you are about to transfer to an External Database.  Review the entire message, ensuring that you have performed the recommended data back-up, and if approved select 'I understand...' and then 'Transfer.'

Transfer to External Database Warning

You will get a 'Database Transfer Completed' message once the transfer is complete.  You have now successfully transferred your operational data from Tasktop's internal database to your own external database.

Database Transfer Complete

Migrating from an External Database to a Different External Database

(warning) If you'd like to migrate your data from one external database to a different external database, please note that you will need to manually transfer the data from the current database to the new target database. If you do not manually transfer the data, Tasktop will not work properly once you switch to the target database settings.  Tasktop will not automatically transfer this data for you.

However, if you are simply updating the location or credentials of your current external database and will continue using the same database, you do not need to transfer any data. Tasktop will continue to work properly.

Once you are ready to update the database information, simply update the Location, Username, and/or Password fields in the Database Connection section, click 'Test Connection,' and then 'Save.'  Read the warning message that pops up, ensuring you have taken all necessary steps, and then click 'I understand...' and 'Save.'  

Moving between databases of the same type...

If you are migrating to a database of the same type (for example, moving from one MySQL database to a different MySQL database), transfer data from the old database to the new database and then simply update the Location, Username, and/or Password fields in the Database Connection section, click 'Test Connection,' and then 'Save.'  Read the warning message that pops up, ensuring you have taken all necessary steps, and then click 'I understand...' and 'Save.'  

Moving between databases of different types...

If you are migrating to a database of a different type (for example, moving from a MySQL database to an Oracle database), follow the instructions below:

  1. Create a new empty database in the new database
  2. Stop Tasktop
  3. Manually replace the jdbc driver jar in <program data>/Tasktop/drivers with the correct driver for the new database (not in <program data>/Tasktop/jdbc-drivers, because the new driver cannot be selected in the UI), and make sure it is named database-driver.jar 
  4. Manually edit <program data>/Tasktop/db/tasktop-db.json with the URL and credentials for the new database
  5. Start Tasktop
  6. Tasktop will create new empty tables in the new database
  7. Stop Tasktop
  8. Copy all the data from the tables in the old database to the tables in the new database, except the tables DATABASECHANGELOG and DATABASECHANGELOGLOCK (copying data for these two tables will cause errors)
  9. Start Tasktop

If your Database Transfer Fails or is Aborted

If your database transfer fails or is aborted, Tasktop will continue to use its internal database to store operational data.  The internal database is not cleared until a successful transfer is completed, so you should not notice any change in performance. 

However, we do recommend reviewing the external database and clearing any data and tables that were created as part of the failed data transfer before starting the transfer process again.

Overriding Database Access

In order to prevent risk of collisions, duplicates, and other errors, Tasktop has functionality to ensure that multiple Tasktop instances are not able to run on the same operational database.  If you connect your instance to a database that is already in use by Tasktop (note that this is not recommended), upon start-up of the new instance, the prior instance will lose database access and stop processing events. When you log on to the prior instance, you will see an error message prompting you to either update your credentials to connect to a different database, or to override database access.  If you override database access, this means that the other instance of Tasktop will lose access to that database.

When overriding, be sure to confirm that no other Tasktop instance is using the database before moving forward. If another Tasktop instance is actively using the database, it is recommended that you shut down the other instance of Tasktop before proceeding.

Override Database Access Message