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.
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.
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:
Standard Authentication
Required Fields:
Optional Fields:
Learn more about how to set up your repository in Planview Hub here.
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:
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:
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.
|
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.
|
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:
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:
The project ID will be at the end of the URL (following oidToken=
).
Finding the Team Property Value
Similar to the Scope property, the Team property ID can be found as follows:
The Team ID will be at the end of the URL (following oidToken=
).
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 |
|
|
|
N/A |
Name |
Name |
Learn more about how to configure person reconciliation in Planview Hub here.
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 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.
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 |
You can learn more about special features in Planview Hub here.
Feature |
Applicable Hub Versions |
Applicable Repository Versions |
---|---|---|
Time Worked (Worklogs) Impersonation |
Tasktop Sync: 3.6 and later |
Any supported repository version: |
Comments Impersonation Public/Private |
Planview Hub: All Tasktop Sync: 3.5 and later |
Any supported repository version: |
Attachments 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: |
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 |
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 |
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 |
---|---|---|---|---|
String |
|
Text |
Build Change Comment Reason Reference Requested by Title |
|
Single Select |
|
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) |
|
Multi Select |
|
Multi select |
Backlog Group (read only; supported for Defect and Story artifacts) |
|
Boolean |
|
Checkbox |
Closed Inactive |
|
Date |
|
Date |
||
Date Time |
N/A |
Created Modified Change Date Create Date |
||
Duration |
||||
Double |
|
Numeric |
Estimate Pts. To Do Value |
|
Long |
N/A |
ID |
||
Person |
N/A |
Closed By |
||
Persons |
Owners |
|||
Relationship(s) Learn how to configure relationships in Planview Hub here. |
N/A |
|||
Rich Text |
|
Rich Text |
Description Benefits |
|
Web Links |
N/A |
Links |
||
Other |
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: |