/ 
Confluence-Client-XMLRPC-2.5
River stage zero No dependents
/ Confluence::Client::XMLRPC

NAME

Confluence::Client::XMLRPC - Client for the Atlassian Confluence wiki, based on RPC::XML

VERSION

version 2.5

SYNOPSIS

my $wiki   = Confluence::Client::XMLRPC->new( <URL>, <user>, <pass> );
# my $result = $object->method(argument,..);

my $newPage = {
    space => 'ds',
    title => 'Sample Page',
    content => '...',
}
my $page = $wiki->storePage($newPage);

$page->{'content'} .= 'updated!';
$page = $wiki->updatePage( $page, { versionComment => 'added text' } );

$wiki->removePage( $page->{'id'} );

METHODS

new ( URL, USER, PASS [, API_VERSION ] )

Creates a new instance object and establishes a session with the server. Returns an empty value on failure or croaks if setRaiseError is true.

Starting with v2.3 you may pass in the API version to use.

Starting with v2.5 the newest API version available for the Confluence server in use will automatically be chosen unless the API version is explicitly passed in. Unlike before - when the module defaulted to using the version 1 API regardless of the Confluence server used - now version 2 will be auto-selected for Confluence >= 4.0.0.

login ( URL, USER, PASS [, API_VERSION ] )

Alias for new.

getPageSummary( PAGE )

This method seems to have been added to the official API in Confluence 4.0.0 but it is undocumented in the XML/RPC and SOAP API docs.

It is a more lightweight alternative to getPage() since a PageSummary contains only a selection of the fields present in a full Page object (hashref). Notably the content of the page is not send back.

You may use this method even with Confluence prior to 4.0 in which case getPage() is called, retrieving a complete Page object which is then stripped down to contain only the fields a PageSummary provides.

updatePage( PAGE [, PAGEUPDATEOPTIONS] )

Updates an already existing page with the data passed in in the Page hashref. The Page given should have id, space, title, content and version fields at a minimum.

Dispatches to either the RPC API method that was introduced in Confluence 2.10 or uses a combination of getPage & storePage to achieve a similar effect with older Confluence versions (but without page update options like version comments).

NOTE - INCOMPATIBLE CHANGE: previous releases of this module provided a method updatePage() that was conceived before Confluence 2.10 introduced the updatePage() API method. Unlike the API method this shim also allowed to create a new page (via storePage()) if the caller did not specify the page id.

In order to bring the behavior of this module in line with the offcial API documentation Confluence::Client::XMLRPC starting from v2.5 only allows its updatePage() method to update already existing pages.

updateOrStorePage( PAGE [, PAGEUPDATEOPTIONS] )

Updates an existing page or - if the pages does not yet exist - creates a new page.

Uses either the id attribute or the combination of space and title from the Page object (hashref) passed in as first argument to determine if an updateable page exists. If so, updates that page. Otherwise, stores a new page.

The second param, PageUpdateOptions, is used only if there is an updateable page and if the updatePage() XML/RPC API method is available (i.e. on Confluence 2.10 or newer). Otherwise, the param is simply ignored.

NOTE: Added in v2.5 of Confluence::Client::XMLRPC this method is the successor in behaviour to the updatePage() as it was implemented in earlier versions of this module. It is intended simply as a convenience method. Unlike the API method storePage() which also allows to either update or create a page it does not rely solely on page ids to identify existing pages but also tries to look up existing pages be space and title. Also unlike storePage() the usage of PageUpdateOptions is possible.

setApiVersion( VERSION )

Sets the API version to use. See section API VERSIONS below for more information on the different API versions and the consequences of using one or the other.

setRaiseError( BOOL ), setPrintError( BOOL )

See section ERROR HANDLING below.

All other method calls are simply mapped (via AUTOLOAD) to RPC method calls.

Please refer to the official list of available methods for further information.

Please refer to the list of data objects for information on the structure of return values and arguments.

The module tries to automatically map between the data types mentioned in the Atlassian docs and the appropriate Perl data types:

Vectors : array references
Structs and data objects : hash references
Boolean : strings "true" and "false"

For everything else, simple scalars are used and mapped to RPC::XML::string, so explicit type conversions should not be required.

Note: the "token" paramater mentioned in the Confluence docs is the session id and is automatically added by this module, so do not pass in a parameter for it when invoking a method.

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 setRaiseError and 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 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;
}

DEBUGGING

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

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 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 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 1.

Note: you can use 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 differences between versions 1 and 2 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 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).

EXAMPLES

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.

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.

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.

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

NOTES

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

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

For further information on the Confluence API itself please refer to the official documentation 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 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.

CAVEAT

ATTENTION, please: This module was written by Asgeir Nilsen in 2004 and later on improved by Giles Lewis, Martin Ellis, and Torben K. Jensen.

I - Heiko Jansen - only took the available source code and created a CPAN distribution for it, because at least to me a Perl module almost does not exist if it's not on available via CPAN.

This package should work with any remote API function.

The original authors tested it with addUserToGroup, getActiveUsers, getPage, getPages, getServerInfo, getUser, and storePage. I (Heiko Jansen) have used it successfully to create and update pages, but I did not test most other API functions and am thus unable to give any guarantee that it will work as expected!

The original module was simply named "Confluence" but since Atlassian is currently working on a new REST-based API I renamed it to Confluence::Client::XMLRPC.

AUTHORS

  • Asgeir Nilsen

  • Giles Lewis

  • Martin Ellis

  • Torben K. Jensen

  • Heiko Jansen <hjansen@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by Heiko Jansen.

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991