BZ-Client

 view release on metacpan or  search on metacpan

lib/BZ/Client/Bug/Attachment.pm  view on Meta::CPAN

If you specified an alias and there is no bug with that alias.

=item 101 - Invalid Bug ID

The C<bug_id> you specified doesn't exist in the database.

=item 102 - Access Denied

You do not have access to the C<bug_id> you specified.

=item 304 - Auth Failure, Attachment is Private

You specified the ID of a private attachment in the L</attachment_ids> argument, and you are not in the "insidergroup" that can see private attachments.

=back

=head2 add

This allows you to add an attachment to a bug in Bugzilla.

Actual Bugzilla API method is "add_attachment".

=head3 History

Added in Bugzilla 4.0.

The return value has changed in Bugzilla 4.4.

=head3 Parameters

An instance of this package or a hash containing:

=over 4

=item ids

I<ids> (array) Required - An array of ints and/or strings - the ID's or aliases of bugs that you want to add this attachment to. The same attachment and comment will be added to all these bugs.

=item data

I<data> (string or base64) Mostly Required - The content of the attachment.

The content will be base64 encoded. Of you can do it yourself by providing this option as a L<BZ::Client::XMPRPC::base64> object.

What is I<"Mostly Required"> you ask? If you provide L</file_name> only, this module will attempt to slurp it to provide this I<data> parameter. See L</file_name> options for more details.

=item file_name

I<file_name> (string) Required - The "file name" that will be displayed in the UI for this attachment.

If no I</data> parameter is provided, this module will attempt to open, slurp the contents of a file with path I<file_name>, base64 encod that data,  placed it into the I</data> parameter, then I<file_name> is truncted to just the files basename.

Failures to open the file (for anyreason) will be silently ignored and the I<file_name> parameter will not be touched.

=item summary

I<summary> (string) Required - A short string describing the attachment.

=item content_type

I<content_type> (string) Required - The MIME type of the attachment, like I<text/plain> or I<image/png>.

=item comment

I<comment> (string) - A comment to add along with this attachment.

=item is_patch

I<is_patch> (boolean) - True if Bugzilla should treat this attachment as a patch. If you specify this, you do not need to specify a L</content_type>. The L</content_type> of the attachment will be forced to C<text/plain>.

Defaults to False if not specified.

=item is_private

I<is_private> (boolean) - True if the attachment should be private (restricted to the "insidergroup"), False if the attachment should be public.

Defaults to False if not specified.

=item flags

An array of hashes with flags to add to the attachment. to create a flag, at least the C<status> and the C<type_id> or C<name> must be provided. An optional requestee can be passed if the flag type is requestable to a specific user.

=over 4

=item name

I<name> (string) - The name of the flag type.

=item type_id

I<type_id> (int) - THe internal flag type ID.

=item status

I<status> (string) - The flags new status  (i.e. "?", "+", "-" or "X" to clear a flag).

=item requestee

I<requestee> (string) - The login of the requestee if the flag type is requestable to a specific user.

=back

=back

=head3 Returns

An array of the attachment ID's created.

=head3 Errors

=over

=item 100 - Invalid Bug Alias

If you specified an alias and there is no bug with that alias.

=item 101 - Invalid Bug ID

The C<bug_id> you specified doesn't exist in the database.

=item 102 - Access Denied

lib/BZ/Client/Bug/Attachment.pm  view on Meta::CPAN

=item id

I<id> The ID of the bug to render the comment against.

=back

=head3 Returns

The HTML rendering

=head3 Errors

=over 4

=item 100 - Invalid Bug Alias

If you specified an alias and there is no bug with that alias.

=item 101 - Invalid Bug ID

The C<bug_id> you specified doesn't exist in the database.

=item 102 - Access Denied

You do not have access to the C<bug_id> you specified.

=back

=head2 update

This allows you to update attachment metadata in Bugzilla.

Actual Bugzilla API method is "update_attachments".

=head3 History

Added in Bugzilla 5.0.

=head3 Parameters

=over 4

=item ids

I<ids> (array) - An array that can contain both bug IDs and bug aliases. All of the attachments (that are visible to you) will be returned for the specified bugs.

=item file_name

I<file_name> (string) Required - The "file name" that will be displayed in the UI for this attachment.

=item summary

I<summary> (string) Required - A short string describing the attachment.

=item comment

I<comment> (string) - A comment to add along with this attachment.

=item content_type

I<content_type> (string) -  The MIME type of the attachment, like C<text/plain> or C<image/png>.

=item is_patch

