Skip to main content
Planview Customer Success Center

Digital.ai Agility

89883000.png

 


 

Overview

To optimize Agile project management, Digital.ai Agility (formerly CollabNet VersionOne) users need to see the data being worked on in third party tools. Planview Hub meets this need by connecting Digital.ai Agility to other tools in the lifecycle, allowing all members of the team to collaborate on shared artifacts and reducing the disconnect between Agile planning and the other members of the extended software development and delivery team.

With Hub, you can integrate Digital.ai Agility with other Agile planning tools, requirements management tools, defect and test management, PPM, and even the help desk, right out of the box. Synchronize defects, requirements, stories, tasks, epics, and more. There’s no custom coding, it’s a straightforward process using our visual configuration tool. Once Hub is in place, you’ll want to integrate more and more of your tools. It’s easy to do – start small, expand over time.

Key Features and Benefits

  • Synchronizes artifacts across the lifecycle, allowing information to flow freely between Digital.ai and other tools.
  • Improve team collaboration by connecting Digital.ai to third party tools and allow artifacts to be synchronized across the lifecycle.
  • Support cross-tool traceability and reporting, removing the need for manual processes and spreadsheets.

Demo Videos

 


 

Connector Setup Details

This section describes the basic steps needed to prepare your Digital.ai instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview 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 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.

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

See instructions on how to create a new user in Digital.ai.

List of minimal user permissions:

  • User should be given the 'System Admin' role.
  • User should be assigned as a 'Project Member' to all projects.

Connecting to the Digital.ai Agility Repository

Standard Authentication

Required Fields:

  • Location/Connection URL 
  • Username 
  • Password
    • If you are using Access Token Authentication, fill out your username and then enter your access token in the Access Token field, but do not enter a Password.
    • Otherwise, enter your username and password and leave the Access Token field blank. If you are using NTLM (Windows Integrated Authentication), enter your NTLM username in the format domain\username.

Optional Fields:

  • Access Token: If you are using Access Token Authentication, fill out your username and then enter your access token in this field, but do not enter a Password. Otherwise, leave this field blank.
  • Enable Legacy NTLM Authentication: If checked, NTLM authentication scheme support will be enabled when authenticating to the repository. See details here.
    • When unchecked, the NTLM authentication scheme support will be disabled and the connector will use basic authentication.
    • Note: This field only applies to on-premise instances of Digital.ai Agility.
  • Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
    • Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment. 
  • Connection Security: If checked, insecure connections to this repository will be allowed. See details here.

Screenshot 2023-10-11 at 5.03.33 PM.png

Learn more about how to set up your repository in Planview Hub here. 

 

           

Creating a Proxy Association Attribute (Tasktop Sync)

What is Proxy Association Attribute?

A custom string attribute is recommended to be used as the proxy association storage. Tasktop Sync needs to keep track of the association between a task and its proxy task. The association is persisted in a proxy store allowing the synchronization to be restored if there is any catastrophic failure of Tasktop Sync. 

A proxy association attribute must be created for each artifact type to be synchronized.

The Proxy Association Attribute field must be a text/string type field in your ALM repository. We recommend creating this field with the name "Tasktop Sync Proxy."

To create a custom string field in Digital.ai, see instructions here or follow these instructions:

A proxy association attribute must be created for each artifact type to be synchronized. This is be done by creating a custom field on the Digital.ai server. (This custom field will be visible in all projects on the server.) If multiple artifact types (e.g., Defect and Requirement) are to be synchronized, then a custom field must be created for each artifact type. Follow the steps below to create a custom field for an artifact type:

  • In the Digital.ai web application, from the top bar, navigate to Administration -> Configuration;
  • Navigate to the Custom Fields tab;
  • At the far right of the desired artifact type, click Add Field;
  • Enter a Display Name (for example, “Sync Proxy Storage”), set the Field Type to Text, and click OK;
  • Click Publish Changes at the bottom of the page;
  • The newly created field should now appear in the Custom Fields view of the web application.

           

           

Initialization and Changes Queries

Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.

The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.

The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope. 

The Digital.ai Agility connector supports the following types of queries:

  • The Project-specific search query returns all artifacts of a specific type, belonging to a specific project, and modified within a specific time frame.
  • The Recently modified query returns all artifacts of a specific type, belonging to any project, and modified within a specific time frame.
  • The Assigned to me query returns all artifacts of a specific type, belonging to a specific project, and having the authenticated user (i.e., the user used to connect to Digital.ai) as one of their Owners.
  • The Search by iteration query returns all artifacts of a specific type, belonging to a specific project, and within a specific iteration.
  • The Search by Type query returns all artifacts of a specific type, belonging to any project.
  • The By server query language search allows the user to specify the criteria for choosing the returned artifacts of the specified type.
  • The Search by Collection query returns all artifacts of a specific type and belonging to a specific project or any project.
  • The Search by Project and Type query returns all artifacts of a specific type and belonging to a specific project.

Query

Instruction

Initialization Query

For initializations query you can select any of the above queries to limit the number of artifacts being retrieved from the repository. For example, choose the "Project specific" search and choose what type of artifacts and which project to retrieve these items from.

Initialization Query

Changes Query

For changes query, it is advised to limit the number of artifacts retrieved from the server and you can use the filter to limit by last modified date. If you created a project specific query in the initializations option, then you can add a filter to only retrieve items changes in the last day or so.

Changes Query

By server query language query setup.

Digital.ai servers have specific syntax for queries. There are two types of queries allowed by Digital.ai: “rest-1 URL” and “query.v1”. Tasktop Sync uses “rest-1 URL”. The “rest-1 URL” grammar is defined here. In addition to specific date values, Tasktop Sync also supports the following relative dates:

@last 24 hours@
@last 3 days@
@last 7 days@

Note: The @ symbols are required.

Examples:

Before writing a query, choose the artifact type (e.g., Backlog item, Defect, etc.). Then, write the conditions that the returned artifacts should satisfy.

The following are sample queries:

  • To get artifacts of a specific project, one needs to know the project’s id (for instructions on how to get project id, consult Finding the Scope Property Value section); assuming it is ‘Scope:1005’, the condition that the artifacts are from this project would be: Scope=‘Scope:1005’.
  • To get artifacts of a specific estimate, 5 for example, the condition would be: Estimate=‘5’.
  • To get artifacts that have been modified within the last 24 hours, the condition would be: ChangeDateUTC>=@last 24 hours@
  • To get artifacts that have been modified on a specific date, September 15, 2015 for example, the condition would be: ChangeDateUTC>=‘2015-09-15T00:00:00.0000000Z’;ChangeDateUTC<‘2015-09-16T00:00:00.0000000Z’. Note that there is a specific format for DateTime that VersionOne servers expect. The semi-colon “;” serves as “AND”, and the bar “|” serves as “OR”.
  • For artifacts that have been modified on September 15, 2015 or September 18, 2015, the condition would be: (ChangeDateUTC>=‘2015-09-15T00:00:00.0000000Z’;ChangeDateUTC<‘2015-09-16T00:00:00.0000000Z’)|(ChangeDateUTC>=‘2015-09-18T00:00:00.0000000Z’;ChangeDateUTC<‘2015-09-19T00:00:00.0000000Z’). Brackets, ‘(’ and ‘)’, can be used to specify precedence and avoid ambiguity in conditions.
  • To get artifacts belonging to a specific project, Scope:1017 that either have estimate greater than 5 or have been modified on or after September 20, 2015, the query would look like: Scope=‘Scope:1017’;(Estimate>‘5’|ChangeDateUTC>=‘2015-09-20T00:00:00.0000000Z’).
  • To get artifacts that belong to a specific team, the team ID is needed (for instructions on how to get team id, consult Finding the team property value section); suppose it is ‘Team:1006’, the condition would be: Team=‘Team:1006’.

