Standard Repository Connection

What is a Repository?

Repository

A repository is any system that houses the artifacts that can be used in an integration. Repositories can be systems used as part of the software delivery process, like MIcro Focus (HPE ALM), CA Agile Central, Jira, etc., or repositories can be more generic databases, like MySQL or Oracle.

A repository connection is a connection to a specific instance of a given repository that permits Tasktop to communicate with that repository. To configure a repository connection, users will need to provide base credentials such as a server URL, a username, and a password.

standard repository is software lifecycle tool such as Jira or ALM that contain artifacts such as defects or requirements.

Video Tutorial

Check out the video below to learn how to create a new repository connection:

Before You Begin

  • When you start up Tasktop, you will be prompted to log in.  Please review the User Management section for instructions on how to log in and manage your user accounts.
  • Next, you will be prompted to set a Master Password, which will be used to encrypt your repository credentials.
  • Before connecting to your repository, make sure that you have applied your license on the Settings screen. You can learn how to apply your license here.

How to Connect to a Standard Repository

Creating a New Connection

To create a repository connection, select 'Repositories' at the top of the screen

Click 'Repositories'

Click the '+ New Repository Connection' button

Click  New Repository Connection

Click the logo of the repository you would like to connect to:

Select Repository


Uploading External Files 

For certain repositories, such as Microsoft Azure DevOps Server (TFS), external files must be uploaded before navigating to the New Repository Connection screen.  If so, you will see a screen similar to the one below.  If you do not see this screen, proceed to the steps listed below in the 'New Repository Connection Screen' section.

External Files Required

To upload the files, a system administrator (a user with file system access to the machine that hosts Tasktop) must add the files to the designated directory:

  • On Windows, the default folder is C:\ProgramData\Tasktop\connector-requirements
  • On Linux, the connector-requirements 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 connector.requirements.path

Once uploaded, select the file from the options available and click 'Use File.'

New Repository Connection Screen

Next, you will be lead to the New Repository Connection screen.

To connect to a repository, you must populate the following fields:

  • Label: This is the name you will give to your Repository Connection. This is how it will be referenced throughout the Tasktop Application.
  • Location: This is the URL used to access the repository.
  • Authentication Details (see authentication section below for more details).

You will also notice a 'Connection Security' checkbox.  This will default to being un-checked (requiring secure connections).  If unchecked, your connection must start with HTTPS and have SSL certificate validation enabled.  If either condition is not met, Tasktop will not connect and provide an error message.  If you choose to check the 'Allow insecure connections...' checkbox, these restrictions will be lifted.  If doing so, please ensure that that configuration aligns with your organization's security policy and the associated risks are understood and accepted.

Note: Tasktop Cloud users must connect to external repositories via HTTPS.

(lightbulb) You may see additional fields on the repository connection screen depending on which repository you are connecting to. See our Connector Documentation for repository-specific information.

New Repository Connection Screen

Authentication

We recommend that you create a new user within your external tool, to be used only for your Tasktop integration. This is the user information you will enter when setting up your repository connection within Tasktop Integration Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization. 

In general, your Tasktop user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Please see our Connector Documentation for repository-specific information regarding user permissions.

Your user should have a secure password.  Please be aware that Tasktop will not allow you to save a repository connection utilizing a weak password, such as 'tasktop.'

For most repositories, you will see a username and password field in the Authentication section.  However, some repositories include additional Authentication options.

Standard Authentication

For most scenarios, you will select 'Standard' Authentication.' This is where you will enter the username and password used to access the repository. We recommend creating login credentials specifically for Tasktop to access your repository.

Standard Authentication

SSO Authentication

If you connect to a repository utilizing CA SSO authentication, you can select one of the additional authentication options offered.

Tasktop currently supports the following SSO implementations:

  • CA Siteminder/CA Single Sign-On (HTTP POST)
  • CA Siteminder/CA Single Sign-On (Login Form)
  • Script (HTTP cookies)
  • X.509 Certificate
HTTP POST

The HTTP Post option, pictured below, will generate the authentication form for you to fill in. Only the first 3 fields are required.

SSO Authentication on Repository Screen

Login Form

The 'Single Sign-On (Login Form)' option, pictured below, will allow you to enter the URL for your SSO log-in form.

SSO Authentication - Login Form

 Once the URL is entered, Tasktop will auto-generate the fields that must be populated to connect to the repository.

 

SSO Login Form Generated
Script (HTTP cookies)

To use the Script (HTTP cookies) authentication method, a system administrator (a user with file system access to the machine that hosts Tasktop) must add the script(s) to the designated directory:

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

Once uploaded, select the script from the options available under the 'Cookie Script' field.  The script will be executed by the machine that hosts Tasktop.  The script is stored in the Tasktop database, but is written to disk upon Tasktop startup and deleted from disk upon Tasktop shutdown.