I<is_patch> (boolean) - True if Bugzilla should treat this attachment as a patch. If you specify this, you do not need to specify a L</content_type>. The L</content_type> of the attachment will be forced to C<text/plain>.

=item is_private

I<is_private> (boolean) - True if the attachment should be private (restricted to the "insidergroup"), False if the attachment should be public.

=item is_obsolete

I<is_obsolete> (boolean) - True if the attachment is obsolete, False otherwise.

=item flags

An array of hashes with flags to add to the attachment. to create a flag, at least the status and the type_id or name must be provided. An optional requestee can be passed if the flag type is requestable to a specific user.

=over 4

=item name

I<name> (string) - The name of the flag type.

=item type_id

I<type_id> (int) - THe internal flag type id.

=item status

I<status> (string) - The flags new status  (i.e. "?", "+", "-" or "X" to clear a flag).

=item requestee

I<requestee> (string) - The login of the requestee if the flag type is requestable to a specific user.

=item id

I<id> (int) - Use C<id> to specify the flag to be updated. You will need to specify the C<id> if more than one flag is set of the same name.

=item new

I<new> (boolean) - Set to true if you specifically want a new flag to be created.

=back

=back

=head3 Returns

An array of hashes with the following fields:

=over 4

=item id

I<id> (int) The id of the attachment that was updated.

=item last_change_time

I<last_change_time> (L<DateTime>) - The exact time that this update was done at, for this attachment. If no update was done (that is, no fields had their values changed and no comment was added) then this will instead be the last time the attachment ...

lib/BZ/Client/Bug/Attachment.pm  view on Meta::CPAN

=item 603 - File Name Not Specified

You did not specify a valid for the L</file_name> argument.

=item 604 - Summary Required

You did not specify a value for the L</summary> argument.

=back

=head2 new

  my $comment = BZ::Client::Bug::Comment->new(
                                          id         => $bug_id,
                                          comment    => $comment,
                                          is_private => 1 || 0,
                                          work_time  => 3.5
                                        );

Creates a new instance with the given details. Doesn't actually touch your Bugzilla Server - see L</add> for that.

=head1 INSTANCE METHODS

This section lists the modules instance methods.

=head2 bug_id

I<bug_id> (int) - The ID of the bug that this attachment is on when reading

I<bug_id> (int or string) - The ID or alias of the bug to append a attachment to when writing. B<Required>.

=head2 data

I<data> (base64 or string) The content of the attachment.

When writing, either provide a string (which will be C<base46> encoded for you) or a L<BZ::Client::XMLRPC::base64> object if you'd like to DIY.

When reading, a L<BZ::Client::XMLRPC::base64> object will be returned. To save you the trip, this object has a C<raw()> and a C<base64()> method. Here is an example.

 my $data = $attachment->data();
 my $file_content_base64_encoded = $data->base64();
 my $original_file_content = $data->raw();

B<Required>, Read and Write.

=head2 file_name

I<file_name> (string) The "file name" that will be displayed in the UI for this attachment.

B<Required>, Read and Write.

=head2 summary

I<summary> (string) A short string describing the attachment.

B<Required>, Read and Write.

=head2 content_type

I<content_type> (string) The MIME type of the attachment, like C<text/plain> or C<image/png>.

B<Required>, Read and Write.

=head2 comment

I<comment> (string or hash) A comment to add along with this attachment. If C<comment> is a hash, it has the following keys:

Only useful when adding attachments.

=over 4

=item body

I<body> (string) The body of the comment.

=item is_markdown

I<is_markdown> (boolean) If set to true, the comment has Markdown structures; otherwise, it is an ordinary text.

=back

=head2 is_patch

I<is_patch> (boolean) True if the attachment should be private (restricted to the "insidergroup"), False if the attachment should be public.

=head2 is_private

I<is_private> (boolean) True if the attachment is private (only visible to a certain group called the "insidergroup"), False otherwise.

=head2 is_obsolete

I<is_obsolete> (boolean) - True if the attachment is obsolete, False otherwise.

=head2 flags

I<flags> (array) An array of hashes with flags to add to the attachment. to create a flag, at least the status and the type_id or name must be provided. An optional requestee can be passed if the flag type is requestable to a specific user.

Read and Write.

=over 4

=item id

I<id> (name) The ID of the flag.

=item name

I<name> (string) The name flag type.

Read and Write.

=item type_id

I<type_id> (int) The internal flag type ID.

Read and Write.

=item creation_date

I<creation_date> (L<DateTime>) The timestamp when this flag was originally created.