Retrieving Schemes with Project Configuration APIs

Reading Time: 5 minutes Handling the configuration of projects can be challenging – whether you’re an admin auditing the configuration of multiple Jira projects, or a developer trying to set the application flow in order to accommodate potential differences in target projects. Our new set of comprehensive REST APIs aim to solve these issues and […]

Reading Time: 5 minutes


Handling the configuration of projects can be challenging – whether you’re an admin auditing the configuration of multiple Jira projects, or a developer trying to set the application flow in order to accommodate potential differences in target projects. Our new set of comprehensive REST APIs aim to solve these issues and more. We’re excited to share an overview of how to use the new APIs for retrieving various project configuration items.

Let’s talk about schemes

The ability to wrap one’s head around effective classic project configuration is what often separates a Jira veteran from the casual user. As such, it constitutes one of Jira’s most notable learning curves. At the root of what makes classic projects so notorious is also what makes them so versatile and customizable: schemes.

Configuration schemes are the mappings between other configuration items and projects. A scheme is how a particular project uses selected issue types, which draw from a set of selected fields. Configuration items at their core are fairly simple entities; it’s the schemes that bring the flexibility to treat them like atomic building blocks to tailor to a projects’ specific needs.

To make this a bit less cryptic, let’s dive in to some examples.

Issue type schemes

Issue type scheme is a configuration that describes which issue types are available to projects and the order in which they are displayed. The issue type is selected by default when creating an issue. In essence, it’s the Issue Types ↔︎ Project mapping.

Issue Type Scheme

Retrieving issue types and issue type Schemes with REST API

To retrieve all available issue type schemes: GET /rest/api/3/issuetypescheme

The response returns a list of issue type schemes IDs:

 {
      "id": "10001",
      "name": "SUP: Kanban Issue Type Scheme",
      "description": "A collection of issue types suited to use in a
 kanban style project."
    },
    {
      "id": "10002",
      "name": "HR: Scrum issue type scheme",
      "description": "",
      "defaultIssueTypeId": "10004"
    }

Learn more: Issue type schemes


To retrieve issue type schemes associated with projects: GET /rest/api/3/issuetypescheme/project

The response returns projectIds for each assigned issue type scheme:

 {
      "issueTypeScheme": {
        "id": "10001",
        "name": "SUP: Kanban Issue Type Scheme",
        "description": ""
      },
      "projectIds": [
        "10002"
      ]
    },
    {
      "issueTypeScheme": {
        "id": "10002",
        "name": "HR: Scrum issue type scheme",
        "description": "",
        "defaultIssueTypeId": "10004"
      },
      "projectIds": [
        "10003",
        "10004",
        "10005"
      ]
    }

Learn more: Issue type schemes for projects


To retrieve Issue types contained by an issue type scheme: GET /rest/api/3/issuetypescheme/mapping

The response contains a list of issue types associated to issue type scheme:

    {
      "issueTypeSchemeId": "10000",
      "issueTypeId": "10001"
    },
    {
      "issueTypeSchemeId": "10000",
      "issueTypeId": "10002"
    }

Learn more: Get issue type scheme mapping

Screen schemes and issue type screen schemes

Now, let’s look into a more complex scheme. Issue type screen scheme takes a screen scheme, applies it to an issue type and associates that relationship to a project: Project ↔︎ Issue Type ↔︎ Screen Scheme.

The below screen scheme is a mapping between screens (containing a collection of fields organized into tabs) and four issue operations: default, create, edit, and view. To sum it all up, issue type screen scheme is responsible for the scenario where in project ABC, when creating a bug, there’s a ‘severity’ field visible on the creation screen.

Retrieving screen schemes and issue type screen schemes with APIs

To retrieve all available screen schemes: GET /rest/api/3/screenscheme