Since Tasktop supports both Windows and Linux, please ensure that your script is able to be executed on the appropriate operating system: .bat for windows or shell script for Linux. 

The Cookie Script will be executed and the standard out (and standard error) must read as a \n separated list of key/value pairs themselves separated by Cookie Key/Value Delimiter (default is’=‘). 

The Cookie Domain and Cookie Path arguments will then be used in the construction of a cookie for each of those key values pairs.

(lightbulb) Note: Since Tasktop creates a copy of the script when the repository configuration is saved, this means that changing the script in the directory will have no direct effect on existing repositories.  For changes to a script to take effect, the user must go to the target repository connection and update the configuration.

Script (HTTP cookies) Authentication on Repository Screen

 X.509 Certificate

To use the X.509 Certificate authentication method, select the X.509 Certificate to upload from your local machine. The certificate is stored in the Tasktop database, but is written to disk upon Tasktop startup and deleted from disk upon Tasktop shutdown.

 

X.509 Certificate Selected
 
Custom Authentication

Some repositories allow for additional authentication methods.  Please see our Connector Documentation for repository-specific information regarding authentication methods.

Proxy Server

If Tasktop is installed behind a firewall, you may need to connect to external repositories (e.g. hosted or cloud ALM tools) through a proxy. To create a connection to such external repositories in Tasktop, you can make Tasktop connect through your proxy by configuring the proxy settings when creating a new repository connection. It is recommended to create login credentials specifically for Tasktop on the proxy server.

(lightbulb) Note that the Proxy Location must be a URL in order for the proxy connection to work. If a .pac script is used in your browser, you will need to open the script and find the URL/port to enter in the Location field.

To use a proxy server, check the 'user proxy server' box and fill in your proxy details in the 'Proxy Server' section on the New Repository Screen:

Proxy Server Configuration


Additional Settings 

(warning) In general, it is recommended that you do not configure the Additional Settings unless you have consulted with Tasktop Support.

Additional Settings 

Repository Query

If you plan to utilize a repository query, select the checkbox here.

(warning) Repository Queries are advanced functionality, and should only be used when you are truly unable to filter as desired using the built-in Tasktop functionality of Repositories, Collections, and Artifact Filtering. You can learn more about repository queries here.

Event Rate Limit 

The Event Rate Limit can be used to mitigate scenarios where an external repository is temporarily receiving an excessive API call rate over short periods of time.  It does this by limiting the number of events processed per minute by Tasktop for that repository.  Events include Tasktop processes such as artifact retrieval, artifact update, and change detection queries.  On average, an event consists of about 3-10+ API calls, but this is highly dependent on the specific repository.  

When setting an Event Rate Limit, you can choose to limit:

  • All events
  • Only full scan events: if this is selected, only low priority events occurring during a full scan will be limited.  High priority events, such as artifact updates, will continue without impact.

Note that the rate set is a maximum rate; Tasktop may process items at a lower rate depending on the event load.

Tasktop's default event rate limit is applied to full scan (observe) events only, at 200 events per minute.

(warning) Caution should be used when setting this value.  The ideal Event Rate Limit is highly dependent on each customer's unique environment. Determining the appropriate value is best achieved through experimentation, using feedback from performance monitoring to tune the value, and making adjustments as necessary. Setting the value too low when there is a large number of projects configured in your collections and a low Change Detection Polling Interval setting can potentially cause Tasktop to be unable to process artifact changes.

Concurrency Limit 

The Concurrency Limit is set at the Repository level, and it limits how much work Tasktop can do in parallel in that repository. It does this by limiting the number of concurrent tasks where the connection is used. We recommend leaving this field blank/set to the default (having no specified limit).

If customers notice that Tasktop is placing too high a load on their repository, we recommend first modifying the Event Rate Limit.  If that is insufficient, or if the source of the high server load is specifically due to having too many open connections on the external repository, the Concurrency Limit can be modified.  We recommend starting with a value between 3-10 and engaging with support to determine an appropriate value for your unique environment.

(warning) Caution should be used when setting this value.  The ideal Concurrency Limit is highly dependent on each customer's unique environment. Determining the appropriate value is best achieved through experimentation, using feedback from performance monitoring to tune the value, and making adjustments as necessary. Setting the value too low when there is a large number of projects configured in your collections and a low Change Detection Polling Interval setting can potentially cause Tasktop to be unable to process artifact changes.

Testing Your Repository Connection

To test your repository connection, click the 'Test Connection' button on the Repository Connection screen, or click the icon on the Repositories screen.

'Test Connection' Button

Test Connection from Repositories Screen

You will see a success or failure message to confirm whether Tasktop was able to connect to your repository.

Successful Connection Message

When your repository fails to connect, you will also see an error message at the bottom of the screen with additional details on the source of the failure:

Failed Connection