.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "JIRA::Client 3pm" .TH JIRA::Client 3pm "2014-08-09" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JIRA::Client \- Extended interface to JIRA's SOAP API .SH "VERSION" .IX Header "VERSION" version 0.42 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use JIRA::Client; \& \& my $jira = JIRA::Client\->new(\*(Aqhttp://jira.example.com/jira\*(Aq, \*(Aquser\*(Aq, \*(Aqpasswd\*(Aq); \& \& my $issue = $jira\->create_issue( \& { \& project => \*(AqTST\*(Aq, \& type => \*(AqBug\*(Aq, \& summary => \*(AqSummary of the bug\*(Aq, \& assignee => \*(Aqgustavo\*(Aq, \& components => [\*(Aqcompa\*(Aq, \*(Aqcompb\*(Aq], \& fixVersions => [\*(Aq1.0.1\*(Aq], \& custom_fields => {Language => \*(AqPerl\*(Aq, Architecture => \*(AqLinux\*(Aq}, \& } \& ); \& \& $issue = eval { $jira\->getIssue(\*(AqTST\-123\*(Aq) }; \& die "Can\*(Aqt getIssue(): $@" if $@; \& \& $jira\->set_filter_iterator(\*(Aqmy\-filter\*(Aq); \& while (my $issue = $jira\->next_issue()) { \& # ... \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1JIRA\s0 is a proprietary bug tracking system from Atlassian (). .PP \&\fB\s-1DEPRECATION WARNING\s0\fR: Please, before using this module consider using the newer \s-1JIRA::REST\s0 because \s-1JIRA\s0's \s-1SOAP API\s0 was deprecated on \s-1JIRA 6.0\s0 and won't be available anymore on \s-1JIRA 7.0.\s0 .PP This module implements an Object Oriented wrapper around \s-1JIRA\s0's \s-1SOAP API,\s0 which is specified in . (This version is known work against \s-1JIRA 4.4.\s0) .PP Moreover, it implements some other methods to make it easier to do some common operations. .SH "API METHODS" .IX Header "API METHODS" With the exception of the \s-1API \s0\f(CW\*(C`login\*(C'\fR and \f(CW\*(C`logout\*(C'\fR 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 \&\f(CW\*(C`token\*(C'\fR argument, because it is supplied transparently by the JIRA::Client object. .PP All methods fail by throwing exceptions (croaking, actually). You may want to guard against this by invoking them within an eval block, like this: .PP .Vb 2 \& my $issue = eval { $jira\->getIssue(\*(AqTST\-123\*(Aq) }; \& die "Can\*(Aqt getIssue(\*(AqTST\-123\*(Aq): $@" if $@; .Ve .PP Some of the \s-1API\s0 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 \s-1SOAP\s0 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. .PP 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 \s-1API\s0 method you can safely pass a value of the type specified second. .IP "A \fBissue key\fR as a string can be specified by a \fBRemoteIssue\fR object." 4 .IX Item "A issue key as a string can be specified by a RemoteIssue object." .PD 0 .IP "A \fBRemoteComment\fR object can be specified by a string." 4 .IX Item "A RemoteComment object can be specified by a string." .IP "A \fBfilterId\fR as a string can be specified by a \fBRemoteFilter\fR object." 4 .IX Item "A filterId as a string can be specified by a RemoteFilter object." .IP "A \fBRemoteFieldValue\fR object array can be specified by a hash mapping field names to values." 4 .IX Item "A RemoteFieldValue object array can be specified by a hash mapping field names to values." .PD .SH "EXTRA METHODS" .IX Header "EXTRA METHODS" This module implements some extra methods to add useful functionality to the \s-1API.\s0 They are described below. Note that their names don't follow the CamelCase convention used by the native \s-1API\s0 methods but the more Perlish underscore_separated_words convention so that you can distinguish them and we can avoid future name clashes. .SS "\fBnew\fP \s-1BASEURL, USER, PASSWD\s0 [, ]" .IX Subsection "new BASEURL, USER, PASSWD [, ]" \&\f(CW\*(C`BASEURL\*(C'\fR is the \s-1JIRA\s0 server's base \s-1URL \s0(e.g., \&\f(CW\*(C`https://jira.example.net\*(C'\fR or \f(CW\*(C`https://example.net/jira\*(C'\fR), to which the default \s-1WSDL\s0 descriptor path (\f(CW\*(C`/rpc/soap/jirasoapservice\-v2?wsdl\*(C'\fR) will be appended in order to construct the underlying SOAP::Lite object. .PP \&\f(CW\*(C`USER\*(C'\fR and \f(CW\*(C`PASSWD\*(C'\fR are the credentials that will be used to authenticate into \s-1JIRA.\s0 .PP Any other arguments will be passed to the SOAP::Lite object that will be created to talk to \s-1JIRA.\s0 .SS "\fBnew\fP \s-1HASH_REF\s0" .IX Subsection "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. .PP The valid hash keys are listed below. .IP "baseurl => \s-1STRING\s0" 4 .IX Item "baseurl => STRING" (Required) The \s-1JIRA\s0 server's base \s-1URL.\s0 .IP "wsdl => \s-1STRING\s0" 4 .IX Item "wsdl => STRING" (Optional) \s-1JIRA\s0's standard \s-1WSDL\s0 descriptor path is \&\f(CW\*(C`/rpc/soap/jirasoapservice\-v2?wsdl\*(C'\fR. If your \s-1JIRA\s0 instance has a non-standard path to the \s-1WSDL\s0 service, you may specify it here. .IP "user => \s-1STRING\s0" 4 .IX Item "user => STRING" (Required) The username to authenticate into \s-1JIRA.\s0 .IP "password => \s-1STRING\s0" 4 .IX Item "password => STRING" (Required) The password to authenticate into \s-1JIRA.\s0 .IP "soapargs => \s-1ARRAY_REF\s0" 4 .IX Item "soapargs => ARRAY_REF" (Optional) Extra arguments to be passed to the SOAP::Lite object that will be created to talk to \s-1JIRA.\s0 .SS "\fBcreate_issue\fP \s-1HASH_REF\s0 [, \s-1SECURITYLEVEL\s0]" .IX Subsection "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 \f(CW\*(C`project\*(C'\fR, \f(CW\*(C`summary\*(C'\fR, and \f(CW\*(C`type\*(C'\fR. .PP This is an easier to use version of the createIssue \s-1API\s0 method. For once it accepts symbolic values for some of the issue fields that the \&\s-1API\s0 method does not. Specifically: .ie n .IP """type"" can be specified by \fIname\fR instead of by \fIid\fR." 4 .el .IP "\f(CWtype\fR can be specified by \fIname\fR instead of by \fIid\fR." 4 .IX Item "type can be specified by name instead of by id." .PD 0 .ie n .IP """priority"" can be specified by \fIname\fR instead of by \fIid\fR." 4 .el .IP "\f(CWpriority\fR can be specified by \fIname\fR instead of by \fIid\fR." 4 .IX Item "priority can be specified by name instead of by id." .ie n .IP """component"" can be specified by a list of component \fInames\fR or \fIids\fR instead of a list of ""RemoteComponent"" objects." 4 .el .IP "\f(CWcomponent\fR can be specified by a list of component \fInames\fR or \fIids\fR instead of a list of \f(CWRemoteComponent\fR objects." 4 .IX Item "component can be specified by a list of component names or ids instead of a list of RemoteComponent objects." .ie n .IP """affectsVersions"" and ""fixVersions"" can be specified by a list of version \fInames\fR or \fIids\fR instead of a list of ""RemoteVersion"" objects." 4 .el .IP "\f(CWaffectsVersions\fR and \f(CWfixVersions\fR can be specified by a list of version \fInames\fR or \fIids\fR instead of a list of \f(CWRemoteVersion\fR objects." 4 .IX Item "affectsVersions and fixVersions can be specified by a list of version names or ids instead of a list of RemoteVersion objects." .ie n .IP """duedate"" can be specified by a DateTime object or by a string in \s-1ISO\s0 standard format (YYYY-MM-DD...). (Note that up to \s-1JIRA 4.3\s0 you could pass a string in the format ""d/MMM/yy"", which was passed as is to \s-1JIRA,\s0 which expected a \fBstring\fR \s-1SOAP\s0 type. However, since \s-1JIRA 4.4\s0 the server expects a \fBdate\fR \s-1SOAP\s0 type, which must be in the \s-1ISO\s0 standard format.)" 4 .el .IP "\f(CWduedate\fR can be specified by a DateTime object or by a string in \s-1ISO\s0 standard format (YYYY-MM-DD...). (Note that up to \s-1JIRA 4.3\s0 you could pass a string in the format ``d/MMM/yy'', which was passed as is to \s-1JIRA,\s0 which expected a \fBstring\fR \s-1SOAP\s0 type. However, since \s-1JIRA 4.4\s0 the server expects a \fBdate\fR \s-1SOAP\s0 type, which must be in the \s-1ISO\s0 standard format.)" 4 .IX Item "duedate can be specified by a DateTime object or by a string in ISO standard format (YYYY-MM-DD...). (Note that up to JIRA 4.3 you could pass a string in the format d/MMM/yy, which was passed as is to JIRA, which expected a string SOAP type. However, since JIRA 4.4 the server expects a date SOAP type, which must be in the ISO standard format.)" .PD .PP It accepts a 'magic' field called \fBparent\fR, which specifies the issue key from which the created issue must be a sub-task. .PP It accepts another 'magic' field called \fBcustom_fields\fR 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 \fBcustomfield_NNNNN\fR) 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. .PP A simple custom field value can be specified by a scalar, which will be properly placed inside an \s-1ARRAY\s0 in order to satisfy the \&\fBRemoteFieldValue\fR's structure. .PP Cascading select fields are properly specified like this: http://tinyurl.com/2bmthoa. The magic short-cut requires a \s-1HASH\s0 where each cascading level is indexed by its level number, starting at zero. So, instead of specifying it like this: .PP .Vb 8 \& { \& id => \*(Aqcustomfield_10011\*(Aq, \& values => [ SOAP::Data\->type(string => \*(Aq10031\*(Aq ) ] \& }, \& { \& id => \*(Aqcustomfield_10011:1\*(Aq, \& values => [ SOAP::Data\->type(string => \*(Aq10188\*(Aq) ], \& }, .Ve .PP You can do it like this: .PP .Vb 1 \& {customfield_10011 => {\*(Aq0\*(Aq => 10031, \*(Aq1\*(Aq => 10188}}, .Ve .PP Note that the original hash keys and values are completely preserved. .SS "\fBupdate_issue\fP \s-1ISSUE_OR_KEY, HASH_REF\s0" .IX Subsection "update_issue ISSUE_OR_KEY, HASH_REF" 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. .PP This is an easier to use version of the updateIssue \s-1API\s0 method because it accepts the same shortcuts that create_issue does. .SS "\fBget_issue_types\fP" .IX Subsection "get_issue_types" Returns a hash mapping the server's issue type names to the RemoteIssueType objects describing them. .SS "\fBget_subtask_issue_types\fP" .IX Subsection "get_subtask_issue_types" Returns a hash mapping the server's sub-task issue type names to the RemoteIssueType objects describing them. .SS "\fBget_statuses\fP" .IX Subsection "get_statuses" Returns a hash mapping the server's status names to the RemoteStatus objects describing them. .SS "\fBget_priorities\fP" .IX Subsection "get_priorities" Returns a hash mapping a server's priorities names to the RemotePriority objects describing them. .SS "\fBget_resolutions\fP" .IX Subsection "get_resolutions" Returns a hash mapping a server's resolution names to the RemoteResolution objects describing them. .SS "\fBget_security_levels\fP PROJECT-KEY" .IX Subsection "get_security_levels PROJECT-KEY" Returns a hash mapping a project's security level names to the RemoteSecurityLevel objects describing them. .SS "\fBget_custom_fields\fP" .IX Subsection "get_custom_fields" Returns a hash mapping \s-1JIRA\s0's custom field names to the RemoteField representing them. It's useful since when you get a RemoteIssue object from this \s-1API\s0 it doesn't contain the custom field's names, but just their identifiers. From the RemoteField object you can obtain the field's \fBid\fR, which is useful when calling the \fBupdateIssue\fR method. .PP The method calls the getCustomFields \s-1API\s0 method the first time and keeps the custom fields information in a cache. .SS "\fBset_custom_fields\fP \s-1HASHREF\s0" .IX Subsection "set_custom_fields HASHREF" Passes a hash mapping \s-1JIRA\s0'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 \s-1JIRA\s0 instance, since only administrators can call the \fBgetCustomFields\fR \&\s-1API\s0 method. .SS "\fBget_components\fP \s-1PROJECT_KEY\s0" .IX Subsection "get_components PROJECT_KEY" Returns a hash mapping a project's components names to the RemoteComponent objects describing them. .SS "\fBget_versions\fP \s-1PROJECT_KEY\s0" .IX Subsection "get_versions PROJECT_KEY" Returns a hash mapping a project's versions names to the RemoteVersion objects describing them. .SS "\fBget_favourite_filters\fP" .IX Subsection "get_favourite_filters" Returns a hash mapping the user's favourite filter names to its filter ids. .SS "\fBset_filter_iterator\fP \s-1FILTER\s0 [, \s-1CACHE_SIZE\s0]" .IX Subsection "set_filter_iterator FILTER [, CACHE_SIZE]" Sets up an iterator for the filter identified by \s-1FILTER.\s0 It must be called before calls to \fBnext_issue\fR. .PP \&\s-1FILTER\s0 can be either a filter \fIid\fR or a filter \fIname\fR, in which case it's converted to a filter id with a call to \f(CW\*(C`getSavedFilters\*(C'\fR. .PP \&\s-1CACHE_SIZE\s0 defines the number of issues that will be pre-fetched by \&\fBnect_issue\fR using \f(CW\*(C`getIssuesFromFilterWithLimit\*(C'\fR. If not specified, a suitable default will be used. .SS "\fBnext_issue\fP" .IX Subsection "next_issue" This must be called after a call to \fBset_filter_iterator\fR. Each call returns a reference to the next issue from the filter. When there are no more issues it returns undef. .SS "\fBprogress_workflow_action_safely\fP \s-1ISSUE, ACTION, PARAMS\s0" .IX Subsection "progress_workflow_action_safely ISSUE, ACTION, PARAMS" This is a safe and easier to use version of the \&\fBprogressWorkflowAction\fR \s-1API\s0 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 \s-1API\s0 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 \s-1JIRA \&\s0. .PP 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 \fBgetFieldsForAction\fR \s-1API\s0 method to grok all fields that are shown in the screen. If there is any field not set in the \s-1ACTION_PARAMS\s0 then it calls \fBgetIssue\fR to grok the missing fields current values. As a result it constructs the necessary RemoteFieldAction array that must be passed to progressWorkflowAction. .PP The method is also easier to use because its arguments are more flexible: .ie n .IP """ISSUE"" can be either an issue key or a RemoteIssue object returned by a previous call to, e.g., ""getIssue""." 4 .el .IP "\f(CWISSUE\fR can be either an issue key or a RemoteIssue object returned by a previous call to, e.g., \f(CWgetIssue\fR." 4 .IX Item "ISSUE can be either an issue key or a RemoteIssue object returned by a previous call to, e.g., getIssue." .PD 0 .ie n .IP """ACTION"" can be either an action \fIid\fR or an action \fIname\fR." 4 .el .IP "\f(CWACTION\fR can be either an action \fIid\fR or an action \fIname\fR." 4 .IX Item "ACTION can be either an action id or an action name." .ie n .IP """PARAMS"" must be a hash mapping field names to field values. This hash is treated in the same way as the hash passed to the function \fBcreate_issue\fR above." 4 .el .IP "\f(CWPARAMS\fR must be a hash mapping field names to field values. This hash is treated in the same way as the hash passed to the function \fBcreate_issue\fR above." 4 .IX Item "PARAMS must be a hash mapping field names to field values. This hash is treated in the same way as the hash passed to the function create_issue above." .PD .PP For example, instead of using this: .PP .Vb 5 \& my $action_id = somehow_grok_the_id_of(\*(Aqclose\*(Aq); \& $jira\->progressWorkflowAction(\*(AqPRJ\-5\*(Aq, $action_id, [ \& RemoteFieldValue\->new(2, \*(Aqnew value\*(Aq), \& ..., # all fields must be specified here \& ]); .Ve .PP And risking to forget to pass some field you can do this: .PP .Vb 1 \& $jira\->progress_workflow_action_safely(\*(AqPRJ\-5\*(Aq, \*(Aqclose\*(Aq, {2 => \*(Aqnew value\*(Aq}); .Ve .SS "\fBget_issue_custom_field_values\fP \s-1ISSUE,\s0 NAME_OR_IDs" .IX Subsection "get_issue_custom_field_values ISSUE, NAME_OR_IDs" 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 \s-1ISSUE\s0's custom fields denoted by their NAME_OR_IDs. Returns undef for custom fields not set on the issue. .PP In scalar context it returns a reference to the list. .SS "\fBattach_files_to_issue\fP \s-1ISSUE, FILES...\s0" .IX Subsection "attach_files_to_issue ISSUE, FILES..." This method attaches one or more files to an issue. The \s-1ISSUE\s0 argument may be an issue key or a \fBRemoteIssue\fR object. The attachments may be specified in two ways: .IP "\s-1STRING\s0" 4 .IX Item "STRING" A string denotes a filename to be open and read. In this case, the attachment name is the file's basename. .IP "\s-1HASHREF\s0" 4 .IX Item "HASHREF" When you want to specify a different name to the attachment or when you already have an \s-1IO\s0 object (a \s-1GLOB,\s0 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. .PP The method retuns the value returned by the \&\fBaddBase64EncodedAttachmentsToIssue\fR \s-1API\s0 method. .PP In the example below, we attach three files to the issue \s-1TST\-1.\s0 The first is called \f(CW\*(C`file1.txt\*(C'\fR and its contents are read from \&\f(CW\*(C`/path/to/file1.txt\*(C'\fR. The second is called \f(CW\*(C`text.txt\*(C'\fR and its contents are read from \f(CW\*(C`/path/to/file2.txt\*(C'\fR. the third is called \&\f(CW\*(C`me.jpg\*(C'\fR and its contents are read from the object refered to by \&\f(CW$fh\fR. .PP .Vb 7 \& $jira\->attach_files_to_issue(\*(AqTST\-1\*(Aq, \& \*(Aq/path/to/file1.txt\*(Aq, \& { \& \*(Aqtext.txt\*(Aq => \*(Aq/path/to/file2.txt\*(Aq, \& \*(Aqme.jpg\*(Aq => $fh, \& }, \& ); .Ve .SS "\fBattach_strings_to_issue\fP \s-1ISSUE, HASHREF\s0" .IX Subsection "attach_strings_to_issue ISSUE, HASHREF" This method attaches one or more strings to an issue. The \s-1ISSUE\s0 argument may be an issue key or a \fBRemoteIssue\fR object. The attachments are specified by a \s-1HASHREF\s0 in which the keys denote the file names and the values their contents. .PP The method retuns the value returned by the \&\fBaddBase64EncodedAttachmentsToIssue\fR \s-1API\s0 method. .SS "\fBfilter_issues_unsorted\fP \s-1FILTER\s0 [, \s-1LIMIT\s0]" .IX Subsection "filter_issues_unsorted FILTER [, LIMIT]" This method returns a list of RemoteIssue objects from the specified \&\s-1FILTER,\s0 which is a string that is understood in one of these ways (in order): .IP "A space-separated list of issue keys" 4 .IX Item "A space-separated list of issue keys" To specify issues explicitly by their keys, which must match /[A\-Z]+\-\ed+/i. The letters in the key are upcased before being passed to getIssue. For example: .Sp .Vb 1 \& KEY\-123 chave\-234 CLAVE\-345 .Ve .IP "The name of a saved filter" 4 .IX Item "The name of a saved filter" If \s-1FILTER\s0 is a single word, it is passed to getIssuesFromFilterWithLimit as a filter name. For example: .Sp .Vb 1 \& sprint\-backlok\-filter .Ve .IP "A \s-1JQL\s0 expression" 4 .IX Item "A JQL expression" As a last resort, \s-1FILTER\s0 is passed to getIssuesFromJqlSearch as a \s-1JQL\s0 expression. For example: .Sp .Vb 1 \& project = CDS AND fixVersion = sprint\-5 .Ve .PP The optional \s-1LIMIT\s0 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 \s-1JIRA\s0 server configuration. .PP 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 \s-1FILTER\s0 argument before passing it to the method. .SS "\fBfilter_issues\fP \s-1FILTER\s0 [, \s-1LIMIT\s0]" .IX Subsection "filter_issues FILTER [, LIMIT]" This method invokes the \fBfilter_issues_unsorted\fR method with the same arguments and returns the list of RemoteIssue objects sorted by issue key. .SH "OTHER CONSTRUCTORS" .IX Header "OTHER CONSTRUCTORS" The \s-1JIRA SOAP API\s0 uses several types of objects (i.e., classes) for which the Perl \s-1SOAP\s0 interface does not provide the necessary constructors. This module implements some of them. .SS "\fBRemoteFieldValue\->new\fP \s-1ID, VALUES\s0" .IX Subsection "RemoteFieldValue->new ID, VALUES" The RemoteFieldValue object represents the value of a field of an issue. It needs two arguments: .IP "\s-1ID\s0" 4 .IX Item "ID" The field name, which must be a valid key for the \s-1ISSUE\s0 hash. .IP "\s-1VALUES\s0" 4 .IX Item "VALUES" A scalar or an array of scalars. .SS "\fBRemoteCustomFieldValue\->new\fP \s-1ID, VALUES\s0" .IX Subsection "RemoteCustomFieldValue->new ID, VALUES" The RemoteCustomFieldValue object represents the value of a custom_field of an issue. It needs two arguments: .IP "\s-1ID\s0" 4 .IX Item "ID" The field name, which must be a valid custom_field key. .IP "\s-1VALUES\s0" 4 .IX Item "VALUES" A scalar or an array of scalars. .SS "\fBRemoteComponent\->new\fP \s-1ID, NAME\s0" .IX Subsection "RemoteComponent->new ID, NAME" .SS "\fBRemoteVersion\->new\fP \s-1ID, NAME\s0" .IX Subsection "RemoteVersion->new ID, NAME" .SH "EXAMPLES" .IX Header "EXAMPLES" Please, see the examples under the \f(CW\*(C`examples\*(C'\fR directory in the module distribution. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \&\s-1JIRA::REST\s0 .SH "AUTHOR" .IX Header "AUTHOR" Gustavo L. de M. Chaves .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2014 by CPqD. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.