This page explains the operating principle and the configuration of REST API Connected items.

REST API Connected item configuration

We are going to walk through the configuration of an issue picker from Atlassian's Jira. 

We create a select list Connected item linked to Atlassian's Jira, with URL: https://jira.atlassian.com/rest/api/2

Fetch data from API

The path to the relevant REST endpoint (the address used to retrieve the issues) is: https://jira.atlassian.com/rest/api/2/search 

When we click on open query, here is (a part of) the JSON document return

JSON return of previous call

{
"expand": "schema,names",
"startAt": 0,
"maxResults": 50,
"total": 274547,
"issues": [
{
	"expand": "operations,versionedRepresentations,editmeta,changelog,renderedFields",
	"id": "1843729",
	"self": "https://jira.atlassian.com/rest/api/2/issue/1843729",
	"key": "SRCTREEWIN-13759",
	"fields": {
		"customfield_16730": {
			"self": "https://jira.atlassian.com/rest/api/2/customFieldOption/13930",
			"value": "Other",
			"id": "13930",
			"disabled": false
		}, 
		"summary": "Please make warning LESS SCARY about a detached head",		
		"status": {
			"self": "https://jira.atlassian.com/rest/api/2/status/11772",
			"description": "This suggestion needs more unique domain votes and comments before being reviewed by our team.",
			"iconUrl": "https://jira.atlassian.com/images/icons/statuses/generic.png",
			"name": "Gathering Interest",
			"id": "11772",
			"statusCategory": {
				"self": "https://jira.atlassian.com/rest/api/2/statuscategory/2",
				"id": 2,
				"key": "new",
				"colorName": "blue-gray",
				"name": "To Do"
				}
			},
		"reporter": {
			"self": "https://jira.atlassian.com/rest/api/2/user?username=6e081c3809bf",
			"name": "6e081c3809bf",
			"key": "JIRAUSER5502814",
			"avatarUrls": {
				"48x48": "https://jira.atlassian.com/secure/useravatar?ownerId=JIRAUSER5502814&avatarId=6473713",
				"24x24": "https://jira.atlassian.com/secure/useravatar?size=small&ownerId=JIRAUSER5502814&avatarId=6473713",
				"16x16": "https://jira.atlassian.com/secure/useravatar?size=xsmall&ownerId=JIRAUSER5502814&avatarId=6473713",
				"32x32": "https://jira.atlassian.com/secure/useravatar?size=medium&ownerId=JIRAUSER5502814&avatarId=6473713"
				},
			"displayName": "Hercules",
			"active": true,
			"timeZone": "Europe/Amsterdam"
			},
		"project": {
			"self": "https://jira.atlassian.com/rest/api/2/project/14510",
			"id": "14510",
			"key": "SRCTREEWIN",
			"name": "Sourcetree for Windows",
			"projectTypeKey": "software",
			"avatarUrls": {
				"48x48": "https://jira.atlassian.com/secure/projectavatar?pid=14510&avatarId=105090",
				"24x24": "https://jira.atlassian.com/secure/projectavatar?size=small&pid=14510&avatarId=105090",
				"16x16": "https://jira.atlassian.com/secure/projectavatar?size=xsmall&pid=14510&avatarId=105090",
				"32x32": "https://jira.atlassian.com/secure/projectavatar?size=medium&pid=14510&avatarId=105090"
				}
			}
}
GROOVY

The next step is to find the array where the desired item options are stored in the returned object. In our case, the array is located at "issues" in line 6.

The array's attributes will be used for the display template configuration.

Customize look & feel

The connected item will display a list containing [...] Now we would like to specify what each entry in the list will look like, using the display template: Issue Key - Issue Summary

In the Freemarker display template, the "row" variable represent a single entry in the JSON option array, we fetch the key and summary by writing: ${row.key} - ${row.fields.summary}

Why?

  • The attribute key is located at the root level of each JSON option
  • The attribute summary is nested under the fields attribute of issues


Runtime