1. A service is analysed and then modelled into a BPMN diagram.
2. Functional Analysts use this diagram to create a Test Design for the given service and do general review.
3. Software Engineers take both the service design and the test design to write (super) code.
4. The service can be exposed publicly through web services. This means two extra tasks for the same service: creating of a public contract and integrating it with the application.

One service, or deliverable, can create up to 5 related tasks, each with their own work flow and transitions; totalling a whopping 6 JIRA issues in total. Every subTask is defined by a specific issueType and has individual custom fields associated with it.

You must be wondering, ‘why all this information? I came here to read about the JIRA Remote API and how I can use it!’. Well, with this information in hand, I hope you can imagine why I took the time to investigate in this matter. After all, I’m the one analysing and modelling the services, and thus inserting all these issues into the system…

Creating up to 6 JIRA issues with their own issueTypes, summary, custom fields for any given service takes a whole lot of time.

Therefore introducing,

The JIRA Remote API Calls

The basics – Authentication

<properties>
        <axis.version>1.4</axis.version>
    </properties>
    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>axistools-maven-plugin</artifactId>
                <version>1.3</version>
                <dependencies>
                    <dependency>
                        <groupId>axis</groupId>
                        <artifactId>axis</artifactId>
                        <version>${axis.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <wsdlFiles>
                        <wsdlFile>jirasoapservice-v2.wsdl</wsdlFile>
                    </wsdlFiles>
                    <packageSpace>com.atlassian.jira.rpc.soap.client</packageSpace>
                </configuration>
                <executions>
                    <execution>
                        <id>wsdl2java-generation</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>wsdl2java</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>axis</groupId>
            <artifactId>axis</artifactId>
            <version>${axis.version}</version>
        </dependency>
    </dependencies>

With the contracts and the necessary code generated, I started with authenticating myself to my local JIRA development machine. When the authentication is succesfull you receive a token-string. You’ll notice that most of the operations require this token as a parameter.

    public static void main(String[] args) throws Exception {
        final JiraSoapServiceServiceLocator soapLocator = new JiraSoapServiceServiceLocator();
        final JiraSoapService soapService = soapLocator.getJirasoapserviceV2(new URL("http://192.168.0.221:8080/rpc/soap/jirasoapservice-v2"));
        String authToken = soapService.login("admin", "admin");
        System.out.println(String.format("Logged in with token %s",authToken));
        soapService.logout(authToken);
    }

Of course you need to change the URL and login credentials in the example above for your environment. The token is printed to the commandLine as proof that we are logged in.

To demonstrate the communication and the robustness of the API, I pass in wrong credentials and a nice Exception is thrown by the API:

 faultCode: {http://schemas.xmlsoap.org/soap/envelope/}Server.userException
 faultSubcode:
 faultString: com.atlassian.jira.rpc.exception.RemoteAuthenticationException: Invalid username or password.
 faultActor:
 faultNode:
 faultDetail:
    {}com.atlassian.jira.rpc.exception.RemoteAuthenticationException:null
    {http://xml.apache.org/axis/}stackTrace:com.atlassian.jira.rpc.exception.RemoteAuthenticationException: Invalid username or password.

Advanced: creating issues

Now we’re logged in, we can experiment with all operations in the API. In this example I’ll be creating an issue with the least amount of effort required. The amount of code needed to create a standard issue is very minimal:

    public static void main(String[] args) throws Exception {
        final JiraSoapServiceServiceLocator soapLocator = new JiraSoapServiceServiceLocator();
        final JiraSoapService soapService = soapLocator.getJirasoapserviceV2(new URL("http://192.168.0.221:8080/rpc/soap/jirasoapservice-v2"));
        final String authToken = soapService.login("admin", "admin");
        System.out.println(String.format("Logged in with token: %S", authToken));
        try {

            final RemoteIssue issueToCreate = new RemoteIssue();
            issueToCreate.setProject(myProjectKey); // use the key of your project
            issueToCreate.setSummary("This will be the summary or 'title' of my issue");
            issueToCreate.setType("3"); // Task

            final RemoteIssue createdIssue = soapService.createIssue(authToken, issueToCreate);
            System.out.println(String.format("Created issue with id %s", createdIssue.getId()));

        } finally {
            soapService.logout(authToken);
        }
    }

Notice the hardcoded values in the issueToCreate. This is because I removed some code for showcase purposes. In real situations, I suggest you use API operations like getProjectByKey, getIssueTypesForProject to use serverside values and thus making your code more dynamic. The same goes for custom fields, fixVersions and other values.

Advanced: creating Sub Tasks

Now a tricky part. I told you my client (and by this, me) is using JIRA 4.3.4. Well, creating SubTasks using the SOAP API is only supported as of Jira 4.4 ! In the 4.4 API there is a nice operation added in the WSDL : createIssueWithParent(String, RemoteIssue, String). This operation is absent in JIRA 4.3.4.

Since we can’t force our client to upgrade their JIRA, this was a bit of a disappointment. I was getting acquainted with the API, creating my parent issues , and now this…

I knew other projects worked around this issue.. I opened the sources of the Jira CLI project and found confirmation for my theory: creating subtasks wasn’t possible using the Remote API over SOAP.

This is why I love Java and Open-Source

The workaround is a form submit to the web page, just like a user would do in the web interface. This solution comes with a risk, since you basically do a http request/response cycle with no validation whatsoever. Should you, like me, opt for this approach, please do proper validation: http response OK, no errors on screen, form submitted ok, …

Here is an example of the most basic code to create a subtask using a form submit. Please add the following dependency to your project to make it compile:

        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpclient</artifactId>
            <version>4.1.2</version>
        </dependency>

Some important notes:

• The username/password must be passed
• The  X-Atlassian-Token header makes JIRA skip form validation, without this it doesn’t work
• Should you be interested in this approach, please use JIRA CLI (or its sources) to do proper validation of the response

This is the essential code, without validation, to create a subtask in the Remote API for JIRA 4.3.4:

public class Example {

    public static void main(String[] args) throws Exception {
        final JiraSoapServiceServiceLocator soapLocator = new JiraSoapServiceServiceLocator();
        final JiraSoapService soapService = soapLocator.getJirasoapserviceV2(new URL(
                "http://192.168.0.221:8080/rpc/soap/jirasoapservice-v2"));
        final String authToken = soapService.login("admin", "admin");
        System.out.println(String.format("Logged in with token: %S", authToken));
        try {
            final RemoteProject project = soapService.getProjectByKey(authToken, "KBOBCE");
            final RemoteIssue issueToCreate = new RemoteIssue();
            issueToCreate.setProject(project.getKey());
            issueToCreate.setSummary("Parent - This will be the summary or 'title' of my issue");
            issueToCreate.setType("3"); // Task

            final RemoteIssue createdIssue = soapService.createIssue(authToken, issueToCreate);
            System.out.println(String.format("Created issue with id %s", createdIssue.getId()));

            RemoteIssue subTask = new RemoteIssue();
            subTask.setSummary("SubTask - This will be the summary or 'title' of my issue");
            subTask.setType("5"); // Sub-Task

            createSubTaskUsingHttpPost(createdIssue.getId(),project.getId(), subTask);

        } finally {
            soapService.logout(authToken);
        }

    }

    private static void createSubTaskUsingHttpPost(String parentIssueId, String projectId, RemoteIssue issue) throws Exception {
        HttpClient httpClient = new DefaultHttpClient();

        List<NameValuePair> params = new ArrayList<NameValuePair>();
        params.add(new BasicNameValuePair("os_username", "admin"));
        params.add(new BasicNameValuePair("os_password", "admin"));

        params.add(new BasicNameValuePair("parentIssueId", parentIssueId));
        params.add(new BasicNameValuePair("pid", projectId));
        params.add(new BasicNameValuePair("issuetype", issue.getType()));
        params.add(new BasicNameValuePair("priority", "3")); //Major

        params.add(new BasicNameValuePair("assignee", "-1")); // Automatic
        params.add(new BasicNameValuePair("description", issue.getDescription()));
        params.add(new BasicNameValuePair("environment", issue.getEnvironment()));
        params.add(new BasicNameValuePair("priority", issue.getPriority()));
        params.add(new BasicNameValuePair("reporter", "admin"));
        params.add(new BasicNameValuePair("summary", issue.getSummary()));

        URI uri = new URI("http://192.168.0.221:8080/secure/CreateSubTaskIssueDetails.jspa");
        uri = URIUtils.createURI(uri.getScheme(), uri.getHost(), uri.getPort(), uri.getPath(), URLEncodedUtils.format(params, "UTF-8"),
                null);

        final HttpGet httpget = new HttpGet(uri);
        httpget.addHeader("X-Atlassian-Token", "no-check");
        httpget.addHeader("Content-Type", "application/xml");
        httpget.addHeader("Accept", "application/xml");

        final ResponseHandler<String> handler = new ResponseHandler<String>() {
            public String handleResponse(HttpResponse response) throws ClientProtocolException, IOException {
                System.out.println(String.format("StatusLine %S", response.getStatusLine()));

                HttpEntity entity = response.getEntity();
                if (entity != null) {
                    return EntityUtils.toString(entity);
                } else {
                    return null;
                }

            }
        };

        final String htmlRresponse = httpClient.execute(httpget, handler); // TODO: Pretty please check the response for errors
        System.out.println(String.format("HtmlResponse: %s", htmlRresponse));
    }

}

In conclusion

My experience with the JIRA Remote API has been quite positive. As this article points out, it’s very easy to get started. Remotely interacting with your JIRA instance has never been easier. The Remote API is under continuous development.

On the downside, I was disappointed to find out that basic functionality like creating subTasks wasn’t supported in my Jira Version (4.3.4). Though a fix was provided, most of the time you can’t just patch a JIRA instance used by a whole organization.

I’m happy to see that Atlassian is streamlining their Remote API. Their focus in the future will be the REST-interface.

References used

Jira 4.3.4 JiraSoapService API -Online JavaDoc for the JiraSoapService

Jira Command Line Interface – A plugin, subproject actually, providing access to your JIRA instance using the commandline. It’s very complete and is well maintained.

Jira RPC Service overview – An overview of the current and future developments of Atlassian in their Remote API/RPC