NAME

Data::Sync - A simple metadirectory/datapump module

SYNOPSIS

 use Data::Sync;

 my $sync = Data::Sync->new(log=>"STDOUT");

 $sync->source($dbhandle,{select=>"select * from testtable"});

 or

 $sync->source($ldaphandle,{filter=>"(cn=*)",
                                scope=>"sub",
                                base=>"ou=testcontainer,dc=test,dc=org"});

 $sync->target($dbhandle,{table=>'targettable',
                                index=>'NAME'});

 or

 $sync->target($ldaphandle);

 $sync->mappings(FIRSTNAME=>'givenName',SURNAME=>'sn');

 $sync->buildattributes(dn=>"cn=%NAME%,ou=testcontainer,dc=test,dc=org",
                        objectclass=>"organizationalUnit");

 $sync->transforms(PHONE=>'s/0(\d{4})/\+44 \($1\) /',
                        ADDRESS=>sub{my $address=shift;
                                        $address=~s/\n/\<BR\>/g;
                                        return $address});

 $sync->run();

DESCRIPTION

Data::Sync is a simple metadirectory/data pump module. It automates a number of the common tasks required when syncing databases & ldap directories.

In order to use Data::Sync, you must define a source and a target. The first parameter to the source & target methods is a bound database/Net::LDAP handle.

Having defined your datasources, define how attributes map between them with mappings. If an attribute returned from the data source has no entry in the mapping table, it will be assumed that the name is the same in both databases.

Attributes can be built up from multiple other attributes using buildattributes. This uses a simple template, %FIELDNAME% which is replaced at run time with the value of the field from the current record. More complex modifications to data can be made with transforms, which runs after the built attributes are created.

Transforms can be made with the method transforms, which takes a hash of FIELDNAME=>transformation. This transformation can be one of three things: a regular expression in string form (see synopsis), the name of a predefined transformation supplied in Data::Sync, or a code ref.

Finally, if you are confident your data is all in the right format, use run. That will read the data from the source, modify it as you have specified, and write it to the target.

WARNING! There is no implied or real warranty associated with the use of this software. That's fairly obvious, but worth repeating here. Metadirectory applications have the potential to destroy data in a very big way - they must be constructed carefully, and thoroughly tested before use on a live system.

CONSTRUCTOR

 my $sync = Data::Sync->new(log=>"STDOUT");
 my $sync = Data::Sync->new(log=>$fh);

The constructor returns a Data::Sync object. To use logging, pass the string STDOUT as the log parameter to print logging to STDOUT, or a lexical filehandle.

METHODS

source

 $sync->source($dbhandle,{select=>"select * from testtable"});

 or

 $sync->source($ldaphandle,{filter=>"(cn=*)",
                                scope=>"sub",
                                base=>"ou=testcontainer,dc=test,dc=org"});

Requires a valid, bound (i.e. logged in) Net::LDAP or DBI handle, and a hash of parameters for the data source. LDAP parameters are: filter scope base attrs controls

(See Net::LDAP for more details of these parameters).

DBI parameters are: select

target

 $sync->target($dbhandle,{table=>'targettable',
                                index=>'NAME'});

 or

 $sync->target($ldaphandle);

Requires a valid, bound (i.e. logged in) DBI or Net::LDAP handle, and a hash of parameters. No parameters are required for LDAP data targets, but a dn must have been either read from the data source or constructed using buildattributes. Valid DBI parameters are

 table - the table you wish to write to on the data target
 index - the attribute you wish to use as an index

Note: if you are writing from DB to LDAP, you must construct all mandatory attributes using buildattributes, or additions will fail.

mappings

 $sync->mappings(FIRSTNAME=>'givenName',SURNAME=>'sn');

Maps individual field names from the data source, to their corresponding field names in the data target.

buildattributes

 $sync->buildattributes(dn=>"cn=%NAME%,ou=testcontainer,dc=test,dc=org",
                        objectclass=>"organizationalUnit");

Builds new target attributes up from existing source attributes. A simple template form is used - the template should be a string variable, containing the source field name between % delimiters. If no % delimiters are found, the string will be written as a literal.

transforms

 $sync->transforms(     PHONE=>'s/0(\\d{4})/\+44 \(\$1\)'/’,
                        OFFICE=>"stripspaces",
                        ADDRESS=>sub{my $address=shift;
                        $address=~s/\n/\<BR\>/g;
                        return $address});

Converts each field in the source data using the parameters passed. Each parameter pair is the target field name, along with a regex (in a string), a coderef, or a standard function. The following list of transformation functions are supplied in this version:

 stripspaces
 stripnewline

Note: If passing a regex in a string, make sure you use single quotes. Double quotes will invite perl to interpolate the contents, with unexpected results.

run

 $sync->run();

No parameters. Reads the data from the source, converts and renames it as defined in mappings, buildattributes and transforms, and writes it to the target.

PREREQS

If you are using LDAP datasources, you will need Net::LDAP. If you are using DBI datasources, you will need DBI and the appropriate DBD drivers.

VERSION

0.01

TODO

CHANGES

COPYRIGHT

Copyright (c) 2004-2005 Charles Colbourn. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Charles Colbourn charlesc@g0n.net

cpanm Data::Sync

perl -MCPAN -e shell
install Data::Sync