++ed by:

1 non-PAUSE user.

François Rappaz
and 1 contributors

NAME

WWW::Zotero::Write - Perl interface to the Zotero Write API

VERSION

Version 0.04

DESCRIPTION

This module use Zotero Write API to add, update, delete items, collections, tags or searches.

SYNOPSIS

      use Data::Dumper;
      use WWW::Zotero::Write;
      #key is the zotero key for the library
      my $client = WWW::Zotero::Write->new(key => 'Inlfxd ... ');

       #@collections is an array of hash ref {name => $collection_name, 
       #                                      parentCollection => $parent_collection_key}

        my ( $ok, $same, $failed ) =
            $client->addCollections( \@collections, group => $groupid );

        unless ($ok) {
           print Dumper ($same), "\n", Dumper($failed), "\n";
           die "Collection not added";
         }
        my @keys;
        for my $c ( sort { $a <=> $b } keys %$ok ) {
            push @keys, $ok->{$c};
         }

         # $keys[ $pos ] contains the key of $items[ $pos ]

       # %data is a hash of fields => values pairs.
       # fields are  key (mandatory), name, parentCollection, relations

        my ( $ok, $same, $failed ) =
        $client->updateCollection( \%data, group => $groupid );

      # @keys is an array of collections zotero keys

        $client->deleteCollections( \@keys, group => $groupid )
            or die("Can't delete collections");


       # @modif is an array of hash ref
       #     { key  => $item_key,
       #        collections => $coll_ref,
       #        version     => $item_version
       #     }
       # $coll_ref is an array ref of collections keys the item belongs to

       my ( $ok, $same, $failed ) =
            $client->updateItems( \@modif, group => $groupid );
        unless ($ok) {
            print Dumper ($same), "\n", Dumper($failed), "\n";
            die "Items collections not modidified in Zotero";
        }

        # @itemkeys is an array of item zotero keys

        $client->deleteItems( \@itemkeys, group => $groupid ) or die("Can't delete items");

        my $template = $client->itemTemplate("book");
        $template->{titre} = "Hello World";
        $template->{date} = "2017";
        # ...

        push @items, $template;
        # @items is an array of hash ref of new data (templates completed with real values)

        my ( $ok, $same, $failed ) =
                $client->addItems( \@items, group => $groupid );
         unless ($ok) {
                print Dumper ($same), "\n", Dumper($failed), "\n";
                die "Items not added to Zotero";
        }
        my @keys;
        for my $c ( sort { $a <=> $b } keys %$ok ) {
            print $c, " ", $ok->{$c}, "\n";
            push @keys, $ok->{$c};
         }
         # $keys[ $pos ] contains the key of $items[ $pos ]

        #@v is an array of tags values
        $client->deleteTags(\@v, group=>$groupid) or die "Can't delete tags";

addCollections($coll_array_ref, user => $userid | group => $groupid)

Add an array of collection.

Param: the array ref of hash ref with collection name and parent key [{"name"=>"coll name", "parentCollection"=> "parent key"}, {}]

Param: the group or the user id

Returns undef if the ResponseCode is not 200 (409: Conflit, 412: Precondition failed)

Returns an array with three hash ref (or undef if the hash are empty): changed, unchanged, failed. The keys are the index of the hash received in argument. The values are the keys given by zotero

updateCollection ($data, group => $groupid | user => $userid)

Update an existing collection.

Param: hash ref of key value pairs. The zotero key of the collection must be present in the hash. Others fields are name, parentCollection, relations.

Param: the group id (hash key: group) or the user id (hash key: user).

Returns an array with three hash ref (or undef if the hash are empty): changed, unchanged, failed.

addItems($items, group => $groupid | user => $userid)

Add an array of items.

Param: the array ref of hash ref with completed item templates.

Param: the group id (hash key: group) or the user id (hash key: user).

Returns undef if the ResponseCode is not 200 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

Returns an array with three hash ref (or undef if the hash are empty): changed, unchanged, failed.

The keys are the index of the hash received in argument. The values are the keys given by zotero

updateItems($data, group => $groupid | user => $userid)

Update an array of items.

Param: the array ref of hash ref which must include the key of the item, the version of the item and the new value.

Param: the group id or the user id pass with the hash keys group or user.

Returns undef if the ResponseCode is not 200 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

Returns an array with three hash ref (or undef if the hashes are empty): changed, unchanged, failed.

The keys are the index of the hash received in argument. The values are the keys given by zotero

=head2 updateCollections($data, group => $groupid | user => $userid)

Update an array of collections.

Param: the array ref of hash ref which must include the key of the collection, and the new value.

Param: the group id or the user id pass with the hash keys group or user.

Returns undef if the ResponseCode is not 200 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

Returns an array with three hash ref (or undef if the hashes are empty): changed, unchanged, failed.

The keys are the index of the hash received in argument. The values are the keys given by zotero

deleteItems($keys, group => $groupid | user => $userid)

Delete an array of items.

Param: the array ref of item keys to delete.

Param: the group or the user id, pass with the hash keys user or group.

Returns undef if the ResponseCode is not 204 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

deleteCollections($keys, group => $groupid | user => $userid)

Delete an array of collections.

Param: the array ref of collection keys to delete.

Param: the group or the user id, pass with the keys group or user.

Returns undef if the ResponseCode is not 204 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

deleteSearches($keys, group => $groupid | user => $userid)

Delete an array of searches.

Param: the array ref of search key to delete.

Param: the group or the user id, pass with the keys group or user.

Returns undef if the ResponseCode is not 204 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

deleteTags($keys, group => $groupid | user => $userid)

Delete an array of tags.

Param: the array ref of tags to delete.

Param: the group or the user id, pass with the keys group or user.

Returns undef if the ResponseCode is not 204 (see https://www.zotero.org/support/dev/web_api/v3/write_requests).

BUGS

See support below.

SUPPORT

Any questions or problems can be posted to me (rappazf) on my gmail account.

The current state of the source can be extract using Mercurial from http://sourceforge.net/projects/www-zotero-write/

AUTHOR

François Rappaz CPAN ID: RAPPAZF

COPYRIGHT

François Rappaz 2017 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

WWW::Zotero