view release on metacpan or  search on metacpan

lib/Confluence/Client/XMLRPC.pm  view on Meta::CPAN

for it when invoking a method.

=head1 ERROR HANDLING

This package has two global flags which control error handling.

  Confluence::Client::XMLRPC::setRaiseError(1);  # Enable die
  Confluence::Client::XMLRPC::setPrintError(1);  # Enable warn
  Confluence::Client::XMLRPC::setRaiseError(0);  # Disable die
  Confluence::Client::XMLRPC::setPrintError(0);  # Disable warn

The C<setRaiseError> and C<setPrintError> functions both return the previous 
setting of the flag so that it may be restored if necessary.

RaiseError is initially set to 1 to preserve the original package behavior.

PrintError is initially set to 0.

If RaiseError is set to 0 then C<Confluence::Client::XMLRPC::lastError()> 
can be used to determine if an error occurred.

  Confluence::Client::XMLRPC::setRaiseError(0);
  my $page = $wiki->getPage($space, $title);
  if ( my $e = Confluence::Client::XMLRPC::lastError() ) {
      say $e;
  }

=head1 DEBUGGING

You can get more info about the communication between your client and the
API by setting the environment variable C<CONFLDEBUG> to a true value.
If you do so, the module will log the messages exchanged to STDERR.

=head1 API VERSIONS

Analogous to the global error handling flags there is a flag to 
set the API version to use:

  Confluence::Client::XMLRPC::setApiVersion($num); # set the version

The C<setApiVersion> function returns the previous setting of the 
flag so that it may be restored if necessary.
The function accepts both plain numbers ("1" or "2") or the full
version namespaces ("confluence1", "confluence2").

The version 2 of the API was introduced with Confluence 4.0 and 
B<Atlassian recommends to use the newer version>.
However, due to backwards compatibility reasons the default value for the 
API version in this module still is B<1>. 

Note: you can use B<most but not all> of the version 1 API calls on newer 
Confluence installations! The Confluence docs contain a detailed and 
authoritative description of the
L<differences between versions 1 and 2|https://developer.atlassian.com/display/CONFDEV/Confluence+XML-RPC+and+SOAP+APIs#ConfluenceXML-RPCandSOAPAPIs-v2apiRemoteAPIversion1andversion2>
of the API!

The new version 2 API implements the same methods as the version 1 API, 
however all content is stored and retrieved using the storage format. 
This means that you cannot, for example, create a page using wiki markup 
with the version 2 API, you must instead define the page using the new
XHTML based storage format.
You will be able to create pages, blogs and comments in wiki markup 
using the version 1 API even on Confluence 4.0 and later. However you 
will no longer be able to retrieve pages, blogs and comments using 
the version 1 API.

To aid in the migration phase Confluence 4.0 and up provide a method
C<convertWikiToStorageFormat()> where you can pass in a string with 
wiki markup and will recieve the same data converted to the new storage 
format (which you can then use to create or update a page).

=head1 EXAMPLES

=over 4

=item C<upload_files.pl> - Upload files

The sample script uploads the contents of a directory to the wiki. Each file 
in the directory is uploaded as a separate page. The page title is the file 
name with extension removed. This script requires five arguments: API url, 
user name, password, space key and a directory name.

=item C<upload_users.pl> - Upload Users

This script reads and loads a list of users from a file (or stdin). If errors 
are encountered then the script will print an error message, but continue 
processing.
This script requires three arguments: API url, name and password of an admin 
user.

=item C<det_group_mbrship.pl> - Determine Group Membership

The script prints the group membership of all users.
This script requires three arguments: API url, name and password of an admin 
user.

=back

Please refer to the C<examples> directory of the distribution for the scripts 
themselves.

=head1 NOTES

The package uses the L<RPC::XML> module to do the heavy lifting. Read the 
perldoc for this package to learn more.

L<RPC::XML> uses LWP for handling C<http>/C<https> messaging. If you are 
experiencing problems when connecting to a C<https> based API endpoint,
please make sure that the necessary modules - like, e.g. 
L<LWP::Protocol::https> - are installed.

For further information on the Confluence API itself please refer to the 
L<official documentation|https://developer.atlassian.com/display/CONFDEV/Confluence+XML-RPC+and+SOAP+APIs>
as provided by Atlassian.

Please note that starting with Confluence 5.5 the XML-RPC API will be 
deprecated, meaning that Atlassian will not add new features or fix bugs 
related to the XML-RPC API for Confluence 5.5 or later.
This does B<not> mean, that this module will not work with newer Confluence
versions: as of now, there is no information if or when Atlassian will remove
the XML-RPC API and rely solely on the new REST API.