Get Details Service

Convert a project, release, cycle, platform, test suite, and build name into the numeric identifiers that other Open API endpoints require, in a single call. Use this API when your automation knows the names of the entities it works with but not their identifiers.

Endpoint

POST /rest/admin/project/getDetails/v1

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
`apiKey`	header	yes	Open API key generated in Integration, Open API in QMetry Test Management.	-	string
`scope`	header	no	Project or scope ID, key, or name.	Default	string
`projectName`	body	yes	Name of the project. The value must exactly match the name of an existing project that the API key user can access.	-	string
`releaseName`	body	no	Name of the release. When you include this parameter, the response contains a `release` object.	-	string
`cycleName`	body	no	Name of the cycle. Send `releaseName` as well, otherwise the cycle cannot be resolved.	-	string
`platformName`	body	no	Name of the platform. When you include this parameter, the response contains a `platform` object.	-	string
`tsEntityKey`	body	no	Entity key of the test suite, for example, `PROJ-TS-2`. When you include this parameter, the response contains a `testSuite` object.	-	string
`buildName`	body	no	Name of the build. When you include this parameter, the response contains a `build` object. The build is resolved directly within the project, so no release or cycle is required.	-	string

Cycle Resolution

The same cycle name can exist under more than one release in a project. To identify a cycle without ambiguity, send releaseName together with cycleName. When you send cycleName without releaseName, the cycle id is always null and the response includes an errorMessage, even if a cycle with that name exists. This is expected behavior, not an error.

Understand the Response Structure

The response returns each resolved entity as a nested object. Only the entities you named in the request appear in the response.

When an entity resolves, its object holds a populated id together with the name, or the entityKey in the case of a test suite.
When an entity does not resolve, its id is null, the name or entityKey is echoed back from the request, and an errorMessage explains the reason.
When a build exists but is archived, its id is null and the errorMessage states that the build is archived. This message distinguishes an archived build from a build that is not found.
A null identifier does not fail the request. The response status remains 200. Always check whether the returned identifier is null before you use it in a later call.

Two members are always present, whichever optional parameters you send:

statusDetails lists the execution statuses configured for the project.
testExecutionViewId holds the default test execution view identifier for the project, or null when no view is configured.

Response

Content-Type: application/json

Status code	Reason	Response model
200	Details fetched successfully. An unresolved optional entity still returns 200, with a `null` identifier and an error message.	ResponseEntity
400	`projectName` is missing, or no project matches the supplied name.	-
401	Unauthorized or session expired.	-
500	The server connection timed out.	-

Example 84. Project Name Only

A minimal request returns the project object along with statusDetails and testExecutionViewId. No optional entity objects appear in the response.

Request

{
  "projectName": "<project-name>"
}

Response

{
  "project": {
    "id": 101,
    "name": "<project-name>"
  },
  "statusDetails": [
    { "id": 1, "name": "PASS" },
    { "id": 2, "name": "FAIL" },
    { "id": 3, "name": "WIP" },
    { "id": 4, "name": "BLOCKED" },
    { "id": 5, "name": "NOT EXECUTED" }
  ],
  "testExecutionViewId": 200
}

Example 85. Resolve a Release, Cycle, Platform, Test Suite, and Build

Request

{
  "projectName": "<project-name>",
  "releaseName": "<release-name>",
  "cycleName": "<cycle-name>",
  "platformName": "<platform-name>",
  "tsEntityKey": "<entity-key>",
  "buildName": "<build-name>"
}

Response

{
  "project": {
    "id": 101,
    "name": "<project-name>"
  },
  "release": {
    "id": 202,
    "name": "<release-name>"
  },
  "cycle": {
    "id": 303,
    "name": "<cycle-name>"
  },
  "platform": {
    "id": 404,
    "name": "<platform-name>"
  },
  "testSuite": {
    "id": 505,
    "entityKey": "<entity-key>"
  },
  "build": {
    "id": 606,
    "name": "<build-name>"
  },
  "statusDetails": [
    { "id": 1, "name": "PASS" },
    { "id": 2, "name": "FAIL" },
    { "id": 3, "name": "WIP" },
    { "id": 4, "name": "BLOCKED" },
    { "id": 5, "name": "NOT EXECUTED" }
  ],
  "testExecutionViewId": 200
}

