This section describes how Elements Connect is integrated with some endpoints of Jira REST API.

Elements Connect is compatible with 3 endpoints:

POST /rest/api/2/issue
to set the value of an Elements Connect field while creating Jira Issues
PUT /rest/api/2/issue/{issueIdOrKey}
to edit the value of an Elements Connect field on an existing Jira Issue
GET /rest/api/2/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}
to get a description of all the custom fields present on an issue creation screen, including Elements Connect fields

GET /rest/api/2/issue/{issueIdOrKey}
to get values and - optionally - the display values of all the Elements connect fields present on an issue
GET /rest/api/2/search
to search for issues and retrieve the stored value and - optionally - the display value of all the Elements connect fields present on an issue

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 "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 "10118" is set on line 10 to "abcat0200000".

To set the value of a Snapshot Text field, you just have to enter a string which corresponds to a valid value (i.e. a value returned by the datasource):

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

Fields of type "Live 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 Text Legacy: com.valiantys.jira.plugins.SQLFeed:com.valiantys.jira.plugin.sqlfeed.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 has no effect when this endpoint is called, it means that all results are always returned.

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.

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

The /rest/api/2/issue/{issueIdOrKey} API returns a full representation of the issue for the given issue key. The result contains all the values of any fields and (optionally) the HTML rendered values.

If parameter expand is set to renderedFields (i.e.: /rest/api/2/issue/{issueIdOrKey}?expand=renderedFields), this endpoint returns the rendered values for all Elements Connect fields in the display view.

Live Text and Legacy fields

In the example below, we try to get the key(s) (value) of an Elements Connect field with id "10000" on a specific issue.

In the renderedFields object we get the rendered value with the template configured in the display view.

{
    "fields": {
        "customfield_10000": ["78"]
    },
	"renderedFields":{
		"customfield_10000":"This is an awesome template: Activision"
	}
}

Snapshot fields

This API is compatible with Elements Connect fields of type snapshot:

Snapshot Text
Snapshot Date
Snapshot Date Time

Regarding fields of type Snapshot, the values returned in the renderedFields section (display values) are the same than those in the fields section.

{
    "fields": {
        "customfield_10000": ["Activision"]
    },
	"renderedFields":{
		"customfield_10000":["Activision"]
	}
}

User fields

This API is not compatible with this type of field when using a Jira version higher than 8.4.x.

In the below example we try to get the value of a user field with id "10000".

The API result contains:

fields: The actual user (user object) with all information
renderedFields: The rendered value (using the template of the display view)

{
    "fields": {
        "customfield_10000": [
			{
				"self": "http://elements.com/jira/rest/api/2/user?username=admin",
				"name": "Artur Hewitt",
				"key": "admin",
				"emailAddress": "admin@admin.com",
				"avatarUrls": {
					"48x48": "https://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=48",
					"24x24": "https://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=24",
					"16x16": "https://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=16",
					"32x32": "https://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=32"
							},
				"displayName": "Artur Hewitt",
				"active": true,
				"timeZone": "Europe/Paris"
				}
			]
   		 }
		}
	"renderedFields":{
	    "customfield_10000":"This is a beautiful template with user :Artur Hewitt"
	}
}

GET /rest/api/2/search

The /rest/api/2/search endpoint returns a full representation of the issues matching a JQL. The result contains all the values of any fields and (optionally) the HTML rendered values.

If parameter expand is set to to renderedFields (i.e.: /rest/api/2/issue/{issueIdOrKey}?expand=renderedFields), this endpoint returns the rendered values for all Elements Connect fields in the display view.

Regarding Elements Connect fields, the behavior is identical to the one described above for the GET /rest/api/2/issue/{issueIdOrKey} endpoint.