Finding the Scope Property Value

The Scope property must be set to the ID of the Digital.ai project to be synchronized. To find the ID of a Digital.ai project:

  1. In the Digital.ai web application, navigate to Administration -> Projects from the top bar.
  2. Expand the System (All Projects) project.
  3. Locate and click on the desired project.
  4. Click on the Version 12 and 13 Logo or Version 14 and up Logo symbol in the top right corner.
  5. The project ID will be at the end of the URL (following oidToken=).

    How to Find the Project ID in VersionOne

Finding the Team Property Value

Similar to the Scope property, the Team property ID can be found as follows:

  1. In the Digital.ai web application, navigate to Administration -> Teams from the top bar.
  2. Click on the desired Team.
  3. Click on the Version 12 and 13 Logo or Version 14 and up Logo symbol in the top right corner.
  4. The Team ID will be at the end of the URL (following oidToken=).

    Finding the Team ID in VersionOne

 

           

 


 

Other Configuration Settings

Person Reconciliation

For person reconciliation, the following fields are available:

Fields Used for Hub’s Default Person Reconciliation Algorithm

Field Names for Person Reconciliation Extensions

(Note that these are case sensitive)

Label in Digital.ai

ID

ID

ID can be found by looking at the user profile's URL (see image below)

Username

Username

Username

Email

Email

Email

N/A

Name

Name

ID in Digital.ai

Learn more about how to configure person reconciliation in Planview Hub here.

Full Scan

In general, a full scan is not required to synchronize updates from this repository. However, it is possible that some read-only fields may require a full scan. Please consult with customer care for additional details.

NTLM Authentication

NTLM authentication scheme support is dependent on the Digital.ai Agility instance installation. There are multiple authentication methods that can be selected upon installation.

  • Digital.ai Agility Authentication: If this method is selected, the connector can support basic or access token authentication. NTLM authentication is not supported.

  • Microsoft Windows Integrated Authentication: If this method is selected, the connector can support NTLM authentication. Basic and access token authentication is not supported.

If you are currently using NTLM authentication and would like to switch to basic or access token authentication, you will need to run the Digital.ai Agility installer to reconfigure your instance.

See Digital.ai documentation for details on installation and limitations

Default Blocklist

The following fields are blocklisted by default. They are excluded from their respective artifact schemas and will not be mappable. 

Please contact customer care if you'd like to unblock certain fields.

Label

Identity

Backlog Group

ParentAndUp

ChildrenAndDown

ChildrenAndDown

ChildrenAndMe

ChildrenAndMe

ChildrenMeAndDown

ChildrenMeAndDown

SplitFromAndUp

SplitFromAndUp

SplitFromMeAndUp

SplitFromMeAndUp

SplitToAndDown

SplitToAndDown

SplitToMeAndDown

SplitToMeAndDown

SuperAndUp

SuperAndUp

SuperMeAndUp

SuperMeAndUp

SubsAndDown

SubsAndDown

SubsMeAndDown

SubsMeAndDown

AllocatedDetailEstimate or Allocated Detail Estimate

AllocatedDetailEstimate

AllocatedToDo

AllocatedToDo

ClosedEstimate

ClosedEstimate

CompleteEstimate

CompleteEstimate

EstimatedAllocatedDone

EstimatedAllocatedDone

EstimatedAllocatedDone

EstimatedDone

IncompleteEstimate

IncompleteEstimate

OpenEstimate

OpenEstimate

CheckCopy

CheckCopy

CheckDeepCopy

CheckDeepCopy

CheckInactivate

CheckInactivate

CheckMakeTemplate

CheckMakeTemplate

CheckQuickClose

CheckQuickClose

CheckQuickSignup

CheckQuickSignup

CheckReactivate

CheckReactivate

CheckShallowCopy

CheckShallowCopy

