JIRA XML-RPC Overview

All Versions

JIRA 4.0 Beta Documentation

Index

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.

JIRA supports both SOAP and XML-RPC. We recommend the SOAP interface as it is more complete.

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.

You may also wish to see the Creating a XML-RPC Client or Creating a 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:
!

If the plugin does not appear as above then your RPC jar has not been properly installed. Download the jar from the repository and copy it to the atlassian-jira/WEB-INF/lib folder of your JIRA installation. Perform a restart and your plugin should appear.

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". To 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

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
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (14)

 

  1. Feb 09, 2004

    Mark Derricutt says:

    User Methods int validateLogin( String userName, String password ) - validate...

    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. Nov 19, 2004

      Elliot Metsger says:

      Right now to validate users we login with an rpcadmin account, then call getUser...

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

  2. May 17, 2004

    Aslak Helles?y says:

    Are you planning to support more project config methods in SOAP/XML-RPC anytime ...

    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. Nov 19, 2004

    Elliot Metsger says:

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

    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. Jan 11, 2005

    Lauri Siljamäki says:

    How about clean searching from Jira without first creating a separate filter for...

    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. Sep 20, 2006

    Anatoliy G. Klimenko says:

    I am going to create some perl scripts for managing users and groups in Jira and...

    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. Sep 21, 2006

    Mei Yan Chan says:

    Hi Anatoliy, The XML-RPC does not actually support any methods on creating user...

    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. Sep 21, 2006

      Anatoliy G. Klimenko says:

      Hi Mei, You are right, I was trying to use unimplemented methods that are not d...

      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. Jun 25, 2007

    steffenj says:

    Is it possible to create sub-tasks And if so, how I used getIssue to get a task...

    Is it possible to create sub-tasks And if so, how

    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. Jan 16, 2008

    Mike Miller says:

    I cant find a way to make updateIssue work. Using the following java code based...

    I cant find a way to make updateIssue work.

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

    XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://myjiraserver.com/rpc/xmlrpc"));
XmlRpcClient  client = new XmlRpcClient();
client.setConfig(config);

ArrayList loginParams = new ArrayList(2);
loginParams.add("user");
loginParams.add("pass");
String token = (String) client.execute("jira1.login", loginParams);

Map issue = new HashMap();
issue.put("description", "blah");
        
ArrayList paramList = new ArrayList(2);
paramList.add(token);
paramList.add(KEY);
paramList.add(issue);
client.execute("jira1.updateIssue", paramList);

    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. Jan 17, 2008

      Mike Miller says:

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

      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

  9. Apr 04, 2008

    Frank Stiller says:

    I did not had any problems so far with the API, except that it is very incomplet...

    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. Jan 14

    Anonymous says:

    Is there any way in XMLRPC (but SOAP does not seem better in this area) to get l...

    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. Apr 22

    Anonymous says:

    Hi, Is there any way to get all issues (open/closed/fixed, any) for given proje...

    Hi,

    Is there any way to get all issues (open/closed/fixed, any) for given project ? I want to generate statistics for different types of bugs from different projects ? I can use filter but if I add new project, I have to go to JIRA and update filter. any pointers ?

    Thanks in advance !

Add Comment


Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.