Skip to end of metadata
Go to start of metadata

JIRA Remote API

Status

REST

Recommended and supported. REST is the recommended and supported remote API in JIRA 5.0 and later. This is where Atlassian will focus its attention from this point onwards, adding functionality and fixing bugs.

XML-RPC

Deprecated in JIRA 6.0.  This means that we will not add new features nor fix bugs related to the XML-RPC API during the JIRA 6.x lifecycle. Read the deprecation announcement for more information.

JSON-RPC

Deprecated in JIRA 6.0.  This means that we will not add new features nor fix bugs related to the JSON-RPC API during the JIRA 6.x lifecycle. Read the deprecation announcement for more information.

Atlassian added JSON-RPC capabilities to JIRA to help you move from the SOAP API to a mechanism that uses more JSON and JavaScript, on the way towards the REST APIs. We recommend that you move to REST as soon as possible. For information on the deprecated SOAP APIs, see Creating a JIRA SOAP Client.

On this page:

Introduction

This page provides basic documentation on JIRA's XML-RPC capabilities. For latest methods available through the XML-RPC please refer to the latest Javadoc for XmlRpcService.

Notes:

  • The URL for XML-RPC requests is http://jira-install/rpc/xmlrpc.
  • All methods must be prefixed by jira1 - to indicate this is version 1 of the API. We might introduce another version in the future.
  • All keys in structs are case sensitive.
  • All strings are passed as UTF-8, and not ASCII per the XML-RPC
  • When reading the APInywhere you see the word Vector, you can interchange it with "Array" or "List" depending on what language you prefer. This is the array data type as defined in the XML-RPC spec.
  • Anywhere you see the word Hashtable, you can interchange it with "Struct" or "Dictionary" or "Map" depending on what language you prefer. This is the struct data type as defined in the XML-RPC spec.
  • The default XML-RPC session lifetime is 60 minutes, it will be editable in the future.

(warning) You may also wish to see the Creating an XML-RPC Client or Creating a JIRA SOAP Client if you're interested in creating a JIRA remote client.

Enable the RPC plugin

To invoke JIRA operations remotely, you should ensure that the RPC plugin is enabled on the JIRA installation you are targeting. If you simply want to create a client to http://jira.atlassian.com/ then you can skip this step. First you need to check if the Accept Remote API Calls has been enabled in 'General Configuration' under 'Global Settings' in the left-hand menu:

Then you need to enable the JIRA RPC Plugin in 'Plugins' under 'System' in the left-hand menu:

(warning) To get the source code of the RPC plugin, see https://bitbucket.org/atlassian_tutorial/jira-rpc-plugin

Your server should now be ready to accept remote procedure calls.

Remote Methods

The most recent and up-to-date source of information of available exposed methods is the Javadoc for the RPC plugin, specifically those on the XmlRpcService.

The Javadoc will often refer to "hashtables with fields from RemoteObject". The hashtable will contain keys that map to the fields available through reflection of the particular RemoteObject. For example, the object RemoteVersion, has the methods getReleaseDate(), getSequence(), isArchived() and isReleased(). This will be converted into a Hashtable with keys releaseDate, sequence, archived and released.

Data Objects

Most returned structs have a summary and a detailed form:

  • The summary form is a primary key (ie project key) and a representative form (ie name)
  • The detailed form will have all of the entity details as might be needed for the client.

Unless otherwise specified, all returned structs are in detailed form.

Project

Key

Type

Value

id

String

the id of the project

key

String

the project key

name

String

the name of the project

url

String

the url to view this project online

projectUrl

String

the url of this project in your organisation (ie not a JIRA URL)

lead

String

the username of the project lead

description

String

a description of this project

Component

Key

Type

Value

id

String

the id of the component

name

String

the name of the component

Version

Key

Type

Value

id

String

the id of the version

name

String

the name of the version

released

boolean

whether or not this version is released

archived

boolean

whether or not this version is archived

IssueType / Status / Resolution

Key

Type

Value

id

String

the id of this constant

name

String

the name of the constant

description

String

the description of this constant

icon

String

the URL to retrieve the icon of this constant

Priority

Key

Type

Value

id

String

the id of this constant

name

String

the name of the constant

description

String

the description of this constant

icon

String

the URL to retrieve the icon of this constant

colour

String

the colour of this constant

Filter

Key

Type

Value

id

String

the id of this filter

name

String

the name of the filter

description

String

the description of this filter

author

String

the username of this filter's owner

project

String

the id of the project this search relates to (null if the search is across projects)

xml

String

a complete XML representation of this search request - I don't recommend you use this for now, it's complex (smile)

