Tosca Cloud Extractor Setup — Customer Guide¶
Configure analytiQa to automatically extract playlists, runs, test cases and plan usage from your Tricentis Tosca Cloud tenant.
Tosca Cloud is Tricentis' SaaS version of Tosca, opened at https://<tenant>.my.tricentis.com. Like Jira and qTest, the Tosca Cloud extractor runs in your analytiQa environment and reads your tenant through its APIs. You don't install anything. If you use Tosca Commander with a local workspace instead, see Tosca Extractor Setup.
Prerequisites¶
- A Tosca Cloud tenant (
https://<tenant>.my.tricentis.com) - A Tosca Cloud administrator, to look up the API client ID and secret (Step 3)
- A secure credential intake link from your Qualtiva technical contact
Step 1: Your Tenant URL¶
The address you use to open Tosca Cloud, for example:
https://yourcompany.my.tricentis.com
If you're unsure, log in to Tosca Cloud. The URL is in your browser address bar.
Step 2: Your Token URL¶
The extractor logs in through your tenant's Okta token endpoint. To find it:
- Open
https://<tenant>/_identity/apiDocs/swagger(replace<tenant>with your tenant address from Step 1) - Click Authorize
- Copy the Token URL. It's an Okta address ending in
/oauth2/default/v1/token
Step 3: Your API Client ID and Secret¶
analytiQa uses the client ID and client secret of your tenant's Tricentis_Cloud_API application. Only a Tosca Cloud administrator can read them.
See Tricentis's guide: Get a client secret.
The client ID and secret don't expire on a schedule. They keep working until an administrator deletes or regenerates the secret, or deactivates the application. If that happens, send us the new secret through a new secure link.
Step 4: Optional Portal Account¶
Plan and usage data (Settings > My plan and Settings > Users) has no public API. The extractor first reads it with the client ID and secret from Step 3, which usually works, so most customers can skip this step.
If your tenant rejects that, we need a Tosca Cloud user without multi-factor authentication (MFA), used only to read those pages. Without it, the extractor still collects everything else and skips the plan and usage data.
Step 5: Enter Your Details¶
Enter the values in the Tosca Cloud section of your secure credential intake link. Never send them by email or chat.
| Field in the secure link | Value |
|---|---|
| Tosca Cloud tenant URL | Step 1 |
| Token URL | Step 2 |
| API client ID | Step 3 |
| API client secret | Step 3 |
| Portal service account (optional) and password | Step 4. Leave empty unless your technical contact asks for it |
Also tell your technical contact:
- Workspaces: all workspaces (default), or only some
- History: how far back the first extraction should go, for example "everything since our Tosca Cloud go-live"
Step 6: Polling Interval¶
analytiQa checks Tosca Cloud every 15 minutes by default. Each run re-reads everything updated in the last 24 hours, so a run that is missed or fails is caught up by the next one. The extraction is read-only. If you need a different frequency, tell your technical contact.
Step 7: Review Your Configuration¶
Before submitting, check:
- ✓ Tenant URL opens your Tosca Cloud
- ✓ Token URL ends in
/oauth2/default/v1/token - ✓ Client ID and secret belong to the Tricentis_Cloud_API application
- ✓ The portal account, if you provide one, has no MFA
- ✓ You've told your technical contact which workspaces and how much history you want
What Happens Next¶
- First extraction: analytiQa loads your history from the agreed start date
- Ongoing updates: every 15 minutes, new and changed playlists, runs and test cases are picked up
- Dashboard ready: log in to the analytiQa dashboard → [Tosca Cloud] Overview
What Gets Extracted¶
From your Tosca Cloud tenant, analytiQa captures:
| Tosca Cloud | What's captured |
|---|---|
| Playlists | Name, workspace and characteristics |
| Playlist runs | Result, start and end time, duration, trigger |
| Test case runs | Passed, failed or canceled, start and end time, duration, environment and the agent that ran it. For failed runs, also why they failed: failure reason, failing step and message (see Failure Detail). Only completed runs are sent |
| Test cases | Name, workspace, work state, author, creation and change dates, plus structure: number of test steps, assertions, engines used (e.g. Html, API, Database), waits. Test cases migrated from Tosca Commander are marked as such |
| Execution statistics | Per test case: total, passed and failed executions, consecutive failures, pass rate and last execution |
| Inventory | Number of test cases, templates, modules, reusable test step blocks and playlists per workspace |
| Plan and usage | Subscription, usage meters (execution credits, editors, agents, storage, test case runs and others), entitlements and seat counts |
| AI credits (optional) | Used, remaining and total Tricentis AI credits, as shown in the portal's Remaining credits popup. Ask your technical contact to turn it on |
The extractor doesn't collect your user list (names and email addresses) unless you ask for it.
Records use the same data model as the Tosca extractor, so if you also use Tosca Commander you can compare both in the same dashboards. Playlist characteristics and test case configuration parameters whose name starts with AQA are mapped the same way as Tosca custom properties (for example AQA-Application becomes Application).
Failure Detail¶
Failed test case runs record why they failed, in the same fields as Tosca. The failure reason is derived the same way as for Tosca, so failure-reason panels such as [Tosca] Error Reasons show Tosca and Tosca Cloud together. Every run also records where it ran.
| Field | What it contains | Where it comes from |
|---|---|---|
error-reasons |
Short failure reasons for grouping, for example Could not find HtmlDocument or Agent disconnected during the execution |
Taken from error-messages, the same way as for Tosca |
error-messages |
One entry per failed test step: the step, its message and details | The run's test step results (the TestSteps.json attachment in Tosca Cloud) |
failed-test-step-path |
Where the run failed: test case, folders and step, for example Example TestCase / CloseBrowser |
Test step results |
log-info |
The run's overall message, for example "Execution will be continued with the next TestCase, because there was an error in the current TestCase." | Test step results, or the run's state details if there are none |
messages |
The whole step log as text, one + Passed or - Failed line per step. Very long logs are shortened |
Test step results |
agent.name, agent.type |
The agent that ran the test case, and its type (for example Cloud-agent or Team-agent) |
The run's execution in Tosca Cloud |
self-healing-used |
Whether Tosca self-healing was used | The run's execution in Tosca Cloud |
state-details |
Why the run ended the way it did, for example Agent disconnected during the execution. or Timeout after 720 minutes. |
The run's execution in Tosca Cloud |
Some failed runs have no test step results in Tosca Cloud, for example when the agent disconnected. Their failure reason then comes from the state details and they have no failing step. Canceled runs keep their state details in log-info and state-details only, so a timeout that cancels a whole playlist doesn't crowd out real failure reasons.
Environment¶
Each test case run takes its environment from the playlist it ran in:
- A playlist parameter named
AQA-Environment(recommended) - Otherwise, a playlist parameter named
EnvironmentorEnv - Otherwise,
Not Set
For example, give a playlist the parameter AQA-Environment = UAT and its runs show the environment UAT. If you also use Tosca, use the same environment names in both so dashboards group them together.
Run Times¶
A test case run's start time, end time and duration are the time it actually ran on the agent. Time spent waiting in the queue for an agent isn't included. It's reported separately, as when the run was queued (queued-at) and how long it waited (queue-duration, in seconds). Runs collected before this change keep their earlier times, which included the wait.
Example Dashboards¶
The [Tosca Cloud] Overview dashboard is set up for you. It shows:
- Test case runs by result, playlist runs, durations and top failing test cases
- Test cases by type and workspace, and how many were added or changed over time
- Plan usage: meters, seats, agents, storage and subscription
- Adoption of Tosca Cloud alongside Tosca, and test cases migrated from Tosca Commander
- Test case structure: primary engine, assertions per test case and the largest test cases
See Using Dashboards for details.
Troubleshooting¶
| Issue | Solution |
|---|---|
"Invalid credentials" or invalid_client |
Check the client ID and secret belong to the Tricentis_Cloud_API application, and that the secret wasn't deleted or regenerated. Check the Token URL is the one from your tenant's swagger page. |
| Runs missing from dashboards | Runs that are still in progress aren't sent. They appear once they've passed, failed or been canceled. |
| No plan or usage data | Your tenant may reject the client ID and secret for these pages. Provide a portal account without MFA (Step 4). |
| Some workspaces missing | Tell your technical contact if you asked for specific workspaces only. |
| Environment is "Not Set" | Add a playlist parameter AQA-Environment (or Environment) with the environment name (Environment). New runs pick it up. Runs already in analytiQa keep their value. |
| Failed run has no failure reason | Tosca Cloud has no test step results or state details for that run. Open the run in Tosca Cloud to see its log. |
More help? See Support & Troubleshooting.
Next Steps¶
- Configure another data source: Jira Setup, qTest Setup or Tosca Setup
- Explore your data: Using Dashboards
- Build custom reports: Common Queries & Reports