Discovering the Project Structure
This page describes how is it possible to query all information to understand the configuration of a project.
Project information
Getting the list of available projects
GET /v3/projects endpoint will return a list of project references which are accessible by the user.
Response example:
[
{
"id": 1,
"name": "Intland Software's Scrum Template",
"type": "ProjectReference"
},
...
]
{
"id": 1,
"name": "Intland Software's Scrum Template",
"type": "ProjectReference"
},
...
]
Getting detailed information about a specific project
GET /v3/projects/{projectId} will return the details of a project.
Response example:
{
"id": 1,
"name": "Intland Software's Scrum Template",
"description": "Agile-Scrum Project Template",
"descriptionFormat": "Wiki",
"version": 1,
"keyName": "ASCRUMT",
"closed": false,
"deleted": false,
"template": true,
"createdAt": "2020-08-04T10:52:45.639",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
}
}
"id": 1,
"name": "Intland Software's Scrum Template",
"description": "Agile-Scrum Project Template",
"descriptionFormat": "Wiki",
"version": 1,
"keyName": "ASCRUMT",
"closed": false,
"deleted": false,
"template": true,
"createdAt": "2020-08-04T10:52:45.639",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
}
}
Searching projects by given criteria
POST /v3/projects/search will return all project which are met a certain criteria.
This can be useful in case of when our project deployment feature is used, as the project id can change during such deployments.
Request body example:
{
"keyName": "ASCRUMT"
}
"keyName": "ASCRUMT"
}
Response example:
{
"page": 1,
"pageSize": 1,
"total": 1,
"projects": [
{
"id": 25,
"name": "Intland Software's Scrum Template",
"description": "Agile-Scrum Project Template",
"descriptionFormat": "Wiki",
"version": 1,
"keyName": "ASCRUMT",
"closed": false,
"deleted": false,
"template": true,
"createdAt": "2020-08-04T10:52:45.639",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
}
}
]
}
"page": 1,
"pageSize": 1,
"total": 1,
"projects": [
{
"id": 25,
"name": "Intland Software's Scrum Template",
"description": "Agile-Scrum Project Template",
"descriptionFormat": "Wiki",
"version": 1,
"keyName": "ASCRUMT",
"closed": false,
"deleted": false,
"template": true,
"createdAt": "2020-08-04T10:52:45.639",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
}
}
]
}
Tracker information
Getting the list of trackers in a specific project
GET /v3/projects/{projectId}/trackers will return a list of tracker references which are contained by a specific project.
Response example:
[
{
"id": 4304,
"name": "Releases",
"type": "TrackerReference"
},
{
"id": 4305,
"name": "User Stories",
"type": "TrackerReference"
},
{
"id": 4306,
"name": "Epics",
"type": "TrackerReference"
},
...
]
{
"id": 4304,
"name": "Releases",
"type": "TrackerReference"
},
{
"id": 4305,
"name": "User Stories",
"type": "TrackerReference"
},
{
"id": 4306,
"name": "Epics",
"type": "TrackerReference"
},
...
]
Getting detailed information about a specific tracker
GET /v3/trackers/{trackerId} will return detailed information about a specific tracker.
Response example:
{
"id": 4304,
"name": "Releases",
"descriptionFormat": "PlainText",
"keyName": "RELEASE",
"version": 1,
"createdAt": "2020-08-04T10:53:47.281",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
},
"type": {
"id": 103,
"name": "Release",
"type": "TrackerTypeReference"
},
"deleted": false,
"hidden": false,
"usingWorkflow": true,
"onlyWorkflowCanCreateNewReferringItem": false,
"usingQuickTransitions": false,
"defaultShowAncestorItems": false,
"defaultShowDescendantItems": false,
"project": {
"id": 25,
"name": "Intland Software's Scrum Template",
"type": "ProjectReference"
},
"availableAsTemplate": false
}
"id": 4304,
"name": "Releases",
"descriptionFormat": "PlainText",
"keyName": "RELEASE",
"version": 1,
"createdAt": "2020-08-04T10:53:47.281",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
},
"type": {
"id": 103,
"name": "Release",
"type": "TrackerTypeReference"
},
"deleted": false,
"hidden": false,
"usingWorkflow": true,
"onlyWorkflowCanCreateNewReferringItem": false,
"usingQuickTransitions": false,
"defaultShowAncestorItems": false,
"defaultShowDescendantItems": false,
"project": {
"id": 25,
"name": "Intland Software's Scrum Template",
"type": "ProjectReference"
},
"availableAsTemplate": false
}
Searching for a specific tracker type
For first we need to use the GET /v3/trackers/types endpoint to find out what kind of trackers are defined in the system.
Response example:
[
{
"id": 1,
"name": "Issue",
"type": "TrackerTypeReference"
},
{
"id": 2,
"name": "Bug",
"type": "TrackerTypeReference"
},
{
"id": 3,
"name": "Change Request",
"type": "TrackerTypeReference"
},
...
{
"id": 103,
"name": "Release",
"type": "TrackerTypeReference"
},
...
]
{
"id": 1,
"name": "Issue",
"type": "TrackerTypeReference"
},
{
"id": 2,
"name": "Bug",
"type": "TrackerTypeReference"
},
{
"id": 3,
"name": "Change Request",
"type": "TrackerTypeReference"
},
...
{
"id": 103,
"name": "Release",
"type": "TrackerTypeReference"
},
...
]
Using the proper TrackerTypeReference we can call the POST /v3/projects/{projectId}/trackers/search endpoint to retrieve only the tracker of a specific type:
Request body example:
{
"types": [
{
"id": 2,
"name": "Bug",
"type": "TrackerTypeReference"
}
]
}
"types": [
{
"id": 2,
"name": "Bug",
"type": "TrackerTypeReference"
}
]
}
Response example:
{
"page": 1,
"pageSize": 1,
"total": 1,
"trackers": [
{
"id": 4307,
"name": "Bugs",
"description": "Errors, flaws, faults in the software product",
"descriptionFormat": "Wiki",
"keyName": "BUG",
"version": 1,
"createdAt": "2020-08-04T10:53:47.281",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
},
"type": {
"id": 2,
"name": "Bug",
"type": "TrackerTypeReference"
},
"deleted": false,
"hidden": false,
"usingWorkflow": true,
"onlyWorkflowCanCreateNewReferringItem": false,
"usingQuickTransitions": false,
"defaultShowAncestorItems": false,
"defaultShowDescendantItems": false,
"project": {
"id": 25,
"name": "Intland Software's Scrum Template",
"type": "ProjectReference"
},
"availableAsTemplate": false
}
]
}
"page": 1,
"pageSize": 1,
"total": 1,
"trackers": [
{
"id": 4307,
"name": "Bugs",
"description": "Errors, flaws, faults in the software product",
"descriptionFormat": "Wiki",
"keyName": "BUG",
"version": 1,
"createdAt": "2020-08-04T10:53:47.281",
"createdBy": {
"id": 1,
"name": "bond",
"type": "UserReference"
},
"type": {
"id": 2,
"name": "Bug",
"type": "TrackerTypeReference"
},
"deleted": false,
"hidden": false,
"usingWorkflow": true,
"onlyWorkflowCanCreateNewReferringItem": false,
"usingQuickTransitions": false,
"defaultShowAncestorItems": false,
"defaultShowDescendantItems": false,
"project": {
"id": 25,
"name": "Intland Software's Scrum Template",
"type": "ProjectReference"
},
"availableAsTemplate": false
}
]
}
Tracker field information
Getting the fields of a tracker
GET /v3/trackers/{trackerId}/fields endpoint will return references of the configured fields in a tracker.
Response example:
[
{
"id": 0,
"name": "ID",
"type": "FieldReference",
"trackerId": 4307
},
{
"id": 1,
"name": "Tracker",
"type": "FieldReference",
"trackerId": 4307
},
{
"id": 2,
"name": "Priority",
"type": "FieldReference",
"trackerId": 4307
},
{
"id": 3,
"name": "Name",
"type": "FieldReference",
"trackerId": 4307
},
...
]
{
"id": 0,
"name": "ID",
"type": "FieldReference",
"trackerId": 4307
},
{
"id": 1,
"name": "Tracker",
"type": "FieldReference",
"trackerId": 4307
},
{
"id": 2,
"name": "Priority",
"type": "FieldReference",
"trackerId": 4307
},
{
"id": 3,
"name": "Name",
"type": "FieldReference",
"trackerId": 4307
},
...
]
Getting detailed information about a field in a specific tracker
GET /v3/trackers/{trackerId}/fields/{fieldId} will return detailed information about a specific field.
Response example:
{
"id": 14,
"name": "Severity",
"description": "VoCA (Voice of Customer Audit)",
"type": "OptionChoiceField",
"hidden": false,
"valueModel": "ChoiceFieldValue<ChoiceOptionReference>",
"mandatoryInStatuses": [
{
"id": 0,
"name": "Unset",
"type": "ChoiceOptionReference"
},
{
"id": 3,
"name": "New / Unassigned",
"type": "ChoiceOptionReference"
},
{
"id": 5,
"name": "In Verification",
"type": "ChoiceOptionReference"
},
{
"id": 7,
"name": "Closed",
"type": "ChoiceOptionReference"
},
{
"id": 8,
"name": "Open In Domain",
"type": "ChoiceOptionReference"
}
],
"multipleValues": false,
"options": [
{
"id": 0,
"name": "Unset",
"type": "ChoiceOptionReference"
},
{
"id": 1,
"name": "VoCA Prio 1",
"type": "ChoiceOptionReference"
},
{
"id": 2,
"name": "VoCA Prio 2",
"type": "ChoiceOptionReference"
},
{
"id": 7,
"name": "Not Applicable",
"type": "ChoiceOptionReference"
}
],
"trackerItemField": "severities",
"referenceType": "ChoiceOptionReference"
},
"id": 14,
"name": "Severity",
"description": "VoCA (Voice of Customer Audit)",
"type": "OptionChoiceField",
"hidden": false,
"valueModel": "ChoiceFieldValue<ChoiceOptionReference>",
"mandatoryInStatuses": [
{
"id": 0,
"name": "Unset",
"type": "ChoiceOptionReference"
},
{
"id": 3,
"name": "New / Unassigned",
"type": "ChoiceOptionReference"
},
{
"id": 5,
"name": "In Verification",
"type": "ChoiceOptionReference"
},
{
"id": 7,
"name": "Closed",
"type": "ChoiceOptionReference"
},
{
"id": 8,
"name": "Open In Domain",
"type": "ChoiceOptionReference"
}
],
"multipleValues": false,
"options": [
{
"id": 0,
"name": "Unset",
"type": "ChoiceOptionReference"
},
{
"id": 1,
"name": "VoCA Prio 1",
"type": "ChoiceOptionReference"
},
{
"id": 2,
"name": "VoCA Prio 2",
"type": "ChoiceOptionReference"
},
{
"id": 7,
"name": "Not Applicable",
"type": "ChoiceOptionReference"
}
],
"trackerItemField": "severities",
"referenceType": "ChoiceOptionReference"
},
id
Id of the field. It can be used to identify a field for example for value modifications.
name
Name of the field.
description
Description of the field.
type
.hidden
Indicator if the field is hidden.
valueModel
The name of the model which needs to be provided in case of value modifications.
mandatoryInStatuses
List of Status options where the field value is mandatory to be set in a tracker item.
multipleValues
Indicator if multiple values are allowed for a choice field.
options
List of options for a choice option field.
trackerItemField
In case that the field is built-in (which means that it's common across all trackers) this property tells where in the TrackerItem model can it be set.
referenceType
For choice fields this property tells which type of references do they accept.
For Example:
• ChoiceOptionReference for choice option fields.
• TrackerItemReference for tacker item reference fields.
Getting permission settings of a tracker field
GET /v3/trackers/{trackerId}/fields/{fieldId}/permissions will return the status/role/permission matrix of a specific field.
UI representation:
Response example:
[
{
"status": {
"id": 0,
"name": "Unset",
"type": "ChoiceOptionReference"
},
"permissions": [
{
"role": {
"id": 1,
"name": "Project Admin",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "READ"
},
{
"role": {
"id": 2,
"name": "Developer",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "READ"
},
...
]
},
{
"status": {
"id": 1,
"name": "New",
"type": "ChoiceOptionReference"
},
"permissions": [
{
"role": {
"id": 1,
"name": "Project Admin",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "WRITE"
},
{
"role": {
"id": 2,
"name": "Developer",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "WRITE"
},
...
},
{
"status": {
"id": 2,
"name": "Verified",
"type": "ChoiceOptionReference"
},
"permissions": [ ... ]
},
{
"status": {
"id": 3,
"name": "In progress",
"type": "ChoiceOptionReference"
},
"permissions": [ ... ]
},
...
]
{
"status": {
"id": 0,
"name": "Unset",
"type": "ChoiceOptionReference"
},
"permissions": [
{
"role": {
"id": 1,
"name": "Project Admin",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "READ"
},
{
"role": {
"id": 2,
"name": "Developer",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "READ"
},
...
]
},
{
"status": {
"id": 1,
"name": "New",
"type": "ChoiceOptionReference"
},
"permissions": [
{
"role": {
"id": 1,
"name": "Project Admin",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "WRITE"
},
{
"role": {
"id": 2,
"name": "Developer",
"type": "RoleReference"
},
"field": null,
"project": null,
"accessLevel": "WRITE"
},
...
},
{
"status": {
"id": 2,
"name": "Verified",
"type": "ChoiceOptionReference"
},
"permissions": [ ... ]
},
{
"status": {
"id": 3,
"name": "In progress",
"type": "ChoiceOptionReference"
},
"permissions": [ ... ]
},
...
]