diff -Nru libjira-client-automated-perl-1.05/Changes libjira-client-automated-perl-1.30/Changes --- libjira-client-automated-perl-1.05/Changes 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/Changes 2015-04-27 04:46:22.000000000 +0000 @@ -1,3 +1,30 @@ +1.3 2015-04-26 21:46:10-07:00 America/Los_Angeles + Added option to close_issue() using a different transition, mainly for localization issues. + (Patch provided by Ivan E. Panchenko .) + +1.2 2015-02-16 22:25:05-08:00 America/Los_Angeles + Added option to return a different set of fields from search_issues(). + Added a new method to get issue comments. + Added support for linking issues. + Added convenience methods for adding and removing labels. + Added the ability to add watchers to an issue. + Updated POD a little. + (Based on patches from Ivan E. Panchenko .) + + Added a new method to change the assignee for an issue. + (Patch provided by José Antonio Perez Testa .) + +1.1 2014-07-13 19:04:36-07:00 America/Los_Angeles + Added support for custom fields in create_issue(). + Changed to allow multiple potential transitions in transition_issue(). + Made error reporting more informative. + Added new trace() method for even more debugging. + Refactored all requests to use a single internal request method. + Extended and unified handling of update hashes. + Formatting fixes in POD. + (Patches provided by Tim Bunce .) + + 1.05 2014-03-31 19:24:19-07:00 America/Los_Angeles Added create_subtask() method to create subtasks easily. Refactored create_issue() to share code with create_subtask(). diff -Nru libjira-client-automated-perl-1.05/debian/changelog libjira-client-automated-perl-1.30/debian/changelog --- libjira-client-automated-perl-1.05/debian/changelog 2014-05-13 18:01:06.000000000 +0000 +++ libjira-client-automated-perl-1.30/debian/changelog 2015-07-05 17:07:57.000000000 +0000 @@ -1,3 +1,16 @@ +libjira-client-automated-perl (1.30-1) unstable; urgency=medium + + [ Salvatore Bonaccorso ] + * Update Vcs-Browser URL to cgit web frontend + + [ Dominique Dumont ] + * watch: mangle upstream version to add a trailing 0. + * Imported Upstream version 1.30 + * control: updated dts-version to 3.9.6, added testsuite param + * copyright: updated years + + -- Dominique Dumont Sun, 05 Jul 2015 19:07:00 +0200 + libjira-client-automated-perl (1.05-1) unstable; urgency=medium * Team upload. diff -Nru libjira-client-automated-perl-1.05/debian/control libjira-client-automated-perl-1.30/debian/control --- libjira-client-automated-perl-1.05/debian/control 2014-05-13 18:01:06.000000000 +0000 +++ libjira-client-automated-perl-1.30/debian/control 2015-07-05 17:07:57.000000000 +0000 @@ -2,6 +2,7 @@ Maintainer: Debian Perl Group Uploaders: Dominique Dumont Section: perl +Testsuite: autopkgtest-pkg-perl Priority: optional Build-Depends: debhelper (>= 9) Build-Depends-Indep: libhttp-message-perl, @@ -10,8 +11,8 @@ libtest-exception-perl, libwww-perl, perl -Standards-Version: 3.9.5 -Vcs-Browser: http://anonscm.debian.org/gitweb/?p=pkg-perl/packages/libjira-client-automated-perl.git +Standards-Version: 3.9.6 +Vcs-Browser: https://anonscm.debian.org/cgit/pkg-perl/packages/libjira-client-automated-perl.git Vcs-Git: git://anonscm.debian.org/pkg-perl/packages/libjira-client-automated-perl.git Homepage: https://metacpan.org/release/JIRA-Client-Automated diff -Nru libjira-client-automated-perl-1.05/debian/copyright libjira-client-automated-perl-1.30/debian/copyright --- libjira-client-automated-perl-1.05/debian/copyright 2014-05-13 18:01:06.000000000 +0000 +++ libjira-client-automated-perl-1.30/debian/copyright 2015-07-05 17:07:57.000000000 +0000 @@ -4,11 +4,11 @@ Source: https://metacpan.org/release/JIRA-Client-Automated Files: * -Copyright: 2014, Polyvore, Inc. +Copyright: 2014-2015, Polyvore, Inc. License: Artistic or GPL-1+ Files: debian/* -Copyright: 2014, Dominique Dumont +Copyright: 2014-2015, Dominique Dumont License: Artistic or GPL-1+ License: Artistic diff -Nru libjira-client-automated-perl-1.05/debian/watch libjira-client-automated-perl-1.30/debian/watch --- libjira-client-automated-perl-1.05/debian/watch 2014-05-13 18:01:06.000000000 +0000 +++ libjira-client-automated-perl-1.30/debian/watch 2015-07-05 17:07:57.000000000 +0000 @@ -1,2 +1,3 @@ version=3 +opts="uversionmangle=s/\.\d$/$&0/;" \ https://metacpan.org/release/JIRA-Client-Automated .*/JIRA-Client-Automated-v?(\d[\d.-]*)\.(?:tar(?:\.gz|\.bz2)?|tgz|zip)$ diff -Nru libjira-client-automated-perl-1.05/lib/JIRA/Client/Automated.pm libjira-client-automated-perl-1.30/lib/JIRA/Client/Automated.pm --- libjira-client-automated-perl-1.05/lib/JIRA/Client/Automated.pm 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/lib/JIRA/Client/Automated.pm 2015-04-27 04:46:22.000000000 +0000 @@ -1,16 +1,16 @@ -use 5.010; use strict; use warnings; +use 5.010; package JIRA::Client::Automated; -$JIRA::Client::Automated::VERSION = '1.05'; +$JIRA::Client::Automated::VERSION = '1.3'; =head1 NAME JIRA::Client::Automated - A JIRA REST Client for automated scripts =head1 VERSION -version 1.05 +version 1.3 =head1 SYNOPSIS @@ -20,6 +20,8 @@ my $jira_ua = $jira->ua(); # to add in a proxy + $jira->trace(1); # enable tracing of requests and responses + # The simplest way to create an issue my $issue = $jira->create_issue($project, $type, $summary, $description); @@ -47,6 +49,7 @@ my $search_results = $jira->search_issues($jql, 1, 100); # query should be a single string of JQL my @issues = $jira->all_search_results($jql, 1000); # query should be a single string of JQL + my $issue = $jira->get_issue($key); $jira->update_issue($key, $update_hash); # update_hash is { field => value, ... } @@ -55,36 +58,60 @@ $jira->transition_issue($key, $transition, $transition_hash); # transition_hash is { field => value, ... } - $jira->close_issue($key, $resolve, $message); # resolve is the resolution value + $jira->close_issue($key, $resolve, $comment); # resolve is the resolution value $jira->delete_issue($key); -=head1 DESCRIPTION + $jira->add_issue_watchers($key, $watcher1, ......); + $jira->add_issue_labels($key, $label1, ......); -JIRA::Client::Automated is an adapter between any automated system and JIRA's REST API. This module is explicitly designed to easily create and close issues within a JIRA instance via automated scripts. -For example, if you run nightly batch jobs, you can use JIRA::Client::Automated to have those jobs automatically create issues in JIRA for you when the script runs into errors. You can attach error log files to the issues and then they'll be waiting in someone's open issues list when they arrive at work the next day. +=head1 DESCRIPTION -If you want to avoid creating the same issue more than once you can search JIRA for it first, only creating it if it doesn't exist. If it does already exist you can add a comment or a new error log to that issue. +JIRA::Client::Automated is an adapter between any automated system and JIRA's +REST API. This module is explicitly designed to easily create and close issues +within a JIRA instance via automated scripts. + +For example, if you run nightly batch jobs, you can use JIRA::Client::Automated +to have those jobs automatically create issues in JIRA for you when the script +runs into errors. You can attach error log files to the issues and then they'll +be waiting in someone's open issues list when they arrive at work the next day. + +If you want to avoid creating the same issue more than once you can search JIRA +for it first, only creating it if it doesn't exist. If it does already exist +you can add a comment or a new error log to that issue. =head1 WORKING WITH JIRA -Atlassian has made a very complete REST API for recent (> 5.0) versions of JIRA. By virtue of being complete it is also somewhat large and a little complex for the beginner. Reading their tutorials is *highly* recommended before you start making hashes to update or transition issues. +Atlassian has made a very complete REST API for recent (> 5.0) versions of +JIRA. By virtue of being complete it is also somewhat large and a little +complex for the beginner. Reading their tutorials is *highly* recommended +before you start making hashes to update or transition issues. L -This module was designed for the JIRA 5.2.11 REST API, as of March 2013, but it works fine with JIRA 6.0 as well. Your mileage may vary with future versions. +This module was designed for the JIRA 5.2.11 REST API, as of March 2013, but it +works fine with JIRA 6.0 as well. Your mileage may vary with future versions. =head1 JIRA ISSUE HASH FORMAT -When you work with an issue in JIRA's REST API, it gives you a JSON file that follows this spec: +When you work with an issue in JIRA's REST API, it gives you a JSON file that +follows this spec: L -JIRA::Client::Automated tries to be nice to you and not make you deal directly with JSON. When you create a new issue, you can pass in just the pieces you want and L will transform them to JSON for you. The same for closing and deleting issues. However there's not much I can do about updating or transitioning issues. Each JIRA installation will have different fields available for each issue type and transition screen and only you will know what they are. So in those cases you'll need to pass in an "update_hash" which will be transformed to the proper JSON by the method. +JIRA::Client::Automated tries to be nice to you and not make you deal directly +with JSON. When you create a new issue, you can pass in just the pieces you +want and L will transform them to JSON for you. The same for +closing and deleting issues. + +Updating and transitioning issues is more complex. Each JIRA installation will +have different fields available for each issue type and transition screen and +only you will know what they are. So in those cases you'll need to pass in an +"update_hash" which will be transformed to the proper JSON by the method. An update_hash looks like this: - { field => value, field2 => value2, ...} + { field1 => value, field2 => value2, ...} For example: @@ -93,11 +120,16 @@ { resolution => { name => "Resolved" } } } -If you do not read JIRA's documentation about their JSON format you will hurt yourself banging your head against your desk in frustration the first few times you try to use L. Please RTFM. +If you do not read JIRA's documentation about their JSON format you will hurt +yourself banging your head against your desk in frustration the first few times +you try to use L. Please RTFM. + +Note that even though JIRA requires JSON, JIRA::Client::Automated will +helpfully translate it to and from regular hashes for you. You only pass hashes +to JIRA::Client::Automated, not direct JSON. -Note that even though JIRA requires JSON, JIRA::Client::Automated will helpfully translate it to and from regular hashes for you. You only pass hashes to JIRA::Client::Automated, not direct JSON. - -But, since you aren't going to read the documentation, I recommend connecting to your JIRA server and calling L with a key you know exists and then dump the result. That'll get you started. +I recommend connecting to your JIRA server and calling L with a +key you know exists and then dump the result. That'll get you started. =head1 METHODS @@ -108,6 +140,7 @@ use HTTP::Request; use HTTP::Request::Common qw(GET POST PUT DELETE); use LWP::Protocol::https; +use Carp; =head2 new @@ -131,9 +164,13 @@ =back -All three parameters are required. JIRA::Client::Automated must connect to the JIRA instance using I username and password. I recommend setting up a special "auto" or "batch" username to use just for use by scripts. - -If you are using Google Account integration, the username and password to use are the ones you set up at the very beginning of the registration process and then never used again because Google logged you in. +All three parameters are required. JIRA::Client::Automated must connect to the +JIRA instance using I username and password. You may want to set up a +special "auto" or "batch" username to use just for use by scripts. + +If you are using Google Account integration, the username and password to use +are the ones you set up at the very beginning of the registration process and +then never used again because Google logged you in. =cut @@ -141,7 +178,7 @@ my ($class, $url, $user, $password) = @_; unless (defined $url && $url && defined $user && $user && defined $password && $password) { - die "Need to specify url, username, and password to access JIRA."; + croak "Need to specify url, username, and password to access JIRA"; } unless ($url =~ m{/$}) { @@ -160,7 +197,7 @@ $auth_url =~ s{:/}{://}; if ($auth_url !~ m|https?://|) { - die "URL for JIRA must be absolute, including 'http://' or 'https://'."; + croak "URL for JIRA must be absolute, including 'http://' or 'https://'"; } my $self = { url => $url, auth_url => $auth_url, user => $user, password => $password }; @@ -170,28 +207,93 @@ $self->{_ua} = LWP::UserAgent->new(); # cached JSON object for handling conversions - $self->{_json} = JSON->new->utf8(); + $self->{_json} = JSON->new->utf8()->allow_nonref; return $self; } + =head2 ua - my $jira_ua = $jira->ua(); + my $ua = $jira->ua(); Returns the L object used to connect to the JIRA instance. Typically used to setup proxies or make other customizations to the UserAgent. For example: - $jira->ua()->env_proxy(); + my $ua = $jira->ua(); + $ua->env_proxy(); + $ua->ssl_opts(...); + $ua->conn_cache( LWP::ConnCache->new() ); =cut sub ua { my $self = shift; + $self->{_ua} = shift if @_; return $self->{_ua}; } + +=head2 trace + + $jira->trace(1); # enable + $jira->trace(0); # disable + $trace = $jira->trace; + +When tracing is enabled each request and response is logged using carp. + +=cut + +sub trace { + my $self = shift; + $self->{_trace} = shift if @_; + return $self->{_trace}; +} + + +sub _handle_error_response { + my ($self, $response, $request) = @_; + + my $msg = $response->status_line; + $msg .= sprintf " %s", $response->decoded_content + if $response->decoded_content; + $msg .= sprintf " (for request: %s)", $request->decoded_content + if $request->decoded_content; + + croak sprintf "Unable to %s %s: %s", + $request->method, $request->uri->path, $msg; +} + + +sub _perform_request { + my ($self, $request, $handlers) = @_; + + $request->authorization_basic($self->{user}, $self->{password}); + + if ($self->trace) { + carp sprintf "request %s %s: %s", + $request->method, $request->uri->path, $request->decoded_content//''; + } + + my $response = $self->{_ua}->request($request); + + if ($self->trace) { + carp sprintf "response %s: %s", + $response->status_line, $response->decoded_content//''; + } + + return $response if $response->is_success(); + + $handlers ||= {}; + my $handler = $handlers->{ $response->code } || sub { + return $self->_handle_error_response($response, $request); + }; + + return $handler->($response, $request, $self); +} + + =head2 create my $issue = $jira->create({ @@ -212,7 +314,16 @@ Creating a new issue, story, task, subtask, etc. -Returns a hash containing the information about the new issue or dies if there is an error. See L for details of the hash. +Returns a hash containing only the basic information about the new issue, or +dies if there is an error. The hash looks like: + + { + id => 24066, + key => "TEST-57", + self => "https://example.atlassian.net/rest/api/latest/issue/24066" + } + +See also L =cut @@ -228,51 +339,58 @@ Content_Type => 'application/json', Content => $issue_json; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error creating new JIRA issue $fields->{summary} " . $response->status_line(); - } + my $response = $self->_perform_request($request); my $new_issue = $self->{_json}->decode($response->decoded_content()); return $new_issue; } + =head2 create_issue - my $issue = $jira->create_issue($project, $type, $summary, $description); + my $issue = $jira->create_issue($project, $type, $summary, $description, $fields); + +Creating a new issue requires the project key, type ("Bug", "Task", etc.), and +a summary and description. + +The optional $fields parameter can be used to pass a reference to a hash of +extra fields to be set when the issue is created, which avoids the need for a +separate L call. For example: -Creating a new issue requires the project key, type ("Bug", "Task", etc.), and a summary and description. Other fields that are on the new issue form could be supported by a subclass, but it's probably easier to use L with JIRA's syntax for now. + $jira->create_issue($project, $type, $summary, $description, { + labels => [ "foo", "bar" ] + }); -Returns a hash containing the information about the new issue or dies if there is an error. See L for details of the hash. +This method calls L and return the same hash reference that it does. =cut sub create_issue { - my ($self, $project, $type, $summary, $description) = @_; + my ($self, $project, $type, $summary, $description, $fields) = @_; - my $fields = { + my $create_fields = { + %{ $fields || {} }, summary => $summary, description => $description, issuetype => { name => $type, }, project => { key => $project, }, }; - return $self->create($fields); + return $self->create($create_fields); } + =head2 create_subtask my $subtask = $jira->create_subtask($project, $summary, $description, $parent_key); # or with optional subtask type my $subtask = $jira->create_subtask($project, $summary, $description, $parent_key, 'sub-task'); -Creating a subtask. If your JIRA instance does not call subtasks "Sub-task" or "sub-task", then you will need to pass in your subtask type. +Creating a subtask. If your JIRA instance does not call subtasks "Sub-task" or +"sub-task", then you will need to pass in your subtask type. -Returns a hash containing the information about the new issue or dies if there is an error. See L for details of the hash. +This method calls L and return the same hash reference that it does. =cut @@ -294,18 +412,44 @@ return $self->create($fields); } + =head2 update_issue - $jira->update_issue($key, $update_hash); + $jira->update_issue($key, $field_update_hash, $update_verb_hash); + +There are two ways to express the updates you want to make to an issue. + +For simple changes you pass $field_update_hash as a reference to a hash of +field_name => new_value pairs. For example: -Updating an issue is one place where JIRA's REST API shows through. You pass in the issue key and update_hash with only the field changes you want in it. See L, above, for details about the format of the update_hash. + $jira->update_issue($key, { summary => $new_summary }); + +That works for simple fields, but there are some, like comments, that can't be +updated in this way. For them you need to use $update_verb_hash. + +The $update_verb_hash parameter allow you to express a series of specific +operations (verbs) to be performed on each field. For example: + + $jira->update_issue($key, undef, { + labels => [ { remove => "test" }, { add => "another" } ], + comments => [ { remove => { id => 10001 } } ] + }); + +The two forms of update can be combined in a single call. + +For more information see: + + https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Edit+issues + https://developer.atlassian.com/display/JIRADEV/Updating+an+Issue+via+the+JIRA+REST+APIs =cut sub update_issue { - my ($self, $key, $update_hash) = @_; + my ($self, $key, $field_update_hash, $update_verb_hash) = @_; - my $issue = { fields => $update_hash }; + my $issue = {}; + $issue->{fields} = $field_update_hash if $field_update_hash; + $issue->{update} = $update_verb_hash if $update_verb_hash; my $issue_json = $self->{_json}->encode($issue); my $uri = "$self->{auth_url}issue/$key"; @@ -314,22 +458,19 @@ Content_Type => 'application/json', Content => $issue_json; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error updating JIRA issue $key " . $response->status_line(); - } + my $response = $self->_perform_request($request); return $key; } + =head2 get_issue my $issue = $jira->get_issue($key); -You can get the details for any issue, given its key. This call returns a hash containing the information for the issue in JIRA's format. See L for details. +Returns details for any issue, given its key. This call returns a hash +containing the information for the issue in JIRA's format. See L for details. =cut @@ -339,53 +480,128 @@ my $request = GET $uri, Content_Type => 'application/json'; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error getting JIRA issue $key " . $response->status_line(); - } + my $response = $self->_perform_request($request); my $new_issue = $self->{_json}->decode($response->decoded_content()); return $new_issue; } -# Each issue could have a different workflow and therefore a different transition id for 'Close Issue', so we -# have to look it up every time. -sub _get_transition_id { - my ($self, $key, $t_name) = @_; + +sub _get_transitions { + my ($self, $key) = @_; my $uri = "$self->{auth_url}issue/$key/transitions"; my $request = GET $uri, Content_Type => 'application/json'; - $request->authorization_basic($self->{user}, $self->{password}); + my $response = $self->_perform_request($request); - my $response = $self->{_ua}->request($request); + my $transitions = $self->{_json}->decode($response->decoded_content())->{transitions}; - if (!$response->is_success()) { - die "Error getting available transitions for JIRA issue $key " . $response->status_line(); - } + return $transitions; +} - my $t_list = $self->{_json}->decode($response->decoded_content()); - my ($t_id); - for my $transition (@{ $$t_list{transitions} }) { - if ($$transition{name} eq $t_name) { - $t_id = $$transition{id}; - } + +# Each issue could have a different workflow and therefore a different +# transition id for 'Close Issue', so we have to look it up every time. +# +# Also, since transition names can be freely edited ('Close', 'Close it!') +# we also match against the destination status name, which is much more +# likely to remain stable ('Closed'). This is low risk because transition +# names are verbs and status names are nouns, so a clash is very unlikely, +# or if they are the same the effect is the same ('Open'). +# +# We also allow the transition names to be specified as an array of names +# in which case the first one that matches either a transition or status is used. +# This makes it easier for scripts to handle the migration of names +# by allowing current and new names to be used so the later change in JIRA +# config doesn't cause any breakage. + +sub _get_transition_id { + my ($self, $key, $t_name) = @_; + + my $transitions = $self->_get_transitions($key); + + my %trans_names = map { $_->{name} => $_ } @$transitions; + my %status_names = map { $_->{to}{name} => $_ } @$transitions; + + my @names = (ref $t_name) ? @$t_name : ($t_name); + my @trans = map { $trans_names{$_} // $status_names{$_} } @names; # // is incompatible with perl <= 5.8 + my $tran = (grep { defined } @trans)[0]; # use the first defined one + + if (not defined $tran) { + my @trans2status = map { "'$_->{name}' (to '$_->{to}{name}')" } @$transitions; + croak sprintf "%s has no transition or reachable status called %s (available transitions: %s)", + $key, + join(", ", map { "'$_'" } @names), + join(", ", sort @trans2status) || ''; } - return $t_id; + return $tran->{id} unless wantarray; + return ($tran->{id}, $tran); } + =head2 transition_issue + $jira->transition_issue($key, $transition); $jira->transition_issue($key, $transition, $update_hash); -Transitioning an issue is what happens when you click the button that says "Resolve Issue" or "Start Progress" on it. Doing this from code is harder, but JIRA::Client::Automated makes it as easy as possible. You pass this method the issue key, the name of the transition (spacing and capitalization matter), and an optional update_hash containing any fields on the transition screen that you want to update. +Transitioning an issue is what happens when you click the button that says +"Resolve Issue" or "Start Progress" on it. Doing this from code is harder, but +JIRA::Client::Automated makes it as easy as possible. + +You pass this method the issue key, the name of the transition or the target +status (spacing and capitalization matter), and an optional update_hash +containing any fields that you want to update. + +=head3 Specifying The Transition + +The provided $transition name is first matched against the available +transitions for the $key issue ('Start Progress', 'Close Issue'). +If there's no match then the names is matched against the available target +status names ('Open', 'Closed'). You can use whichever is most appropriate. +For example, in your configuration the transition names might vary between +different kinds of projects but the status names might be the same. +In which case scripts that are meant to work across multiple projects +might prefer to use the status names. + +The $transition parameter can also be specified as a reference to an array of +names. In this case the first one that matches either a transition name or +status name is used. This makes it easier for scripts to work across multiple +kinds of projects and/or handle the migration of names by allowing current and +future names to be used, so the later change in JIRA config doesn't cause any +breakage. + +=head3 Specifying Updates + +If you have required fields on the transition screen (such as "Resolution" for +the "Resolve Issue" screen), you must pass those fields in as part of the +update_hash or you will get an error from the server. See L for the format of the update_hash. + +(Note: it appears that in some obscure cases missing required fields may cause the +transition to fail I causing an error from the server. For example +a field that's required but isn't configured to appear on the transition screen.) + +The $update_hash is a combination of the $field_update_hash and $update_verb_hash +parameters used by the L method. Like this: + + $update_hash = { + fields => $field_update_hash, + update => $update_verb_hash + }; -If you have required fields on the transition screen (such as "Resolution" for the "Resolve Issue" screen), you must pass those fields in as part of the update_hash or you will get an error from the server. See L for the format of the update_hash. +You can use it to express both simple field settings and more complex update +operations. For example: + + $jira->transition_issue($key, $transition, { + fields => { summary => $new_summary }, + update => { + labels => [ { remove => "test" }, { add => "another" } ], + comments => [ { remove => { id => 10001 } } ] + } + }); =cut @@ -402,54 +618,72 @@ Content_Type => 'application/json', Content => $t_json; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error with $t_name for JIRA issue $key: " . $response->status_line(); - } + my $response = $self->_perform_request($request); return $key; } + =head2 close_issue - $jira->close_issue($key, $resolve, $message); + $jira->close_issue($key); + $jira->close_issue($key, $resolve); + $jira->close_issue($key, $resolve, $comment); + $jira->close_issue($key, $resolve, $comment, $update_hash); + $jira->close_issue($key, $resolve, $comment, $update_hash, $operation); -Pass in the resolution reason and an optional comment to close an issue. Using this method requires that the issue is is a status where it can use the "Close Issue" transition. If not, you will get an error from the server. -Resolution ("Fixed", "Won't Fix", etc.) is only required if the issue hasn't already been resolved in an earlier transition. If you try to resolve an issue twice, you will get an error. +Pass in the resolution reason and an optional comment to close an issue. Using +this method requires that the issue is is a status where it can use the "Close +Issue" transition (or other one, specified by $operation). +If not, you will get an error from the server. + +Resolution ("Fixed", "Won't Fix", etc.) is only required if the issue hasn't +already been resolved in an earlier transition. If you try to resolve an issue +twice, you will get an error. If you do not supply a comment, the default value is "Issue closed by script". -If your JIRA installation has extra required fields on the "Close Issue" screen then you'll want to use the more generic L call instead. +The $update_hash can be used to set or edit the values of other fields. + +The $operation paramter can be used to specify the closing transition type. This +can be useful when your JIRA configuration uses nonstandard or localized +transition and status names, e.g. + + use utf8; + $jira->close_issue($key, $resolve, $comment, $update_hash, "Done"); + +See L for more details. + +This method is a wrapper for L. =cut sub close_issue { - my ($self, $key, $resolve, $comment) = @_; + my ($self, $key, $resolve, $comment, $update_hash, $operation) = @_; - $comment //= 'Issue closed by script'; + $comment //= 'Issue closed by script'; # // is incompatible with perl <= 5.8 + $operation //= [ 'Close Issue', 'Close', 'Closed' ]; - my ($closing); - if ($resolve) { - $closing = { - update => { comment => [{ add => { body => $comment }, }] }, - fields => { resolution => { name => $resolve } }, - }; - } else { - $closing = { update => { comment => [{ add => { body => $comment }, }] }, }; - } + $update_hash ||= {}; + + push @{$update_hash->{update}{comment}}, { + add => { body => $comment } + }; - return $self->transition_issue($key, 'Close Issue', $closing); + $update_hash->{fields}{resolution} = { name => $resolve } + if $resolve; + + return $self->transition_issue($key, $operation, $update_hash); } + =head2 delete_issue $jira->delete_issue($key); -Deleting issues is for testing your JIRA code. In real situations you almost always want to close unwanted issues with an "Oops!" resolution instead. +Deleting issues is for testing your JIRA code. In real situations you almost +always want to close unwanted issues with an "Oops!" resolution instead. =cut @@ -459,22 +693,21 @@ my $uri = "$self->{auth_url}issue/$key"; my $request = DELETE $uri; - $request->authorization_basic($self->{user}, $self->{password}); - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error deleting JIRA issue $key " . $response->status_line(); - } + my $response = $self->_perform_request($request); return $key; } + =head2 create_comment $jira->create_comment($key, $text); -You may use any valid JIRA markup in comment text. (This is handy for tables of values explaining why something in the database is wrong.) Note that comments are all created by the user you used to create your JIRA::Client::Automated object, so you'll see that name often. +You may use any valid JIRA markup in comment text. (This is handy for tables of +values explaining why something in the database is wrong.) Note that comments +are all created by the user you used to create your JIRA::Client::Automated +object, so you'll see that name often. =cut @@ -490,26 +723,26 @@ Content_Type => 'application/json', Content => $comment_json; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error creating new JIRA comment for $key : $text " . $response->status_line(); - } + my $response = $self->_perform_request($request); my $new_comment = $self->{_json}->decode($response->decoded_content()); return $new_comment; } + =head2 search_issues - my @search_results = $jira->search_issues($jql, 1, 100); + my @search_results = $jira->search_issues($jql, 1, 100, $fields); -You've used JQL before, when you did an "Advanced Search" in the JIRA web interface. That's the only way to search via the REST API. +You've used JQL before, when you did an "Advanced Search" in the JIRA web +interface. That's the only way to search via the REST API. -This is a paged method. Pass in the starting result number and number of results per page and it will return issues a page at a time. If you know you want all of the results, you can use L instead. +This is a paged method. Pass in the starting result number and number of +results per page and it will return issues a page at a time. If you know you +want all of the results, you can use L instead. + +Optional parameter $fields is the arrayref containing the list of fields to be returned. This method returns a hashref containing up to five values: @@ -560,13 +793,14 @@ # Note: if $max is > 1000 (set by jira.search.views.default.max in # http://jira.example.com/secure/admin/ViewSystemInfo.jspa) then it'll be truncated to 1000 anyway. sub search_issues { - my ($self, $jql, $start, $max) = @_; + my ($self, $jql, $start, $max, $fields) = @_; + $fields ||= ['*navigable']; my $query = { jql => $jql, startAt => $start, maxResults => $max, - fields => ['*navigable'], + fields => $fields, }; my $query_json = $self->{_json}->encode($query); @@ -576,22 +810,20 @@ Content_Type => 'application/json', Content => $query_json; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); + my $response = $self->_perform_request($request, { + 400 => sub { # pass-thru 400 responses for us to deal with below + my ($response, $request, $self) = @_; + return $response; + }, + }); - if (!$response->is_success()) { - if ($response->code() == 400) { - my $error_msg = $self->{_json}->decode($response->decoded_content()); - return { total => 0, errors => $error_msg->{errorMessages} }; - } else { - die "Error searching for $jql from $start for $max results " . $response->status_line(); - } + if ($response->code == 400) { + my $error_msg = $self->{_json}->decode($response->decoded_content()); + return { total => 0, errors => $error_msg->{errorMessages} }; } my $results = $self->{_json}->decode($response->decoded_content()); - # TODO: make this return a hash labeling the metadata instead of just a list. return { total => $$results{total}, start => $$results{startAt}, @@ -599,11 +831,15 @@ issues => $$results{issues} }; } + =head2 all_search_results my @issues = $jira->all_search_results($jql, 1000); -Like L, but returns all the results as an array of issues. You can specify the maximum number to return, but no matter what, it can't return more than the value of jira.search.views.default.max for your JIRA installation. +Like L, but returns all the results as an array of issues. +You can specify the maximum number to return, but no matter what, it can't +return more than the value of jira.search.views.default.max for your JIRA +installation. =cut @@ -611,7 +847,7 @@ my ($self, $jql, $max) = @_; my $start = 0; - $max //= 100; # is a param for testing + $max //= 100; # is a param for testing ; // is incompatible with perl <= 5.8 my $total = 0; my (@all_results, @issues, $results); @@ -628,13 +864,35 @@ return @all_results; } +=head2 get_issue_comments + + $jira->get_issue_comments($key); + +Returns arryref of all comments to the given issue. + +=cut + +sub get_issue_comments { + my ($self, $key) = @_; + my $uri = "$self->{auth_url}issue/$key/comment"; + my $request = GET $uri; + my $response = $self->_perform_request($request); + my $content = $self->{_json}->decode($response->decoded_content()); + + # dereference to get just the comments arrayref + my $comments = $content->{comments}; + return $comments; +} + =head2 attach_file_to_issue $jira->attach_file_to_issue($key, $filename); -This method does not let you attach a comment to the issue at the same time. You'll need to call L for that. +This method does not let you attach a comment to the issue at the same time. +You'll need to call L for that. -Watch out for file permissions! If the user running the script does not have permission to read the file it is trying to upload, you'll get weird errors. +Watch out for file permissions! If the user running the script does not have +permission to read the file it is trying to upload, you'll get weird errors. =cut @@ -648,24 +906,23 @@ 'X-Atlassian-Token' => 'nocheck', # required by JIRA XSRF protection Content => [file => [$filename],]; - $request->authorization_basic($self->{user}, $self->{password}); - - my $response = $self->{_ua}->request($request); - - if (!$response->is_success()) { - die "Error attaching $filename to JIRA issue $key: " . $response->status_line(); - } + my $response = $self->_perform_request($request); my $new_attachment = $self->{_json}->decode($response->decoded_content()); return $new_attachment; } + =head2 make_browse_url my $url = $jira->make_browse_url($key); -A helper method to make emails containing lists of bugs easier to use. This just appends the key to the URL for the JIRA server so that you can click on it and go directly to that issue. +A helper method to return the "C<.../browse/$key>" url for the issue. +It's handy to make emails containing lists of bugs easier to create. + +This just appends the key to the URL for the JIRA server so that you can click +on it and go directly to that issue. =cut @@ -675,11 +932,168 @@ return $self->{url} . 'browse/' . $key; } +=head2 get_link_types + + my $all_link_types = $jira->get_link_types(); + +Get the arrayref of all possible link types. + +=cut + +sub get_link_types { + my ($self) = @_; + + my $uri = "$self->{auth_url}issueLinkType"; + my $request = GET $uri; + my $response = $self->_perform_request($request); + + # dereference to arrayref, for convenience later + my $content = $self->{_json}->decode($response->decoded_content()); + my $link_types = $content->{issueLinkTypes}; + + return $link_types; +} + +=head2 link_issues + + $jira->link_issues($from, $to, $type); + +Establish a link of the type named $type from issue key $from to issue key $to . +Returns nothing on success; structure containing error messages otherwise. + +=cut + + +sub link_issues { + my ($self, $from, $to, $type) = @_; + + my $uri = "$self->{auth_url}issueLink/"; + my $link = { + inwardIssue => { key => $to }, + outwardIssue => { key => $from }, + type => { name => $type }, + }; + + my $link_json = $self->{_json}->encode($link); + + my $request = POST $uri, + Content_Type => 'application/json', + Content => $link_json; + + my $response = $self->_perform_request($request); + + if($response->code != 201) { + return $self->{_json}->decode($response->decoded_content()); + } + return; +} + +=head2 add_issue_labels + + $jira->add_issue_labels($issue_key, @labels); + +Adds one more more labels to the specified issue. + +=cut + + +sub add_issue_labels { + my ($self, $issue_key, @labels) = @_; + $self->update_issue($issue_key, {}, { labels => [ map {{ add => $_ }} @labels ] } ); +} + +=head2 remove_issue_labels + + $jira->remove_issue_labels($issue_key, @labels); + +Removes one more more labels from the specified issue. + +=cut + +sub remove_issue_labels { + my ($self, $issue_key, @labels) = @_; + $self->update_issue($issue_key, {}, { labels => [ map {{ remove => $_ }} @labels ] } ); +} + +=head2 add_issue_watchers + + $jira->add_issue_watchers($key, @watchers); + +Adds watchers to the specified issue. Returns nothing if success; otherwise returns a structure containing error message. + +=cut + +sub add_issue_watchers { + my ($self, $key, @watchers) = @_; + my $uri = "$self->{auth_url}issue/$key/watchers"; + foreach my $w (@watchers) { + my $request = POST $uri, + Content_Type => 'application/json', + Content => $self->{_json}->encode($w); + my $response = $self->_perform_request($request); + if($response->code != 204) { + return $self->{_json}->decode($response->decoded_content()); + } + } + return; +} + +=head2 get_issue_watchers + + $jira->get_issue_watchers($key); + +Returns arryref of all watchers of the given issue. + +=cut + +sub get_issue_watchers { + my ($self, $key) = @_; + my $uri = "$self->{auth_url}issue/$key/watchers"; + my $request = GET $uri; + my $response = $self->_perform_request($request); + my $content = $self->{_json}->decode($response->decoded_content()); + + # dereference to get just the watchers arrayref + my $watchers = $content->{watchers}; + return $watchers; +} + +=head2 assign_issue + + $jira->assign_issue($key, $assignee_name); + +Assigns the issue to that person. Returns the key of the issue if it succeeds. + +=cut + +sub assign_issue { + my ($self, $key, $assignee_name) = @_; + + my $assignee = {}; + $assignee->{name} = $assignee_name; + + my $issue_json = $self->{_json}->encode($assignee); + my $uri = "$self->{auth_url}issue/$key/assignee"; + + my $request = PUT $uri, + Content_Type => 'application/json', + Content => $issue_json; + + my $response = $self->_perform_request($request); + + return $key; +} + =head1 FAQ =head2 Why is there no object for a JIRA issue? -Because it seemed silly. You I write such an object and give it methods to transition itself, close itself, etc., but when you are working with JIRA from batch scripts, you're never really working with just one issue at a time. And when you have a hundred of them, it's easier to not objectify them and just use JIRA::Client::Automated as a mediator. That said, if this is important to you, I wouldn't say no to a patch offering this option. +Because it seemed silly. You I write such an object and give it methods +to transition itself, close itself, etc., but when you are working with JIRA +from batch scripts, you're never really working with just one issue at a time. +And when you have a hundred of them, it's easier to not objectify them and just +use JIRA::Client::Automated as a mediator. That said, if this is important to +you, I wouldn't say no to a patch offering this option. =head1 BUGS @@ -695,6 +1109,12 @@ =over 4 +=item Tim Bunce + +=back + +=over 4 + =item Dominique Dumont =back @@ -705,6 +1125,19 @@ =back +=over 4 + +=item Ivan E. Panchenko + +=back + +=encoding utf8 + +=over 4 + +=item José Antonio Perez Testa + +=back =head1 COPYRIGHT AND LICENSE diff -Nru libjira-client-automated-perl-1.05/LICENSE libjira-client-automated-perl-1.30/LICENSE --- libjira-client-automated-perl-1.05/LICENSE 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/LICENSE 2015-04-27 04:46:22.000000000 +0000 @@ -1,4 +1,4 @@ -This software is copyright (c) 2014 by Polyvore, Inc. . +This software is copyright (c) 2015 by Polyvore, Inc. . This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. @@ -12,7 +12,7 @@ --- The GNU General Public License, Version 1, February 1989 --- -This software is Copyright (c) 2014 by Polyvore, Inc. . +This software is Copyright (c) 2015 by Polyvore, Inc. . This is free software, licensed under: @@ -272,7 +272,7 @@ --- The Artistic License 1.0 --- -This software is Copyright (c) 2014 by Polyvore, Inc. . +This software is Copyright (c) 2015 by Polyvore, Inc. . This is free software, licensed under: diff -Nru libjira-client-automated-perl-1.05/Makefile.PL libjira-client-automated-perl-1.30/Makefile.PL --- libjira-client-automated-perl-1.05/Makefile.PL 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/Makefile.PL 2015-04-27 04:46:22.000000000 +0000 @@ -21,6 +21,7 @@ "LICENSE" => "perl", "NAME" => "JIRA::Client::Automated", "PREREQ_PM" => { + "Carp" => 0, "HTTP::Request" => 0, "HTTP::Request::Common" => 0, "JSON" => 0, @@ -35,7 +36,7 @@ "Test::Exception" => 0, "Test::More" => 0 }, - "VERSION" => "1.05", + "VERSION" => "1.3", "test" => { "TESTS" => "t/*.t" } @@ -43,6 +44,7 @@ my %FallbackPrereqs = ( + "Carp" => 0, "File::Spec" => 0, "File::Temp" => 0, "HTTP::Request" => 0, diff -Nru libjira-client-automated-perl-1.05/META.yml libjira-client-automated-perl-1.30/META.yml --- libjira-client-automated-perl-1.05/META.yml 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/META.yml 2015-04-27 04:46:22.000000000 +0000 @@ -19,8 +19,9 @@ provides: JIRA::Client::Automated: file: lib/JIRA/Client/Automated.pm - version: '1.05' + version: '1.3' requires: + Carp: '0' HTTP::Request: '0' HTTP::Request::Common: '0' JSON: '0' @@ -29,4 +30,4 @@ perl: '5.010' strict: '0' warnings: '0' -version: '1.05' +version: '1.3' diff -Nru libjira-client-automated-perl-1.05/README libjira-client-automated-perl-1.30/README --- libjira-client-automated-perl-1.05/README 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/README 2015-04-27 04:46:22.000000000 +0000 @@ -4,7 +4,7 @@ VERSION - version 1.05 + version 1.3 SYNOPSIS @@ -14,6 +14,8 @@ my $jira_ua = $jira->ua(); # to add in a proxy + $jira->trace(1); # enable tracing of requests and responses + # The simplest way to create an issue my $issue = $jira->create_issue($project, $type, $summary, $description); @@ -41,6 +43,7 @@ my $search_results = $jira->search_issues($jql, 1, 100); # query should be a single string of JQL my @issues = $jira->all_search_results($jql, 1000); # query should be a single string of JQL + my $issue = $jira->get_issue($key); $jira->update_issue($key, $update_hash); # update_hash is { field => value, ... } @@ -49,8 +52,11 @@ $jira->transition_issue($key, $transition, $transition_hash); # transition_hash is { field => value, ... } - $jira->close_issue($key, $resolve, $message); # resolve is the resolution value + $jira->close_issue($key, $resolve, $comment); # resolve is the resolution value $jira->delete_issue($key); + + $jira->add_issue_watchers($key, $watcher1, ......); + $jira->add_issue_labels($key, $label1, ......); DESCRIPTION @@ -94,16 +100,17 @@ JIRA::Client::Automated tries to be nice to you and not make you deal directly with JSON. When you create a new issue, you can pass in just the pieces you want and "create_issue" will transform them to JSON for - you. The same for closing and deleting issues. However there's not much - I can do about updating or transitioning issues. Each JIRA installation - will have different fields available for each issue type and transition - screen and only you will know what they are. So in those cases you'll - need to pass in an "update_hash" which will be transformed to the - proper JSON by the method. + you. The same for closing and deleting issues. + + Updating and transitioning issues is more complex. Each JIRA + installation will have different fields available for each issue type + and transition screen and only you will know what they are. So in those + cases you'll need to pass in an "update_hash" which will be transformed + to the proper JSON by the method. An update_hash looks like this: - { field => value, field2 => value2, ...} + { field1 => value, field2 => value2, ...} For example: @@ -120,9 +127,9 @@ helpfully translate it to and from regular hashes for you. You only pass hashes to JIRA::Client::Automated, not direct JSON. - But, since you aren't going to read the documentation, I recommend - connecting to your JIRA server and calling "get_issue" with a key you - know exists and then dump the result. That'll get you started. + I recommend connecting to your JIRA server and calling "get_issue" with + a key you know exists and then dump the result. That'll get you + started. METHODS @@ -140,8 +147,8 @@ 3. Password for that user All three parameters are required. JIRA::Client::Automated must connect - to the JIRA instance using some username and password. I recommend - setting up a special "auto" or "batch" username to use just for use by + to the JIRA instance using some username and password. You may want to + set up a special "auto" or "batch" username to use just for use by scripts. If you are using Google Account integration, the username and password @@ -151,13 +158,24 @@ ua - my $jira_ua = $jira->ua(); + my $ua = $jira->ua(); Returns the LWP::UserAgent object used to connect to the JIRA instance. Typically used to setup proxies or make other customizations to the UserAgent. For example: - $jira->ua()->env_proxy(); + my $ua = $jira->ua(); + $ua->env_proxy(); + $ua->ssl_opts(...); + $ua->conn_cache( LWP::ConnCache->new() ); + + trace + + $jira->trace(1); # enable + $jira->trace(0); # disable + $trace = $jira->trace; + + When tracing is enabled each request and response is logged using carp. create @@ -179,22 +197,36 @@ Creating a new issue, story, task, subtask, etc. - Returns a hash containing the information about the new issue or dies - if there is an error. See "JIRA ISSUE HASH FORMAT" for details of the - hash. + Returns a hash containing only the basic information about the new + issue, or dies if there is an error. The hash looks like: + + { + id => 24066, + key => "TEST-57", + self => "https://example.atlassian.net/rest/api/latest/issue/24066" + } + + See also + https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+- + +Create+Issue create_issue - my $issue = $jira->create_issue($project, $type, $summary, $description); + my $issue = $jira->create_issue($project, $type, $summary, $description, $fields); Creating a new issue requires the project key, type ("Bug", "Task", - etc.), and a summary and description. Other fields that are on the new - issue form could be supported by a subclass, but it's probably easier - to use "update_issue" with JIRA's syntax for now. - - Returns a hash containing the information about the new issue or dies - if there is an error. See "JIRA ISSUE HASH FORMAT" for details of the - hash. + etc.), and a summary and description. + + The optional $fields parameter can be used to pass a reference to a + hash of extra fields to be set when the issue is created, which avoids + the need for a separate "update_issue" call. For example: + + $jira->create_issue($project, $type, $summary, $description, { + labels => [ "foo", "bar" ] + }); + + This method calls "create" and return the same hash reference that it + does. create_subtask @@ -206,51 +238,122 @@ "Sub-task" or "sub-task", then you will need to pass in your subtask type. - Returns a hash containing the information about the new issue or dies - if there is an error. See "JIRA ISSUE HASH FORMAT" for details of the - hash. + This method calls "create" and return the same hash reference that it + does. update_issue - $jira->update_issue($key, $update_hash); + $jira->update_issue($key, $field_update_hash, $update_verb_hash); + + There are two ways to express the updates you want to make to an issue. + + For simple changes you pass $field_update_hash as a reference to a hash + of field_name => new_value pairs. For example: - Updating an issue is one place where JIRA's REST API shows through. You - pass in the issue key and update_hash with only the field changes you - want in it. See "JIRA ISSUE HASH FORMAT", above, for details about the - format of the update_hash. + $jira->update_issue($key, { summary => $new_summary }); + + That works for simple fields, but there are some, like comments, that + can't be updated in this way. For them you need to use + $update_verb_hash. + + The $update_verb_hash parameter allow you to express a series of + specific operations (verbs) to be performed on each field. For example: + + $jira->update_issue($key, undef, { + labels => [ { remove => "test" }, { add => "another" } ], + comments => [ { remove => { id => 10001 } } ] + }); + + The two forms of update can be combined in a single call. + + For more information see: + + https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Edit+issues + https://developer.atlassian.com/display/JIRADEV/Updating+an+Issue+via+the+JIRA+REST+APIs get_issue my $issue = $jira->get_issue($key); - You can get the details for any issue, given its key. This call returns - a hash containing the information for the issue in JIRA's format. See - "JIRA ISSUE HASH FORMAT" for details. + Returns details for any issue, given its key. This call returns a hash + containing the information for the issue in JIRA's format. See "JIRA + ISSUE HASH FORMAT" for details. transition_issue + $jira->transition_issue($key, $transition); $jira->transition_issue($key, $transition, $update_hash); Transitioning an issue is what happens when you click the button that says "Resolve Issue" or "Start Progress" on it. Doing this from code is - harder, but JIRA::Client::Automated makes it as easy as possible. You - pass this method the issue key, the name of the transition (spacing and - capitalization matter), and an optional update_hash containing any - fields on the transition screen that you want to update. + harder, but JIRA::Client::Automated makes it as easy as possible. + + You pass this method the issue key, the name of the transition or the + target status (spacing and capitalization matter), and an optional + update_hash containing any fields that you want to update. + + Specifying The Transition + + The provided $transition name is first matched against the available + transitions for the $key issue ('Start Progress', 'Close Issue'). If + there's no match then the names is matched against the available target + status names ('Open', 'Closed'). You can use whichever is most + appropriate. For example, in your configuration the transition names + might vary between different kinds of projects but the status names + might be the same. In which case scripts that are meant to work across + multiple projects might prefer to use the status names. + + The $transition parameter can also be specified as a reference to an + array of names. In this case the first one that matches either a + transition name or status name is used. This makes it easier for + scripts to work across multiple kinds of projects and/or handle the + migration of names by allowing current and future names to be used, so + the later change in JIRA config doesn't cause any breakage. + + Specifying Updates If you have required fields on the transition screen (such as "Resolution" for the "Resolve Issue" screen), you must pass those fields in as part of the update_hash or you will get an error from the server. See "JIRA ISSUE HASH FORMAT" for the format of the update_hash. + (Note: it appears that in some obscure cases missing required fields + may cause the transition to fail without causing an error from the + server. For example a field that's required but isn't configured to + appear on the transition screen.) + + The $update_hash is a combination of the $field_update_hash and + $update_verb_hash parameters used by the "update_issue" method. Like + this: + + $update_hash = { + fields => $field_update_hash, + update => $update_verb_hash + }; + + You can use it to express both simple field settings and more complex + update operations. For example: + + $jira->transition_issue($key, $transition, { + fields => { summary => $new_summary }, + update => { + labels => [ { remove => "test" }, { add => "another" } ], + comments => [ { remove => { id => 10001 } } ] + } + }); + close_issue - $jira->close_issue($key, $resolve, $message); + $jira->close_issue($key); + $jira->close_issue($key, $resolve); + $jira->close_issue($key, $resolve, $comment); + $jira->close_issue($key, $resolve, $comment, $update_hash); + $jira->close_issue($key, $resolve, $comment, $update_hash, $operation); Pass in the resolution reason and an optional comment to close an issue. Using this method requires that the issue is is a status where - it can use the "Close Issue" transition. If not, you will get an error - from the server. + it can use the "Close Issue" transition (or other one, specified by + $operation). If not, you will get an error from the server. Resolution ("Fixed", "Won't Fix", etc.) is only required if the issue hasn't already been resolved in an earlier transition. If you try to @@ -259,9 +362,18 @@ If you do not supply a comment, the default value is "Issue closed by script". - If your JIRA installation has extra required fields on the "Close - Issue" screen then you'll want to use the more generic - "transition_issue" call instead. + The $update_hash can be used to set or edit the values of other fields. + + The $operation paramter can be used to specify the closing transition + type. This can be useful when your JIRA configuration uses nonstandard + or localized transition and status names, e.g. + + use utf8; + $jira->close_issue($key, $resolve, $comment, $update_hash, "Done"); + + See "transition_issue" for more details. + + This method is a wrapper for "transition_issue". delete_issue @@ -282,7 +394,7 @@ search_issues - my @search_results = $jira->search_issues($jql, 1, 100); + my @search_results = $jira->search_issues($jql, 1, 100, $fields); You've used JQL before, when you did an "Advanced Search" in the JIRA web interface. That's the only way to search via the REST API. @@ -292,6 +404,9 @@ know you want all of the results, you can use "all_search_results" instead. + Optional parameter $fields is the arrayref containing the list of + fields to be returned. + This method returns a hashref containing up to five values: 1. total => total number of results @@ -328,6 +443,12 @@ what, it can't return more than the value of jira.search.views.default.max for your JIRA installation. + get_issue_comments + + $jira->get_issue_comments($key); + + Returns arryref of all comments to the given issue. + attach_file_to_issue $jira->attach_file_to_issue($key, $filename); @@ -343,10 +464,58 @@ my $url = $jira->make_browse_url($key); - A helper method to make emails containing lists of bugs easier to use. + A helper method to return the ".../browse/$key" url for the issue. It's + handy to make emails containing lists of bugs easier to create. + This just appends the key to the URL for the JIRA server so that you can click on it and go directly to that issue. + get_link_types + + my $all_link_types = $jira->get_link_types(); + + Get the arrayref of all possible link types. + + link_issues + + $jira->link_issues($from, $to, $type); + + Establish a link of the type named $type from issue key $from to issue + key $to . Returns nothing on success; structure containing error + messages otherwise. + + add_issue_labels + + $jira->add_issue_labels($issue_key, @labels); + + Adds one more more labels to the specified issue. + + remove_issue_labels + + $jira->remove_issue_labels($issue_key, @labels); + + Removes one more more labels from the specified issue. + + add_issue_watchers + + $jira->add_issue_watchers($key, @watchers); + + Adds watchers to the specified issue. Returns nothing if success; + otherwise returns a structure containing error message. + + get_issue_watchers + + $jira->get_issue_watchers($key); + + Returns arryref of all watchers of the given issue. + + assign_issue + + $jira->assign_issue($key, $assignee_name); + + Assigns the issue to that person. Returns the key of the issue if it + succeeds. + FAQ Why is there no object for a JIRA issue? @@ -371,10 +540,16 @@ Thanks very much to: + Tim Bunce + Dominique Dumont Zhuang (John) Li <7humblerocks@gmail.com> + Ivan E. Panchenko + + José Antonio Perez Testa + COPYRIGHT AND LICENSE This software is copyright (c) 2014 by Polyvore, Inc. diff -Nru libjira-client-automated-perl-1.05/t/jira-client-automated.t libjira-client-automated-perl-1.30/t/jira-client-automated.t --- libjira-client-automated-perl-1.05/t/jira-client-automated.t 2014-04-01 02:24:31.000000000 +0000 +++ libjira-client-automated-perl-1.30/t/jira-client-automated.t 2015-04-27 04:46:22.000000000 +0000 @@ -13,14 +13,14 @@ } # Set JIRA access information in ENV vars or pass it to the test. -my $jira_server = $ENV{JIRA_CLIENT_AUTOMATED_URL} || $ARGV[0]; -my $jira_project = $ENV{JIRA_CLIENT_AUTOMATED_PROJECT} || $ARGV[1]; -my $jira_user = $ENV{JIRA_CLIENT_AUTOMATED_USER} || $ARGV[2]; +my $jira_server = $ENV{JIRA_CLIENT_AUTOMATED_URL} || $ARGV[0]; +my $jira_project = $ENV{JIRA_CLIENT_AUTOMATED_PROJECT} || $ARGV[1]; +my $jira_user = $ENV{JIRA_CLIENT_AUTOMATED_USER} || $ARGV[2]; my $jira_password = $ENV{JIRA_CLIENT_AUTOMATED_PASSWORD} || $ARGV[3]; SKIP: { -my $skip_text = <new($jira_server, $jira_user, $jira_password), 'new'); -isa_ok($jira, $JCA); - -# Create an issue -ok($issue = $jira->create_issue($jira_project, 'Bug', "$JCA Test Script", "Created by $JCA Test Script automatically."), 'create_issue'); -isa_ok($issue, 'HASH'); -ok($key = $issue->{key}, 'create_issue key'); -ok($issue = $jira->get_issue($key), 'get_issue'); -is($issue->{fields}{summary}, "$JCA Test Script", 'create_issue summary'); -is($issue->{fields}{description}, "Created by $JCA Test Script automatically.", 'create_issue description'); - -# Comment on an issue -ok($jira->create_comment($key, "Comment from $JCA Test Script."), 'create_comment'); -ok($issue = $jira->get_issue($key), 'get_issue to see comment'); -is($issue->{fields}{comment}{comments}[0]{body}, "Comment from $JCA Test Script.", 'create_comment worked'); - -# Update an issue -ok($jira->update_issue($key, {summary => "$JCA updated"}), 'update_issue'); -ok($issue = $jira->get_issue($key), 'get_issue to see update'); -is($issue->{fields}{summary}, "$JCA updated", 'update_issue summary'); - -# Attach a file to an issue -my $tmp = File::Temp->new(); -print $tmp "Attach this file to $JCA test issue $key.\n"; -close $tmp; -my $filepath = $tmp->filename(); -my ($volume, $directories, $filename) = File::Spec->splitpath( $filepath ); - -ok($jira->attach_file_to_issue($key, $tmp->filename()), 'attach_file_to_issue'); -ok($issue = $jira->get_issue($key), 'get_issue to see attachment'); -is($issue->{fields}{attachment}[0]{filename}, $filename, 'attach_file_to_issue attachment'); -undef $tmp; # File::Temp unlinks the file when it goes out of scope - -# Transition an issue through its workflow -ok($jira->transition_issue($key, 'Start Progress'), 'transition_issue'); -ok($issue = $jira->get_issue($key), 'get_issue to see transition'); -is($issue->{fields}{status}{name}, 'In Progress', 'transition_issue status'); - -# Search for issues -# complicated queries work too: -# my $jql -# = 'project = ' -# . $self->{_jira_project} -# . ' AND resolution in (Fixed, "Won\'t Fix", Duplicate, Incomplete, "Cannot Reproduce") ' -# . 'AND issuetype = "Broken Crawler" ' -# . 'AND status in (Verify, "Copy Crawler to Polyvore") ' -# . 'AND reporter in (pv_eng) ' -# . 'ORDER BY createdDate DESC'; -my $jql = "KEY = $key"; -ok(@issues = $jira->all_search_results($jql, 10), 'all_search_results'); -is($issues[0]->{key}, $key, 'all_search_results found issue'); - -# Create a sub-task -my ($subtask, $sub_key); -ok($subtask = $jira->create_subtask($jira_project, "$JCA Test Subtask", "Created by $JCA Test Script automatically.", $issue->{key}), 'create_subtask'); -isa_ok($subtask, 'HASH'); -ok($sub_key = $subtask->{key}, 'create_subtask key'); -ok($subtask = $jira->get_issue($sub_key), 'get_issue subtask'); -is($subtask->{fields}{summary}, "$JCA Test Subtask", 'create_subtask summary'); -is($subtask->{fields}{description}, "Created by $JCA Test Script automatically.", 'create_subtask description'); -ok($jira->delete_issue($sub_key), 'delete_issue subtask'); - -ok($subtask = $jira->create_subtask($jira_project, "$JCA Test Subtask", "Created by $JCA Test Script automatically.", $issue->{key}, 'Sub-task'), 'create_subtask with type'); -isa_ok($subtask, 'HASH'); -ok($sub_key = $subtask->{key}, 'create_subtask with type key'); -ok($subtask = $jira->get_issue($sub_key), 'get_issue subtask with type'); -ok($jira->delete_issue($sub_key), 'delete_issue subtask'); - -# Close an issue -ok($jira->close_issue($key, 'Fixed', "Closed by $JCA Test Script"), 'close_issue'); -ok($issue = $jira->get_issue($key), 'get_issue to see closed'); -is($issue->{fields}{status}{name}, 'Closed', 'close_issue status'); - -# Delete our test issue -# You wouldn't want to do this in production; they're handy to keep around as documentation -ok($jira->delete_issue($key), 'delete_issue'); -throws_ok {@issues = $jira->all_search_results($jql, 10)} qr/does not exist/, 'all_search_results after delete'; + # Create new JCA object + ok($jira = JIRA::Client::Automated->new($jira_server, $jira_user, $jira_password), 'new'); + isa_ok($jira, $JCA); + + # --- read-only tests first + + # check search that returns no matches + @issues = $jira->all_search_results('createdDate = "1971-01-01"', 10); + is @issues, 0, 'all_search_results with no results'; + + @issues = $jira->all_search_results('KEY = NONESUCH-999999', 10); + is @issues, 0, 'all_search_results with invalid key'; + + # save link_types for later testing + ok($link_types = $jira->get_link_types(), 'get_link_types'); + cmp_ok( (grep { $_->{name} eq 'Blocks' } @$link_types), '>=', 1, 'has blocks link type'); + + # --- read-only tests first + + # Create an issue + $issue = $jira->create_issue( + $jira_project, 'Bug', + "$JCA Test Script", + "Created by $JCA Test Script automatically.", + { labels => ["Commentary"] }); + ok($issue, 'create_issue'); + isa_ok($issue, 'HASH'); + ok($key = $issue->{key}, 'create_issue key'); + ok($issue = $jira->get_issue($key), 'get_issue'); + is($issue->{fields}{summary}, "$JCA Test Script", 'create_issue summary'); + is($issue->{fields}{description}, "Created by $JCA Test Script automatically.", 'create_issue description'); + is($issue->{fields}{labels}[0], "Commentary", 'create_issue labels'); + + # Comment on an issue + my ($comments); + ok($jira->create_comment($key, "Comment from $JCA Test Script."), 'create_comment'); + ok($comments = $jira->get_issue_comments($key), 'get_issue_comments'); + is($comments->[0]{body}, "Comment from $JCA Test Script.", 'create_comment worked'); + + # Update an issue + ok($jira->update_issue($key, { summary => "$JCA updated" }), 'update_issue'); + ok($issue = $jira->get_issue($key), 'get_issue to see update'); + is($issue->{fields}{summary}, "$JCA updated", 'update_issue summary'); + + # Label an issue + ok($jira->add_issue_labels($key, 'testing'), 'add_issue_labels'); + ok($issue = $jira->get_issue($key), 'get_issue to see add_issue_labels'); + is(grep(m/^testing$/, @{$issue->{fields}{labels}}), 1, 'add_issue_labels worked'); + ok($jira->remove_issue_labels($key, 'testing'), 'remove_issue_labels'); + ok($issue = $jira->get_issue($key), 'get_issue to see remove_issue_labels'); + is(grep(m/^testing$/, @{$issue->{fields}{labels}}), 0, 'remove _issue_labels worked'); + + # Attach a file to an issue + my $tmp = File::Temp->new(); + print $tmp "Attach this file to $JCA test issue $key.\n"; + close $tmp; + my $filepath = $tmp->filename(); + my ($volume, $directories, $filename) = File::Spec->splitpath($filepath); + + ok($jira->attach_file_to_issue($key, $tmp->filename()), 'attach_file_to_issue'); + ok($issue = $jira->get_issue($key), 'get_issue to see attachment'); + is($issue->{fields}{attachment}[0]{filename}, $filename, 'attach_file_to_issue attachment'); + undef $tmp; # File::Temp unlinks the file when it goes out of scope + + # NOTE: these user-based tests may not do much, if your system auto-assigns + # issues to the creator, but they are at least testing the API calls. + # add watcher + my ($watchers); + is($jira->add_issue_watchers($key, $jira_user), undef, 'add_issue_watchers'); + ok($watchers = $jira->get_issue_watchers($key), 'get_issue_watchers'); + is($watchers->[0]{name}, $jira_user, 'added watcher'); + + # assign issue + ok($jira->assign_issue($key, $jira_user), 'assign_issue'); + ok($issue = $jira->get_issue($key), 'get_issue to see assignee'); + is($issue->{fields}{assignee}{name}, $jira_user, 'assigned issue'); + + # Transition tests + throws_ok { + $jira->transition_issue($key, 'NoneSuch Foo'); + } + qr/has no transition.*NoneSuch Foo/, 'transition_issue with unknown name'; + throws_ok { + $jira->transition_issue($key, ['NoneSuch Bar', 'NoneSuch Baz']); + } + qr/has no transition.*NoneSuch Bar.*NoneSuch Baz/, 'transition_issue with unknown names'; + + # Transition an issue through its workflow + my $transition_alternatives = ['Start Progress', 'Add to backlog', 'Open']; + my $prev_status_name = $issue->{fields}{status}{name}; + ok($jira->transition_issue($key, $transition_alternatives), 'transition_issue'); + ok($issue = $jira->get_issue($key), 'get_issue to see transition'); + isnt($issue->{fields}{status}{name}, + $prev_status_name, "transition_issue status (now $issue->{fields}{status}{name})"); + + # Search for issues + # complicated queries work too: + # my $jql + # = 'project = ' + # . $self->{_jira_project} + # . ' AND resolution in (Fixed, "Won\'t Fix", Duplicate, Incomplete, "Cannot Reproduce") ' + # . 'AND issuetype = "Broken Crawler" ' + # . 'AND status in (Verify, "Copy Crawler to Polyvore") ' + # . 'AND reporter in (pv_eng) ' + # . 'ORDER BY createdDate DESC'; + my $jql = "KEY = $key"; + ok(@issues = $jira->all_search_results($jql, 10), 'all_search_results'); + is($issues[0]->{key}, $key, 'all_search_results found issue'); + + # Create a sub-task + my ($subtask, $sub_key); + ok( $subtask = $jira->create_subtask( + $jira_project, + "$JCA Test Subtask", + "Created by $JCA Test Script automatically.", + $issue->{key} + ), + 'create_subtask' + ); + isa_ok($subtask, 'HASH'); + ok($sub_key = $subtask->{key}, 'create_subtask key'); + ok($subtask = $jira->get_issue($sub_key), 'get_issue subtask'); + is($subtask->{fields}{summary}, "$JCA Test Subtask", 'create_subtask summary'); + is($subtask->{fields}{description}, "Created by $JCA Test Script automatically.", 'create_subtask description'); + ok($jira->delete_issue($sub_key), 'delete_issue subtask'); + + ok( $subtask = $jira->create_subtask( + $jira_project, "$JCA Test Subtask", + "Created by $JCA Test Script automatically.", $issue->{key}, + 'Sub-task' + ), + 'create_subtask with type' + ); + isa_ok($subtask, 'HASH'); + ok($sub_key = $subtask->{key}, 'create_subtask with type key'); + ok($subtask = $jira->get_issue($sub_key), 'get_issue subtask with type'); + + # Link two issues + is($jira->link_issues($issue->{key}, $subtask->{key}, $link_types->[0]->{name}), undef, 'link_issues'); + ok($subtask = $jira->get_issue($sub_key), 'get_issue subtask to check link worked'); + my $issuelink = $subtask->{fields}{issuelinks}[0]; + is($issuelink->{type}{name}, $link_types->[0]->{name}, 'created correct type of link'); + is($issuelink->{outwardIssue}{key}, $issue->{key}, 'linked to correct issue'); + + # Delete sub-task + ok($jira->delete_issue($sub_key), 'delete_issue subtask'); + + # Close an issue + ok($jira->close_issue($key, 'Fixed', "Closed by $JCA Test Script"), 'close_issue'); + ok($issue = $jira->get_issue($key), 'get_issue to see closed'); + is($issue->{fields}{status}{name}, 'Closed', 'close_issue status'); + + # Delete our test issue + # You wouldn't want to do this in production; they're handy to keep around as documentation + # May fail with 403 Forbidden + ok($jira->delete_issue($key), 'delete_issue'); + throws_ok { @issues = $jira->all_search_results($jql, 10) } qr/does not exist/, 'all_search_results after delete'; } done_testing()