CheckSplit

CheckSplit

History

History

Now

Now

Prior

Prior

RetireComment

RetireComment

RetireDate

RetireDate

RetireDateUTC

RetireDateUTC

Retired By

RetiredBy

RetireReason

RetireReason

Weekdays

Weekdays

 


 

Supported Features

Special Features Supported

You can learn more about special features in Planview Hub here.

Feature

Applicable Hub Versions

Applicable Repository Versions

checkicon.png Time Worked (Worklogs)

checkicon.png Impersonation

Tasktop Sync: 3.6 and later

Any supported repository version:

checkicon.png Comments

checkicon.png Impersonation

Not_allowed.svg.png Public/Private

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

checkicon.png Attachments

Not_allowed.svg.png Impersonation

Planview Hub: All

Tasktop Sync: 3.6 and later

Any supported repository version:

N/A - State Transitions

(Digital.ai does not use state transitions. Status can flow out of or into Digital.ai as a single-select.)

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

 


 

Supported Artifacts

Supported Work Items

Learn about the difference between containers and work items in Planview Hub here

Supported Work Item Type

Applicable Hub Versions

Applicable Repository Versions

Unique URL?

Story (Backlog Item)

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Yes

Defect

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Yes

Epic

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Yes

Task

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Yes

Test

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Yes

Request

Planview Hub: All

Tasktop Sync: 4.4 and later

Any supported repository version:

Yes

Issue

Planview Hub: 17.4 and later

Tasktop Sync: 4.12 and later

Any supported repository version:

Yes

Supported Containers

Learn more about containment in Planview Hub here

Containers that can synchronize between repositories

Applicable Hub Versions

Applicable Repository Versions

Unique URL?

N/A

     

Containers used to define the boundary of a collection

(When clicking 'Manage Project' on a Collection)

(N/A - entire repository serves as a container)

Planview Hub: 20.3.3 and later

Any supported repository version:

N/A

Projects

Planview Hub: 17.1.0 - 20.3.2

Any supported repository version:

N/A

Containers used for artifact routing

Projects

Planview Hub: All

Any supported repository version:

N/A

Child Projects

Planview Hub: All

Any supported repository version:

N/A

 


 

Supported Field Types

Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.

Standard Field Type

Does Hub support custom fields of this type?

How is field type referenced in the repository?

Sample Repository Fields Supported

Particular Repository Fields NOT Supported

checkicon.png String

checkicon.png

Text

Build

Change Comment

Reason

Reference

Requested by

Title

 

checkicon.png Single Select

checkicon.png

Dropdown

Project

Complexity

Status

Class of Service

Source

Sprint

Team

Type

Priority

Rollup Categories (read only; supported in 18.4.0.20180801 and later; 4.16 and later)

 

checkicon.png Multi Select

checkicon.png

Multi select

Backlog Group (read only; supported for Defect and Story artifacts)

 

checkicon.png Boolean

checkicon.png

Checkbox

Closed

Inactive

 

checkicon.png Date

checkicon.png

Date

   

checkicon.png Date Time

N/A

 

Created

Modified

Change Date

Create Date

 

Not_allowed.svg.png Duration

       

checkicon.png Double

checkicon.png

Numeric

Estimate Pts.

To Do

Value

 

checkicon.png Long

N/A

 

ID

 

checkicon.png Person

N/A

 

Closed By

 

checkicon.png Persons

   

Owners

 

checkicon.png Relationship(s)

Learn how to configure relationships in Planview Hub here.

N/A

     

checkicon.png Rich Text

checkicon.png

Rich Text

Description

Benefits

 

checkicon.png Web Links

N/A

 

Links

 

Not_allowed.svg.png Other

       

 


 

Functional Limitations

Category

Limitation

Applicable Hub Versions

Applicable Repository Versions

Third Party Functional Limitation

Field Configuration

When updates are made to a field, Hub may not detect changes immediately due to Internet Information Server (IIS) caching. 

