/ 
ZCS-Admin-0.07
River stage zero No dependents
/ ZCS::Admin

NAME

ZCS::Admin - module for the Zimbra Collaboration Suite (ZCS) Admin web services

SYNOPSIS

use ZCS::Admin;

my $zimbra = ZCS::Admin->new;
my $resp = $zimbra->auth( name => 'admin', password => 'mypass' );
die ZCS::Admin->faultinfo($resp) if !$resp;
...

DESCRIPTION

The ZCS::Admin Perl module uses SOAP to interface with the Zimbra Collaboration Suite Admin web services (primarily SOAP but also REST).

METHODS

new

my $z = ZCS::Admin->new(
    name     => 'zimbra',
    password => $pass,
);
die ZCS::Admin->faultinfo($z) if !$z;

Create a new instance of ZCS::Admin. On errors a SOAP fault object is returned. See SOAP::WSDL documentation for details of the SOAP fault object.

During object instantiation the auth method is called to ensure communcation with the server is possible.

The default the Admin SOAP service URL is typically:

https://127.0.0.1:7071/service/admin/soap

Use the 'proxy' argument to specify a different URL than the default:

...->new( proxy => 'https://my.svr.loc:7071/service/admin/soap', ... )

A ZCS::Admin has the following object attributes:

name

The user name for authentication.

password

The password for authentication.

proxy

The URL of the ZCS Admin SOAP service

new_element

$z->new_element($element);

Get the instance of a "ZCS::Admin::Elements::$element" object.

Note: This can be used as a class or object method.

new_type

$z->new_type($element);

Get the instance of a "ZCS::Admin::Types::$type" object.

Note: This can be used as a class or object method.

new_fault

$z->new_fault( \%args );

Get the instance of a SOAP::WSDL::SOAP::Typelib::Fault11.

Note: This can be used as a class or object method.

Warning: the object type is likely to change in a future release but the object will still likely behave in a similar manner to the current object.

faultinfo

$z->faultinfo($fault);

Note: This can be used as a class or object method.

Returns a string containing the concatenation of "Code" from the ZCS fault detail (if available), the "faultstring", and the "Trace" from the ZCS fault detail (if available).

client

Creates and returns a new instance of ZCS::Admin::Interfaces::Admin::AdminSoap12, which is the underlying object being used to communicate with the ZCS Admin SOAP service. On errors a SOAP fault object is returned. See SOAP::WSDL documentation for details of the SOAP fault object.

cl

Gets a ZCS::Admin::Interfaces::Admin::AdminSoap12 object via client() and calls auth() if the current session authentication information has expired or no session information is already stored.

REST and SOAP Interface Calls

auth

Calls Auth on the underlying ZCS Admin object, removes stale context() information and caches new authentication information on success. Returns itself (for call chaining if desired) or a SOAP Fault object on failures.

delegateauth

$z->delegateauth( name => $acct );

Calls DelegateAuth on the underlying ZCS Admin object. And returns results.

Probably need to do more but this is a start. Probably need some sort of context updating in most cases. But not sure how we should manage multiple contexts and push/pop them as we need.

Returns DelegateAuth response for now.

context

Returns a context element object using cached information if it exists or by calling cl() if no cached data is available (auth() clears a cached context object if re-authentication has taken place).

createaccount

$z->createaccount( name => $name, password => $password, a => \@attr );

getaccount

getaccountinfo

$z->getaccount( name => $acct );
$z->getaccountinfo( name => $acct );

Arguments:

{id|name} => $acct

getaccountid

my $id = $z->getaccountid($acct);

addaccountalias

$z->addaccountalias( name => $acct, alias => $alias );

Arguments:

{id|name} => $acct

removeaccountalias

$z->removeaccountalias( name => $acct, alias => $alias );

Arguments:

{id|name} => $acct

modifyaccount

$z->modifyaccount( name => $acct, attr1 => val1, attr2 => val2, ... );

Arguments:

{id|name} => $acct

renameaccount

$z->renameaccount( name => $acct, $newname );

Arguments:

{id|name} => $acct
$newname

deleteaccount

$z->deleteaccount( name => $acct );

Arguments:

{id|name} => $acct

getcos

$z->getcos( name => $cos, @attrs );

Arguments:

{id|name} => $cos
@attrs (optional)

getcosid

$z->getcosid($cos);

getserver

$z->getserver( name => $svr, %args);

Arguments:

{id|name} => $svr
applyConfig => 0|1
attrs => "attr1,attr2" || [qw(attr1 attr2)]

searchdirectory

$z->searchdirectory( query => query, %args );

Arguments:

query => $query
limit => $limit
types => "type1,type2,..."
...

enablearchive

$z->enablearchive( {id|name} => $acct, %args );

Arguments:

{id|name} => $acct # acct-for-which-archiving-is-being-enabled
create => 0|1
name => $name
password => $pass
cos => $cosname # BUG: only allow name at the moment
a => \@attr

disablearchive

$z->disablearchive( {id|name} => $acct );

Arguments:

{id|name} => $acct # acct-for-which-archiving-is-already-enabled

exportmailbox

$z->exportmailbox( name => 'user@dom', dest => 'my.svr.loc', ... );

Arguments:

name => $acct # account email address
dest => $server # hostname of target server
destPort => $port # target port for mailbox import
switchover => 1|0 # update ldap on/off
overwrite => 1|0 # replace target mailbox if it exists

Notes: when switchover is 1, ldap is updated to use the target server as the mailhost for the account; the original host is not longer in use. When switchover is 0, no ldap setting is updated after the move.

if overwrite = 1, the target mailbox will be replaced if it exists

purgemovedmailbox

 $z->purgemovedmailbox( 'user@dom' );

<PurgeMovedMailboxRequest>
  <mbox name="{account email address}"/>
</PurgeMovedMailboxRequest>

Following a successful mailbox move to a new server, the mailbox on the old server remains. This allows manually checking the new mailbox to confirm the move worked. Afterwards, PurgeMovedMailboxRequest should be used to remove the old mailbox and reclaim the space.

addmessage

$z->addmessage( name => $name, folder => $folder, file => $file )

POST a message from file $file to /home/$name/$folder using the ZCS REST interface.

getdistributionlist

$z->getdistributionlist( name => $list );

Arguments:

{id|name} => $list

createdistributionlist

$z->createtdistributionlist( name => $list );

deletedistributionlist

$z->deletedistributionlist( name => $list );

Arguments:

{id|name} => $list

Helper Methods

get_from_a

my @vals = $z->get_from_a( $result->get_a, @attrs );

Returns an array (arrayref in SCALAR context) of values for attributes (case-insensitively) matched from the list of attribute name(s) specified in @attrs.

Returns undef on error.

item_from_attr

my @item = $z->item_from_attr(@attr_name_val_pairs);

Returns an array (arrayref in SCALAR context) of ItemAttribute types populated with the name/value pairs specified in @attr_name_val_pairs.

Returns undef on error.

SEE ALSO

See the following documentation and links to related software and topics:

AUTHOR

Phil Pearl <phil@zimbra.com>

COPYRIGHT AND LICENSE

Copyright (C) 2010-2011 by Phil Pearl. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.