Skip to main content
Planview Customer Success Center

Tricentis Tosca

Tricentis

 

 

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

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
  • 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:

  1. Prepare the database for multiuser mode by following instructions here.
  2. Create a new workspace and select your repository type under 'Common Repository' in 'Create New Workspace.'
  3. 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. 
    1. 57081858.png
  4. The workspace created in step 2 can be open while using Hub.

Screenshot 2023-08-11 at 4.10.57 PM.png

Personal Access Token Authentication

Planview Hub: 23.4 and later

Tricentis Tosca (Data Center): 15 and later

Required Fields:

See details to learn how to create a personal access token in Tosca.

Screenshot 2023-10-30 at 10.34.30 AM.png

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.

Tosca_Repo_Proxy_Auth.png

Required Fields:

  • Location/Proxy URL
  • 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
  • Personal Access Token
    • See details to learn how to create a personal access token in Tosca

Authentication and Routing Flow

clipboard_ef5c756d1dfaa5e720a082b47a38aa607.png

  1. 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
  2. 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
  3. 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

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

Feature

Applicable Hub Versions

Applicable Repository Versions

1Not_allowed.svg.png Time Worked (Worklogs)

1Not_allowed.svg.png Impersonation

 

 

1Not_allowed.svg.png Comments

1Not_allowed.svg.png Impersonation

1Not_allowed.svg.png Public/Private

 

 

1checkicon.png Attachments

1Not_allowed.svg.png Impersonation

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:

1Not_allowed.svg.png Person Reconciliation

 

 

 


 

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

Learn more about supported test integration scenarios using Tosca here.

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

Learn more about supported test integration scenarios using Tosca here.

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

Learn more about supported test integration scenarios using Tosca here.

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

Learn more about supported test integration scenarios using Tosca here.

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.

Learn more about supported test integration scenarios using Tosca 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.

Learn more about supported test integration scenarios using Tosca 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.

Learn more about supported test integration scenarios using Tosca 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

1checkicon.png String

1checkicon.png

String (Property)

Date

Name

Change Request State

Change Request Id

Aggregated Description

Comment

Log Info

 

1checkicon.png Single Select

 

 

Result

Creation Container

Workspace

Type

Container (Read Only)

 

1Not_allowed.svg.png Multi Select

 

 

 

 

1checkicon.png Boolean

 

 

Changes Allowed

Has Missing References

 

1Not_allowed.svg.png Date

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.

 

 

 

 

1checkicon.png Date Time

 

 

 

 

1Not_allowed.svg.png Duration

 

 

 

 

1checkicon.png Double

 

 

Weight Relative

Test Case Design Coverage

Status Passed

 

1checkicon.png Long

 

 

Failed Test Cases

Manual Items

Passed Test Cases

Required Test Cases

 

1Not_allowed.svg.png Person

 

 

 

 

1Not_allowed.svg.png Persons

 

 

 

 

1checkicon.png Relationship(s)

Learn how to configure relationships in Planview Hub here.

 

 

Hierarchy with Requirements

Relationship between Executiontestcaselog and Requirement (read only)

 

1Not_allowed.svg.png Rich Text

 

 

 

 

1Not_allowed.svg.png Web Links

 

 

 

 

1checkicon.png Container Links

1Not_allowed.svg.png

Container

Parent 'Container' of each supported type:

Execution List

Requirement Set

Folder

 

1Not_allowed.svg.png Other

 

 

 

 

 


 

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 worker-threads="1", the default is 5.

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: