Tags:
create new tag
, view all tags

JIRA REST Plugin

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: Tip: This plugin is generic enough, it can used to establish REST connections to data sources other than JIRA.

Alternatives to this plugin:

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.

diagram.png

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.

ALERT! 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

jira-rest-query.png
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 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

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.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip JiraRestPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/JiraRestPlugin.txt Plugin documentation
      data/TWiki/JiraRestQuery.txt REST API query
      data/TWiki/VarJIRAREST.txt JIRAREST documentation
      lib/TWiki/Plugins/JiraRestPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/JiraRestPlugin/Core.pm Core Perl module
      lib/TWiki/Plugins/JiraRestPlugin/Config.spec Configuration file
      pub/TWiki/JiraRestPlugin/diagram.txt Diagram image
    • Set the ownership of the extracted directories and files to the webserver user.

  • Install dependencies:
    • Install the REST:Client module and its dependencies

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Set the following settings in the Extensions section:
      {Plugins}{JiraRestPlugin}{RestDomain} - JIRA domain name
      {Plugins}{JiraRestPlugin}{RestBase} - REST base URL path
      {Plugins}{JiraRestPlugin}{User} - JIRA user login name
      {Plugins}{JiraRestPlugin}{Password} - JIRA user password
    • Note: If the REST domain uses TLS (https protocol) and does not have a valid certificate, you can disable checking the validity by adding this to twiki/lib/LocalSite.cfg:
      $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;
    • Test if the installation was successful:
      • Run a query in JiraRestQuery, such as: "get" command="/auth/1/session"

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
2015-09-16: TWikibug:Item7663: Doc fix in JiraRestQuery, document use of $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME}
2015-07-24: TWikibug:Item7663: Add support for JSON back reference to returned content, such as $(content.key)
2015-07-06: TWikibug:Item7663: Add example to create an Epic in JIRA Agile
2015-06-15: TWikibug:Item7663: Doc improvements
2015-06-12: TWikibug:Item7663: Ability to do multiple REST API calls in one session using action, action2, action3, etc.
2015-06-10: TWikibug:Item7663: Add JSON filter to interactive REST API query form; improved images
2015-06-08: TWikibug:Item7663: Return consistent JSON output; better error handling; add JIRA REST examples
2015-06-05: TWikibug:Item7663: Initial version
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

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 JiraRestPlugin.md5 r15 r14 r13 r12 r11 manage 0.2 K 2015-09-16 - 21:02 PeterThoeny  
Compressed Zip archivetgz JiraRestPlugin.tgz r15 r14 r13 r12 r11 manage 75.4 K 2015-09-16 - 21:02 PeterThoeny  
Compressed Zip archivezip JiraRestPlugin.zip r15 r14 r13 r12 r11 manage 86.4 K 2015-09-16 - 21:02 PeterThoeny  
Unknown file formatEXT JiraRestPlugin_installer r2 r1 manage 3.7 K 2015-09-16 - 21:02 PeterThoeny  
Edit | Attach | Watch | Print version | History: r7 < r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r7 - 2015-09-16 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.