Documentation for JIRA 4.2. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

JIRA ships with the RPC plugin which enables remote access through XML-RPC and SOAP. This document contains notes on how to perform various operations (e.g. creating issues) via a Java SOAP client.

Remotely exposed operations.

Before you begin, check out the javadoc for the RPC plugin, specifically JiraSoapService, which has information on all the methods available through SOAP and and XML-RPC. Also check the list of RPC bugs, listed on the RPC plugin page, to see that none will affect you.

Icon

Please note that the SOAP service respects the permissions and screen configurations that are set up in JIRA. For example, if you have configured JIRA so that the screen for a given issue type does not include a 'Summary' field, then you will not be permitted to set a value for the 'Summary' field through the SOAP request.

Icon

Some of our users have recommended SOAPUI (http://www.soapui.org/).
It allows you to import the WSDL from JIRA and it then displays all remote calls and all sorts of details and testing possibilities. Check it out!
Thanks goes to Karl-Koenig Koenigsson for this info.

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) 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.

WSDL descriptor

Icon

SOAP is not compatible with Axis2 and Xfire. Please see JRA-12152. There is also a patch for Axis. Please download it from JRA-20351.

Regardless of the language or SOAP API used, you will need the WSDL descriptor for your JIRA installation. This is found at http://your_installation/rpc/soap/jirasoapservice-v2?wsdl. For instance, http://jira.atlassian.com's (http://jira.atlassian.com's) WSDL file is:

http://jira.atlassian.com/rpc/soap/jirasoapservice-v2?wsdl

Sample Java SOAP client

Check out the latest demo SOAP client distribution from the Atlassian public repository. This contains a Maven 2 project configured to use Apache Axis, and a sample Java SOAP client which creates test issues in http://jira.atlassian.com.
Read the README.txt in the root directory for further instructions.

To give you an idea of what a Java SOAP client looks like, here is the sample client's code for creating issues:

The various external classes (JiraSoapService etc) are the classes generated automatically from WSDL by the Maven Axis plugin.

Python (SOAPPy) client

The following code demonstrates how to create an issue and comment (on http://jira.atlassian.com) using python:

Icon

Python's SOAP support is considerably less well developed than Java's, and some SOAP calls may fail (e.g. addUserToGroup()). Also as SOAPpy is rather dated now, see the comments below for details of using python-suds instead.

Ruby client

Ben Walding (Codehaus) reports:

I've worked with the developers of SOAP4R and they've made the Ruby SOAP libraries work with JIRA. It was the client libraries at fault - they were ignoring the WSDL and sending integers instead of longs.

A gem for marginally simpler access to JIRA can be found at http://jira4r.rubyhaus.org/ (there is also a confluence gem at http://confluence4r.rubyhaus.org/

The gems take care of authentication and provide helper methods where the Jira / Confluence interfaces are missing useful methods or behave strangely (eg. provides a getProject; provides a getGroup that doesn't throw exceptions).

There is a JIRA4R sample Ruby script available in the samples (thanks Jonathan Zhang). If you have any Ruby samples to share, please let us know so we can include them into the repository as well.

See also

Creating a XML-RPC Client