The response contains a list of screen schemes:

     {
      "id": 10010,
      "name": "Employees screen scheme",
      "description": "Managing employees data",
      "screens": {
        "default": 10017,
        "edit": 10019,
        "create": 10019,
        "view": 10020
      }

Learn more: Get all screen schemes


To retrieve all available issue type screen schemes: GET /rest/api/3/issuetypescreenscheme

The response lists Issue type screen schemes:

 {
      "id": "10000",
      "name": "Office issue type screen scheme",
      "description": "Managing office projects"
 }

Learn more: Get issue type screen schemes


To retrieve issue type screen schemes associated with projects: GET /rest/api/3/issuetypescreenscheme/project

The response lists issue type screen schemes with associated projectIds:

{ 
      "issueTypeScreenScheme": {
        "id": "1",
        "name": "Default Issue Type Screen Scheme",
        "description": "The default issue type screen scheme"
      },
      "projectIds": [
        "10000",
        "10001"
      ]
}

Learn more: Get issue type screen schemes for projects


To retrieve all available Issue Type Screen Scheme items: GET /rest/api/3/issuetypescreenscheme/mapping

The response returns the mapping of issue type screen schemes with issue types and screen schemes:

 {
      "issueTypeScreenSchemeId": "10020",
      "issueTypeId": "10000",
      "screenSchemeId": "10010"
 }

Learn more: Get issue type screen scheme items

Other configuration schemes

With the changes and new endpoints we have recently introduced, developers and admins can now utilize APIs to retrieve all project configurations schemes. Learn more about working with other configuration components by reading their corresponding doc sets, including:

See the APIs in action

Scenario:
You are building an awesome app that will enhance the way bugs are handled in the service channel. Before you deploy the functionality, your app can verify that the correct configuration context is available to apply changes and make necessary adjustments.

Task:
Check if in every project the assigned issue type scheme has a bug issue type.

Solution:
First, we need let’s determine the id of the Bug issue type:

GET /rest/api/3/issuetype
 {
    "self": "https://your-domain.atlassian.net/rest/api/3/issueType/3",
    "id": "3",
    "description": "A problem with the software.",
    "iconUrl": "https://your-domain.atlassian.net//secure/viewavatar?
size=xsmall&avatarId=10299&avatarType=issuetype",",
    "name": "Bug",
    "subtask": false,
    "avatarId": 1
  }

Then, let’s get all issue type schemes associated with the existing projects:

GET /rest/api/3/issuetypescheme/project?
projectId=10000&projectId=10001&projectId=10002

 "values": [
    {
      "issueTypeScheme": {
        "id": "10000",
        "name": "Default Issue Type Scheme",
        "description": "Default issue type scheme is the 
 list of global issue types...",
        "defaultIssueTypeId": "3",
        "isDefault": true
      },
      "projectIds": [
        "10000",
        "10001"
      ]
    },
    {
      "issueTypeScheme": {
        "id": "10001",
        "name": "SUP: Kanban Issue Type Scheme",
        "description": "A collection of issue types suited to use 
in a kanban style project."
      },
      "projectIds": [
        "10002"
      ]
    }
  ]

We can see that there are two issue type schemes in scope. Let’s check which issue types belong to these schemes:

GET /rest/api/3/issuetypescheme/mapping?
issueTypeSchemeId=10000&issueTypeSchemeId=10001
"values": [
    {
      "issueTypeSchemeId": "10000",
      "issueTypeId": "3"
    },
    {
      "issueTypeSchemeId": "10000",
      "issueTypeId": "10001"
    },
    {
      "issueTypeSchemeId": "10000",
      "issueTypeId": "10002"
    },
    {
      "issueTypeSchemeId": "10001",
      "issueTypeId": "10000"
    }
  ]

It’s clear that the issue type scheme with Id 10001 does not contain a Bug issue type. You can add it by using our newly-released endpoint, add issue types to issue type schemes:

PUT /rest/api/3/issuetypescheme/10001/issuetype

{
"issueTypeIds": ["3"]
}

Keep calm and configure projects

Classic project configuration had been a significant gap in Jira Cloud extensibility. We aim to change this, as providing API coverage in this area is a top priority of the Jira Cloud Ecosystem teams. Stay tuned and follow along on our Developer Community to learn more about new features as we release them.

Up next: APIs to assign schemes to projects, CRUD for issue types and issue type schemes

Let us know what you think

Your feedback is critical in helping us deliver safe and comprehensive extensibility in Jira Cloud. What are your initial impressions about GET APIs for classic project configuration? Will you use it? Will it help you build better apps? Let us know by posting on the Developer Community (add tags: jira-cloud, rest-api and project-config ).

Is there a classic project configuration API that you are waiting for? Let us know by filing a feature request.

Learn more about developing for Jira Cloud from our documentation.

The post Retrieving Schemes with Project Configuration APIs appeared first on Atlassian Developer Blog.

Source: Atlassian