Creating a JIRA SOAP Client

JIRA's SOAP and XML-RPC remote APIs have been deprecated since JIRA 6.0 and will be removed in JIRA 7.0. Read the announcement for more information. 

Applicable:

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.

Time estimate:

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.

This document illustrates the use of the JIRA SOAP API to create a remote JIRA client application. However, if developing for JIRA 5.0 or later, we recommend that you use the REST API instead. See JIRA RPC Services for usage guidelines on the remote access APIs in JIRA.

As an alternative to developing client applications against the SOAP API directly, as described in this tutorial, you can use the SOAP API through a client wrapper library instead, such as the JIRA SOAP library. This alleviates you from needing to compile and code against the WSDL directly.

Plugin source

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:

git clone https://bitbucket.org/atlassian_tutorial/jira-java-soap-client

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:

  1. 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.
  2. 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. 
  3. 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.
  4. Create a user for the application with the username and password of soaptester.
  5. 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'.

  6. 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:

  1. Create the project directory that will contain your SOAP client source code and resource files using the following command:
    mkdir soap_client_jira
  2. Change to the soap_client_jira directory 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.

  3. Now, in the same directory, create a new directory for the SOAP client module as follows:
    mkdir jira-soapclient
  4. In the new directory, create a new file named pom.xml and add the following text to the file:

  5. Replace myhost in the jira.soapclient.jiraurl element with the host name of your JIRA instance.
  6. Create directories under the jira-soapclient directory to form the following source file path:
    src/main/java/com/atlassian/jira_soapclient/
  7. In the new jira_soapclient directory under src, create the file SOAPSessions.java and add the following code:


    SOAPSession.java handles the connection to the JIRA SOAP service. 

  8. In the same directory, create the file SOAPClient.java and 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.
  9. Replace hostname in the baseUrl value assignment with the host name of your JIRA instance. For example:
    String baseUrl = "http://jira-host:2990/jira/rpc/soap/jirasoapservice-v2";
  10. Verify that your JIRA instance is serving the WSDL properly by opening the following URL in a browser:
    http://hostname:2990/jira/rpc/soap/jirasoapservice-v2?wsdl
    Replace 'hostname' with the hostname appropriate for your JIRA instance. To run our client application, we will need access to this WSDL.
  11. Create a new directory named wsdl at the following location under your project home:
    /jira-soapclient/src/main/wsdl

That's it! You can now test out the client application.

Step 3. Run the application

Give your application a try:

  1. In the jira-soapclient directory under your project home, run the following command:
    mvn -Pfetch-wsdl -Djira.soapclient.jiraurl=http://hostname:2990/jira
    Replace hostname in jiraurl with the one appropriate for your JIRA instance.

    To use the Maven executable included in the Atlassian SDK, prepend atlas- to the Maven command. For example:
    atlas-mvn -Pfetch-wsdl -Djira.soapclient.jiraurl=http://hostname:2990/jira
     

  2. Build the client application:
    mvn -Pbuildclient
  3. 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.

Powered by Confluence and Scroll Viewport