Creating a XML-RPC Client

JIRA 3.0 and above ships with the JIRA XML-RPC Plugin which enables remote access through XML-RPC and SOAP. Utilising this feature with XML-RPC couldn't be much easier with some help from the Apache XML-RPC package. In this tutorial, we write a basic XML-RPC client (using Apache XML-RPC) that logs in, retrieves projects and then log out again. A Python client is also demonstrated.

You may also be interested in the Creating a SOAP Client (more methods are exposed via SOAP than XML-RPC).

Getting the latest XML-RPC client

You can download the latest XML-RPC client with the JIRA Plugin Development Kit

Enabling the RPC plugin

The methods exposed via XML-RPC are listed in the RPC plugin Javadoc for the XmlRpcService class. The JIRA XML-RPC API Spec has more information (though not guaranteed to be up-to-date).

To run the Java client in this tutorial, you'll need to download the Apache XML-RPC libraries and make it available in your classpath.

You should also ensure that the XML-RPC plugin has 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 the General Configuration tab under Global Settings.

Then you need to enable the JIRA RPC Plugin as below.

If the plugin does not appear as above then your XML-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

Now that your server is ready to accept remote procedure calls, we begin creating a Java XML-RPC client.

Python XML-RPC client

XML-RPC in Python is very easy. Here is a sample client that creates test issues on http://jira.atlassian.com:

#!/usr/bin/python

# Sample Python client accessing JIRA via XML-RPC. Methods requiring
# more than basic user-level access are commented out.
#
# Refer to the XML-RPC Javadoc to see what calls are available:
# http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/xmlrpc/XmlRpcService.html

import xmlrpclib

s = xmlrpclib.ServerProxy('http://jira.atlassian.com/rpc/xmlrpc')
#s = xmlrpclib.ServerProxy('http://192.168.0.87:8080/rpc/xmlrpc')
auth = s.jira1.login('xmlrpctester', 'xmlrpctester')

newissue = s.jira1.createIssue(auth, { 'project': 'TST', 'type': 2,
        'summary': 'Issue created via XML-RPC', 'description': 'Created with a Python client'})

print "Created %s/browse/%s" % (s.jira1.getServerInfo(auth)['baseUrl'], newissue['key'])

print "Commenting on issue.."
s.jira1.addComment(auth, newissue['key'], 'Comment added with XML-RPC')

print "Modifying issue..."
s.jira1.updateIssue(auth, newissue['key'], {
                "summary": ["[Updated] issue created via XML-RPC"],

                # Setting a custom field. The id (10010) is discoverable from
                # the database or URLs in the admin section

                "customfield_10010": ["Random text set in updateIssue method"],

                # Demonstrate setting a cascading selectlist:
                "customfield_10061": ["10098"],
                "customfield_10061_1": ["10105"],
                "components": ["10370"]

                })


print "Done!"

Java client

The goal of this tutorial is to create a client that makes three simple remote calls to JIRA. Here we login, retrieve the project information and then logout again. You can take a look at the full source code here (xmlrpc-2.x) or here (xmlrpc-3.x).

The first step is to configure your details.

public static final String JIRA_URI  = "http://jira.atlassian.com";
public static final String RPC_PATH  = "/rpc/xmlrpc";
public static final String USER_NAME = "enteryourlogin@atlassian.com";
public static final String PASSWORD  = "yourpassword";

All XML-RPC calls are invoked at with the path /rpc/xmlrpc by default. You need to configure your username and password appropriately.

// Initialise RPC Client
XmlRpcClient rpcClient = new XmlRpcClient(JIRA_URI + RPC_PATH);

// Login and retrieve logon token
Vector loginParams = new Vector(2);
loginParams.add(USER_NAME);
loginParams.add(PASSWORD);
String loginToken = (String) rpcClient.execute("jira1.login", loginParams);

Method calls to JIRA via XML-RPC need to be prefixed with "jira1.". Parameters to methods are passed as sequenced Objects in a Vector. In the above code, we log into jira.atlassian.com. We receive back a loginToken which will need to be passed to all subsequent method calls.

// Retrieve projects
Vector loginTokenVector = new Vector(1);
loginTokenVector.add(loginToken);
List projects = (List)rpcClient.execute("jira1.getProjects", loginTokenVector);

// Print projects
for (Iterator iterator = projects.iterator(); iterator.hasNext();)
{
    Map project =  (Map) iterator.next();
    System.out.println(project.get("name") + " with lead " + project.get("lead"));
}

The RPC client calls the getProjects method passing the loginToken. This returns with a Vector of projects which are represented by HashTable objects. For information on what methods are available as well as what properties are available on returned projects, you'll again need to look at the JIRA XML-RPC API Spec.

// Log out
Boolean bool = (Boolean) rpcClient.execute("jira1.logout", loginTokenVector);
System.out.println("Logout successful: " + bool);

Lastly, we log out of the system, again passing the loginToken in a Vector form.

There it is! A simple client for JIRA XML-RPC. If you wish to extend or customize the JIRA XML-RPC plugin itself, you can download the latest source from the repository.

Perl Client

Here's an XMLRPC client that uses the XMLRPC::Lite module (distributed with ActivePerl and available for free on CPAN).

#!/usr/bin/perl

# toy jira perl client using XMLRPC
# logs in, creates an issue
# handles failure or prints issue fields
# logs out.

use strict;
use warnings;

use XMLRPC::Lite;
use Data::Dumper;

my $jira = XMLRPC::Lite->proxy('http://localhost:8080/jira/rpc/xmlrpc');
my $auth = $jira->call("jira1.login", "admin", "admin")->result();
my $call = $jira->call("jira1.createIssue", $auth, {
    'project' => 'CEL',
    'type' => 2,
    'summary' => 'Issue created via XMLRPC',
    'assignee' => 'admin',
    'description' => 'Created with a Perl client'});
my $fault = $call->fault();
if (defined $fault) {
    die $call->faultstring();
} else {
    print "issue created:\n";
    print Dumper($call->result());
}
$jira->call("jira1.logout", $auth);

XMLRPC::Lite is poorly documented, using it for this simple example required reading the code - it is not advised for newbie perl hackers.

Creating a XML-RPC Client

Enabling the RPC plugin

Python XML-RPC client

Java client

Perl Client

See also

Labels:

Children (1)

Comments (16)

Adam Downer says:

David Blevins says:

David Blevins says:

Test User says:

Yuen-Chi Lian says:

Pablo Costa says:

Java Client

Yuen-Chi Lian says:

Baerrach bonDierne says:

jian zhang says:

Mark Derricutt says:

Wiesław says:

Igor V Demin says:

Valentyn Gatsuk says:

amit mitra says:

Valentyn Gatsuk says:

Steven Rowland says: