With the exception of the API login and logout methods, which aren't needed, all other methods are available through the JIRA::Client object interface. You must call them with the same name as documented in the specification but you should not pass the token argument, because it is supplied transparently by the JIRA::Client object.

All methods fail by throwing exceptions (croaking, actually). You may want to guard against this by invoking them within an eval block, like this:

Some of the API methods require hard-to-build data structures as arguments. This module tries to make them easier to call by accepting simpler structures and implicitly constructing the more elaborated ones before making the actual SOAP call. Note that this is an option, i.e, you can either pass the elaborate structures by yourself or the simpler ones in the call.

The items below are all the implemented implicit conversions. Wherever a parameter of the type specified first is required (as an rvalue, not as an lvalue) by an API method you can safely pass a value of the type specified second.

This module implements some extra methods to add useful functionality to the API. They are described below. Note that their names don't follow the CamelCase convention used by the native API methods but the more Perlish underscore_separated_words convention so that you can distinguish them and we can avoid future name clashes.

BASEURL is the JIRA server's base URL (e.g., https://jira.example.net or https://example.net/jira), to which the default WSDL descriptor path (/rpc/soap/jirasoapservice-v2?wsdl) will be appended in order to construct the underlying SOAP::Lite object.

USER and PASSWD are the credentials that will be used to authenticate into JIRA.

Any other arguments will be passed to the SOAP::Lite object that will be created to talk to JIRA.

You can invoke the constructor with a single hash-ref argument. The same arguments that are passed as a list above can be passed by name with a hash. This constructor is also more flexible, as it makes room for extra arguments.

It accepts a 'magic' field called parent, which specifies the issue key from which the created issue must be a sub-task.

It accepts another 'magic' field called custom_fields to make it easy to set custom fields. It accepts a hash mapping each custom field to its value. The custom field can be specified by its id (in the format customfield_NNNNN) or by its name, in which case the method will try to convert it to its id. Note that to do that conversion the user needs administrator rights.

A simple custom field value can be specified by a scalar, which will be properly placed inside an ARRAY in order to satisfy the RemoteFieldValue's structure.

Cascading select fields are properly specified like this: http://tinyurl.com/2bmthoa. The magic short-cut requires a HASH where each cascading level is indexed by its level number, starting at zero. So, instead of specifying it like this:

Update a issue given a hash containing the values for its fields. The first argument may be an issue key or a RemoteIssue object. The second argument must be a hash-ref specifying the fields's values just like documented in the create_issue function above.

This is an easier to use version of the updateIssue API method because it accepts the same shortcuts that create_issue does.

Returns a hash mapping JIRA's custom field names to the RemoteField representing them. It's useful since when you get a RemoteIssue object from this API it doesn't contain the custom field's names, but just their identifiers. From the RemoteField object you can obtain the field's id, which is useful when calling the updateIssue method.

The method calls the getCustomFields API method the first time and keeps the custom fields information in a cache.

Passes a hash mapping JIRA's custom field names to the RemoteField representing them to populate the custom field's cache. This can be useful if you don't have administrative privileges to the JIRA instance, since only administrators can call the getCustomFields API method.

This is a safe and easier to use version of the progressWorkflowAction API method which is used to progress an issue through a workflow's action while making edits to the fields that are shown in the action screen. The API method is dangerous because if you forget to provide new values to all the fields shown in the screen, then the fields not provided will become undefined in the issue. The problem has a pending issue on Atlassian's JIRA http://jira.atlassian.com/browse/JRA-8717.

This method plays it safe by making sure that all fields shown in the screen that already have a value are given new (or the same) values so that they don't get undefined. It calls the getFieldsForAction API method to grok all fields that are shown in the screen. If there is any field not set in the ACTION_PARAMS then it calls getIssue to grok the missing fields current values. As a result it constructs the necessary RemoteFieldAction array that must be passed to progressWorkflowAction.

The method is also easier to use because its arguments are more flexible:

This method receives a RemoteField object and a list of names or ids of custom fields. It returns a list of references to the ARRAYs containing the values of the ISSUE's custom fields denoted by their NAME_OR_IDs. Returns undef for custom fields not set on the issue.

When you want to specify a different name to the attachment or when you already have an IO object (a GLOB, a IO::File, or a FileHandle) you must pass them as values of a hash. The keys of the hash are taken as the attachment name. You can specify more than one attachment in each hash.

The method retuns the value returned by the addBase64EncodedAttachmentsToIssue API method.

In the example below, we attach three files to the issue TST-1. The first is called file1.txt and its contents are read from /path/to/file1.txt. The second is called text.txt and its contents are read from /path/to/file2.txt. the third is called me.jpg and its contents are read from the object refered to by $fh.

This method attaches one or more strings to an issue. The ISSUE argument may be an issue key or a RemoteIssue object. The attachments are specified by a HASHREF in which the keys denote the file names and the values their contents.

The method retuns the value returned by the addBase64EncodedAttachmentsToIssue API method.

As a last resort, FILTER is passed to getIssuesFromJqlSearch as a JQL expression. For example:

project = CDS AND fixVersion = sprint-5

The optional LIMIT argument specified the maximum number of issues that can be returned. It has a default limit of 1000, but this can be overridden by the JIRA server configuration.

This method is meant to be used as a flexible interface for human beings to request a list of issues. Be warned, however, that you are responsible to de-taint the FILTER argument before passing it to the method.