JIRA REST Plugin

Page contents

• JIRA REST Plugin
  • Introduction
  • Description
    • User authentication
    • Interactive JIRA REST API Query
  • Syntax Rules
    • JIRAREST{"..."} -- call JIRA issue tracker using REST API
    • JSON Response
    • JSON back reference
  • JIRA REST Examples
    • Get session info of currently authenticated user
    • Create new issue in TEST project
    • Post a comment to an issue in TEST project
    • Get an issue in TEST project
    • Create new Epic and Story in JIRA Agile's TP project
  • Plugin Installation Instructions
  • Plugin Info

JIRA issue tracker interface using REST API

Introduction

JIRA is a popular issue and project tracker by Atlassian. Organizations using TWiki and JIRA can use this plugin to reference and update JIRA content from within TWiki topics.

: Tip: This plugin is generic enough, it can used to establish REST connections to data sources other than JIRA.

Alternatives to this plugin:

• Create your own issue and project tracker in TWiki using TWikiForms and FormattedSearch.
• TWiki:Plugins.JiraPlugin (not installed) - display JIRA issues using JQL search.

Description

This plugin handles a %JIRAREST{}% variable. Use it to get, create and update content in JIRA. The JIRAREST variables makes a REST (Representational state transfer) API call to a JIRA server. Data sent to JIRA and received from JIRA is in JSON format.

User authentication

The user is identified on the JIRA sever with user name and password using basic authentication, specified either in the configuration (default user), or as JIRAREST parameters.

NOTE: Basic authentication transmit user and password unencrypted. Because of this we recommend to run the TWiki server and the REST connection between the TWiki server and the JIRA server under TLS (Transport Layer Security, "https:" protocol) only.

Interactive JIRA REST API Query

Use the JIRA REST API query form to interactively send REST requests to the JIRA server. The query form asks for the action (REST method), command (REST API call), data (for PUT and POST methods), user and password. Omit the user and password if you want to use the default user and password specified in configure. Specifying the password is safe as long as the TWiki server enforces TLS.

To learn the JIRA REST API commands read the JIRA REST API documentation.

Syntax Rules

JIRAREST{"..."} -- call JIRA issue tracker using REST API

• Interface to the Atassian JIRA issue tracker via JIRA REST API call.
• Syntax: %JIRAREST{ "..." command="..." }%
• Parameters:

  Parameter	Description	Default
  "..." or action="..."	Action to take. This is the REST method: "get" for GET, "put" for PUT, "post" for POST, and "delete" for DELETE method.	"" (no action)
  command="..."	REST command, such as: "/rest/api/2/issue/TEST-1"	(required)
  data="..."	Request body sent with REST call, such as: " { \"id\": \"10009\" } "	(required for put and post actions)
  action2="..." command2="..." data2="..."	Conduct a second action after successful execution of the first action. Use this to do multiple REST API calls in one session. No action is taken if there was an error in the first action. In the same way, action3, action4, etc can be executed.	(optional)
  user="..."	User for REST call; default is configure setting {Plugins}{JiraRestPlugin}{User}	(configure setting)
  password="..."	Password for REST call; default is configure setting {Plugins}{JiraRestPlugin}{Password}	(configure setting)

• Example: %JIRAREST{ "get" command="/rest/auth/1/session" }%
• Category: ApplicationsAndComponentsVariables, DatabaseAndFormsVariables, DevelopmentVariables, ImportVariables, WorkflowAndAutomationVariables

JSON Response

The %JIRAREST{}% variable returns a JSON object with the following format:

{ "code": CODE, "content": CONTENT, "error": ERROR, "header": HEADER }

• CODE - response code; example: 201
• CONTENT - response data, in JSON format; example: { "id": "59935", "key": "TEST-6952", "self": "http://jira.example.com/jira/rest/api/2/issue/59935" }
• ERROR - error message; empty string "" if no error; example: "POST '/api/2/issue/' returns code 400"
• HEADER - response header, only shown if {Plugins}{JiraRestPlugin}{Debug} is set to 2; example: { "Cache-Control": "no-cache, no-store, no-transform", "Connection": "close", ... }

Tip: Use the SetGetPlugin to traverse and extract content from the JSON response. See interactive JIRA REST API query form.

It is possible to issue multiple REST API calls in one session using action="..." command="..." data="..." action2="..." command2="..." data2="..." etc. Example JSON response with three actions:

{ "code": 200, "content": {...}, "error": "",
  "code2": 200, "content2": {...}, "error2": "",
  "code3": 200, "content3": {...}, "error3": "" }

JSON back reference

It is possible to use returned content as input for subsequent command<N>="..." and data<N>="...". For example, in the first command="..." you create an issue of type Epic, and in command2="..." you want to create a Story issue, using the key returned by the first command as the "Epic Link" in the Story.

The syntax of a JSON back reference to the content of the first command is $(content.<name>), such as $(content.key). For example, the back reference to object "ID" in the content of the second command is $(content2.ID)

See example to create an Epic and a Story, using a JSON back reference to set the Epic Link in the Story.

Notes:

• If the value of a back reference is a string, the enclosing quotes are stripped.
• At this time only top level objects can be referenced, e.g. arrays and nested objects are not supported at this time.

JIRA REST Examples

