====== Quickstart tutorial ======


===== Introduction =====

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.

===== Launch the sample directory =====

Download the lsc-core archive to use the embedded OpenDS directory:
   - Check and install the [[.:requirements]]
   - Download the [[http://tools.lsc-project.org/attachments/download/56/lsc-core-1.1.1.tar.bz2|latest]] **lsc-core-1.1.//X//.tar.bz2** archive from the [[http://tools.lsc-project.org/files|download area]]
   - Decompress the archive, enter the directory and start OpenDS:
<code shell>
$ tar xjf lsc-core-1.1.1.tar.bz2
$ cd lsc-core-1.1.1
$ ant startLdapServer
</code>

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

===== Quickstart with a new project from the lsc-sample archive =====

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:
   - Download the [[http://tools.lsc-project.org/attachments/download/57/lsc-sample-1.1.1.tar.bz2|latest]] **lsc-sample-1.1.//X//.tar.bz2** archive from the [[http://tools.lsc-project.org/files|download area]]
   - Decompress the archive and enter the directory:
<code shell>$ tar xjf lsc-sample-1.1.1.tar.bz2
$ cd lsc-sample-1.1.1</code>

===== Fetch required Java dependencies using Maven =====

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:

<code bash>
$ mvn package
</code>

===== Generating your first task through the CLI / graphic installer =====

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:
<code bash>
$ cat sample/csvtosql/sample.csv 
"id";"uid";"endOfValidity";"sn";"cn";"givenName";"mail";"address";"userPassword"
;;"10/27/1999";"Kowalski";"Mike Kowalski";"Mike";...
</code>

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

<code bash>$ ant lsc::generateWizard</code>

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.
===== Customizing the task =====

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:
  - The configuration file, **lsc.properties**
  - 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 [[.:index|Documentation section]] for more details on customizing your tasks, in particular the [[.:configuration:start|Configuration file section]].

===== Test your synchronization task =====

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

<code bash>$ ant lsc::sample</code>

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!

===== Configure the data sources =====

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

You will find the following structure:

<code java>
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"
</code>

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)

===== Information about the different task types =====

    * 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

===== What now? =====

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