Example 86. Cycle Name Sent Without a Release Name

The cycle id is null because the cycle cannot be resolved without a release. To resolve the cycle, send releaseName together with cycleName.

Request

{
  "projectName": "<project-name>",
  "cycleName": "<cycle-name>"
}

Response

{
  "project": {
    "id": 101,
    "name": "<project-name>"
  },
  "cycle": {
    "id": null,
    "name": "<cycle-name>",
    "errorMessage": "Release name either not provided or not available, hence unable to fetch cycle."
  },
  "statusDetails": [
    { "id": 1, "name": "PASS" },
    { "id": 2, "name": "FAIL" },
    { "id": 3, "name": "WIP" },
    { "id": 4, "name": "BLOCKED" },
    { "id": 5, "name": "NOT EXECUTED" }
  ],
  "testExecutionViewId": 200
}

Example 87. Entity Not Found

When a named entity does not exist, the identifier is null and the response explains why.

{
  "release": {
    "id": null,
    "name": "BadRelease",
    "errorMessage": "No release found with name: BadRelease."
  }
}

Example 88. Test Suite Not Resolved

The testSuite id is null, with an errorMessage, when the entity key does not exist in the project or cannot be parsed to a number.

Request

{
  "projectName": "<project-name>",
  "releaseName": "<release-name>",
  "tsEntityKey": "<entity-key>"
}

Response

{
  "project": {
    "id": 101,
    "name": "<project-name>"
  },
  "release": {
    "id": 202,
    "name": "<release-name>"
  },
  "testSuite": {
    "id": null,
    "entityKey": "<entity-key>",
    "errorMessage": "<error-message>"
  },
  "statusDetails": [
    { "id": 1, "name": "PASS" },
    { "id": 2, "name": "FAIL" },
    { "id": 3, "name": "WIP" },
    { "id": 4, "name": "BLOCKED" },
    { "id": 5, "name": "NOT EXECUTED" }
  ],
  "testExecutionViewId": 200
}

Example 89. Build Is Archived

When the build exists but is archived, the build id is null and the errorMessage states that the build is archived.

{
  "projectName": "<project-name>",
  "buildName": "<archived-build-name>"
}

Response

{
  "project": {
    "id": 101,
    "name": "<project-name>"
  },
  "build": {
    "id": null,
    "name": "<archived-build-name>",
    "errorMessage": "Build '<archived-build-name>' is archived."
  },
  "statusDetails": [
    { "id": 1, "name": "PASS" },
    { "id": 2, "name": "FAIL" },
    { "id": 3, "name": "WIP" },
    { "id": 4, "name": "BLOCKED" },
    { "id": 5, "name": "NOT EXECUTED" }
  ],
  "testExecutionViewId": 200
}

Example 90. Build Not Found

Request

{
  "projectName": "<project-name>",
  "buildName": "BuildThatDoesNotExist"
}

Response

{
  "project": {
    "id": 101,
    "name": "<project-name>"
  },
  "build": {
    "id": null,
    "name": "BuildThatDoesNotExist",
    "errorMessage": "No build found with name: BuildThatDoesNotExist."
  },
  "statusDetails": [
    { "id": 1, "name": "PASS" },
    { "id": 2, "name": "FAIL" },
    { "id": 3, "name": "WIP" },
    { "id": 4, "name": "BLOCKED" },
    { "id": 5, "name": "NOT EXECUTED" }
  ],
  "testExecutionViewId": 200
}

Error Responses

Missing projectName:

{
  "success": false,
  "code": "projectName is mandatory."
}

Project not found:

{
  "success": false,
  "code": "No project found with name: ProjectThatDoesNotExist."
}

When projectName is missing or does not match a project that the API key can access, no other parameter is evaluated.

In this section:

Get Details Service

Error Responses

Search results