• You can use the JIRA REST API query form to try these examples.
• See JIRA REST API Tutorials to get started.
• See JIRA REST API documentation for details.

Get session info of currently authenticated user

%JIRAREST{
  action="get"
  command="/rest/auth/1/session"
  data=""
  user="admin"
  password="*****"
}%

JSON Response:

{ "code": 200, "content": { "self": "http://jira.example.com/jira/rest/api/latest/user?username=admin", "name": "admin", "loginInfo": { "failedLoginCount": 59, "loginCount": 88, "lastFailedLoginTime": "2015-06-01T19:01:20.393-0700", "previousLoginTime": "2015-06-08T15:36:36.839-0700" } }, "error": "" }

Create new issue in TEST project

%JIRAREST{
  action="post"
  command="/rest/api/2/issue/"
  data="DATA"
  user="admin"
  password="*****"
}%

With DATA set to:

{
  "fields": {
    "project":
    {
      "key": "TEST"
    },
    "summary": "REST ye merry gentlemen.",
    "description": "Creating an issue using project key and issue type name via the REST API",
    "versions": [ { "name": "1.2" } ],
    "components": [ { "name": "ESC" } ],
    "issuetype": {
      "name": "Task"
    }
  }
}

Note: Quotes in DATA need to be escaped, such as \"fields\". No escaping is needed when the JIRA REST API query form is used.

JSON Response:

{ "code": 201, "content": { "id": "59937", "key": "TEST-6953", "self": "http://jira.example.com/jira/rest/api/2/issue/59937" }, "error": "" }

Post a comment to an issue in TEST project

%JIRAREST{
  action="post"
  command="/rest/api/2/issue/TEST-6953/comment?expand"
  data="{ \"body\": \"This is a comment submitted via JIRA REST API.\" }"
  user="admin"
  password="*****"
}%

Note: Quotes in the data parameter are escaped. No escaping is needed when the JIRA REST API query form is used: { "body": "This is a comment submitted via JIRA REST API." }

JSON Response:

{ "code": 201, "content": { "self": "http://jira.example.com/jira/rest/api/2/issue/59937/comment/161767", "id": "161767", "author": { "self": "http://jira.example.com/jira/rest/api/2/user?username=admin", "name": "admin", ... }, "error": "" }

Get an issue in TEST project

%JIRAREST{
  action="get"
  command="/rest/api/2/issue/TEST-6953"
  data=""
  user="admin"
  password="*****"
}%

JSON Response:

{ "code": 200, "content": { "expand": "renderedFields,names,schema,transitions,operations,editmeta,changelog", "id": "59937", "self": "http://jira.example.com/jira/rest/api/2/issue/59937", "key": "TEST-6953", "fields": { "progress": { "progress": 0, "total": 0 }, "summary": "REST ye merry gentlemen.", ... }, "error": "" }

Create new Epic and Story in JIRA Agile's TP project

This is a more complex example issuing two commands in one session. The first command creates an Epic, the second command creates a Story linked to the newly created Epic.

%JIRAREST{
  action="post"
  command="/rest/api/2/issue/"
  data="DATA"
  action2="post"
  command2="/rest/api/2/issue/"
  data2="DATA2"
  user="admin"
  password="*****"
}%

With DATA set to:

{
  "fields": {
    "project":
    {
      "key": "TP"
    },
    "customfield_10704": "New Epic (via REST)",
    "summary": "Epic summary via REST API",
    "description": "Creating an Epic using project key and issue type name via the REST API",
    "issuetype": {
      "name": "Epic"
    }
  }
}

With DATA2 set to:

{
  "fields": {
    "project":
    {
      "key": "TP"
    },
    "customfield_10701": "$(content.key)",
    "summary": "Story #1 under Epic $(content.key) via REST API",
    "description": "Creating a Story using project key and issue type name via the REST API",
    "issuetype": {
      "name": "Story"
    }
  }
}

The $(content.key) is a JSON back reference to the key of the Epic created by the first command.

Note: Quotes in DATA need to be escaped, such as \"fields\". No escaping is needed when the JIRA REST API query form is used.

JSON Response:

{
 "error": "",
 "content": {
   "self": "http://jira.example.com/jira/rest/api/2/issue/60015",
   "id": "60015",
   "key": "TP-8"
 },
 "code": 201,
 "error2": "",
 "content2": {
   "self": "http://jira.example.com/jira/rest/api/2/issue/60016",
   "id": "60016",
   "key": "TP-9"
 },
 "code2": 201
}

Plugin Installation Instructions

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = JIRA issue tracker interface using REST API

Plugin Author:	TWiki:Main.PeterThoeny
Copyright:	© 2015 Wave Systems Corp. © 2015 TWiki:Main.PeterThoeny © 2015 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Sponsor:	Wave Systems Corp.
Plugin Version:	2015-09-16

TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	CPAN:JSON (required for JiraRestQuery form)
Other Dependencies:	SetGetPlugin version 2015-03-27 or later (required for JiraRestQuery form)
Perl Version:	5.005
Benchmarks:	GoodStyle 100%, FormattedSearch 99%, JiraRestPlugin 99%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/JiraRestPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/JiraRestPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/JiraRestPluginAppraisal

Related: JiraRestQuery, VarJIRAREST, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory