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

Brett Miles SSC

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?

Andy Heinzer

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