Quickstart tutorial

This tutorial will walk you through creating a synchronization engine from a CSV file to a directory. It is based on a sample archive that you can download, including CSV data, a Java embedded database (HSQLDB) and directory (OpenDS), so it just works out of the box :)

Versions from the 1.1.* branch are covered here. Behavior will be different in the upcoming 1.2 branch.

Download the lsc-core archive to use the embedded OpenDS directory:

1. Check and install the Requirements
2. Download the latest lsc-core-1.1.X.tar.bz2 archive from the download area
3. Decompress the archive, enter the directory and start OpenDS:

$ tar xjf lsc-core-1.1.1.tar.bz2
$ cd lsc-core-1.1.1
$ ant startLdapServer

Note: You must leave this command running, and use a new shell for the rest of this tutorial.

You need the lsc-sample project as a template to instantiate your own synchronization engine. This will automatically download the LSC-core library (a lsc-core-X.Y.Z.jar archive) where the main functions are provided.

Let's go:

1. Download the latest lsc-sample-1.1.X.tar.bz2 archive from the download area
2. Decompress the archive and enter the directory:

$ tar xjf lsc-sample-1.1.1.tar.bz2
$ cd lsc-sample-1.1.1

As specified above, you are going to build the template project to get the new task wizard. But please be patient until Maven retrieves all required dependencies to it's cache (this is when you need those cookies we mentioned).

To start this, use Maven2 directly on the command line from the lsc-sample directory:

$ mvn package

We will set up LSC to synchronize the contents of the sample CSV file in sample/csvtosql/sample.csv to the embedded LDAP directory we just started.

Take a look at the contents of this file:

$ cat sample/csvtosql/sample.csv 
"id";"uid";"endOfValidity";"sn";"cn";"givenName";"mail";"address";"userPassword"
;;"10/27/1999";"Kowalski";"Mike Kowalski";"Mike";...

In the root of the lsc-sample directory, launch the following command:

$ ant lsc::generateWizard

Answer the questions and let the engine generate Java files for your directory contents. First, the first try:

• Pass through the first two screens by clicking on “Next” on the first screen, and by accepting the BSD license.
• Select CSV to directory, and leave the other values unaltered. The Task name may be anything you like, without spaces. Classes are generated in src/impl/java which is the default location for generated code.
• Leave the values unaltered in the CSV parameters screen: you are specifying to use the sample CSV file provided (sample/csvtosql/sample.csv) with ”;” as a field seperator
• Leave the values unaltered in the the Target directory properties screen - defaults use the embedded OpenDS directory at the following URI: ldap://localhost:33389/ with the LSC project naming context (dc=lsc-project,dc=org)
• In the next screen, click on the Show details button before clicking on Generate.

PLEASE LOOK at the result log, because you may find useful information and error messages in case something goes wrong! This output will be saved in the ant.install.log file in the lsc-sample directory.

This is the most complex part because this is when you need to integrate your business rules in the tool.

This must be done in at least two places:

1. The configuration file, lsc.properties
2. The SQL queries to run on the embedded database (the CSV file is loaded into a database to make querying easier)

For this sample, replace the configuration file and the generated SQL query file with the sample customized files:

$ cp misc/lsc.properties.sample etc/lsc.properties
$ cp misc/InetOrgPerson.xml.sample \
  etc/sql-map-config.d/InetOrgPerson.xml

See the Documentation section for more details on customizing your tasks, in particular the Configuration file section.

First, we must load the CSV file into the embedded HSQLDB database. To do this easily, just launch the following command:

$ ant lsc::sample

This command is going to print the command usage. Synchronization parameters are passed to the Java program as specified below.

$ ant lsc::synchronize

To launch the synchronization engine, use the following Ant task. The following example launches all synchronization tasks (-s all):

$ ant -Dsynchronize.parameters="-f $PWD/etc -s all" lsc::synchronize

You can also launch comma separated specified tasks (-c task1,task2). Try the clean operation:

$ ant -Dsynchronize.parameters="-f $PWD/etc -c MySyncTask" lsc::synchronize

The modifications applied to the directory will be displayed in LDIF format as they are performed. Browse the test LDAP directory with any browser tool (such as Apache Directory Studio, LDAP Browser, GQ, jxplorer…) on ldap://localhost:33389/ and see the changes!

Now it's time to look at the main properties file: etc/lsc.properties

You will find the following structure:

src.database.driver = org.hsqldb.jdbcDriver
src.database.url = jdbc:hsqldb:file:hsqldb/lsc
src.database.username = sa
src.database.password =
 
dst.java.naming.factory.initial = com.sun.jndi.ldap.LdapCtxFactory
dst.java.naming.ldap.derefAliases = never
dst.java.naming.ldap.version = 3
dst.java.naming.provider.url = ldap://localhost:33389/dc=lsc-project,dc=org
dst.java.naming.referral = ignore
dst.java.naming.security.authentication = simple
dst.java.naming.security.credentials = secret
dst.java.naming.security.principal = cn=Directory Manager
 
dn.real_root = dc=lsc-project,dc=org
 
lsc.tasks = MySyncTask
 
lsc.tasks.MySyncTask.type = db2ldap
lsc.tasks.MySyncTask.dn = "mail=" + srcBean.getAttributeValueById("mail") \
    + ",ou=People"
lsc.tasks.MySyncTask.srcService = org.lsc.service.InetOrgPersonJDBCService
lsc.tasks.MySyncTask.dstService = org.lsc.jndi.SimpleJndiDstService
lsc.tasks.MySyncTask.dstService.attrId = mail
lsc.tasks.MySyncTask.dstService.baseDn = ou=People
lsc.tasks.MySyncTask.dstService.filterAll = (objectClass=inetOrgPerson)
lsc.tasks.MySyncTask.dstService.filterId = \
    (&(objectClass=inetOrgPerson)(mail={mail}))
lsc.tasks.MySyncTask.object = org.lsc.objects.inetOrgPerson
lsc.tasks.MySyncTask.bean = org.lsc.beans.inetOrgPersonBean
 
lsc.syncoptions.MySyncTask = org.lsc.beans.syncoptions.PropertiesBasedSyncOptions
lsc.syncoptions.MySyncTask.default.action = F
lsc.syncoptions.MySyncTask.userPassword.action = K
lsc.syncoptions.MySyncTask.userPassword.default_value = "changethis"

There are potentially five main prefixes:

• dst: properties specified with this prefix are used to connect and authenticate against the destination directory
• src: properties specified with this prefix are properties specified with this prefix are used to connect and authenticate against the source directory or the source database
• dn: LDAP DNs for commonly used branches
• lsc.tasks: specify the tasks properties (see tasks)
• lsc.syncoptions: specify the synchronization options (see synchronization options)

• Comma Separated Values files to LDAP directory

The generator engine will read the first line of your CSV file and generate the CSV to SQL required stuff to fill the embedded HsqlDB engine and provide default parameters to use it. The next steps are shared with a simple “Database to LDAP directory” task.

• Database to LDAP Directory synchronization
• LDAP Directory to LDAP Directory synchronization

Once you feel comfortable working with this sample, you probably want to start using a real database or directory. See the documentation for more details.