This tutorial applies to JIRA 4.3 and higher.
Level of experience:
This is an intermediate tutorial. You should have completed at least one beginner tutorial before working through this tutorial. See the list of tutorials in DAC.
It should take you approximately 1 hour to complete this tutorial.
On this page:
Overview of the tutorial
JIRA presents a SOAP interface that client applications can use to invoke JIRA operations remotely. A client application can use the SOAP interface to perform operations such as creating, modifying, and reading JIRA issues.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source using the get source option here: https://bitbucket.org/atlassian_tutorial/jira-java-soap-client.
Environment used in the tutorial
To keep things simple, the client you build in this tutorial invokes operations in a local, developer instance of JIRA. You will install it using the Atlassian SDK. The following instructions use SDK version 4.1, which installs JIRA version 5.1.6 by default. To see Javadoc for this version, see our reference documentation page. If creating an application intended for another version, refer to the JIRA Javadoc for your version. The SOAP API is exposed in JIRA by the RPC JIRA plugin.
The tutorial code relies on Maven 2. If you have the Atlassian SDK, you already have Maven 2. Before starting, make sure you have Maven 2 and, if necessary, install it.
These instructions use Linux OS for its command examples. The exact commands you need to enter may differ depending on your operating system.
Step 1. Install and configure the local JIRA instance
Start by installing and setting up a local JIRA instance using the Atlassian SDK:
- Open a terminal window and run the following command:
atlas-run-standalone --product jira
The command downloads and starts a developer's instance of JIRA. This takes a few moments to finish.
- When JIRA finishes starting up, open a browser and log in to JIRA using the default administrator account. The default username and password are admin/admin.
- Create a new project named TST.
This is the name of the project in which our client application will create issues. Note that, to keep the client code simple, both the name of the project and credentials for the SOAP client user are hard-coded into the client code.
- Create a user for the application with the username and password of soaptester.
- Open the Administration Console and make sure that the RPC JIRA plugin is present and enabled.
Client application invoke SOAP methods through the RPC JIRA plugin. Since JIRA 4.3, the RPC plugin is included and enabled by default in JIRA. You can verify the RPC JIRA Plugin on your instance in the 'Manage Add-ons' page. On the page, expand the System Plugin list and search for 'RPC JIRA plugin'.
- Before deploying to a production system, you would also need to ensure that JIRA is configured to accept remote API calls has been enabled. This option appears in the Options list on the System > General Configuration page. It is enabled by default in the JIRA developer instance installed by the SDK.
JIRA is now ready to go.
Step 2. Create the SOAP client project
From the command line:
- Create the project directory that will contain your SOAP client source code and resource files using the following command:
Change to the
soap_client_jiradirectory and create a new file named
pom.xml, and add to it the following code:
This will be the parent POM for the Java SOAP client module,
jira-soapclient. This makes it easier to expand the project later.
- Now, in the same directory, create a new directory for the SOAP client module as follows:
In the new directory, create a new file named
pom.xmland add the following text to the file:
- Replace myhost in the
jira.soapclient.jiraurlelement with the host name of your JIRA instance.
- Create directories under the
jira-soapclientdirectory to form the following source file path:
In the new
src, create the file
SOAPSessions.javaand add the following code:
SOAPSession.javahandles the connection to the JIRA SOAP service.
In the same directory, create the file
SOAPClient.javaand add the following code:
Note that the class defines a few constants it will use for the new JIRA issues. The class does just a few things:
Connects to the JIRA instance.
- Establishes an authenticated session.
- Creates an issue.
- Replace hostname in the
baseUrlvalue assignment with the host name of your JIRA instance. For example:
String baseUrl = "http://jira-host:2990/jira/rpc/soap/jirasoapservice-v2";
- Verify that your JIRA instance is serving the WSDL properly by opening the following URL in a browser:
Replace 'hostname' with the hostname appropriate for your JIRA instance. To run our client application, we will need access to this WSDL.
- Create a new directory named
wsdlat the following location under your project home:
That's it! You can now test out the client application.
Step 3. Run the application
Give your application a try:
jira-soapclientdirectory under your project home, run the following command:
mvn -Pfetch-wsdl -Djira.soapclient.jiraurl=
Replace hostname in
jiraurlwith the one appropriate for your JIRA instance.
- Build the client application:
- Now run the client application:
mvn exec:java -Dexec.mainClass="com.atlassian.jira_soapclient.SOAPClient"
If successful, you should see a message similar to the following in the screen output.
After the success message, the print out includes details for the new issues. If you navigate to the project in JIRA, you'll see the newly created issue. Each time you execute the command, the client application creates a new issue.