Creating a SOAP Client

JIRA 3.0 and above 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 (JIRA 3.1 or above required).

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.

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.

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

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

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 WSDL file is:

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

In JIRA 3.0.x, the URL is http://your_installation/rpc/soap/jiraservice-v1.wsdl. The sample SOAP client below has this pre-packaged, so you don't need to do anything further if using it.

Sample Java SOAP client

Check out the latest demo SOAP client distribution. 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:

    private static RemoteIssue testCreateIssue(JiraSoapService jiraSoapService, String token)
            throws java.rmi.RemoteException
    {
        Timing timing = Timing.startTiming("CreateIssue");
        try
        {
            // Create the issue
            RemoteIssue issue = new RemoteIssue();
            issue.setProject(PROJECT_KEY);
            issue.setType(ISSUE_TYPE_ID);

            issue.setSummary(SUMMARY_NAME);
            issue.setPriority(PRIORITY_ID);
            issue.setDuedate(Calendar.getInstance());
            issue.setAssignee("");

            // Add remote compoments
            RemoteComponent component = new RemoteComponent();
            component.setId(COMPONENT_ID);
            issue.setComponents(new RemoteComponent[] { component });

            // Add remote versions
            RemoteVersion version = new RemoteVersion();
            version.setId(VERSION_ID);
            RemoteVersion[] remoteVersions = new RemoteVersion[] { version };
            issue.setFixVersions(remoteVersions);

            // Add custom fields
            RemoteCustomFieldValue customFieldValue = new RemoteCustomFieldValue(CUSTOM_FIELD_KEY_1, "", new String[] { CUSTOM_FIELD_VALUE_1 });
            RemoteCustomFieldValue customFieldValue2 = new RemoteCustomFieldValue(CUSTOM_FIELD_KEY_2, "", new String[] { CUSTOM_FIELD_VALUE_2 });
            RemoteCustomFieldValue[] customFieldValues = new RemoteCustomFieldValue[] { customFieldValue, customFieldValue2 };
            issue.setCustomFieldValues(customFieldValues);

            // Run the create issue code
            RemoteIssue returnedIssue = jiraSoapService.createIssue(token, issue);
            final String issueKey = returnedIssue.getKey();

            System.out.println("\tSuccessfully created issue " + issueKey);
            printIssueDetails(returnedIssue);
            return returnedIssue;
        }
        finally
        {
            timing.printTiming();
        }

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

Python (SOAPPy) client

Due to a JIRA/Axis bug, Python clients will not work with JIRA versions earlier than 3.3.1. In 3.3.1 and above, the following code demonstrates how to create an issue and comment (on http://jira.atlassian.com):

#!/usr/bin/python

# Sample Python client accessing JIRA via SOAP. By default, accesses
# http://jira.atlassian.com with a public account. Methods requiring
# more than basic user-level access are commented out. Change the URL
# and project/issue details for local testing.
#
# Note: This Python client only works with JIRA 3.3.1 and above (see
# http://jira.atlassian.com/browse/JRA-7321)
#
# Refer to the SOAP Javadoc to see what calls are available:
# http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html

import SOAPpy, getpass, datetime

soap = SOAPpy.WSDL.Proxy('http://jira.atlassian.com/rpc/soap/jirasoapservice-v2?wsdl')
#soap = SOAPpy.WSDL.Proxy('http://localhost:8090/jira/rpc/soap/jirasoapservice-v2?wsdl')

#jirauser = raw_input("Username for jira [fred]: ")
#if jirauser == "":
#    jirauser = "fred"
#
#passwd = getpass.getpass("Password for %s: " % jirauser)
#passwd="fredspassword"

jirauser='soaptester'
passwd='soaptester'

# This prints available methods, but the WSDL doesn't include argument
# names so its fairly useless. Refer to the Javadoc URL above instead
#print 'Available methods: ', soap.methods.keys()

def listSOAPmethods():
	for key in soap.methods.keys():
	    print key, ': '
	    for param in soap.methods[key].inparams:
		print '\t', param.name.ljust(10), param.type
	    for param in soap.methods[key].outparams:
		print '\tOut: ', param.name.ljust(10), param.type


auth = soap.login(jirauser, passwd)

issue = soap.getIssue(auth, 'TST-3410')
print "Retrieved issue:", issue
print

# Note: if anyone can get timestamps to work, please let us know how!

baseurl = soap.getServerInfo(auth)['baseUrl']
newissue = soap.createIssue(auth, {'project': 'TST', 'type': '1', 'summary': 'Issue created with Python!'})
print "Created %s/browse/%s" % (baseurl, newissue['key'])

print "Adding comment.."
soap.addComment(auth, newissue['key'], {'body': 'Comment added with SOAP'})

print 'Updating issue..'
soap.updateIssue(auth, newissue['key'], [
		{"id": "summary", "values": ['[Updated] Issue created with Python'] },

		# Change issue type to 'New feature'
		{"id":"issuetype", "values":'2'},

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

		{"id": "customfield_10010", "values": ["Random text set in updateIssue method"] },

		{"id":"fixVersions", "values":['10331']},
		# Demonstrate setting a cascading selectlist:
		{"id": "customfield_10061", "values": ["10098"]},
		{"id": "customfield_10061_1", "values": ["10105"]},
		{"id": "duedate", "values": datetime.date.today().strftime("%d-%b-%y")}

		])

print 'Resolving issue..'
# Note: all fields prompted for in the transition (eg. assignee) need to
# be set, or they will become blank.
soap.progressWorkflowAction(auth, newissue['key'], '2', [
		{"id": "assignee", "values": "jefft" },
		{"id":"fixVersions", "values":['10331']},
		{"id": "resolution", "values": "2" }
		])


# Re. 'assignee' above, see http://jira.atlassian.com/browse/JRA-9018

# This works if you have the right permissions
#user = soap.createUser(auth, "testuser2", "testuser2", "SOAP-created user", "newuser@localhost")
#print "Created user ", user

#group = soap.getGroup(auth, "jira-developers")
# Adding a user to a group. Naming the parameters may be required (see
# http://jira.atlassian.com/browse/JRA-7971). You may experience other
# problems (see http://jira.atlassian.com/browse/JRA-7920).
#soap.addUserToGroup(token=auth, group=group, user=user)

# Adding a version to a project. If you figure out the syntax for the date please submit it back to Atlassian
#soap.addVersion(auth, "TST", {'name': 'Version 1'})


print "Done!"

# vim set textwidth=1000:

Python's SOAP support is considerably less well developed than Java's, and some SOAP calls may fail (e.g. addUserToGroup()).

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.

All Versions

JIRA 4.0 Documentation

Creating a SOAP Client

Remotely exposed operations.

Enable the RPC plugin

WSDL descriptor

Sample Java SOAP client

Python (SOAPPy) client

Ruby client

See also

Labels

Children (1)

Comments (166)

Bill Schneider says:

sleiman rabah says:

Mike Doustan says:

Anton Mazkovoi says:

npeeters says:

Jeff Turner says:

Dan Black says:

Anton Mazkovoi says:

Anonymous says:

Jason Kohls says:

Amrit Lalli says:

Amrit Lalli says:

Mark Chaimungkalanont says:

Landon Bradshaw says:

Mike Cannon-Brookes says:

Marcelo Riss says:

Mark Chaimungkalanont says:

Amrit Lalli says:

Nick Menere says:

Amrit Lalli says:

Jeff Turner says:

Amrit Lalli says:

Amrit Lalli says:

Dylan Etkin says:

Amrit Lalli says:

Dylan Etkin says:

David Smiley says:

Jeff Turner says:

David Smiley says:

Nick Menere says:

Richard Wallace says:

Richard Wallace says:

Nick Menere says:

Richard Wallace says:

Nick Menere says:

Richard Wallace says:

Nick Menere says:

Nathaniel Pryce says:

Dylan Etkin says:

Nathaniel Pryce says:

Dylan Etkin says:

Sikhar J Saikia says:

Yuen-Chi Lian says:

taylor steil says:

Gustavo Chaves says:

Nathaniel Pryce says:

Dylan Etkin says:

Yuen-Chi Lian says:

David Coultous says:

Ugo Cei says:

Yuen-Chi Lian says:

Clemens Reimann says:

Yuen-Chi Lian says:

Ugo Cei says:

Yuen-Chi Lian says:

Yuen-Chi Lian says:

Ugo Cei says:

Yuen-Chi Lian says:

Anonymous says:

Stefan Schmidt says:

Stefan Schmidt says:

Anonymous says:

Benjill Cubas says:

Yuen-Chi Lian says:

Kartik says:

Yuen-Chi Lian says:

Chris says: