Tricentis Tosca
Overview
When your software engineering teams use Agile methods, requirements created by business analysts or user stories created by developers must flow easily to your QA team. This ensures that tests are written directly against these requirements or stories. Similarly, any failed tests must flow back to the developers, so bugs can be quickly remedied.
Planview Hub meets this need by integrating Tosca Test Suite with the tools that business analysts, software developers, scrum masters, testers, and other team members use everyday. By synchronizing artifacts across everyone's tool of choice, Hub enhances Tosca's tools for collaboration.
For example:
- Let’s say your developers use Agile methods and manage their work in Atlassian Jira, but your testers use Tosca for QA activity.
- Hub will automatically represent user stories from Jira as requirements in Tosca. QA engineers can then create and execute specific test cases to cover those requirements.
- When testing reveals a defect, Hub will create a defect in Jira, and re-create the relationship between the new defect and the originating user story. This gives the developers the context they need to fix the bug.
- The status of that defect will also flow back to Tosca, letting QA know when a given test is ready to be run again.
Key Features and Benefits
- Synchronizes artifacts across the lifecycle, allowing information to flow freely between Tosca and other tools
- Improve team collaboration by connecting Tosca to third party tools and allow artifacts to be synchronized across the lifecycle.
- Support cross-tool traceability and reporting, particularly between requirements and defects - removing the need for manual processes and spreadsheets
- Synchronizes requirements from RM tools or user stories from Agile tools to Tosca requirements
- Synchronizes failed tests from Tosca to defects in Agile tools
- Allows for automatic reporting of defects found during test execution from QA to development
Common Integration Patterns
Demo Videos
Connector Setup Details
This section describes the basic steps needed to prepare your Tricentis Tosca 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 Hub user in Tricentis Tosca.
List of minimal user permissions:
- Hub supports local workspace users only (LDAP users are not supported)
- User should be under the "Admins" user group to view/retrieve a list of users.
- User should have Set Result allowed enabled to set the execution results.
- User should have Level as "Expert" or "Advanced" to have read/write permissions on multiuser projects.
Note: The credentials you supply must be valid for every workspace you plan to include in your collection (in Hub).
Connecting to the Tricentis Tosca Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- Example Format: http://abc-tosca223.van.server.com:8...ToscaCommander
- Username
- Password
- Please be aware that the “Successfully connected” response from Hub on the repository screen does NOT guarantee that Hub will be able to connect to the Tosca Workstation if the requirements listed above are not met.
Optional Fields:
- 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.
Note: As a general rule, Tosca Commander and Hub cannot be open and running at the same time, since both are using the same APIs. Therefore, to be able to integrate with Tosca, you have to close your Tosca Commander workspace. However, a workaround is available:
- Prepare the database for multiuser mode by following instructions here.
- Create a new workspace and select your repository type under 'Common Repository' in 'Create New Workspace.'
- Create an additional workspace for your Hub instance. This time, ensure that you select 'Use existing Repository' under 'Common Repository' and select the Common Repository that you created in step 2.
- The workspace created in step 2 can be open while using Hub.
Personal Access Token Authentication
Planview Hub: 23.4 and later
Tricentis Tosca (Data Center): 15 and later
Required Fields:
- Location/Connection URL
- Example Format: http://abc-tosca223.van.server.com:8...ToscaCommander
- Personal Access Token
See details to learn how to create a personal access token in Tosca.
Learn more about how to set up your repository in Planview Hub here.
Personal Access Token with OAuth2.0 Proxy Authentication
Planview Hub: 24.2 and later
Tricentis Tosca (Data Center): 15 and later
The Tosca connector supports proxy authentication using the OAuth 2.0 client credentials authentication flow to authenticate with the proxy through an identity provider, and using Personal Access Token authentication to authenticate with Tosca after the proxy.
Required Fields:
- Location/Proxy URL
- Example format: http://proxy-domain.com/proxy-path
- Identity Provider URL: Used to obtain the authentication token from the identity provider
- Client ID: A unique identifier assigned to a client application when it is registered with the identity provider
- Client Secret: Used to authenticate the identity of the client application when making requests to the identity provider
- Scope: Specify the access permissions
- Route: Based on the route, the request is redirected to the corresponding endpoint configured in the proxy
- Example:
Proxy URL: http://proxy-domain.com/proxy-path
Suppose the proxy is configured with the following route and corresponding redirection URL:Route
Redirection URL
Route123
Resource Path: /obj/1234
With this route configuration, upon successful authentication, the proxy will redirect the URL to: https://dev-tosca...com:8.../abc/obj/1234
- Example:
- Personal Access Token
- See details to learn how to create a personal access token in Tosca
Authentication and Routing Flow
- HTTP Request Headers:
- Authorization: OAuth2 token obtained from the Identity Provider
- RepoAuthorization: Repository Token
- AuthMode: Set to "pat" (Personal Access Token)
- Route: Specify the route to the specific repository
- Proxy Authentication with Identity Provider:
- The proxy authenticates the OAuth2 token provided in the Authorization header with the Identity Provider, verifying its validity and checking for necessary permissions
- Validation and Redirection:
- Upon successful validation, the proxy replaces the content of the Authorization header with the RepoAuthorization token — this replacement is essential for redirecting the request to the repository, which requires the repository-specific token
- The route header specifies the destination repository for redirection
- If the validation process encounters an error, an error response is sent back to the client
Workspace Repository Configuration
Planview Hub: 17.1 - 17.3
A workspace name needs to be provided when specifying connection settings to Tricentis Tosca version 8. For versions 9 and above, this field is optionally used to specify a workspace to authenticate user credentials against. If no workspace is specified, authentication is carried out against the first workspace returned alphabetically from the repository.
Repository Queries
Tosca performs full artifact searches and is not restricted to single artifact types. This can lead to performance and slowdown issues. To help reduce the number of artifacts requiring processing, Repository Queries — which utilize Tosca’s Virtual Folders — can be used. For example, Virtual Folder Queries (TQL, Tosca Query Language) are provided in the table below.
Note: It is important that the SortBy ‘-revision’ setting is applied to All Virtual Folders.
Setup:
- Enable the Repository Query check box on the Tosca repository
- Create the Virtual Folders in Tosca (ensuring that the Hub user has access to the workspace)
- The Virtual Folder can be run inside of Tosca to verify the correct artifacts are shown
- Select each Collection and configure the relevant Repository Query
Example Queries for each test artifact type
| Applicable Tosca Collection | Virtual Folder Query | Virtual Folder SortBy | Virtual Folder Location |
|---|---|---|---|
| Test Folders |
=>SUBPARTS:TCFolder |
-revision | Place this Virtual Folder at the same level as the topmost Test Folders you wish to synchronize |
| Test Cases | =>SUBPARTS:TestCase | -revision | Place this virtual folder at the same level as the topmost Test Folders you wish to synchronize |
| Test Set Folders (Execution List Folders) | =>SUBPARTS:TCFolder | -revision | Place this virtual folder at the same level as the topmost Test Set Folders (Execution List Folders) you wish to synchronize |
| Test Sets (Execution Lists) | =>SUBPARTS:ExecutionList | -revision | Place this virtual folder at the same level as the topmost Test Set Folders (Execution List Folders) you wish to synchronize) |
| Test Instances (Execution Entries) | =>SUBPARTS:ExecutionEntry | -revision | Place this virtual folder at the same level as the topmost Test Set Folders (Execution List Folders) you wish to synchronize) |
| Test Runs (Execution Test Case Logs) | =>SUBPARTS:ExecutionTestCaseLog | -revision | Place this virtual folder at the same level as the topmost Test Set Folders (Execution List Folders) you wish to synchronize) |
Other Configuration Settings
Attachments
In order to synchronize attachments, the Tosca REST API must be configured to support attachments. This requires the AttachmentPath property to be specified in the web.config file for the REST service. Details of how to configure the Tosca API for attachments can be found on the Tosca documentation page. Choose the TC REST API tab and select the appropriate documentation for the Tosca version in use. Information about attachment configuration can be found in the overview and in the Requests > Adding files section.
Learn more about how to configure attachment flow in Planview Hub here.
Person Reconciliation
Tosca repository does not provide person fields in Hub, therefore, you will not be able to map any person fields.
Learn more about how to configure person reconciliation in Planview Hub here.
Full Scan
Due to third party API limitations, updates to the following fields may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:
- Removing a Linked Defect on an Execution Entry
- Linked Requirement on an Execution Test Case Log
- Renaming a Test Case on related Execution Test Case Logs
- Changes made in single-user workspaces
-
Note: It is recommended to use multi-user workspaces only.
-
If you are using Tosca version 10.3 or later, then single-user workspaces are not supported with Hub.
-
As of Planview Hub 18.4, single-user workspaces are no longer supported for any version of Tosca.
-
-
If you have a Tosca repository already created, you should create a new workspace connected to that repository to be used by Hub. Tick "Use existing Repository" when creating a new workspace in Tosca. In other words, have a separate workspace used solely by Hub.
-
- Changes made to calculated read-only fields
Note: Execution Entries and Execution Test Case Logs are available in Hub UI, but not fully supported by Hub. Please contact support with any questions.
Learn more about how to configure change detection and full scan intervals in Planview Hub here.
Supported Features
Special Features Supported
|
Feature |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
Planview Hub: All |
Any supported repository version: |
|
N/A - State Transitions (Status can flow out of Tosca as a single select, but not into Tosca, as transitions are not supported) |
Planview Hub: All |
Any supported repository version: |
|
|
|
|
Time Worked (Worklogs)
Attachments
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? |
|---|---|---|---|
|
Requirement |
Planview Hub: All |
Any supported repository version: |
No accessible web URL. Connector uses unique REST URI for location. |
|
Defect |
Planview Hub: All |
Supported versions including 9.2 and later |
No accessible web URL. Connector uses unique REST URI for location. |
|
Test Case |
Planview Hub: 17.2 and later |
Supported versions including 9.2 and later |
No accessible web URL. Connector uses unique REST URI for location. |
|
Execution Test Case Log |
Planview Hub: 17.1 - 19.1 Supported as a container in later versions |
Any supported repository version: |
No accessible web URL. Connector uses unique REST URI for location. |
|
Execution Entry |
Planview Hub: 17.2 and later |
Supported versions including 9.2 and later |
No accessible web URL. Connector uses unique REST URI for location. |
|
Execution List |
Planview Hub: 17.2 - 19.1 Supported as a container in later versions |
Supported versions including 9.2 and later |
No accessible web URL. Connector uses unique REST URI for location. |
Supported Containers
Learn more about containment in Planview Hub here.
|
Containers that can synchronize between repositories |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
Execution List Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here. |
Planview Hub: 19.2 and later |
Any supported repository version: |
Yes |
|
Execution List Folder Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here. |
Planview Hub: 19.2 and later |
Any supported repository version: |
Yes |
|
Test Case Folder Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here. |
Planview Hub: 19.2 and later |
Any supported repository version: |
Yes |
|
Requirement Sets Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here. |
Planview Hub: 20.4 and later |
Any supported repository version: |
Yes |
|
Containers used to define the boundary of a collection (When clicking 'Manage Projects' on the Collection) |
|
|
|
|
Workspaces |
Planview Hub: All |
Any supported repository version: |
N/A |
|
Containers used for artifact routing/container mirroring |
|
|
|
|
For Requirement Sets, Defects, Execution Lists, and Test Cases: Generic Folders |
Planview Hub: All |
Any supported repository version: |
N/A |
|
For Requirements: Requirement Sets |
Planview Hub: All |
Any supported repository version: |
N/A |
|
For Execution Test Case Logs: Execution List Folder |
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 (Property) Date |
Name Change Request State Change Request Id Aggregated Description Comment Log Info |
|
|
|
|
|
Result Creation Container Workspace Type Container (Read Only) |
|
|
|
|
|
|
|
|
|
|
|
Changes Allowed Has Missing References |
|
|
Note: In Tosca, custom 'date' fields are referenced in the UI, but behave as string fields. Therefore what Tosca refers to as a 'date' field is supported, as a string. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Weight Relative Test Case Design Coverage Status Passed |
|
|
|
|
|
Failed Test Cases Manual Items Passed Test Cases Required Test Cases |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Learn how to configure relationships in Planview Hub here. |
|
|
Hierarchy with Requirements Relationship between Executiontestcaselog and Requirement (read only) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Container |
Parent 'Container' of each supported type: Execution List Requirement Set Folder |
|
|
|
|
|
|
|
Functional Limitations
|
Category |
Limitation |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
Third Party Functional Limitation |
Proxy Gateway Authentication Token-based authentication is applicable to Tosca Server-Based repositories. It's important to note that repositories like Multi-User Workspace do not support this and only allow username and password authentication. |
Planview Hub: 23.4 and later |
Tosca Data Center: 15 and later |
|
Good to Know |
Proxy Gateway Authentication Tosca does not provide a distinct error code for an invalid token. Therefore, users may find it challenging to determine whether they have entered an incorrect token or if the token has expired. |
Planview Hub: 23.4 and later |
Tosca Data Center: 15 and later |
|
Third Party Functional Limitation
|
Personal Access Token Authentication Personal Access Token authentication only works for Tosca server-based repositories. Other repositories like Multi User Workspace support username and password only. |
Planview Hub: 23.4 and later
|
Tosca Data Center: 15 and later |
|
Good to Know
|
Personal Access Token Authentication Tosca does not support separate error codes for invalid tokens. As a result, it may be difficult to determine when a token expires or if the wrong token is entered. |
Planview Hub: 23.4 and later
|
Tosca Data Center: 15 and later |
|
Good to Know
|
Personal Access Token Authentication Tosca server-based repositories do not support username and password. |
Planview Hub: 23.4 and later
|
Tosca Data Center: 15 and later |
|
Good to Know |
Test Steps Only ExecutionXTestStepLogs have test step values in their JSON String field because ExecutionTestStepLogs (ManualTestSteps) do not record results for their test step values. |
Planview Hub: 23.4 and later |
Any supported repository version: |
|
Third Party API Limitation |
Test Step Results Test Step Results do not have a stable ID. As such, they cannot be synchronized into target repositories that do have a stable ID field. |
Planview Hub: 23.4 and later |
Any supported repository version: |
|
Good to Know |
Test Steps All test steps flowing into Tosca are created as ManualTestSteps. |
Planview Hub: 23.4 and later |
Any supported repository version: |
|
Feature Unsupported |
Test Cases Conditional statements and loops in Test Cases are not supported. |
Planview Hub: 23.4 and later |
Any supported repository version: |
|
Third Party API Limitation |
Calculated Read-Only Fields Updates made to calculated read-only fields will not be detected unless a high fidelity full scan is performed. |
Planview Hub: All |
Any supported repository version: |
|
Third Party API Limitation |
Workspaces Workspaces with the same name are not supported in Hub. |
Planview Hub: All |
Any supported repository version: |
|
Good to Know |
Execution TestCase Logs Execution TestCase Log artifacts will flow to the other side of an integration in the order that they were created under their Execution Entry parent. When processing an event for a new Execution TestCase Log artifact, Hub will check whether the previously created Execution TestCase Log artifact was synchronized. If so, it will continue to flow this artifact in the integration. If not, Hub will move the event back into its queue for automatic retry later on. Note: Hub's normal exponential backoff behavior will apply before retrying an unsuccessful event. |
Planview Hub: 21.3 and later |
Any supported repository version: |
|
Good to Know |
Test Connection When creating a Tosca repository connection, clicking the 'Test Connection' button does not test the authentication — It only tests that it can reach the Tosca server. As a result, you may still encounter authentication errors despite a successful 'test connection.' |
Planview Hub: All |
Any supported repository version: |
|
Third Party API Limitation |
Generic Folders If a folder is moved on the other side of a Tosca integration, Generic folders will not be updated. |
Planview Hub: 20.4 and later |
Any supported repository version: |
|
Third Party API Limitation |
Generic Folders Generic folders cannot be created at the 'Root' context as this level maps to tabs. |
Planview Tasktop Hub: 20.4 and later |
Any supported repository version: |
|
Third Party API Limitation |
Test Case Folders The Test Case folder is not supported as a Generic folder. |
Planview Hub: 20.4 and later |
Any supported repository version: |
|
Feature Unsupported |
Creation Errors Creation of Business Test Cases, Business Execution Lists, Test Mandates, Test Mandate Entries, and new items beneath Test Mandates via Tasktop is unsupported. Attempting to create any of these will result in errors in the activity log. |
Planview Hub: All |
Any supported repository version: |
|
Known Defects |
Change Detection Changes from updating workspace via a second workspace are not detected if no items are initially in the workspace. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Attachments Tosca must be configured to support creating and retrieving attachments via the REST API. |
Planview Hub: All |
Any supported repository version: |
|
Third Party API Limitation |
Attachments Attachments with some special characters and unicode characters in the filename will fail to synchronize. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Configuration Tosca allows opening workspaces without providing credentials if the target workspace contains only one user named “Admin” with no password assigned. This does not work in TCRS. In TCRS, credentials have to be provided with every request. The above means that an additional user (e.g. "tasktop") needs to be created in order to use REST API. When logged as Admin, go to Project > Administration, right click there and create a user. Right-click on the user to set a password. |
Planview Hub: All |
Any supported repository version: |
|
Best Practice |
Errors In synchronizer.xml set If you start noticing "Artifact stale" errors and task pairs being locked, it is due to the workspace needing to be locked for requirement writing. You may adjust the concurrent threads made to the server, however, all the errors should eventually be gone/retried. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Relationships SubRequirements (children) field is read-only. Can be used to get parent-child relationship out of Tosca, but it's not expected to be updated. To create requirements hierarchy in Tosca use the SuperRequirement field, which represents parent of the given requirement, and is writeable. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Requirements Use "Text Markup Transformation" caster when mapping Requirement's Description to a field in other system. Use a simple formatting for Tosca, like "Confluence". |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Requirements For new Requirements a field called "SynchronizationPolicy" needs to be set. Use "Literal Value" caster to set it to the default i.e. "CustomizableDefaultIsOn". |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Configuration Virtual folder queries should only query for types that are supported by Hub. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Configuration The Tosca connector no longer requires a workspace to be entered when adding a new repository for versions 9 and above. Instead, this field can be used to optionally specify a workspace verify a user's credentials against. If no workspace is provided, the connector verifies the credentials against the first workspace returned alphabetically. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Configuration Tosca workspaces should be configured as multi-user workspaces when used with Hub. |
Planview Hub: 17.3 and later |
Supported versions including 10.3 and later |
|
Third Party API Limitation |
Test Management Attachments are not supported for ExecutionTest Case Logs Note: Execution Test Case Logs are available in Hub UI, but not fully supported by Hub. Please contact support with any questions. |
Planview Hub: All |
Any supported repository version: |