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"
  },
  ...
]

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"
  }
}

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"
}

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"
      }
    }
  ]
}

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"
  },
  ...
]

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
}

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"
  },
  ...
]

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"
    }
  ]
}

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
    }
  ]
}

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
  },
  ...
]

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

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

Discriminator property.

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": [ ... ]
  },
  ...
]