view release on metacpan or  search on metacpan

lib/JIRA/Client.pm  view on Meta::CPAN

Moreover, it implements some other methods to make it easier to do
some common operations.

=head1 API METHODS

With the exception of the API C<login> and C<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
C<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:

  my $issue = eval { $jira->getIssue('TST-123') };
  die "Can't getIssue('TST-123'): $@" if $@;

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.

=over 4

=item A B<issue key> as a string can be specified by a B<RemoteIssue> object.

=item A B<RemoteComment> object can be specified by a string.

=item A B<filterId> as a string can be specified by a B<RemoteFilter> object.

=item A B<RemoteFieldValue> object array can be specified by a hash mapping field names to values.

=back

=head1 EXTRA METHODS

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.

=head2 B<new> BASEURL, USER, PASSWD [, <SOAP::Lite arguments>]

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

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

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

=head2 B<new> HASH_REF

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.

The valid hash keys are listed below.

=over

=item baseurl => STRING

(Required) The JIRA server's base URL.

=item wsdl => STRING

(Optional) JIRA's standard WSDL descriptor path is
C</rpc/soap/jirasoapservice-v2?wsdl>. If your JIRA instance has a
non-standard path to the WSDL service, you may specify it here.

=item user => STRING

(Required) The username to authenticate into JIRA.

=item password => STRING

(Required) The password to authenticate into JIRA.

=item soapargs => ARRAY_REF

(Optional) Extra arguments to be passed to the L<SOAP::Lite> object
that will be created to talk to JIRA.

=back

=head2 B<create_issue> HASH_REF [, SECURITYLEVEL]

Creates a new issue given a hash containing the initial values for its
fields and, optionally, a security-level. The hash must specify at
least the fields C<project>, C<summary>, and C<type>.

This is an easier to use version of the createIssue API method. For
once it accepts symbolic values for some of the issue fields that the
API method does not. Specifically:

=over 4

=item C<type> can be specified by I<name> instead of by I<id>.

=item C<priority> can be specified by I<name> instead of by I<id>.

=item C<component> can be specified by a list of component I<names> or
I<ids> instead of a list of C<RemoteComponent> objects.