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.
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:
- Field configuration and field configuration schemes
- Workflow schemes
- Notification schemes
- Permission schemes
- Issue security schemes
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.