Jira REST API


This sections describe how Elements Connect is integrated with some endpoints of Jira REST API.

Elements Connect is compatible with 3 endpoints:

POST /rest/api/2/issue

Here is how to set the value of an Elements Connect field while creating an issue with the /rest/api/2/issue endpoint.

Fields of type "Live Text" and "Snapshot Text"

In the example below, an issue is created in the Jira project with id "10000".
The value of the Elements Connect field with id "10119" is set on line 10 to "abcat0200000".

To set the value of an Elements Connect field:

  • You must pass an array of strings, even if the field is a single value field.
  • The field value must be a valid Elements Connect field key.
    If you send the Elements Connect field display value instead of its key, the value will be saved but you will have an error on display.


{
    "fields": {
        "project": {
            "id": "10000"
        },
        "summary": "Created with REST API",
        "issuetype": {
            "id": "10003"
        },
        "customfield_10119": ["abcat0200000"]
    }
}

Fields of type "Live User"

In the example below, an issue is created in the Jira project with id "10000".
The value of the Elements Connect user field with id "10120" is set on line 13 to "user1".

To set the value of an Elements Connect field:

  • You must pass an array of object(s), even if the field is a single value field.
  • The field value must be a valid username.
    If you send a user ID value instead of its username, the issue will not be created.
{
    "fields": {
        "project": {
            "id": "10000"
        },
        "summary": "Created with REST API",
        "issuetype": {
            "id": "10003"
        },
        "assignee": {
            "name": "user1"
        }
        "customfield_10120": [
            {"name": "user1"}
        ]
    }
}

PUT /rest/api/2/issue/{issueIdOrKey}

Here is how to set the value of an Elements Connect field while editing an issue with the /rest/api/2/issue/{issueIdOrKey} endpoint.

Field of type "Live Text" and "Snapshot text"

In the example below, the value of the Elements Connect field with id "10000" is set to "abcat0200001".
Just like when creating an issue, you must pass Elements Connect fields keys in an array of strings.

{
  "fields": {
   "customfield_10000": ["abcat0200001"]
  }
}

Field of type "Live User"

In the example below, the value of the Elements Connect field with id "10000" is set to "user1".
Just like when creating an issue, you must pass Elements Connect fields username in an array of object(s).

{
    "fields": {
        "customfield_10000": [
            {"name": "user1"}
        ]
    }
}

GET /rest/api/2/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}

The GET /rest/api/2/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId} API provides a description of all the custom fields present on an issue creation screen, including Elements Connect fields.

Third party products like Zendesk or TestRail rely on this API to create Issue creation form, you can also use it in a custom development.

Usage

Example value on a Live Text Elements Connect field (field plugged to the awesome GiantBomb REST API):

{
   "required":false,
   "schema":{
      "type":"array",
      "items":"string",
      "custom":"com.valiantys.jira.plugins.SQLFeed:nfeed-standard-customfield-type",
      "customId":10904
   },
   "name":"Company",
   "fieldId":"customfield_10904",
   "hasDefaultValue":false,
   "operations":[
      "set"
   ],
   "allowedValues":[
      {
         "value":"Abacus Software, Inc.",
         "id":"73"
      },
      {
         "value":"Acclaim Entertainment, Inc.",
         "id":"88"
      },
      {
         "value":"Activision",
         "id":"78"
      },
      (...)
      {
         "value":"n-Space, Inc.",
         "id":"33"
      }
   ]
}


The custom  attribute of the schema object depends on the Elements Connect field type:

  • Live Text: com.valiantys.jira.plugins.SQLFeed:nfeed-standard-customfield-type
  • Live User: com.valiantys.jira.plugins.SQLFeed:com.valiantys.jira.plugins.sqlfeed.user.customfield.type
  • Snapshot Text: com.valiantys.jira.plugins.SQLFeed:nfeed-unplugged-customfield-type

allowedValues  contains the custom field options:

  • value: the field "display value" which shall be displayed in the field editor
  • id: the field stored value - the "key" - which shall be sent in Jira when creating the issue (see POST /rest/api/2/issue section above).

    Regarding fields of type Snapshot text, value and id  are the same (the stored value is equal to the display value).

Elements Connect field types compatibility

This API is compatible with Elements Connect fields of type:

  • Live Text
  • Live User
  • Snapshot Text

Values of Snapshot Date and Snapshot Datetime are not included in the response of the /createmeta API.

Dependencies

Because Elements Connect only gets a limited context, only three dependencies can be resolved when this API is called:

  • $currentUser 
  • $issue.project 
  • $issue.issueType 

If a field query has dependencies to other custom fields or attributes, there is a great chance that the field values won't be resolved and thus allowedValues will be empty.

maxResults

maxResults parameter is applied when retrieving values. If you need to retrieve all the field options, you must set maxResults to 0.

Deactivated by default

To avoid unexpected performance issues, by default Elements Connect fields are not included in the response of /createmeta.
It can be activated manually field by field from the "Advanced" tab of the field configuration screen through the option /createmeta.

Keep in mind that activating this option can increase the response time of the /createmeta API. The reason is that the query of the fields on which it is active will be executed at each call of /createmeta, which can take time.