If IIS caching is enabled, we recommend restarting Digital.ai in IIS after updating a field.

Planview Hub: All

Tasktop Sync: All

Any supported repository version:

Feature Unsupported

Deleted Artifacts

Digital.ai artifacts that are deleted (that have the AssetState "deleted") are not supported by Hub.

Planview Hub: All

Tasktop Sync: All

Any supported repository version:

Third Party API Limitation

Number Fields

Digital.ai internally stores numeric types to a preset number of decimal digits but the web application presents the number rounded to two decimal places.

Note that a loss of precision may occur when attempting to store more than two decimal places.

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Third Party API Limitation

Custom Fields

In Digital.ai 19.3.9 and earlier, the connector cannot retrieve display names of custom fields. The connector displays the corresponding System Name instead.

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Third Party API Limitation

Optimistic Locking

Connector client cannot detect when an artifact is out of date when making changes to its attachments (optimistic locking)

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Feature Unsupported

Closed Artifacts

Attempting to update a closed Digital.ai artifact will produce an error in Hub (with the exception of updating the 'isClosed' boolean field to re-open the artifact).

Fields on closed Digital.ai artifacts are read-only (though the Hub UI may not indicate that they are read-only).

Planview Hub: All

Tasktop Sync: 3.5 and later

Any supported repository version:

Configuration Requirement

Tasks

Digital.ai Tasks require a parent item. This is either a backlog item/story or a defect. If a two-way sync is being used then the Parent Item of the task and the artifact it is being synced to need to be included in one of the active mappings.

Planview Hub: All

Tasktop Sync: 4.2 and later

Any supported repository version:

Third Party API Limitation

On-Demand (Cloud) Instances

Schema for Digital.ai on-demand instances sometimes fails to discover the "Found By" field.

This may cause sync failures if this field is mapped.

In Dev, this shouldn't cause failures, but the field may simply be missing from task editor. This should be fixed by refreshing the repository configuration a few minutes later.

Planview Hub: All

Tasktop Sync: 3.5 and later

On Demand Version

Configuration Requirement

Authentication

Access-token based authentication is not supported if NTLM is also enabled on the repository.

Planview Hub: All

Tasktop Sync: 4.2 and later

Supported repository versions including 15 and later and on-demand

Third Party Functional Limitation

Requests

The artifact type Request does not support the "Search by Iteration" search type. Requests do not have an Iteration field

Planview Hub: All

Tasktop Sync: 4.4 and later

Any supported repository version:

Third Party Functional Limitation

Date Fields

Digital.ai query language does not support relative date (i.e. no function to get current date). Any relative date calculation should be done at client side.

Planview Hub: All

Tasktop Sync: 4.4 and later

Any supported repository version:

Third Party Functional Limitation

Web Links

Digital.ai allows links to be in various, potentially invalid forms (e.g., a URI containing spaces or something like a:a). However, Hub requires Web Link values to be valid URIs. If an invalid link value is retrieved from a Digital.ai artifact, that value will be ignored (will not flow). Hub will not remove the value on the Digital.ai side.

If a previously-synchronized Digital.ai link is updated to an invalid value, that value will now be ignored, which could lead to the link value in the target artifact being removed.

Planview Hub: 18.1.7 and later

Tasktop Sync: 4.13.7 and later

Any supported repository version:

Third Party Functional Limitation

Issues

The artifact type Issue does not support the "Search by Iteration" search type. Issues do not have an Iteration field

Planview Hub: 17.4 and later

Tasktop Sync: 4.12 and later

Any supported repository version:

Third Party API Limitation

Time Tracking

Digital.ai sends an empty Member on Worklogs when a user has been deleted. Sync ignores all worklogs where this is the case. If a user has synced a worklog to another system and that user is subsequently deleted worklog in destination system will be deleted.

Tasktop Sync: 4.5 and later

Any supported repository version: