Inconsistencies between the Create Issue API and the corresponding Get Create Issue Metadata

Brett Miles SSC January 5, 2021

I'm developing a integration with Jira using the REST API's and have found a number of discrepancies between the metadata returned by the Get Create Issue Metadata API (of the form rest/api/3/issue/createmeta?projectKeys={ProjectKey}&expand=projects.issuetypes.fields) and the corresponding Create Issue API (rest/api/3/issue)

The first anomaly is that the metadata for the Sprint (customfield_10020) advises that it is of type array

"customfield_10020": {
"required": false,
"schema": {
"type": "array",
"items": "json",
"custom": "com.pyxis.greenhopper.jira:gh-sprint",
"customId": 10020
},
"name": "Sprint",
"key": "customfield_10020",
"hasDefaultValue": false,
"operations": [
"set"
]
},

however if an array is passed in the body of the Create Issue API it fails with the following error: 

{
"errorMessages": [
"Number value expected as the Sprint id."
],
"errors": {
}
}

passing a simply number for the sprint id works successfully.

Also, the Description field metadata reports that it is of type string regardless of whether the api version used is 2 or 3.

 "description": {
"required": false,
"schema": {
"type": "string",
"system": "description"
},
"name": "Description",
"key": "description",
"hasDefaultValue": false,
"operations": [
"set"
]
},

Version 2 of the Create Issue API () does accept a plain string value, however, version 3 of the API fails with the following error:

{
"errorMessages": [
],
"errors": {
"description": "Operation value must be an Atlassian Document (see the Atlassian Document Format)"
}
}

As a side issue, the Get Issue Create Metadata API returns "timetracking" as one of the "fields" and yet it is actually a wrapper around to individual fields (Original Estimate and Remaining Estimate) which are not reported at all.  My expectation was that calling the Get Create Issue Metadata API should provide all of the information necessary to correctly structure the Create Issue API and yet it appears to be both inaccurate and incomplete.  Am I missing a piece of the puzzle?

2 answers

2 votes
Brett Miles SSC January 7, 2021

Hi Andy.  Thanks for responding, although I don't think it fully addresses the issues raised.  While I appreciate you raising ticket JRACLOUD-75814 for the Description string vs ADF issue, you've copied in the response from the Sprint example into the ticket.  While I'm not familiar with the terminology used by Atlassian but I would have thought the ticket should be raised as a bug rather than a feature request - the API is returning the wrong information.

With regards to the Sprint field, since an issue can be associated with more than one sprint, the returned value of array actually seems appropriate.  In this case, it would appear to be a bug in the Create Issue API that is the problem.  I would also expect to see a ticket raised to address that.  Also, the use case of adding an issue into a future sprint has none of the implications that you've mentioned.  I am also already retrieving the relevant board id's and sprints via other API's - the anomalies described in my original post have nothing to do with identifying an appropriate sprint id value - it is with the behaviour of the 2 API's mentioned.  I also don't see the distinction on whether this is a Jira Core provided field or a field provided by an add-in.  Sprints are a fairly integral part of the Jira experience and the API is meant to return details of both core and custom fields - therefore it should be providing correct information and therefore I believe this is also a bug.

With regards to the reference to the Jira Software REST API reference guide, I had already noticed that the versions and behaviours of the Jira Cloud API's are NOT the same as the Jira Software REST API's, so the reference that I've been using is https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/

For the timetracking fields, the API reference you've provided looks at the time estimation settings against an existing issue, not what is needed to create a new issue.  That is the purpose of the "Get Create Issue Metadata API" and it is not meeting its basic reason for existence if it isn't providing the complete set of information needed to create an issue.  Similarly, the url parameter "&expand=projects.issuetypes.fields" is not expanding all the fields since TimeTracking is NOT a field but a parent node above the 2 actually time estimation fields of Original Estimate and Remaining Estimate.  Since the API is not expanding out to the lowest level fields, the API is returning insufficient metadata and therefore I also see this as a bug

Regards

Brett

nitin.karthy June 1, 2023

Was there any solution to the Sprint issue? i.e in Jira 9.8.1 also I can see the Sprint custom field ERRONEOUSLY returning type as array. What is the recommended way to address this inconsitency between the metadata API and the create API?

Brett Miles June 28, 2023

Hi @nitin.karthy .  That's a question for Atlassian. 

0 votes
Andy Heinzer
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 6, 2021

Hi Brett,

I see that you are creating an integration for Jira Cloud and it seems that you have found some inconsistencies in regards to information returned by these endpoints in the REST API.

In regards to the Sprint field, this is a custom field that is provided by the Jira Software application.  It is not a field that exists in Jira Core alone (or Jira sites that only have Jira Service Desk).  Other apps or plugins to Jira can create their own custom fields that behave in a manner other than expected by the Jira Core REST API.  This should explain why this field is listed as an array, but actually only requires a numeric sprint id value to populate here.  I can see why that might be confusing.  However most of the time, issues tend to get created in Jira before they are then assigned to be in a sprint.  

That is not to say that it is impossible to create an issue directly into a sprint, but this isn't always a good idea.  For example, if the sprint is already in progress, creating a new issue causes a scope change that can negatively affect reporting on the active sprint (burndown report tracks such changes).

If you want to set the sprint field for an issue, you would need to know what sprint this issue should go into.  In order to do that, you will probably want to consult the Jira Software REST API reference guide instead.  You will likely need to first find the board in question.  Once you know that boardid, you can then query the sprint endpoint, and pass it that board id in order to see what sprints are available to that board in order to find the correct sprint id to use.

 

As for the Description field indicating the expected type of string here, I believe this is a hold over from the previous wiki editor in Jira.  That old editor would have only expected strings, however the new editor that exists in all Jira Cloud today is always using that newer ADF format.  I suspect that the REST API simply has not be updated to reflect this yet.  I can see how this is misleading.  So I created a feature request to make that REST API be more explicit about the data type that is actually expected.  You can track that request over in JRACLOUD-75814.

 

As for the timetracking concerns here, again we need to first understand if this is a Jira Core issue or a Jira Software one.  Jira Software will provide additional features of estimations.  These estimations are typically set when viewing that issue on a specific board.  While you can use time tracking / log work on any issue in Jira (if time tracking is enabled), the estimations for an issue are really more inline with the Agile Boards in which case the agile endpoint GET /rest/agile/1.0/issue/{issueIdOrKey}/estimation might be more helpful here.  All issues in Jira can have work logged against them using the Issue worklogs endpoints. This tends to be a better means to track this as adding worklog to an existing issue will then also update the timespent field on the issue, as well as adjust the remaining estimate automatically for that issue.

 

I hope this helps.  Thanks for bringing up these concerns to us.  Please let me know if we can be of any additional help here.

Andy

Suggest an answer

Log in or Sign up to answer
DEPLOYMENT TYPE
CLOUD
PRODUCT PLAN
FREE
PERMISSIONS LEVEL
Site Admin
TAGS
AUG Leaders

Atlassian Community Events