NAME

JIRA::REST::Class - An OO Class module built atop JIRA::REST for dealing with JIRA issues and their data as objects.

VERSION

version 0.01

SYNOPSIS

  use JIRA::REST::Class;

  my $jira = JIRA::REST::Class->new('https://jira.example.net',
                                    'myuser', 'mypass');

  # if your server uses self-signed SSL certificates
  $jira->SSL_verify_none;

  # allow the class to fetch the metadata for your project
  $jira->project('MYPROJECT');

  # get issue by key
  my ($issue) = $jira->issues('MYPROJECT-101');

  # get multiple issues by key
  my @issues = $jira->issues('MYPROJECT-101', 'MYPROJECT-102', 'MYPROJECT-103');

  # get multiple issues through search
  my @issues =
      $jira->issues({ jql => 'project = "'MYPROJECT" and status = "open"' });

  # get an iterator for a search
  my $search =
      $jira->iterator({ jql => 'project = "'MYPROJECT" and status = "open"' });

  if ( $search->issue_count ) {
      printf "Found %d open issues in MYPROJECT:\n", $search->issue_count;
      while ( my $issue = $search->next ) {
          printf "  Issue %s is open\n", $issue->key;
      }
  }
  else {
      print "No open issues in MYPROJECT.\n";
  }

DESCRIPTION

An OO Class module built atop JIRA::REST for dealing with JIRA issues and their data as objects.

This code is a work in progress, so it's bound to be incomplete. I add methods to it as I discover I need them. I also code for fields that might exist in my JIRA server's configuration but not in yours. It is my intent to make things more generic as I go on so they will "just work" no matter how your server is configured.

CONSTRUCTOR

new(URL, USERNAME, PASSWORD [, REST_CLIENT_CONFIG])

The constructor new() mimics the constructor for JIRA::REST, and accepts up to four arguments (this documentation is lifted directly from JIRA::REST's documentation):

• URL

  A string or a URI object denoting the base URL of the JIRA server. This is a required argument.

  You may choose a specific API version by appending the /rest/api/VERSION string to the URL's path. It's more common to left it unspecified, in which case the /rest/api/latest string is appended automatically to the URL.

• USERNAME

  The username of a JIRA user.

  It can be undefined if PASSWORD is also undefined. In such a case the user credentials are looked up in the .netrc file.

• PASSWORD

  The HTTP password of the user. (This is the password the user uses to log in to JIRA's web interface.)

  It can be undefined, in which case the user credentials are looked up in the .netrc file.

• REST_CLIENT_CONFIG

  A JIRA::REST object uses a REST::Client object to make the REST invocations. This optional argument must be a hash-ref that can be fed to the REST::Client constructor. Note that the URL argument overwrites any value associated with the host key in this hash.

  To use a network proxy please set the 'proxy' argument to the string or URI object describing the fully qualified (including port) URL to your network proxy. This is an extension to the REST::Client configuration and will be removed from the hash before passing it on to the REST::Client constructor.

METHODS

issues QUERY

issues KEY [, KEY...]

The issues method can be called two ways: either by providing a list of issue keys, or by proving a single hash reference which describes a JIRA query in the same format used by JIRA::REST (essentially, jql => "JQL query string").

The return value is an array of JIRA::REST::Class::Issue objects.

query QUERY

The query method takes a single parameter: a hash reference which describes a JIRA query in the same format used by JIRA::REST (essentially, jql => "JQL query string").

The return value is a single JIRA::REST::Class::Query object.

iterator QUERY

The query method takes a single parameter: a hash reference which describes a JIRA query in the same format used by JIRA::REST (essentially, jql => "JQL query string"). It accepts an additional field, however: restart_if_lt_total. If this field is set to a true value, the iterator will keep track of the number of results fetched and, if when the results run out this number doesn't match the number of results predicted by the query, it will restart the query. This is particularly useful if you are transforming a number of issues through an iterator, and the transformation causes the issues to no longer match the query.

The return value is a single JIRA::REST::Class::Iterator object. The issues returned by the query can be obtained in serial by repeatedly calling next on this object, which returns a series of JIRA::REST::Class::Issue objects.

get URL [, QUERY]

A wrapper for JIRA::REST's GET method.

maxResults

An accessor that allows setting a global default for maxResults. Defaults to 50.

issue_types

Returns a list of defined issue types (as JIRA::REST::Class::Issue::Type objects) for this server.

projects

Returns a list of projects (as JIRA::REST::Class::Project objects) for this server.

project PROJECT_ID || PROJECT_KEY || PROJECT_NAME

Returns a JIRA::REST::Class::Project object for the project specified. Returns undef if the project doesn't exist.

SSL_verify_none

Disables the SSL options SSL_verify_mode and verify_hostname on the user agent used by this class' REST::Client object.

INTERNAL METHODS

post

Wrapper around JIRA::REST's POST method.

put

Wrapper around JIRA::REST's PUT method.

delete

Wrapper around JIRA::REST's DELETE method.

rest_api_url_base

Returns the base URL for this JIRA server's REST API.

strip_protocol_and_host

A method to take the provided URL and strip the protocol and host from it.

url

An accessor for the URL passed to the JIRA::REST object.

username

An accessor for the username passed to the JIRA::REST object.

password

An accessor for the password passed to the JIRA::REST object.

rest_client_config

An accessor for the REST client config passed to the JIRA::REST object.

factory

An accessor for the JIRA::REST::Class::Factory.

JIRA_REST

An accessor that returns the JIRA::REST object being used.

REST_CLIENT

An accessor that returns the REST::Client object inside the JIRA::REST object being used.

SEE ALSO

• JIRA::REST

  JIRA::REST::Class uses JIRA::REST to perform all its interaction with JIRA.

• REST::Client

  JIRA::REST uses a REST::Client object to perform its low-level interactions.

• JIRA REST API Reference

  Atlassian's official JIRA REST API Reference.

REPOSITORY

https://github.com/packy/JIRA-REST-Class

AUTHOR

Packy Anderson <packy@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Packy Anderson.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm JIRA::REST::Class

perl -MCPAN -e shell
install JIRA::REST::Class