Digital.ai Agility
- Last updated
- Save as PDF
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.
Common Integration Patterns
- Escalating Help Desk Problems to Developers
- Sharing Customer Feature Requests with Product
- Sharing Stories and Defects between Dev and Test
- Providing Developers with Early Visibility into Requirements
- Providing Testers with Early Visibility into Requirements
- Associating Planning Items to Implementation Artifacts
- Reporting Known Defects to the Help Desk
- Aligning Testing Teams across Testing Tools
- Populating Requirements into PLM Tools
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
- Example Format: http://myversionone.com/versionone
- 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.
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.
|
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:
- 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:
- In the Digital.ai web application, navigate to Administration -> Projects from the top bar.
- Expand the System (All Projects) project.
- Locate and click on the desired project.
- Click on the or symbol in the top right corner.
-
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:
- In the Digital.ai web application, navigate to Administration -> Teams from the top bar.
- Click on the desired Team.
- Click on the or symbol in the top right corner.
-
The Team ID will be at the end of the URL (following
oidToken=
).
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 |
|
|
|
N/A |
Name |
Name |
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 |
---|---|---|
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: |
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 |
---|---|---|---|---|
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 |
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: |