User

Key

Type

Value

name

String

the username of this user

fullname

String

the full name of this user

email

String

the email address of this user

  • No labels

16 Comments

  1. User Methods

    • int validateLogin( String userName, String password ) - validates a user/password but doesn't log them in. Return codes for user unknown, bad password, account disabled.

    Filter

    Does the xml field contain the contents of the filter results ( the RSS ), a URL to the RSS ( sans os_username/os_password ), or an XML representation of the filter definition? I could see a use for all three. An XML representation of the filter definition could be a FilterDefinition type, maybe a simple hashtable of vectors ( projects, resolutions, types, status ). This could then be reused in the above createFilter() method.

    Searching

    • Filter createFilter( String token, FilterDefinition filterDefinition ) - Creates a few filter with the specified definition.
    • Filter updateFilter( String token, String filterId, FillterDefinition filterDefinition ) - update an existing filter with new settings ( effectively deleteFilter, createFilter ).

    Issue Retrievel

    I think RSS should be used as much as possible here, either by returning an RSS URL that matches whatever search query, or ( not sure how viable this is ) embedded the RSS in an XML-RPC/SOAP response. Or both.

    • String getIssueFeedForFilter( String token, String filterId ) - return a URL for the matching filters RSS feed.
    • Vector getIssuesForFilter( String token, String filterId ) - return a Vector of Issue objects for the matching filter.
    • Issue getIssue( String token, String issueId ) - return a single issue.
    • Issue getIssueCommentFeed( String token, String issueId ) - return a URL for the issues comments in RSS.
    • Issue getIssueComments( String token, String issueId ) - return a Vector of Comment objects for the issue.

    I'll let the mind wander a bit more whilst I eat.

    1. Right now to validate users we login with an rpcadmin account, then call getUser(token, username).

  2. Are you planning to support more project config methods in SOAP/XML-RPC anytime soon? I'd like to close this one -> http://jira.codehaus.org/browse/HAUS-459

    I would need:

    void createPermissionScheme(String name, String description, Permission[] permissions)
    void createNotificationScheme(String name, String description, Notification[] permissions)
    void createProject(String key, String name, String url, String leadDeveloper, String defaultAssignee, String description, String notificationScheme, String permissionScheme, String issueSecurityScheme)
    void addToGroup(String user, String group)

  3. Commenting on Mark Derricutt's comment above regarding user validation:

    • int validateLogin( String userName, String password )

    The method should take the login token like so:

    • int validateLogin( String token, String userName, String password )

    You probaly do not want people to anonymously ping your RPC interface to see what usernames are valid and what are not. That would be a security issue.

  4. How about clean searching from Jira without first creating a separate filter for the search?

    1. String getIssueFeedForFilter( String token, String searchTerm) - return a URL for the matching filters RSS feed.
    2. Vector getIssuesForFilter( String token, String searchTerm) - return a Vector of Issue objects for the matching filter.

    and

    1. String getIssueFeedForFilter( String token, FilterDefinition filterDefinition) - return a URL for the matching filters RSS feed.
    2. Vector getIssuesForFilter( String token, FilterDefinition filterDefinition ) - return a Vector of Issue objects for the matching filter.

    This would make it a lot easier to search Jira remotely and perhaps connect to Confluence search too.

  5. I am going to create some perl scripts for managing users and groups in Jira and Perforce. I have no problems with Perforce when using P4Perl (P4.pm), but struggling to get same results for Jira using XMLRPC. I can successfully execute some calls, like in this script below (I am doing all this from Perl debugger in interactive mode and x command works a Data::Dumper to see what I am actually getting):

    use strict;
    use XMLRPC-Lite;
    use warnings;
    use Data::Dumper;

    my $jira = XMLRPC::Lite->proxy('http://carbon/jira/rpc/xmlrpc') or die $!;
    my $auth =$jira->call("jira1.login","admin","passwd")->result();

    #successful cals that work for me:
    my $projects   = $jira->call("jira1.getProjects",$auth)->result();
    my $issueTypes = $jira->call("jira1.getIssueTypes",$auth)->result();
    my $priorities = $jira->call("jira1.getPriorities",$auth)->result();
    my $issue      = $jira->call("jira1.getIssue",$auth,"AS-102515")->result();
    my $user       = $jira->call("jira1.getUser",$auth,"aklimenko")->result();
    #For example, this is what I am getting for user

    #user hash result
        'email' => 'aklimenko@blackboard.com'    'fullname' => 'Anatoliy Klimenko'    'name' => 'aklimenko'

    #some other successful calls       
    my $serverInfo = $jira->call("jira1.getServerInfo",$auth)->result();
    my $issuesSearchResult = $jira->call("jira1.getIssuesFromTextSearch",$auth,"calendar")->result();
     Can somebody help me to figure out correct syntax to get  list of all users, create user and group, add user to group?

    I have problem with this. For example, when I am trying to utilize this method createUser(User admin, String username, String password, String fullName, String email) from class UserServiceImpl, I am getting NoSuchMethodException (probably because not passing correct list of arguments).

    Any thoughts? 

  6. Hi Anatoliy,

    The XML-RPC does not actually support any methods on creating user/group, listing of all users, and adding user to group. The UserServiceImpl which you mentioned is only used by the JIRA SOAP Service. I would recommend you to switch to using SOAP as it is more complete and updated. As you are using Perl, Perl's SOAP::Lite can be a good choice for you.

    Regards,
    Mei

    1. Hi Mei,

      You are right, I was trying to use unimplemented methods that are not defined in public class JiraXmlRpcService.

      I will try SOAP::Light.

      Thanks!

      Anatoliy

  7. Is it possible to create sub-tasks(question) And if so, how(question)

    I used getIssue to get a task and its subtask but looking at the resulting hashtables i did not find anything that links the two issues together.
    Is it at least possible to create a new issue, submit it, and later assign it to be a sub-task (either manually or via rpc updateIssue command.

  8. I cant find a way to make updateIssue work.

    Using the following java code based on apache XML-RPC 3.1

    I get the following exception:
    Exception in thread "main" org.apache.xmlrpc.XmlRpcException: java.lang.Exception: java.lang.ClassCastException: java.lang.String

    Based on the javadoc RemoteIssue.setDescription takes a string.

    Is there some structure on what the xml is supposed to look like? Does anyone know how to get the raw xml out of the server to see what it really takes?

    1. I installed a test copy of the latest Jira with the latest plugin. 3.12.1

      The error message is now:
      java.lang.Exception: java.lang.ClassCastException: java.lang.String cannot be cast to java.util.Vector


    2. I had the same problem. The documentation is not very clear as all the methods that expect (field, values) pairs in a Java Map are infact expecting (field, vector) pairs, so you can, in theory, have multiple values associated with a given field. In practice you normally only want to support one value, but you still need to pass a vector of length one i.e. 

  9. I did not had any problems so far with the API, except that it is very incomplete (and asynchron compared to confluence's interface). I wrote me some classes to manage both a JIRA and a Confluence installation, but i am now at the point that i would have to build in basic functionality to work on correctly, e.g. get a Users Group or set a Users Password in JIRA is impossible. And that this page has been last updated in 2005 says almost all about the completeness of the SOAP interface.
    Currently i am evaluating how to go to the JIRA database directly and then update the essential cache of it, that it does not get inconsistent

  10. Anonymous

    Is there any way in XMLRPC (but SOAP does not seem better in this area) to get list of field values in the context of the project ?

    getResolutions for example give you the list of all resolutions, but you do not know which one you can use in a given project.

    How would you use that to pass valid argument ?

  11. Anonymous

    Hi,Am trying to run the xml-rpc with JIRA4.3.1 but when am trying to create issue gettting the below exception.Please help me to resolve,i tried the same with SOAP also getting the same error,

    org.apache.xmlrpc.XmlRpcException

    at org.apache.xmlrpc.client.XmlRpcStreamTransport.readResponse(

    at org.apache.xmlrpc.client.XmlRpcStreamTransport.sendRequest(

    at org.apache.xmlrpc.client.XmlRpcHttpTransport.sendRequest(

    at org.apache.xmlrpc.client.XmlRpcSunHttpTransport.sendRequest(

    at org.apache.xmlrpc.client.XmlRpcClientWorker.execute(

    at org.apache.xmlrpc.client.XmlRpcClient.execute(

    at org.apache.xmlrpc.client.XmlRpcClient.execute(

    at org.apache.xmlrpc.client.XmlRpcClient.execute(

    at com.test.RPCClient.main(: java.lang.Exception: java.lang.ClassCastException: java.lang.Boolean cannot be cast to com.atlassian.crowd.embedded.api.UserXmlRpcStreamTransport.java:197)XmlRpcStreamTransport.java:156)XmlRpcHttpTransport.java:143)XmlRpcSunHttpTransport.java:69)XmlRpcClientWorker.java:56)XmlRpcClient.java:167)XmlRpcClient.java:158)XmlRpcClient.java:147)RPCClient.java:101)

  12. Anonymous

    why issue links doesn't be contained in RemoteIssue bean, which I really need to organize my issues list.